Overview of the NAG Library for .NET

[image]

NAG Library for .NET Release 2
Overview of the NAG Library for .NET

The NAG Library contains over 1,600 algorithms which are powerful, reliable and flexible. The Library is organised into Chapters, with each Chapter concentrating on a particular area of numerical mathematics.

About the NAG Library for .NET

The NAG Library for .NET, provides Microsoft .NET users with access to NAG's comprehensive set of optimization and statistical algorithms, together with a representative sample of algorithms from other Chapters of the Library. This Library includes algorithms from the following Chapters: Library Identification (A00), Roots of Equations (C05), Summation of Series (C06), Wavelet Transforms (C09), Quadrature (D01), Interpolation (E01), Curve and Surface Fitting (E02), Optimization (E04), Global Optimization (E05), Linear Algebra (F01, F06, F07, F08), Statistics (G01, G02, G03, G05, G13), Operations Research (H), Special functions (S), Constant and Utility functions (X01, X02, X04).

Note that in many cases not all the algorithms in a Chapter are provided at this time, however the class documentation, derived from the NAG Fortran Library Chapter Introductions, may still refer to algorithms not currently provided in the NAG Library for .NET. The tables of contents and tabulated lists of methods in each class do however accurately reflect the methods provided in this release.

Key features

The NAG Library for .NET has two main components: a .NET assembly of managed code (NagLibrary32.dll, NagLibrary64.dll) and a shared library of unmanaged Code (DTW3207DA.dll or DTW6407DA.dll). The .NET managed assembly consists of a set of classes with static methods with relatively simple interfaces based on the NAG Fortran Library. These interfaces make calls to the NAG Library routines in (DTW3207DA.dll or DTW6407DA.dll). Note that these unmanaged libraries do include all the functionality of Mark 24 of the NAG Fortran library, example C# declarations giving access to these interfaces are included in the distribution. Further details on calling the unmanaged library from .NET are available from the NAG website

Help is provided in the form of Visual Studio Intellisense, and an HTML help file (NagLibrary.chm) together with online documentation at www.nag.co.uk/DT. Note that the Visual studio context sensitive HTML help is not supplied with this release.

Also provided with the NAG Library for .NET are example classes, data and results for each of the static methods in the managed assemblies (NagLibrary32.dll, NagLibrary64.dll). Every example class has a Main method, hence each of the example classes can be used as a self contained class within a console project or via the command line. These examples can be used as templates for your own applications.

A NAG Library for .NET application is also included which can be executed from the Start Menu (Start->NAG->NAG Library for .NET Version 2->NAG Library for .NET Example Application). This application provides a GUI that enables any subset of example programs to be conveniently executed.

Changes since Version 1

The underlying computational code has been updated to Mark 24 of the NAG Fortran Library. Several new methods have been added as detailed below.

New Methods in this Version

c05au
Zero of continuous function, Brent algorithm, from a given starting value, binary search for interval
c05aw
Zero of continuous function, continuation method, from a given starting value
c05ay
Zero of continuous function in a given interval, Brent algorithm
c05qb
Solution of a system of nonlinear equations using function values only (easy-to-use)
c05qd
Solution of a system of nonlinear equations using function values only (reverse communication)
c05qc
Solution of a system of nonlinear equations using function values only (comprehensive)
c05rb
Solution of a system of nonlinear equations using first derivatives (easy-to-use)
c05rc
Solution of a system of nonlinear equations using first derivatives (comprehensive)
c05rd
Solution of a system of nonlinear equations using first derivatives (reverse communication)
c05zd
Check user's function for calculating first derivatives of a set of nonlinear functions of several variables
e04jc
Minimum by quadratic approximation, function of several variables, simple bounds, using function values only
e04pc
Computes the least squares solution to a set of linear equations subject to fixed upper and lower bounds on the variables. An option is provided to return a minimal length solution if a solution is not unique
e04nf
QP problem (dense)
e05uc
Global optimization using multi-start, nonlinear constraints
e05us
Global optimization of a sum of squares problem using multi-start, nonlinear constraints
f01ed
Real symmetric matrix exponential
f01ef
Function of a real symmetric matrix
f01fc
Complex matrix exponential
f01fd
Complex Hermitian matrix exponential
f01ff
Function of a complex Hermitian matrix
f01va
Copies a real triangular matrix from full format to packed format scheme
f01vb
Copies a complex triangular matrix from full format to packed format scheme
f01vc
Copies a real triangular matrix from packed format to full format scheme
f01vd
Copies a complex triangular matrix from packed format to full format scheme
f01ve
Copies a real triangular matrix from full format to Rectangular Full Packed format scheme
f01vf
Copies a complex triangular matrix from full format to Rectangular Full Packed format scheme
f01vg
Copies a real triangular matrix from Rectangular Full Packed format to full format scheme
f01vh
Copies a complex triangular matrix from Rectangular Full Packed format to full format scheme
f01vj
Copies a real triangular matrix from packed format to Rectangular Full Packed format scheme
f01vk
Copies a complex triangular matrix from packed format to Rectangular Full Packed format scheme
f01vl
Copies a real triangular matrix from Rectangular Full Packed format to packed format scheme
f01vm
Copies a complex triangular matrix from Rectangular Full Packed format to packed format scheme
f06qf
Matrix copy, real rectangular or trapezoidal matrix
f07te
Solution of real triangular system of linear equations, multiple right-hand sides
f07th
Error bounds for solution of real triangular system of linear equations, multiple right-hand sides
g02ab
Computes the nearest correlation matrix to a real square matrix, augmented g02aa to incorporate weights and bounds
g02ae
Computes the nearest correlation matrix with k-factor structure to a real square matrix
g02qf
Linear quantile regression, simple interface, independent, identically distributed (IID) errors
g02qg
Linear quantile regression, comprehensive interface
g05kk
Primes a pseudorandom number generator for generating multiple streams using skip-ahead, skipping ahead a power of 2
g07ga
Outlier detection using method of Peirce, raw data or single variance supplied
g07gb
Outlier detection using method of Peirce, two variances supplied
h02bb
Integer LP problem (dense)
h02cb
Integer QP problem (dense)
h02ce
Integer LP or QP problem (sparse), using e04nk
x04cb
Print real general matrix (comprehensive)
x04db
Print complex general matrix (comprehensive)

Widthdrawn Methods

c05ad
See: c05ay
c05ag
See: c05au
c05aj
See: c05aw
c05nb
See: c05qb
c05nc
See: c05qc
c05nd
See: c05qd
c05pb
See: c05rb
c05pc
See: c05rc
c05pd
See: c05rd
c05za
See: c05zd
e04zc
No longer required
g13dc
See: g13dd

Product Installation and Activation

The NAG Library for .NET is a fully license managed product. To use the product you will need to obtain a license key. This can be obtained by following the instructions after clicking 'Request or install license key' found in the Start menu(Start->NAG->NAG Library for .NET Version 2). To ensure that the license has been installed correctly please run the NAG Library for .NET Example Application (described in the previous section) and execute one of the example programs.

For more complex licensing situations, or if you encounter problems with the installation or use of this software, please contact the NAG Technical Support Service at support@nag.co.uk.

Send comments on this topic to support@nag.co.uk


Overview of the NAG Library for .NET

[image]

NAG Library for .NET Release 2
Overview of the NAG Library for .NET

The NAG Library contains over 1,600 algorithms which are powerful, reliable and flexible. The Library is organised into Chapters, with each Chapter concentrating on a particular area of numerical mathematics.

About the NAG Library for .NET

The NAG Library for .NET, provides Microsoft .NET users with access to NAG's comprehensive set of optimization and statistical algorithms, together with a representative sample of algorithms from other Chapters of the Library. This Library includes algorithms from the following Chapters: Library Identification (A00), Roots of Equations (C05), Summation of Series (C06), Wavelet Transforms (C09), Quadrature (D01), Interpolation (E01), Curve and Surface Fitting (E02), Optimization (E04), Global Optimization (E05), Linear Algebra (F01, F06, F07, F08), Statistics (G01, G02, G03, G05, G13), Operations Research (H), Special functions (S), Constant and Utility functions (X01, X02, X04).

Note that in many cases not all the algorithms in a Chapter are provided at this time, however the class documentation, derived from the NAG Fortran Library Chapter Introductions, may still refer to algorithms not currently provided in the NAG Library for .NET. The tables of contents and tabulated lists of methods in each class do however accurately reflect the methods provided in this release.

Key features

The NAG Library for .NET has two main components: a .NET assembly of managed code (NagLibrary32.dll, NagLibrary64.dll) and a shared library of unmanaged Code (DTW3207DA.dll or DTW6407DA.dll). The .NET managed assembly consists of a set of classes with static methods with relatively simple interfaces based on the NAG Fortran Library. These interfaces make calls to the NAG Library routines in (DTW3207DA.dll or DTW6407DA.dll). Note that these unmanaged libraries do include all the functionality of Mark 24 of the NAG Fortran library, example C# declarations giving access to these interfaces are included in the distribution. Further details on calling the unmanaged library from .NET are available from the NAG website

Help is provided in the form of Visual Studio Intellisense, and an HTML help file (NagLibrary.chm) together with online documentation at www.nag.co.uk/DT. Note that the Visual studio context sensitive HTML help is not supplied with this release.

Also provided with the NAG Library for .NET are example classes, data and results for each of the static methods in the managed assemblies (NagLibrary32.dll, NagLibrary64.dll). Every example class has a Main method, hence each of the example classes can be used as a self contained class within a console project or via the command line. These examples can be used as templates for your own applications.

A NAG Library for .NET application is also included which can be executed from the Start Menu (Start->NAG->NAG Library for .NET Version 2->NAG Library for .NET Example Application). This application provides a GUI that enables any subset of example programs to be conveniently executed.

Changes since Version 1

The underlying computational code has been updated to Mark 24 of the NAG Fortran Library. Several new methods have been added as detailed below.

New Methods in this Version

c05au
Zero of continuous function, Brent algorithm, from a given starting value, binary search for interval
c05aw
Zero of continuous function, continuation method, from a given starting value
c05ay
Zero of continuous function in a given interval, Brent algorithm
c05qb
Solution of a system of nonlinear equations using function values only (easy-to-use)
c05qd
Solution of a system of nonlinear equations using function values only (reverse communication)
c05qc
Solution of a system of nonlinear equations using function values only (comprehensive)
c05rb
Solution of a system of nonlinear equations using first derivatives (easy-to-use)
c05rc
Solution of a system of nonlinear equations using first derivatives (comprehensive)
c05rd
Solution of a system of nonlinear equations using first derivatives (reverse communication)
c05zd
Check user's function for calculating first derivatives of a set of nonlinear functions of several variables
e04jc
Minimum by quadratic approximation, function of several variables, simple bounds, using function values only
e04pc
Computes the least squares solution to a set of linear equations subject to fixed upper and lower bounds on the variables. An option is provided to return a minimal length solution if a solution is not unique
e04nf
QP problem (dense)
e05uc
Global optimization using multi-start, nonlinear constraints
e05us
Global optimization of a sum of squares problem using multi-start, nonlinear constraints
f01ed
Real symmetric matrix exponential
f01ef
Function of a real symmetric matrix
f01fc
Complex matrix exponential
f01fd
Complex Hermitian matrix exponential
f01ff
Function of a complex Hermitian matrix
f01va
Copies a real triangular matrix from full format to packed format scheme
f01vb
Copies a complex triangular matrix from full format to packed format scheme
f01vc
Copies a real triangular matrix from packed format to full format scheme
f01vd
Copies a complex triangular matrix from packed format to full format scheme
f01ve
Copies a real triangular matrix from full format to Rectangular Full Packed format scheme
f01vf
Copies a complex triangular matrix from full format to Rectangular Full Packed format scheme
f01vg
Copies a real triangular matrix from Rectangular Full Packed format to full format scheme
f01vh
Copies a complex triangular matrix from Rectangular Full Packed format to full format scheme
f01vj
Copies a real triangular matrix from packed format to Rectangular Full Packed format scheme
f01vk
Copies a complex triangular matrix from packed format to Rectangular Full Packed format scheme
f01vl
Copies a real triangular matrix from Rectangular Full Packed format to packed format scheme
f01vm
Copies a complex triangular matrix from Rectangular Full Packed format to packed format scheme
f06qf
Matrix copy, real rectangular or trapezoidal matrix
f07te
Solution of real triangular system of linear equations, multiple right-hand sides
f07th
Error bounds for solution of real triangular system of linear equations, multiple right-hand sides
g02ab
Computes the nearest correlation matrix to a real square matrix, augmented g02aa to incorporate weights and bounds
g02ae
Computes the nearest correlation matrix with k-factor structure to a real square matrix
g02qf
Linear quantile regression, simple interface, independent, identically distributed (IID) errors
g02qg
Linear quantile regression, comprehensive interface
g05kk
Primes a pseudorandom number generator for generating multiple streams using skip-ahead, skipping ahead a power of 2
g07ga
Outlier detection using method of Peirce, raw data or single variance supplied
g07gb
Outlier detection using method of Peirce, two variances supplied
h02bb
Integer LP problem (dense)
h02cb
Integer QP problem (dense)
h02ce
Integer LP or QP problem (sparse), using e04nk
x04cb
Print real general matrix (comprehensive)
x04db
Print complex general matrix (comprehensive)

Widthdrawn Methods

c05ad
See: c05ay
c05ag
See: c05au
c05aj
See: c05aw
c05nb
See: c05qb
c05nc
See: c05qc
c05nd
See: c05qd
c05pb
See: c05rb
c05pc
See: c05rc
c05pd
See: c05rd
c05za
See: c05zd
e04zc
No longer required
g13dc
See: g13dd

Product Installation and Activation

The NAG Library for .NET is a fully license managed product. To use the product you will need to obtain a license key. This can be obtained by following the instructions after clicking 'Request or install license key' found in the Start menu(Start->NAG->NAG Library for .NET Version 2). To ensure that the license has been installed correctly please run the NAG Library for .NET Example Application (described in the previous section) and execute one of the example programs.

For more complex licensing situations, or if you encounter problems with the installation or use of this software, please contact the NAG Technical Support Service at support@nag.co.uk.


Introduction

[image]

NAG Library for .NET Release 2
Introduction

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/numeric/dt/dtw3a02da/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:

  • NAG UK
  • NAG North America
  • NAG Japan


NAG F# examples

[image]

NAG Library for .NET Release 2
NAG F# examples

F# — Background

F# is a functional programming language derived from OCAML, which in turn has a shared ancestry with the Standard ML.

F# uses a syntax derived from OCAML but has many additional features in particular making it interface better with .NET constructs (as it compiles to the same CLR virtual machine as other .NET languages). Thus it should be easy to call the NAG Library for .NET from F#, and so it is, however the resulting interface doesn't always lead to idiomatic functional programming calling conventions. In this post I hope to show some reasons for this, and also show how with a few lines of F#, one can produce alternative interfaces to the NAG library that may allow more natural functional use, and be tuned to the particular requirements of your application.

F# is a very expressive language that is designed to support many different programming styles, although with a strongly functional foundation. As such there are several styles in which one may define a function (method). One of the distinguishing features of the ML family of languages is that they are strongly typed but that (when restricted to the core functional features) types never need to be explicitly declared, the expressions are statically analyzed at compile time and the type inferred.

F# may be used in two ways; as a compiler (compiling to CIL code as is done for C# or VB.NET) but also as an interactive interpreter that offers a read eval print loop interface familiar to lisp programmers and users of systems such as MATLAB or Maple.

Before looking at some specific examples from the NAG library, I want to look at a simpler example of a function for adding two numbers.

Sum Example

The first example uses a style that looks perhaps most familiar. Note however that unlike many imperative programming languages, F# functions only ever take a single argument. (a,b) here does not represent a pair of values but a single value, being a pair of integers (represented by the type int * int.

// sum_tuple declaration
> let sum_tuple (a,b) = a + b;;
val sum_tuple : int * int -> int

A more idiomatically functional style is the curried form, where instead of taking a sequence of values as input, the function takes one integer, returning a function which is in turn applied to the second integer, returning the sum.

// sum_curried declaration
> let sum_curried a  b = a + b;;
val sum_curried : int -> int -> int

As well as variables holding values (int in this case) ML based languages allow variables that hold references (pointers) to values (the type int ref here). the assignment operator := updates the referenced value (while the reference binding itself doesn't change). Passing such a reference type is one way to simulate the “output parameters” of functions or subroutines in imperative languages. The unit type shown as the return type is similar to void function in C, or a subroutine in Fortran.

// sum_ref declaration
> let sum_ref (a,b,r) = r := a + b;;
val sum_ref : int * int * int ref -> unit

In addition to the reference types derived from ML, F# provides a syntax to the .NET mechanisms of passing value types by reference. The example below uses the type annotation r:byref<int> to force this mechanism to be used, and uses the assignment operator <- rather than := to update the value. Passing a value type by reference rather than passing a parameter of reference type isn't something one would often do in native F# code, however methods derived from .NET libraries written in other languages often derive these types in F#.

// sum_byref declaration
> let sum_byref (a,b,r:byref<int>) = r <- a + b;;
val sum_byref : int * int * byref<int> -> unit

These four definitions may used as follows to calculate 3 = 1 + 2:

// Simple sum examples

> let r1 = sum_tuple (1,2);;
val r1 : int = 3

> let r2 = sum_curried 1 2;;
val r2 : int = 3

> let rr3 = ref 0;;
val rr3 : int ref = {contents = 0;}
> sum_ref (1,2,rr3);;
val it : unit = ()
> let r3 = !rr3;;
val r3 : int = 3

> let mutable r4 = 0;;
val mutable r4 : int = 0
> sum_byref(1,2,&r4);;
val it : unit = ()
> r4;;
val it : int = 3

The first two forms are clearly a bit more convenient, however the second two forms, which require the declaration of a variable to hold the result, are not hard and should be familiar to anyone used to a more imperative programming style. This essentially is a function of the main design aims of F#, that it should stress the functional approach, but give full access to any .NET methods even if they are designed for an imperative or Object Oriented rather than functional, declarative interface. The extra verbosity of the use of references is over exaggerated in these examples as I am using the interactive F# system and using the ;; terminator to cause the system to echo the value and type of each expression. This is a useful aid to see what's happening, but in practice one would often use the compiler which does not echo types at each stage, or not use the ;; terminator on every line if using the interactive system.

The benefits of the tuple or curried version when used in a functional programming language like F# are more apparent when functions are composed. If one wanted to calculate (1+1) + (2+2) (ignoring the fact that (1+1) + (2+2) is already valid F# ) then as sum_tuple and sum_curried are side effect free functions returning results they may be composed in a very natural way:

// composing sum examples (functional)
> let c1=sum_tuple (sum_tuple(1,1),sum_tuple(2,2));;
val c1 : int = 6

> let c2=sum_curried (sum_curried 1 1) (sum_curried 2 2);;
val c2 : int = 6

The signatures of sum_ref and sum_byref on the other hand lead to a more imperative calling style, where temporary variables need to be declared to hold (references to) the intermediate results.

// composing sum examples (imperative)
> let r3a = ref 0;;
val r3a : int ref = {contents = 0;}
> let r3b = ref 0;;
val r3b : int ref = {contents = 0;}
> let r3c = ref 0;;
val r3c : int ref = {contents = 0;}
> sum_ref (1,1,r3a);;
val it : unit = ()
> sum_ref (2,2,r3b);;
val it : unit = ()
> sum_ref (!r3a,!r3b,r3c);;
val it : unit = ()
> let c3 = !r3c;;
val c3 : int = 6

> let mutable r4a = 0;;
val mutable r4a : int = 0
> let mutable r4b = 0;;
val mutable r4b : int = 0
> let mutable c4 = 0;;
val mutable c4 : int = 0
> sum_byref (1,1,&r4a);;
val it : unit = ()
> sum_byref (2,2,&r4b);;
val it : unit = ()
> sum_byref (r4a,r4b,&c4);;
val it : unit = ()
> c4;;
val it : int = 6

If you had obtained a library providing sum_ref but you wanted to code in a more natural (in F#) functional style it is easy to “wrap” sum_ref to give for example the same interface as nag_curried.

// mysum declaration and use
> let  mysum a b =
   let r = ref 0
   sum_ref(a,b,r)
   !r ;;
val mysum : int -> int -> int

> let c5=mysum(mysum 1 1) (mysum 2 2);;
val c5 : int = 6

Having looked at the toy “sum” example, we'll move on to look at some real examples from the NAG Library for .NET.

NAG Library for .NET

Firstly some details to reference the NAG Library. The #r syntax is only used for the interactive interpreter. For the F# compiler, command-line arguments or the usual Visual Studio reference settings are used instead. Also “open” the System and NagLibrary namespaces to avoid having to use fully qualified names on each method call.

// NAG Library reference for fsi
> #if INTERACTIVE
#I @"c:\Program Files\NAG\DTW02"
#r "NagLibrary32.dll"
#endif
open System
open NagLibrary
--> Added 'c:\Program Files\NAG\DTW02' to library include path
--> Referenced 'c:\Program Files\NAG\DTW02\NagLibrary32.dll'

A00: Licence Check Example

First call the simplest function in the library, that just returns true if a valid NAG licence is detected.

// a00ac example
> printfn "Have a NAG licence: %b" (A00.a00ac())
Have a NAG licence: true
val it : unit = ()

While this is a very simple example, it shows many of the advantages of the functional style and the top level interactive loop. Similar to MATLAB, the F# interface allows access to the NAG library functionality with the absolute minimum of additional syntax or programming steps. No main program, no explicit variable declarations, no explicit compilation steps etc.

D01: Quadrature Example

Next we take a slightly more complicated example from the Quadrature chapter. The method integrates the supplied function between the specified bounds, returning extra information about the number of iterations and accuracy. While it is straightforward to call this method, the values returned by byref parameters, and the need to explicitly cast the function to be integrated to the delegate type mean that the style resembles sum_byref above rather than the more idiomatically functional sum_curried.

Just as an example, two styles of setting up the parameters by reference are used. The classic ML style of defining values of reference type, which are dereferenced using !, and an alternative syntax (for npts) using an explicitly mutable variable which acts more like variables in imperative languages, in which the dereferencing is automatic.

// d01ah example: direct call
> let if1 = ref 0
let mutable npts=0
let relerr= ref 0.0
let f x = Math.Sin(x:double)
let nlimit=1000
let ff= D01.D01AH_F(f)
let result1 = D01.d01ah(
               0.0,Math.PI,0.01,&npts,relerr,ff,nlimit, if1);;
val mutable npts : int = 7
val relerr : float ref = {contents = 0.0006944567037;}
val f : float -> float
val nlimit : int = 1000
val ff : D01.D01AH_F
val result1 : float = 2.0
> !if1;;
val it : int = 0
> npts;;
val it : int = 7
> !relerr;
val it : float = 0.0006944567037

F# has some facilities to automatically present output parameters in a more functional style. If parameters passed by reference appear at the end of the .NET signature of a method, F# provides an alternative signature where the reference parameters may be omitted from the method call, and the returned results are provided as a list of values. F# will also implicitly apply a delegate constructor if the method is passed a compatible anonymous function (lambda expression), even though it will not automatically cast a variable bound to a function to the appropriate delegate type.

In this case, we may omit the final ifail parameter, whose value (0) is returned as the second item in the returned sequence rather than being captured by a reference parameter (ifl in the above example). However the position of the input parameter nlimit prevents this automatic system being used to avoid using explicit references for npts. Also rather than passing the variable ff, of type D01.D01AH_FC an anonymous function is used.

// d01ah example: returning a tuple
> let (result2,if2) = D01.d01ah(
                      0.0,Math.PI,0.01,&npts, relerr,(fun x -> f x),nlimit);;
val result2 : float = 2.0
val if2 : int = 0
> npts;;
val it : int = 7
> !relerr;;
val it : float = 0.0006944567037

As with the mysum example above, if this method is to be called often, a more naturally functional interface may be prefered.

The exact choice of interface depends a lot on personal requirements, but also personal aesthetic judgments. In the example below I've used a curried form for the input parameters, and a record type to capture the output fields, but for other uses one may use a tuple form for input and capture the results as a tuple (or by the use of out parameters).

// declaration of myd01ah: curried, returning a record
> type d01ahresults = {result: float ; npts: int ; relerr: float; ifail: int}

> let myd01ah f interval epsr nlimit =
    let ff=D01.D01AH_F(f)
    let (a,b) = interval
    let npts = ref 0
    let relerr = ref 0.0
    let ifl = ref 0
    let result = D01.d01ah(a,b,epsr,npts,relerr,ff,nlimit,ifl)
    {result= result; npts= !npts;relerr= !relerr;ifail= !ifl} ;;
val myd01ah :
  (float -> float) -> float * float -> float -> int -> d01ahresults

Having set up this method we may directly integrate Math.Sin over the specified interval without the need to define any subsidiary reference or delegate objects. So the entire d01ah example program collapses into one line.

// using myd01ah
> myd01ah Math.Sin (0.0,Math.PI) 0.01 1000 ;;
val it : d01ahresults = {result = 2.0;
                         npts = 7;
                         relerr = 0.0006944567037;
                         ifail = 0;}

E04: Optimization Example

Finally, a more complicated example from the optimization chapter. The callback function that must be supplied has reference parameters, and again there are several reference parameters for the top level method.

The style used here is similar to that used for the D01 example, a curried form for input parameters, and a record type to capture the results. In addition pairs of float parameters in the original interface have been combined into a single input parameter and a single result field, denoting intervals.

// declaration of mye04ab: curried, returning a record
> type  e04abresults = { minimum: float ; x: float; bounds: (float*float);
                       iter: int; ifail: int }

> let mye04ab f interv  e1 e2  mc =
    let a,b = interv
    let ra = ref a
    let rb = ref b
    let fx = ref 0.0
    let x = ref 0.0
    let mcr = ref mc
    let ifr = ref 0
    E04.e04ab((fun x res -> res <- f x),
               ref e1, ref e2, ra, rb, mcr ,x, fx ,ifr)
    {minimum = !fx; x = !x;bounds = (!ra,!rb); iter= !mcr; ifail = !ifr} ;;
val mye04ab :
  (float -> float) -> float * float -> float -> float -> int -> e04abresults

Again, once this method is defined, the minimization method can be called directly without having to set up any reference variables or delegates.

// using mye04ab
> mye04ab (fun x ->  (Math.Sin x) / x) (3.0,5.0) 0.0 0.0 30 ;;
val it : e04abresults = {minimum = -0.2172336282;
                         x = 4.493409455;
                         bounds = (4.493409397, 4.493409513);
                         iter = 10;
                         ifail = 0;}

Printed Output

The methods in the NAG Library for .NET typically return results via reference parameters (or return values of functions) however text can be directed to an output stream in the following situations:

  • The errors and warnings raised by the library will not throw a .NET exception. Instead the method will return with a non zero ifail value. As described in the Introduction to the Library, the display of the warnings may be controlled by setting the Warning property of the PrintManager class appropriately.
  • Certain methods in the library have facilities to display monitoring information. In some cases this monitoring is controlled by a user supplied monitoring function. The C# example programs provided with the library use monitoring callback methods that use Console.WriteLine however the user supplied method may direct the monitoring information to any suitable destination, for example a TextBox in a windows form application. In other cases, monitoring is controlled by integer or boolean flags to enable the monitoring, in this case, final destination stream may be controlled as for warnings, by setting the Message property on teh Printmanager class.

The next two examples use a windows form application (derived from a copy of the sample form in the F# sample distribution from Microsoft).

Monitoring Function (e04cb example)

e04cb is an example of a method that takes a user supplied method to monitor the progress of the iteration. We define a small F# wrapper as before (although this time returning a tuple of values rather than a record of a named record type).

// declaration of  mye04cb

let mye04cb n x tolf tolx func monit maxcal =
    let ffunc = new E04.E04CB_FUNCT(
                     fun n xc (res:byref<float>) -> res <- func xc)
    let fmonit = new E04.E04CB_MONIT(monit)
    let ifl = ref 0
    let rf = ref 0.0
    E04.e04cb(n,x,rf,tolx,tolf,ffunc,fmonit,maxcal,ifl)
    (x,!rf)

We then define the function to be minimised, and the initial bounds on the variable.

// object function for e04cb example

let mutable e04cbf = fun (xc: float[]) ->
    Math.Exp(xc.[0]) * (4.00e0 * xc.[0] * (xc.[0] + xc.[1]) +
    2.00e0 * xc.[1] * (xc.[1] + 1.00e0) +
    1.00e0);

// e04cb example bounds

let mutable e04cbx = [|-1.0;1.0|]

In this example we will use a simplified monitoring function that only prints the number of iterations. As we are using a windows form application we don't want to write to the console. the form has a TextBox declared (textB) and we want the monitoring function to update the text property of that box:

// e04cb monit function

let e04cbmonitor  fmin fmax sim n ncall se vr =
       textB.Text <- ( textB.Text +
                     (sprintf " There have been %d function calls\n" ncall))

When the "Run Example 1" menu option is chosen, the runexmpl1 method is executed:

// run the e04cb example

let runexmpl1 () =
       textB.BackColor<- Drawing.Color.White
       textB.Text <- "monitor\n"
       textB2.Text <- sprintf "The final function value is ...\n"
       let (interv,vl) = mye04cb  2 e04cbx (Math.Sqrt(X02.x02aj()))
                                 (Math.Sqrt(Math.Sqrt(X02.x02aj())))
                                  e04cbf
                                  e04cbmonitor
                                  100
       textB2.Text <- ( textB2.Text + (sprintf "  %f \n" vl))

As can be seen, this just initializes the text in the two text boxes, calls mye04cb and then finally retrieves the reference to the minimum value and updates the results text box. the monitoring text box will have been updated during the progress of the iteration by e04cbmonitor

fsharp form executed from Visual Studio

If the form is executed by the F# interpreter (fsi command line or the F# interactive window in Visual Studio) then we can make use of the above mutable definitions to change the function to be minimized without restarting the form application. Entering (for example):

// Update e04cb object function

e04cbf <- fun (xc: float[]) -> 1.0;;

At the interactive prompt will cause the variable e04cbf to be updated (to represent the constant function 1) re-selecting the “Run e04cb example” menu option will cause e04cb to be re-executed using this object function (finding the minimum value of 1). Future versions of F# may expose the interpreter as an eval function (as in lisp and some other functional languages) which would avoid the need to maintain an open interpreter window, however use of the interpreter in this way is still quite a powerful way of interacting with the system,

Internal Monitoring (e04xa example)

Some methods in the library do not take a user supplied monitoring function, but instead handle the monitoring internally, often controlled by an integer parameter (or optional parameter) that controls verbosity of the output. By default this monitoring information will be sent to System.Console.WriteLine however as described above it may be sent to a more appropriate stream, or as shown below to a textbox. We take e04xa as a simple example of such a function.

// declaration of  mye04xa

let mye04xa mlevel n epsrf x mode objfun hforw =
    let objf = ref 0.0
    let objgrd :float array = Array.zeroCreate n
    let hcntrl :float array = Array.zeroCreate n
    let h :float [,] = Array2D.zeroCreate n n
    let info : int array = Array.zeroCreate n
    let mref = ref mode
    let objfref = ref 0.0
    let warnref = ref 0
    let ifailref = ref 0
    let objfund = E04.E04XA_OBJFUN(
                   fun (a:byref<int>) b c (d:byref<float>) e f ->
                    d <- objfun a b c d e f
                    )
    E04.e04xa (mlevel,n,epsrf,x,mref,objfund,hforw,objfref,objgrd,
               hcntrl,h,warnref,info,ifailref)
    (!objfref,objgrd,hcntrl,h,!warnref)

// e04xa object function

let e04xaobjfun int n (x: float array) objf objgrd nstate =
  let a = x.[0] + 10.0*x.[1]
  let b = x.[2] - x.[3]
  let c = x.[1] - 2.0*x.[2]
  let d = x.[0] - x.[3]
  a*a + 5.0*b*b + c*c*c*c + 10.0*d*d*d*d

This time when the “Run e04xa” menu option is chosen, the following method is executed

// run the e04xa example

// make mode a parameter just so we can force an error to occur

// 0 is a valid but 10 is not a valid input value for mode.

let runexmpl2 (mode) =
       textB.BackColor<- Drawing.Color.White
       textB.Text <- "monitor\n"
       textB2.Text <- sprintf "The final function value is ...\n"
//  Beta 2 code needed to redirect Console.Out
//  Now we can use PrintManager properties.
//      let oldOut = Console.Out
//       let strWriter = new IO.StringWriter()
//       Console.SetOut(strWriter);

       PrintManager.Message <- (fun s -> textB.Text <- textB.Text + s  + "\n")
       PrintManager.Warning <- (fun s ->
                                 textB.BackColor<- Drawing.Color.Red
                                 textB.Text <- textB.Text + "\nError:\n" + s   + "\n")

       let (objf,z1,z2,z3,z4)=
           mye04xa
             (*mlevel*) 10
             (*n*) 4
             (*epsrf*) 0.0
             (*x*) [|3.0;-1.0;0.0;1.0|]
             (*mode*) mode
             (*objfun*) e04xaobjfun
             (*hforw*) [|-1.0;-1.0;-1.0;-1.0|]
//       Console.SetOut(oldOut)
//       textB.Text <- strWriter.ToString()

       textB2.Text <- ( textB2.Text + (sprintf "  %f \n" objf))

F# Files

nagfsharp1.fsx: F# file including all the Console Application code shown above. Note: if this is used in an F# Interactive session (Control-Alt-F in Visual Studio) it references c:\Program Files\NAG\DTW02\NagLibrary32.dll. You will need to adjust the Include directives if the library is installed at a different location.

nagfsharp2.fsx: F# file including the full code for a windows form application, with a drop down menu giving the option to run two example programs with monitoring enabled. This is essentially the “Hello World” Form Example from the F# sample distribution from Microsoft, extended with the code to run NAG examples, as shown in the previous section. Note: if this is used in an F# Interactive session (Control-Alt-F in Visual Studio) it references c:\Program Files\NAG\DTW02\NagLibrary32.dll. You will need to adjust the Include directives if the library is installed at a different location.

nagfsharp3.fsx: An additional example, from Sorin Seban, giving the e04uc example program as F# code.

Conclusions

This article has give examples showing how to call the NAG Library for .NET from the interactive top level loop of F#, and in particular how writing small functions around the supplied methods can result in greatly simplified calling conventions.

It has been asked whether it would be possible for the supplied .NET methods to be more F#-like. It would be possible for example to place all out or ref parameters at the end of the method parameter list, however this wouldn't always lead to the most natural interface in C# or VB.NET, and F# users would perhaps still want to make similar wrappers to avoid the need to explicitly declare delegates, or to use named record types for output, or curried forms for input as in the examples above.


NAG Fortran Library Interfaces

[image]

NAG Library for .NET Release 2
NAG Fortran Library Interfaces

The .NET Library does not currently include documented interfaces to all of the NAG Library, however the supplied DTW3A02DA and DTW6402DA libraries are compatible with The Fortran Libraries FLDLL24M and and FLW6I24DC respectively. The Fortran libraries are distributed with .NET declarations to call the libraries from .NET and the installation directory of this .NET library includes copies of these interfaces wiith the DLLLImport commands modified to call DTW3A02DA or DTW6402DA. Please see the files flcsdnet.cs and flcsdnet64.cs.

These files may be compiled to produce a nag_declarations Class or individual declarations for the routines of interest may be copied into your project. Note that unlike the documented .NET methods, if using these interfaces the user is responsible for marshalling data between the managed and unmanaged code, and any error messages are printed via the underlying native dll, not through .NET streams. Further information and examples may be found on the NAG website.


C++ and using Object fields

[image]

NAG Library for .NET Release 2
C++ and using Object fields

This article was originally published on the NAG Blog. Further items may be posted on the blog from time to time.

This article goves examples of C++/CLR use and of using methods from objects rather than static methods as callback parameters to the NAG methods.

It takes the existing C# example for the optimisation routine e04uc and modifies it in two ways. Firstly converting to C++/CLR, and then modifying the example so that the objective function being minimised is a method of an object (of locally declared class NagDelegate) and to demonstrate two ways in which data may be passed between successive calls to this callback parameter.

Note that C++/CLR has extended syntax (notably ^ and gcnew in this example) which declare managed data that will be managed and potentially garbage collected by the .NET runtime system.

Once the class and its method are defined, the only thing that needs to be done to pass this method to the e04uc method is to declare the delegate object using the syntax

E04::E04UC_OBJFUN^ objfunE  =
    gcnew E04::E04UC_OBJFUN(nagdelegate, &NagDelegate::objfun);

Unlike the situation in C#, you need to specify both the class and the particular method as two separate parameters when declaring the delegate.

As mentioned above, the method NagDelegate::objfun demonstrates two ways in which data may be accessed, in both cases here the data is a counter reporting how many times the objective function was evaluated by the optimisation algorithm. static_counter is a static variable and counter is a local field of the NagDelegate object. As may be seen by the results when the program is run, both methods work as expected, returning the same value.

  static_counter++;
  counter++;

The C++ example program is shown in full at the end of this post. To run it using Visual Studio, just start a new project and replace the default program by the code below. You must then select the project references and add a reference to the NagLibrary32 or NagLibrary64 .NET assemblies. The program should then run and produce the output shown.

 // csharpfromcpp.cpp : main project file.
 #include "stdafx.h"
 using namespace System;
 using namespace NagLibrary;

 static int static_counter;

 public ref class NagDelegate
 {
 public:
     int counter;
     void objfun(int% mode, int n, array <double>^ x, double% objf,
                 array <double>^ objgrd, int nstate)
     {
         //      Routine to evaluate objective function
         //      and its 1st derivatives.
         static_counter++;
         counter++;
         double one = 1.00e0;
         double two = 2.00e0;
         if ((mode == 0) || (mode == 2))
             {
                 objf = x[0] * x[3] * (x[0] + x[1] + x[2]) + x[2];
             }
         //
         if ((mode == 1) || (mode == 2))
             {
                 objgrd[0] = x[3] * (two * x[0] + x[1] + x[2]);
                 objgrd[1] = x[0] * x[3];
                 objgrd[2] = x[0] * x[3] + one;
                 objgrd[3] = x[0] * (x[0] + x[1] + x[2]);
             }
         //
     }
 };

 void confun( int% mode, int ncnln, int n, array< int >^ needc,
               array< double >^ x, array <double>^ c,
                     array <double,2>^ cjac, int nstate)
     {
       //      Routine to evaluate the nonlinear constraints
       //       and their 1st derivatives.
       double zero = 0.00e0;
       double two = 2.00e0;
       int i,  j;
       if (nstate == 1)
       {
         //  First call to confun.  Set all Jacobian elements to zero.
         //  Note that this will only work when 'Derivative Level = 3'
         //  (the default; see Section 11.2).
         for (j = 1; j <= n; j++)
         {
           for (i = 1; i <= ncnln; i++)
           {
             cjac[i - 1, j - 1] = zero;
           }
         }
       }
       //
       if (needc[0] > 0)
       {
         if ((mode == 0) || (mode == 2))
         {
           c[0] = (x[0]) * (x[0]) +
                          (x[1]) * (x[1]) + (x[2]) * (x[2]) + (x[3]) * (x[3]);
         }
         if ((mode == 1) || (mode == 2))
         {
           cjac[0, 0] = two * x[0];
           cjac[0, 1] = two * x[1];
           cjac[0, 2] = two * x[2];
           cjac[0, 3] = two * x[3];
         }
       }
       //
       if (needc[1] > 0)
       {
         if ((mode == 0) || (mode == 2))
         {
           c[1] = x[0] * x[1] * x[2] * x[3];
         }
         if ((mode == 1) || (mode == 2))
         {
           cjac[1, 0] = x[1] * x[2] * x[3];
           cjac[1, 1] = x[0] * x[2] * x[3];
           cjac[1, 2] = x[0] * x[1] * x[3];
           cjac[1, 3] = x[0] * x[1] * x[2];
         }
       }
       //
     }

 int main(array<System::String ^> ^args)
 {
         double objf = 0.0;
         int i,  ifail,  iter,  j,  n,  nclin,  ncnln;
         Console::WriteLine(L"e04uc Example Program Results");
         //      Skip heading in data file
         n = 4;
         nclin = 1;
         ncnln = 2;
         array< double, 2 >^ a = gcnew array< double, 2 >( nclin, n);
         a[0, 0]=1;
         a[0, 1]=1;
         a[0, 2]=1;
         a[0, 3]=1;

         array< double >^ bl = gcnew array< double >(n + nclin +ncnln);
         bl[0] = 1.0;
         bl[1] = 1.0;
         bl[2] = 1.0;
         bl[3] = 1.0;
         bl[4] = -1.0e+25;
         bl[5] = -1.0e+25;
         bl[6] = 25.0;

         array< double >^ bu = gcnew array< double >(n + nclin +ncnln);
         bu[0] = 5.0;
         bu[1] = 5.0;
         bu[2] = 5.0;
         bu[3] = 5.0;
         bu[4] = 20.0;
         bu[5] = 40.0;
         bu[6] = 1.0e25;

         array< double >^ c = gcnew array< double >(ncnln);
         array< double, 2 >^ cjac = gcnew array< double, 2 >(ncnln, n);
         array< double >^ clamda = gcnew array< double >(n + nclin +ncnln);
         array< double >^ objgrd = gcnew array< double >(n);
         array< double, 2 >^ r = gcnew array< double, 2 >(n, n);
         array< double >^ x = gcnew array< double >(n);
         x[0] = 1.0;
         x[1] = 5.0;
         x[2] = 5.0;
         x[3] = 1.0;

         array< int >^ istate = gcnew array< int >(n + nclin +ncnln);

              E04::e04ucOptions^ options = gcnew E04::e04ucOptions() ;
              E04::E04UC_CONFUN^ confunE = gcnew  E04::E04UC_CONFUN(confun);

              NagDelegate^ nagdelegate =
                        gcnew NagDelegate();
              E04::E04UC_OBJFUN^ objfunE  =
                        gcnew  E04::E04UC_OBJFUN(nagdelegate,  &NagDelegate::objfun);
              E04::e04uc(n, nclin, ncnln, a, bl, bu, confunE, objfunE, iter, istate, c,
                         cjac, clamda, objf, objgrd, r, x, options, ifail);

              Console::WriteLine("The objective value on return is {0}. ",
                      objf);
              Console::WriteLine("Objfun has been  called {0} times, using class member",
                      nagdelegate->counter);
              Console::WriteLine("Objfun has been  called {0} times, using a static variable",
                      static_counter);

     return 0;
 }

When run the following output is produced:

e04uc Example Program Results
The objective value on return is 17.0140172891347.
Objfun has been  called 7 times, using class member
Objfun has been  called 7 times, using a static variable


NagLibrary Namespace

[image]

NAG Library for .NET Release 2
NagLibrary Namespace
Send Feedback
Namespace for all classes in the NAG Library for .NET.

Classes

Class Description
A00
The methods in this chapter provide information about the NAG Library.
a00ac enables you to check if a valid key is available for the library licence management system.
Information about the precise implementation of the NAG Library in use will be needed when communicating with the NAG Response Centre (see the Library Overview).
C05
This chapter is concerned with the calculation of zeros of continuous functions of one or more variables. The majority of problems considered are for real-valued functions of real variables, in which case complex equations must be expressed in terms of the equivalent larger system of real equations.
C05..::..c05qdCommunications
Communications Class for c05qd
C05..::..c05rdCommunications
Communications Class for c05rd
C06
This chapter is concerned with the following tasks.
(a) | Calculating the discrete Fourier transform of a sequence of real or complex data values.
(b) | Calculating the discrete convolution or the discrete correlation of two sequences of real or complex data values using discrete Fourier transforms.
(c) | Calculating the inverse Laplace transform of a user-supplied method.
(d) | Direct summation of orthogonal series.
(e) | Acceleration of convergence of a seuqnce of real values.
C09
This chapter is concerned with the analysis of datasets (or functions or operators) in terms of frequency and scale components using wavelet transforms. Wavelet transforms have been applied in many fields from time series analysis to image processing and the localization in either frequency or scale that they provide is useful for data compression or denoising. In general the standard wavelet transform uses dilation and scaling of a chosen function, ψ t, (called the mother wavelet) such that
ψ a,b t=1 a ψ t-b a
where a gives the scaling and b determines the translation. Wavelet methods can be divided into continuous transforms and discrete transforms. In the continuous case, the pair a and b are real numbers with a>0. For the discrete transform, a and b can be chosen as a=2-j, b=k 2-j for integers j, k
ψ j,k t=2 j/2 ψ 2 j t-k.
The continuous real valued, one-dimensional wavelet transform (CWT) is included in this chapter. The discrete wavelet transform (DWT) at a single level together with its inverse and the multi-level DWT with inverse are also provided for one, two and three dimensions. The Maximal Overlap DWT (MODWT) together with its inverse and the multi-level MODWT with inverse are provided for one dimension. The choice of wavelet for CWT includes the Morlet wavelet and derivatives of a Gaussian while the DWT and MODWT offer the orthogonal wavelets of Daubechies and a selection of biorthogonal wavelets.
C09..::..C09Communications
Communications Class
D01
This chapter provides methods for the numerical evaluation of definite integrals in one or more dimensions and for evaluating weights and abscissae of integration rules.
E01
This chapter is concerned with the interpolation of a function of one or more variables. When provided with the value of the function (and possibly one or more of its lowest-order derivatives) at each of a number of values of the variable(s), the NAG Library methods provide either an interpolating function or an interpolated value. For some of the interpolating functions, there are supporting NAG Library methods to evaluate, differentiate or integrate them.
E02
The main aim of this chapter is to assist you in finding a function which approximates a set of data points. Typically the data contain random errors, as of experimental measurement, which need to be smoothed out. To seek an approximation to the data, it is first necessary to specify for the approximating function a mathematical form (a polynomial, for example) which contains a number of unspecified coefficients: the appropriate fitting method then derives for the coefficients the values which provide the best fit of that particular form. The chapter deals mainly with curve and surface fitting (i.e., fitting with functions of one and of two variables) when a polynomial or a cubic spline is used as the fitting function, since these cover the most common needs. However, fitting with other functions and/or more variables can be undertaken by means of general linear or nonlinear methods (some of which are contained in other chapters) depending on whether the coefficients in the function occur linearly or nonlinearly. Cases where a graph rather than a set of data points is given can be treated simply by first reading a suitable set of points from the graph.
The chapter also contains methods for evaluating, differentiating and integrating polynomial and spline curves and surfaces, once the numerical values of their coefficients have been determined.
There is, too, a method for computing a Padé approximant of a mathematical function (see [Padé Approximants] and [Padé Approximants]).
E04
An optimization problem involves minimizing a function (called the objective function) of several variables, possibly subject to restrictions on the values of the variables defined by a set of constraint functions. Most methods in the Library are concerned with function minimization only, since the problem of maximizing a given objective function F(x) is equivalent to minimizing -F x. Some methods allow you to specify whether you are solving a minimization or maximization problem, carrying out the required transformation of the objective function in the latter case.
In general methods in this chapter find a local minimum of a function f, that is a point x* s.t. for all x near x* f x≥f x*.
The E05 class contains methods to find the global minimum of a function f. At a global minimum x* f x≥f x* for all x.
The (H not in this release) contains methods typically regarded as belonging to the field of operations research.
This introduction is only a brief guide to the subject of optimization designed for the casual user. Anyone with a difficult or protracted problem to solve will find it beneficial to consult a more detailed text, such as Gill et al. (1981) or Fletcher (1987).
If you are unfamiliar with the mathematics of the subject you may find some sections difficult at first reading; if so, you should concentrate on [Types of Optimization Problems], [Geometric Representation and Terminology], [Scaling], [Analysis of Computed Results] and [Recommendations on Choice and Use of Available Methods].
E04..::..e04dgOptions
Options Class for e04dg
E04..::..e04mfOptions
Options Class for e04mf
E04..::..e04ncOptions
Options Class for e04nc
E04..::..e04nfOptions
Options Class for e04nf
E04..::..e04nkOptions
Options Class for e04nk
E04..::..e04nqOptions
Options Class for e04nq
E04..::..e04ucOptions
Options Class for e04uc
E04..::..e04ufOptions
Options Class for e04uf
E04..::..e04ugOptions
Options Class for e04ug
E04..::..e04usOptions
Options Class for e04us
E04..::..e04vhOptions
Options Class for e04vh
E04..::..e04wdOptions
Options Class for e04wd
E05
Global optimization involves finding the absolute maximum or minimum value of a function (the objective function) of several variables, possibly subject to restrictions (defined by a set of bounds or constraint functions) on the values of the variables. Such problems can be much harder to solve than local optimization problems (which are discussed in E04 class) because it is difficult to determine whether a potential optimum found is global, and because of the nonlocal methods required to avoid becoming trapped near local optima. Most optimization methods in the NAG Library are concerned with function minimization only, since the problem of maximizing a given objective function F is equivalent to minimizing -F. In e05jb, (E05SAF not in this release) and (E05SBF not in this release), you may specify whether you are solving a minimization or maximization problem; in the latter case, the required transformation of the objective function will be carried out automatically. In what follows we refer exclusively to minimization problems.
This introduction is a brief guide to the subject of global optimization, designed for the casual user. For further details you may find it beneficial to consult a more detailed text, such as Neumaier (2004). Furthermore, much of the material in the E04 class is relevant in this context also. In particular, it is strongly recommended that you read [] in the E04 class Chapter Introduction.
E05..::..e05jbOptions
Options Class for e05jb
E05..::..e05ucOptions
Options Class for e05uc
E05..::..e05usOptions
Options Class for e05us
F01
This chapter provides facilities for four types of problem:
(i) | Matrix Inversion
(ii) | Matrix Factorizations
(iii) | Matrix Arithmetic and Manipulation
(iv) | Matrix Functions
These problems are discussed separately in [Matrix Inversion], [Matrix Factorizations], [Matrix Arithmetic and Manipulation] and [Matrix Functions].
F06
This chapter is concerned with basic linear algebra methods which perform elementary algebraic operations involving scalars, vectors and matrices. It includes methods which conform to the specifications of the BLAS (Basic Linear Algebra Subprograms).
F07
This chapter provides methods for the solution of systems of simultaneous linear equations, and associated computations. It provides methods for
  • – matrix factorizations;
  • – solution of linear equations;
  • – estimating matrix condition numbers;
  • – computing error bounds for the solution of linear equations;
  • – matrix inversion;
  • – computing scaling factors to equilibrate a matrix.
Methods are provided for both real and complex data.
For a general introduction to the solution of systems of linear equations, you should turn first to (F04 not in this release). The decision trees, in [Decision Trees] in the F04 class Chapter Introduction, direct you to the most appropriate methods in (F04 not in this release) F07 class for solving your particular problem. In particular, (F04 not in this release) F07 class contain Black Box (or driver) methods which enable some standard types of problem to be solved by a call to a single method. Where possible, methods in (F04 not in this release) call F07 class methods to perform the necessary computational tasks.
There are two types of driver methods in this chapter: simple drivers which just return the solution to the linear equations; and expert drivers which also return condition and error estimates and, in many cases, also allow equilibration. The simple drivers for real matrices have names of the form and for complex matrices have names of the form The expert drivers for real matrices have names of the form and for complex matrices have names of the form
The methods in this chapter ( F07 class) handle only dense and band matrices (not matrices with more specialised structures, or general sparse matrices).
The methods in this chapter have all been derived from the LAPACK project (see Anderson et al. (1999)). They have been designed to be efficient on a wide range of high-performance computers, without compromising efficiency on conventional serial machines.
F08
This chapter provides methods for the solution of linear least squares problems, eigenvalue problems and singular value problems, as well as associated computations. It provides methods for:
  • – solution of linear least squares problems
  • – solution of symmetric eigenvalue problems
  • – solution of nonsymmetric eigenvalue problems
  • – solution of singular value problems
  • – solution of generalized linear least squares problems
  • – solution of generalized symmetric-definite eigenvalue problems
  • – solution of generalized nonsymmetric eigenvalue problems
  • – solution of generalized singular value problems
  • – matrix factorizations associated with the above problems
  • – estimating condition numbers of eigenvalue and eigenvector problems
  • – estimating the numerical rank of a matrix
  • – solution of the Sylvester matrix equation
Methods are provided for both real and complex data.
For a general introduction to the solution of linear least squares problems, you should turn first to (F04 not in this release). The decision trees, at the end of (F04 not in this release), direct you to the most appropriate methods in (F04 not in this release) F08 class. (F04 not in this release) F08 class contain Black Box (or driver) methods which enable standard linear least squares problems to be solved by a call to a single method.
For a general introduction to eigenvalue and singular value problems, you should turn first to (F02 not in this release). The decision trees, at the end of (F02 not in this release), direct you to the most appropriate methods in (F02 not in this release) F08 class. (F02 not in this release) F08 class contain Black Box (or driver) methods which enable standard types of problem to be solved by a call to a single method. Often methods in (F02 not in this release) call F08 class methods to perform the necessary computational tasks.
The methods in this chapter ( F08 class) handle only dense, band, tridiagonal and Hessenberg matrices (not matrices with more specialised structures, or general sparse matrices). The tables in [Recommendations on Choice and Use of Available Methods] and the decision trees in [Decision Trees] direct you to the most appropriate methods in F08 class.
The methods in this chapter have all been derived from the LAPACK project (see Anderson et al. (1999)). They have been designed to be efficient on a wide range of high-performance computers, without compromising efficiency on conventional serial machines.
It is not expected that you will need to read all of the following sections, but rather you will pick out those sections relevant to your particular problem.
G01
This chapter covers three topics:
  • plots, descriptive statistics, and exploratory data analysis;
  • statistical distribution functions and their inverses;
  • testing for Normality and other distributions.
G02
This chapter is concerned with two techniques – correlation analysis and regression modelling – both of which are concerned with determining the inter-relationships among two or more variables.
Other chapters of the NAG Library which cover similar problems are E02 class E04 class. E02 class methods may be used to fit linear models by criteria other than least squares, and also for polynomial regression; E04 class methods may be used to fit nonlinear models and linearly constrained linear models.
G02..::..g02qgOptions
Options Class for g02qg
G03
This chapter is concerned with methods for studying multivariate data. A multivariate dataset consists of several variables recorded on a number of objects or individuals. Multivariate methods can be classified as those that seek to examine the relationships between the variables (e.g., principal components), known as variable-directed methods, and those that seek to examine the relationships between the objects (e.g., cluster analysis), known as individual-directed methods.
Multiple regression is not included in this chapter as it involves the relationship of a single variable, known as the response variable, to the other variables in the dataset, the explanatory variables. Routines for multiple regression are provided in G02 class.
G05
This chapter is concerned with the generation of sequences of independent pseudorandom and quasi-random numbers from various distributions, and models.
G05..::..G05State
Class for holding the state of the Random number generator.
G07
This chapter deals with the estimation of unknown parameters of a univariate distribution. It includes both point and interval estimation using maximum likelihood and robust methods.
G13
This chapter provides facilities for investigating and modelling the statistical structure of series of observations collected at points in time. The models may then be used to forecast the series.
The chapter covers the following models and approaches.
1. | Univariate time series analysis, including autocorrelation functions and autoregressive moving average (ARMA) models.
2. | Univariate spectral analysis.
3. | Transfer function (multi-input) modelling, in which one time series is dependent on other time series.
4. | Bivariate spectral methods including coherency, gain and input response functions.
5. | Vector ARMA models for multivariate time series.
6. | Kalman filter models.
7. | GARCH models for volatility.
8. | Inhomogeneous Time Series.
H
This chapter provides methods to solve certain integer programming, transportation and shortest path problems. Additionally ‘best subset’ methods are included.
H..::..h02bbOptions
Options Class for h02bb
H..::..h02cbOptions
Options Class for h02cb
H..::..h02ceOptions
Options Class for h02ce
S
This chapter is concerned with the provision of some commonly occurring physical and mathematical functions.
X01
This chapter is concerned with the provision of mathematical constants required by other methods within the Library.
X02
This chapter is concerned with parameters which characterise certain aspects of the computing environment in which the NAG Library is implemented. They relate primarily to floating-point arithmetic, but also to integer arithmetic, the elementary functions and exception handling. The values of the parameters vary from one implementation of the Library to another, but within the context of a single implementation they are constants.
The parameters are intended for use primarily by other methods in the Library, but users of the Library may sometimes need to refer to them directly.
X04
This chapter contains utility methods concerned with input and output to or from an external file.
PrintManager
Utility class to control the output of error messages and monitoring information. See the examples in the Library Introduction.
DataReader
DataReader Class, IO stream for reading NAG Data files

Structures

Structure | Description
Complex | Struct to denote a complex value as two doubles.

Delegates

Delegate Description
C05..::..C05AU_F
f must evaluate the function f whose zero is to be determined.
C05..::..C05AW_F
f must evaluate the function f whose zero is to be determined.
C05..::..C05AY_F
f must evaluate the function f whose zero is to be determined.
C05..::..C05QB_FCN
fcn must return the values of the functions fi at a point x.
C05..::..C05QC_FCN
fcn must return the values of the functions fi at a point x, unless iflag=0 on entry to c05qc.
C05..::..C05RB_FCN
Depending upon the value of iflag, fcn must either return the values of the functions fi at a point x or return the Jacobian at x.
C05..::..C05RC_FCN
Depending upon the value of iflag, fcn must either return the values of the functions fi at a point x or return the Jacobian at x.
D01..::..D01AH_F
f must return the value of the integrand f at a given point.
D01..::..D01AJ_F
f must return the value of the integrand f at a given point.
D01..::..D01AK_F
f must return the value of the integrand f at a given point.
D01..::..D01AL_F
f must return the value of the integrand f at a given point.
D01..::..D01AM_F
f must return the value of the integrand f at a given point.
D01..::..D01AN_G
g must return the value of the function g at a given point x.
D01..::..D01AP_G
g must return the value of the function g at a given point x.
D01..::..D01AQ_G
g must return the value of the function g at a given point x.
D01..::..D01AR_FUN
fun must return the value of the integrand f at a specified point.
D01..::..D01AS_G
g must return the value of the function g at a given point x.
D01..::..D01BD_F
f must return the value of the integrand f at a given point.
D01..::..D01DA_F
f must return the value of the integrand f at a given point.
D01..::..D01DA_PHI1
phi1 must return the lower limit of the inner integral for a given value of y.
D01..::..D01DA_PHI2
phi2 must return the upper limit of the inner integral for a given value of y.
D01..::..D01FC_FUNCTN
functn must return the value of the integrand f at a given point.
D01..::..D01GD_VECFUN
vecfun must evaluate the integrand at a specified set of points.
D01..::..D01GD_VECREG
vecreg must evaluate the limits of integration in any dimension for a set of points.
D01..::..D01JA_F
f must return the value of the integrand f at a given point.
D01..::..D01PA_FUNCTN
functn must return the value of the integrand f at a given point.
E04..::..E04AB_FUNCT
You must supply this method to calculate the value of the function F x at any point x in a,b. It should be tested separately before being used in conjunction with e04ab.
E04..::..E04BB_FUNCT
You must supply this method to calculate the values of F x and dFdx at any point x in a,b.
It should be tested separately before being used in conjunction with e04bb.
E04..::..E04CB_FUNCT
funct must evaluate the function F at a specified point. It should be tested separately before being used in conjunction with e04cb.
E04..::..E04CB_MONIT
monit may be used to monitor the optimization process. It is invoked once every iteration.
If no monitoring is required, monit may be the dummy monitoring method E04CBK supplied by the NAG Library.
E04..::..E04DG_OBJFUN
objfun must calculate the objective function F x and possibly its gradient as well for a specified n-element vector x.
E04..::..E04FC_LSQFUN
lsqfun must calculate the vector of values fi x at any point x. (However, if you do not wish to calculate the residuals at a particular x, there is the option of setting a parameter to cause e04fc to terminate immediately.)
E04..::..E04FC_LSQMON
If iprint≥0, you must supply lsqmon which is suitable for monitoring the minimization process. lsqmon must not change the values of any of its parameters.
If iprint<0, the dummy method E04FDZ can be used as lsqmon.
E04..::..E04FY_LSFUN1
You must supply this method to calculate the vector of values fi x at any point x. It should be tested separately before being used in conjunction with e04fy (see the E04 class).
E04..::..E04GD_LSQFUN
lsqfun must calculate the vector of values fi x and Jacobian matrix of first derivatives ∂fi∂xj at any point x. (However, if you do not wish to calculate the residuals or first derivatives at a particular x, there is the option of setting a parameter to cause e04gd to terminate immediately.)
E04..::..E04GD_LSQMON
If iprint≥0, you must supply lsqmon which is suitable for monitoring the minimization process. lsqmon must not change the values of any of its parameters.
If iprint<0, the dummy method E04FDZ can be used as lsqmon.
E04..::..E04GY_LSFUN2
You must supply this method to calculate the vector of values fi x and the Jacobian matrix of first derivatives ∂fi∂xj at any point x. It should be tested separately before being used in conjunction with e04gy (see the E04 class).
E04..::..E04GZ_LSFUN2
You must supply this method to calculate the vector of values fi x and the Jacobian matrix of first derivatives ∂fi∂xj at any point x. It should be tested separately before being used in conjunction with e04gz.
E04..::..E04HC_FUNCT
funct must evaluate the function and its first derivatives at a given point. (The minimization methods mentioned in [Description] gives you the option of resetting parameters of funct to cause the minimization process to terminate immediately. e04hc will also terminate immediately, without finishing the checking process, if the parameter in question is reset.)
E04..::..E04HD_FUNCT
funct must evaluate the function and its first derivatives at a given point. (e04lb gives you the option of resetting parameters of funct to cause the minimization process to terminate immediately. e04hd will also terminate immediately, without finishing the checking process, if the parameter in question is reset.)
E04..::..E04HD_H
h must evaluate the second derivatives of the function at a given point. (As with funct, a parameter can be set to cause immediate termination.)
E04..::..E04HE_LSQFUN
lsqfun must calculate the vector of values fi x and Jacobian matrix of first derivatives ∂fi∂xj at any point x. (However, if you do not wish to calculate the residuals or first derivatives at a particular x, there is the option of setting a parameter to cause e04he to terminate immediately.)
E04..::..E04HE_LSQHES
lsqhes must calculate the elements of the symmetric matrix
B x=∑i=1 m fi x Gi x,
at any point x, where Gi x is the Hessian matrix of fi x. (As with lsqfun, there is the option of causing e04he to terminate immediately.)
E04..::..E04HE_LSQMON
If iprint≥0, you must supply lsqmon which is suitable for monitoring the minimization process. lsqmon must not change the values of any of its parameters.
If iprint<0, the dummy method E04FDZ can be used as lsqmon.
E04..::..E04HY_LSFUN2
You must supply this method to calculate the vector of values fi x and the Jacobian matrix of first derivatives ∂fi∂xj at any point x. It should be tested separately before being used in conjunction with e04hy (see the E04 class).
E04..::..E04HY_LSHES2
You must supply this method to calculate the elements of the symmetric matrix
B x=∑i=1 m fi x Gi x,
at any point x, where Gi x is the Hessian matrix of fi x. It should be tested separately before being used in conjunction with e04hy (see the E04 class).
E04..::..E04JC_MONFUN
monfun may be used to monitor the optimization process. It is invoked every time a new trust-region radius is chosen.
If no monitoring is required, monfun may be the dummy monitoring method E04JCP supplied by the NAG Library.
E04..::..E04JC_OBJFUN
objfun must evaluate the objective function F at a specified vector x.
E04..::..E04JY_FUNCT1
You must supply funct1 to calculate the value of the function F x at any point x. It should be tested separately before being used with e04jy (see the E04 class).
E04..::..E04KD_FUNCT
funct must evaluate the function F x and its first derivatives ∂F∂xj at a specified point. (However, if you do not wish to calculate F or its first derivatives at a particular x, there is the option of setting a parameter to cause e04kd to terminate immediately.)
E04..::..E04KD_MONIT
If iprint≥0, you must supply monit which is suitable for monitoring the minimization process. monit must not change the values of any of its parameters.
If iprint<0, a monit with the correct parameter list must still be supplied, although it will not be called.
E04..::..E04KY_FUNCT2
You must supply funct2 to calculate the values of the function F x and its first derivative ∂F∂xj at any point x. It should be tested separately before being used in conjunction with e04ky (see the E04 class).
E04..::..E04KZ_FUNCT2
You must supply this method to calculate the values of the function F x and its first derivatives ∂F∂xj at any point x. It should be tested separately before being used in conjunction with e04kz (see E04 class).
E04..::..E04LB_FUNCT
funct must evaluate the function F x and its first derivatives ∂F∂xj at any point x. (However, if you do not wish to calculate F x or its first derivatives at a particular x, there is the option of setting a parameter to cause e04lb to terminate immediately.)
E04..::..E04LB_H
h must calculate the second derivatives of F at any point x. (As with funct, there is the option of causing e04lb to terminate immediately.)
E04..::..E04LB_MONIT
If iprint≥0, you must supply monit which is suitable for monitoring the minimization process. monit must not change the values of any of its parameters.
If iprint<0, a monit with the correct parameter list should still be supplied, although it will not be called.
E04..::..E04LY_FUNCT2
You must supply this method to calculate the values of the function F x and its first derivatives ∂F∂xj at any point x. It should be tested separately before being used in conjunction with e04ly (see the E04 class).
E04..::..E04LY_HESS2
You must supply this method to evaluate the elements H ij=∂2 F∂xi∂xj of the matrix of second derivatives of F x at any point x. It should be tested separately before being used in conjunction with e04ly (see the E04 class).
E04..::..E04NF_QPHESS
In general, you need not provide a version of qphess, because a ‘default’ method with name E04NFU/E54NFU is included in the Library. However, the algorithm of e04nf requires only the product of H or HT H and a vector x; and in some cases you may obtain increased efficiency by providing a version of qphess that avoids the need to define the elements of the matrices H or HT H explicitly.
qphess is not referenced if the problem is of type FP or LP, in which case qphess may be the method E04NFU/E54NFU.
E04..::..E04NK_QPHX
For QP problems, you must supply a version of qphx to compute the matrix product Hx. If H has zero rows and columns, it is most efficient to order the variables x=yz T so that
Hx=H 1000yz=H 1 y0,
where the nonlinear variables y appear first as shown. For FP and LP problems, qphx will never be called by e04nk and hence qphx may be the dummy method E04NKU/E54NKU.
E04..::..E04NQ_QPHX
For QP problems, you must supply a version of qphx to compute the matrix product Hx for a given vector x. If H has rows and columns of zeros, it is most efficient to order x so that the nonlinear variables appear first. For example, if x=y,z T and only y enters the objective quadratically then
Hx=H 1000yz=H 1 y0. (2)
In this case, ncolh should be the dimension of y, and qphx should compute H 1 y. For FP and LP problems, qphx will never be called by e04nq and hence qphx may be the dummy method E04NSH.
E04..::..E04UC_CONFUN
confun must calculate the vector c x of nonlinear constraint functions and (optionally) its Jacobian (=∂c∂x) for a specified n-element vector x. If there are no nonlinear constraints (i.e., ncnln=0), confun will never be called by e04uc and confun may be the dummy method E04UDM. (E04UDM is included in the NAG Library.) If there are nonlinear constraints, the first call to confun will occur before the first call to objfun.
E04..::..E04UC_OBJFUN
objfun must calculate the objective function F x and (optionally) its gradient g x=∂F∂x for a specified n-vector x.
E04..::..E04UG_CONFUN
confun must calculate the vector F x of nonlinear constraint functions and (optionally) its Jacobian =∂F∂x for a specified n 1′′ (≤n) element vector x. If there are no nonlinear constraints (i.e., ncnln=0), confun will never be called by e04ug and confun may be the dummy method E04UGM. (E04UGM is included in the NAG Library.) If there are nonlinear constraints, the first call to confun will occur before the first call to objfun.
E04..::..E04UG_OBJFUN
objfun must calculate the nonlinear part of the objective function f x and (optionally) its gradient =∂f∂x for a specified n 1′ (≤n) element vector x. If there are no nonlinear objective variables (i.e., nonln=0), objfun will never be called by e04ug and objfun may be the dummy method E04UGN. (E04UGN is included in the NAG Library.)
E04..::..E04US_CONFUN
confun must calculate the vector c x of nonlinear constraint functions and (optionally) its Jacobian (=∂c∂x) for a specified n-element vector x. If there are no nonlinear constraints (i.e., ncnln=0), confun will never be called by e04us and confun may be the dummy method E04UDM. (E04UDM is included in the NAG Library.) If there are nonlinear constraints, the first call to confun will occur before the first call to objfun.
E04..::..E04US_OBJFUN
objfun must calculate either the ith element of the vector f x=f 1 x,f 2 x,…,fm x T or all m elements of f x and (optionally) its Jacobian (=∂f∂x) for a specified n-element vector x.
E04..::..E04VH_USRFUN
usrfun must define the nonlinear portion f x of the problem functions F x=f x+Ax, along with its gradient elements G ij x=∂fi x∂xj. (A dummy method is needed even if f≡0 and all functions are linear.)
In general, usrfun should return all function and gradient values on every entry except perhaps the last. This provides maximum reliability and corresponds to the default option setting, Derivative Option=1.
The elements of G x are stored in the array g 1:usrfun_leng in the order specified by the input arrays igfun and jgvar.
In practice it is often convenient not to code gradients. e04vh is able to estimate them by finite differences, using a call to usrfun for each variable xj for which some ∂fi x∂xj needs to be estimated. However, this reduces the reliability of the optimization algorithm, and it can be very expensive if there are many such variables xj.
As a compromise, e04vh allows you to code as many gradients as you like. This option is implemented as follows. Just before usrfun is called, each element of the derivative array g is initialized to a specific value. On exit, any element retaining that value must be estimated by finite differences.
Some rules of thumb follow:
(i) | for maximum reliability, compute all gradients;
(ii) | if the gradients are expensive to compute, specify optional parameter Nonderivative Linesearch and use the value of the input parameter needg to avoid computing them on certain entries. (There is no need to compute gradients if needg=0 on entry to usrfun.);
(iii) | if not all gradients are known, you must specify Derivative Option=0. You should still compute as many gradients as you can. (It often happens that some of them are constant or zero.);
(iv) | again, if the known gradients are expensive, don't compute them if needg=0 on entry to usrfun;
(v) | use the input parameter status to test for special actions on the first or last entries;
(vi) | while usrfun is being developed, use the optional parameter Verify Level to check the computation of gradients that are supposedly known;
(vii) | usrfun is not called until the linear constraints and bounds on x are satisfied. This helps confine x to regions where the functions fi x are likely to be defined. However, be aware of the optional parameter Minor Feasibility Tolerance if the functions have singularities on the constraint boundaries;
(viii) | set status=-1 if some of the functions are undefined. The linesearch will shorten the step and try again;
(ix) | set status≤-2 if you want e04vh to stop.
E04..::..E04VJ_USRFUN
usrfun must define the problem functions F x. This method is passed to e04vj as the external parameter usrfun.
E04..::..E04WD_CONFUN
confun must calculate the vector c x of nonlinear constraint functions and (optionally) its Jacobian, ∂c∂x, for a specified n-vector x. If there are no nonlinear constraints (i.e., ncnln=0), e04wd will never call confun, so it may be the dummy method E04WDP. (E04WDP is included in the NAG Library). If there are nonlinear constraints, the first call to confun will occur before the first call to objfun.
If all constraint gradients (Jacobian elements) are known (i.e., Derivative Level=2 or 3), any constant elements may be assigned to cjac once only at the start of the optimization. An element of cjac that is not subsequently assigned in confun will retain its initial value throughout. Constant elements may be loaded in cjac during the first call to confun (signalled by the value of nstate=1). The ability to preload constants is useful when many Jacobian elements are identically zero, in which case cjac may be initialized to zero and nonzero elements may be reset by confun.
It must be emphasized that, if Derivative Level<2, unassigned elements of cjac are not treated as constant; they are estimated by finite differences, at nontrivial expense.
E04..::..E04WD_OBJFUN
objfun must calculate the objective function F x and (optionally) its gradient g x=∂F∂x for a specified n-vector x.
E04..::..E04XA_OBJFUN
If mode=0 or 2, objfun must calculate the objective function; otherwise if mode=1, objfun must calculate the objective function and the gradients.
E04..::..E04YA_LSQFUN
lsqfun must calculate the vector of values fi x and their first derivatives ∂fi∂xj at any point x. (The minimization methods mentioned in [Description] give you the option of resetting a parameter to terminate immediately. e04ya will also terminate immediately, without finishing the checking process, if the parameter in question is reset.)
E04..::..E04YB_LSQFUN
lsqfun must calculate the vector of values fi x and their first derivatives ∂fi∂xj at any point x. (e04he gives you the option of resetting parameters of lsqfun to cause the minimization process to terminate immediately. e04yb will also terminate immediately, without finishing the checking process, if the parameter in question is reset.)
E04..::..E04YB_LSQHES
lsqhes must calculate the elements of the symmetric matrix
B x=∑i=1 m fi x Gi x,
at any point x, where Gi x is the Hessian matrix of fi x. (As with lsqfun, a parameter can be set to cause immediate termination.)
E05..::..E05JB_MONIT
monit may be used to monitor the optimization process. It is invoked upon every successful completion of the procedure in which a sub-box is considered for splitting. It will also be called just before e05jb exits if that splitting procedure was not successful.
If no monitoring is required, monit may be the dummy monitoring method E05JBK supplied by the NAG Library.
E05..::..E05JB_OBJFUN
objfun must evaluate the objective function F x for a specified n-vector x.
E05..::..E05UC_CONFUN
confun must calculate the vector c x of nonlinear constraint functions and (optionally) its Jacobian (=∂c∂x) for a specified n-element vector x. If there are no nonlinear constraints (i.e., ncnln=0), confun will never be called by e05uc and confun may be the dummy method E04UDM. (E04UDM is included in the NAG Library.) If there are nonlinear constraints, the first call to confun will occur before the first call to objfun.
E05..::..E05UC_OBJFUN
objfun must calculate the objective function F x and (optionally) its gradient g x=∂F∂x for a specified n-vector x.
E05..::..E05UC_START
start must calculate the npts starting points to be used by the local optimizer. If you do not wish to write a method specific to your problem then E05UCZ may be used as the actual argument. E05UCZ is supplied in the NAG Library and uses the NAG quasi-random number generators to distribute starting points uniformly across the domain. It is affected by the value of repeat.
E05..::..E05US_CONFUN
confun must calculate the vector c x of nonlinear constraint functions and (optionally) its Jacobian (=∂c∂x) for a specified n-element vector x. If there are no nonlinear constraints (i.e., ncnln=0), confun will never be called by e05us and confun may be the dummy method E04UDM. (E04UDM is included in the NAG Library.) If there are nonlinear constraints, the first call to confun will occur before the first call to objfun.
E05..::..E05US_OBJFUN
objfun must calculate either the ith element of the vector f x=f 1 x,f 2 x,…,fm x T or all m elements of f x and (optionally) its Jacobian (=∂f∂x) for a specified n-element vector x.
E05..::..E05US_START
start must calculate the npts starting points to be used by the local optimizer. If you do not wish to write a method specific to your problem then E05UCZ may be used as the actual argument. E05UCZ is supplied in the NAG Library and uses the NAG quasi-random number generators to distribute starting points uniformly across the domain. It is affected by the value of repeat1.
F01..::..F01EF_F
The method f evaluates f zi at a number of points zi.
F01..::..F01FF_F
The method f evaluates f zi at a number of points zi.
G02..::..G02EF_MONFUN
You may define your own function or specify the NAG defined default function G02EFH.
G02..::..G02HB_UCV
ucv must return the value of the function u for a given value of its argument. The value of u must be non-negative.
G02..::..G02HD_CHI
If isigma>0, chi must return the value of the weight function χ for a given value of its argument. The value of χ must be non-negative.
G02..::..G02HD_PSI
psi must return the value of the weight function ψ for a given value of its argument.
G02..::..G02HF_PSI
psi must return the value of the ψ function for a given value of its argument.
G02..::..G02HF_PSP
psp must return the value of ψ′t=d dt ψ t for a given value of its argument.
G02..::..G02HL_UCV
ucv must return the values of the functions u and w and their derivatives for a given value of its argument.
G02..::..G02HM_UCV
ucv must return the values of the functions u and w for a given value of its argument.
H..::..H02CB_MONIT
monit may be used to print out intermediate output and to affect the course of the computation. Specifically, it allows you to specify a realistic value for the cut-off value (see [Description]) and to terminate the algorithm. If you do not require any intermediate output, have no estimate of the cut-off value and require an exhaustive tree search then monit may be the dummy method H02CBU.
H..::..H02CB_QPHESS
In general, you need not provide a version of qphess, because a ‘default’ method with name e04nfu is included in the Library. However, the algorithm of h02cb requires only the product of H or HT H and a vector x; and in some cases you may obtain increased efficiency by providing a version of qphess that avoids the need to define the elements of the matrices H or HT H explicitly. qphess is not referenced if the problem is of type FP or LP, in which case qphess may be the method e04nfu.
H..::..H02CE_MONIT
To provide feed-back on the progress of the branch and bound process. Additionally monit provides, via its parameter halt, the ability to terminate the process. (You might choose to do this when an integer solution is found, rather than search for a better solution.) If you do not require any intermediate output then monit may be the dummy method (H02CEY not in this release).
H..::..H02CE_QPHX
For QP problems, you must supply a version of qphx to compute the matrix product Hx. If H has rows and columns consisting entirely of zeros, it is most efficient to order the variables x=y z T so that
Hx=H 1000yz=H 1 y0,
where the nonlinear variables y appear first as shown. For LP problems, qphx will never be called by h02ce.
PrintManager..::..MessageLogger
Delegate type to use for messages.


Nag Utilities

[image]

NAG Library for .NET Release 2
Nag Utilities

NAG Utilities


Complex Structure

[image]

NAG Library for .NET Release 2
Complex Structure
Members See Also Send Feedback
Struct to denote a complex value as two doubles.

Syntax

C#
public struct Complex : IFormattable
Visual Basic
Public Structure Complex _
    Implements IFormattable
Visual C++
public value class Complex : IFormattable
F#
[<SealedAttribute>]
type Complex =
    struct
        interface IFormattable
    end

See Also

Complex Members
NagLibrary Namespace
NAG Library Overview


Complex Members

[image] [image]

NAG Library for .NET Release 2
Complex Members
Complex Structure Constructors Methods Fields See Also Send Feedback

The Complex type exposes the following members.

Constructors

Name | Description
Complex | Overloaded.

Methods

Name | Description
Abs | Absolute value
Parse | Parse a string literal such as "(1.0,1.0)" as a Complex
ToString | Overloaded.

Operators

Name | Description
Addition | Addition
Division | Overloaded.
Multiply | Overloaded.
Subtraction | Overloaded.
UnaryNegation | Unary Minus

Fields

Name | Description
im | Imaginary Part.
re | Real Part.

See Also

Complex Structure


Complex Constructor

[image] [image]

NAG Library for .NET Release 2
Complex Constructor
Complex Structure See Also Send Feedback

Overload List

Name | Description
Complex(Double) | Complex Constructor for Real Line
Complex(Int32) | Complex Constructor for Integers
Complex(Double, Double) | Complex Constructor

See Also

Complex Structure
Complex Members


Complex Constructor (Double)

[image]

NAG Library for .NET Release 2
Complex Constructor (Double)
Complex Structure See Also Send Feedback
Complex Constructor for Real Line

Syntax

C#
public Complex(
    double r
)
Visual Basic
Public Sub New ( _
    r As Double _
)
Visual C++
public:
Complex(
    double r
)
F#
new :
        r : float -> Complex

Parameters

r
Type: System..::..Double
Real part

See Also

Complex Structure
Complex Members
Complex Overload


Complex Constructor (Int32)

[image]

NAG Library for .NET Release 2
Complex Constructor (Int32)
Complex Structure See Also Send Feedback
Complex Constructor for Integers

Syntax

C#
public Complex(
    int i
)
Visual Basic
Public Sub New ( _
    i As Integer _
)
Visual C++
public:
Complex(
    int i
)
F#
new :
        i : int -> Complex

Parameters

i
Type: System..::..Int32
Real part

See Also

Complex Structure
Complex Members
Complex Overload


Complex Constructor (Double, Double)

[image]

NAG Library for .NET Release 2
Complex Constructor (Double, Double)
Complex Structure See Also Send Feedback
Complex Constructor

Syntax

C#
public Complex(
    double r,
    double i
)
Visual Basic
Public Sub New ( _
    r As Double, _
    i As Double _
)
Visual C++
public:
Complex(
    double r,
    double i
)
F#
new :
        r : float *
        i : float -> Complex

Parameters

r
Type: System..::..Double
Real part
i
Type: System..::..Double
Imaginary part

See Also

Complex Structure
Complex Members
Complex Overload


Complex Fields

[image] [image]

NAG Library for .NET Release 2
Complex Fields
Complex Structure See Also Send Feedback

The Complex type exposes the following members.

Fields

Name | Description
im | Imaginary Part.
re | Real Part.

See Also

Complex Structure


im Field

[image]

NAG Library for .NET Release 2
Complex..::im Field
Complex Structure See Also Send Feedback
Imaginary Part.

Syntax

C#
public double im
Visual Basic
Public im As Double
Visual C++
public:
double im
F#
val mutable im: float

See Also

Complex Structure
Complex Members


re Field

[image]

NAG Library for .NET Release 2
Complex..::re Field
Complex Structure See Also Send Feedback
Real Part.

Syntax

C#
public double re
Visual Basic
Public re As Double
Visual C++
public:
double re
F#
val mutable re: float

See Also

Complex Structure
Complex Members


Complex Methods

[image] [image]

NAG Library for .NET Release 2
Complex Methods
Complex Structure See Also Send Feedback

The Complex type exposes the following members.

Methods

Name | Description
Abs | Absolute value
Parse | Parse a string literal such as "(1.0,1.0)" as a Complex
ToString | Overloaded.

See Also

Complex Structure


Abs Method

[image]

NAG Library for .NET Release 2
Complex..::Abs Method
Complex Structure See Also Send Feedback
Absolute value

Syntax

C#
public static double Abs(
    Complex z
)
Visual Basic
Public Shared Function Abs ( _
    z As Complex _
) As Double
Visual C++
public:
static double Abs(
    Complex z
)
F#
static member Abs :
        z : Complex -> float

Parameters

z
Type: NagLibrary..::..Complex
Complex arg

Return Value

abs(z)

See Also

Complex Structure
Complex Members


Parse Method

[image]

NAG Library for .NET Release 2
Complex..::Parse Method
Complex Structure See Also Send Feedback
Parse a string literal such as "(1.0,1.0)" as a Complex

Syntax

C#
public static Complex Parse(
    string s
)
Visual Basic
Public Shared Function Parse ( _
    s As String _
) As Complex
Visual C++
public:
static Complex Parse(
    String^ s
)
F#
static member Parse :
        s : string -> Complex

Parameters

s
Type: System..::..String
String representing a Complex value

Return Value

result of parsing a string literal such as "(1.0,1.0)" as a Complex

See Also

Complex Structure
Complex Members


ToString Method

[image] [image]

NAG Library for .NET Release 2
Complex..::ToString Method
Complex Structure See Also Send Feedback

Overload List

Name | Description
ToString()()()() | Express a Complex as a string literal. (Overrides ValueType..::..ToString()()()().)
ToString(String) | Express a Complex as a string literal.
ToString(String, IFormatProvider) | Express a Complex as a string literal.

See Also

Complex Structure
Complex Members


ToString Method

[image]

NAG Library for .NET Release 2
Complex..::ToString Method
Complex Structure See Also Send Feedback
Express a Complex as a string literal.

Syntax

C#
public override string ToString()
Visual Basic
Public Overrides Function ToString As String
Visual C++
public:
virtual String^ ToString() override
F#
abstract ToString : unit -> string
override ToString : unit -> string

Return Value

Complex as a string literal.

See Also

Complex Structure
Complex Members
ToString Overload


ToString Method (String)

[image]

NAG Library for .NET Release 2
Complex..::ToString Method (String)
Complex Structure See Also Send Feedback
Express a Complex as a string literal.

Syntax

C#
public string ToString(
    string format
)
Visual Basic
Public Function ToString ( _
    format As String _
) As String
Visual C++
public:
String^ ToString(
    String^ format
)
F#
member ToString :
        format : string -> string

Parameters

format
Type: System..::..String
format string (passed to double)

Return Value

Complex as a string literal.

See Also

Complex Structure
Complex Members
ToString Overload


ToString Method (String, IFormatProvider)

[image]

NAG Library for .NET Release 2
Complex..::ToString Method (String, IFormatProvider)
Complex Structure See Also Send Feedback
Express a Complex as a string literal.

Syntax

C#
public string ToString(
    string format,
    IFormatProvider provider
)
Visual Basic
Public Function ToString ( _
    format As String, _
    provider As IFormatProvider _
) As String
Visual C++
public:
virtual String^ ToString(
    String^ format,
    IFormatProvider^ provider
) sealed
F#
abstract ToString :
        format : string *
        provider : IFormatProvider -> string
override ToString :
        format : string *
        provider : IFormatProvider -> string

Parameters

format
Type: System..::..String
format string (passed to double)
provider
Type: System..::..IFormatProvider
provider (passed to double)

Return Value

Complex as a string literal.

Implements

IFormattable..::..ToString(String, IFormatProvider)

See Also

Complex Structure
Complex Members
ToString Overload


Complex Operators

[image] [image]

NAG Library for .NET Release 2
Complex Operators
Complex Structure See Also Send Feedback

The Complex type exposes the following members.

Operators

Name | Description
Addition | Addition
Division | Overloaded.
Multiply | Overloaded.
Subtraction | Overloaded.
UnaryNegation | Unary Minus

See Also

Complex Structure


Addition Operator

[image]

NAG Library for .NET Release 2
Complex..::Addition Operator
Complex Structure See Also Send Feedback
Addition

Syntax

C#
public static Complex operator +(
    Complex z1,
    Complex z2
)
Visual Basic
Public Shared Operator + ( _
    z1 As Complex, _
    z2 As Complex _
) As Complex
Visual C++
public:
static Complex operator +(
    Complex z1,
    Complex z2
)
F#
static let inline (+)
        z1 : Complex *
        z2 : Complex  : Complex

Parameters

z1
Type: NagLibrary..::..Complex
Complex arg
z2
Type: NagLibrary..::..Complex
Complex arg

Return Value

z1 + z2

See Also

Complex Structure
Complex Members


Division Method

[image] [image]

NAG Library for .NET Release 2
Complex..::Division Method
Complex Structure See Also Send Feedback

Overload List

Name | Description
Division(Double, Complex) | Division
Division(Complex, Complex) | Division
Division(Complex, Double) | Division

See Also

Complex Structure
Complex Members


Division Operator (Double, Complex)

[image]

NAG Library for .NET Release 2
Complex..::Division Operator (Double, Complex)
Complex Structure See Also Send Feedback
Division

Syntax

C#
public static Complex operator /(
    double d1,
    Complex z2
)
Visual Basic
Public Shared Operator / ( _
    d1 As Double, _
    z2 As Complex _
) As Complex
Visual C++
public:
static Complex operator /(
    double d1,
    Complex z2
)
F#
static let inline (/)
        d1 : float *
        z2 : Complex  : Complex

Parameters

d1
Type: System..::..Double
Real arg
z2
Type: NagLibrary..::..Complex
Complex arg

Return Value

d1 / z2

See Also

Complex Structure
Complex Members
Division Overload


Division Operator (Complex, Complex)

[image]

NAG Library for .NET Release 2
Complex..::Division Operator (Complex, Complex)
Complex Structure See Also Send Feedback
Division

Syntax

C#
public static Complex operator /(
    Complex z1,
    Complex z2
)
Visual Basic
Public Shared Operator / ( _
    z1 As Complex, _
    z2 As Complex _
) As Complex
Visual C++
public:
static Complex operator /(
    Complex z1,
    Complex z2
)
F#
static let inline (/)
        z1 : Complex *
        z2 : Complex  : Complex

Parameters

z1
Type: NagLibrary..::..Complex
Complex arg
z2
Type: NagLibrary..::..Complex
Complex arg

Return Value

z1 / z2

See Also

Complex Structure
Complex Members
Division Overload


Division Operator (Complex, Double)

[image]

NAG Library for .NET Release 2
Complex..::Division Operator (Complex, Double)
Complex Structure See Also Send Feedback
Division

Syntax

C#
public static Complex operator /(
    Complex z1,
    double r2
)
Visual Basic
Public Shared Operator / ( _
    z1 As Complex, _
    r2 As Double _
) As Complex
Visual C++
public:
static Complex operator /(
    Complex z1,
    double r2
)
F#
static let inline (/)
        z1 : Complex *
        r2 : float  : Complex

Parameters

z1
Type: NagLibrary..::..Complex
Complex arg
r2
Type: System..::..Double
Double arg

Return Value

z1 / z2

See Also

Complex Structure
Complex Members
Division Overload


Multiply Method

[image] [image]

NAG Library for .NET Release 2
Complex..::Multiply Method
Complex Structure See Also Send Feedback

Overload List

Name | Description
Multiply(Double, Complex) | Multiplication
Multiply(Complex, Complex) | Multiplcation
Multiply(Complex, Double) | Multiplication

See Also

Complex Structure
Complex Members


Multiply Operator (Double, Complex)

[image]

NAG Library for .NET Release 2
Complex..::Multiply Operator (Double, Complex)
Complex Structure See Also Send Feedback
Multiplication

Syntax

C#
public static Complex operator *(
    double r1,
    Complex z2
)
Visual Basic
Public Shared Operator * ( _
    r1 As Double, _
    z2 As Complex _
) As Complex
Visual C++
public:
static Complex operator *(
    double r1,
    Complex z2
)
F#
static let inline (*)
        r1 : float *
        z2 : Complex  : Complex

Parameters

r1
Type: System..::..Double
Double arg
z2
Type: NagLibrary..::..Complex
Complex arg

Return Value

r1 * z2

See Also

Complex Structure
Complex Members
Multiply Overload


Multiply Operator (Complex, Complex)

[image]

NAG Library for .NET Release 2
Complex..::Multiply Operator (Complex, Complex)
Complex Structure See Also Send Feedback
Multiplcation

Syntax

C#
public static Complex operator *(
    Complex z1,
    Complex z2
)
Visual Basic
Public Shared Operator * ( _
    z1 As Complex, _
    z2 As Complex _
) As Complex
Visual C++
public:
static Complex operator *(
    Complex z1,
    Complex z2
)
F#
static let inline (*)
        z1 : Complex *
        z2 : Complex  : Complex

Parameters

z1
Type: NagLibrary..::..Complex
Complex arg
z2
Type: NagLibrary..::..Complex
Complex arg

Return Value

z1 * z2

See Also

Complex Structure
Complex Members
Multiply Overload


Multiply Operator (Complex, Double)

[image]

NAG Library for .NET Release 2
Complex..::Multiply Operator (Complex, Double)
Complex Structure See Also Send Feedback
Multiplication

Syntax

C#
public static Complex operator *(
    Complex z1,
    double r2
)
Visual Basic
Public Shared Operator * ( _
    z1 As Complex, _
    r2 As Double _
) As Complex
Visual C++
public:
static Complex operator *(
    Complex z1,
    double r2
)
F#
static let inline (*)
        z1 : Complex *
        r2 : float  : Complex

Parameters

z1
Type: NagLibrary..::..Complex
Complex arg
r2
Type: System..::..Double
Double arg

Return Value

z1 * r2

See Also

Complex Structure
Complex Members
Multiply Overload


Subtraction Method

[image] [image]

NAG Library for .NET Release 2
Complex..::Subtraction Method
Complex Structure See Also Send Feedback

Overload List

Name | Description
Subtraction(Complex, Complex) | Subtraction
Subtraction(Complex, Double) | Subtraction

See Also

Complex Structure
Complex Members


Subtraction Operator (Complex, Complex)

[image]

NAG Library for .NET Release 2
Complex..::Subtraction Operator (Complex, Complex)
Complex Structure See Also Send Feedback
Subtraction

Syntax

C#
public static Complex operator -(
    Complex z1,
    Complex z2
)
Visual Basic
Public Shared Operator - ( _
    z1 As Complex, _
    z2 As Complex _
) As Complex
Visual C++
public:
static Complex operator -(
    Complex z1,
    Complex z2
)
F#
static let inline (-)
        z1 : Complex *
        z2 : Complex  : Complex

Parameters

z1
Type: NagLibrary..::..Complex
Complex arg
z2
Type: NagLibrary..::..Complex
Complex arg

Return Value

z1 - z2

See Also

Complex Structure
Complex Members
Subtraction Overload


Subtraction Operator (Complex, Double)

[image]

NAG Library for .NET Release 2
Complex..::Subtraction Operator (Complex, Double)
Complex Structure See Also Send Feedback
Subtraction

Syntax

C#
public static Complex operator -(
    Complex z1,
    double d2
)
Visual Basic
Public Shared Operator - ( _
    z1 As Complex, _
    d2 As Double _
) As Complex
Visual C++
public:
static Complex operator -(
    Complex z1,
    double d2
)
F#
static let inline (-)
        z1 : Complex *
        d2 : float  : Complex

Parameters

z1
Type: NagLibrary..::..Complex
Complex arg
d2
Type: System..::..Double
Double arg

Return Value

z1 - d2

See Also

Complex Structure
Complex Members
Subtraction Overload


UnaryNegation Operator

[image]

NAG Library for .NET Release 2
Complex..::UnaryNegation Operator
Complex Structure See Also Send Feedback
Unary Minus

Syntax

C#
public static Complex operator -(
    Complex z1
)
Visual Basic
Public Shared Operator - ( _
    z1 As Complex _
) As Complex
Visual C++
public:
static Complex operator -(
    Complex z1
)
F#
static let inline (-)
        z1 : Complex  : Complex

Parameters

z1
Type: NagLibrary..::..Complex
Complex arg

Return Value

-z1

See Also

Complex Structure
Complex Members


DataReader Class

[image]

NAG Library for .NET Release 2
DataReader Class
Members See Also Send Feedback
DataReader Class, IO stream for reading NAG Data files

Syntax

C#
public class DataReader
Visual Basic
Public Class DataReader
Visual C++
public ref class DataReader
F#
type DataReader =  class end

Inheritance Hierarchy

System..::..Object
NagLibrary..::..DataReader

See Also

DataReader Members


DataReader Members

[image] [image]

NAG Library for .NET Release 2
DataReader Members
DataReader Class Constructors Methods See Also Send Feedback

The DataReader type exposes the following members.

Constructors

Name | Description
DataReader | Construct DataReader from filename string

Methods

Name | Description
Next | Iterator to return the next value
ReadLine | ReadLine, from StreamReader
Reset | Reset the value parser to the next line

See Also

DataReader Class


DataReader Constructor

[image]

NAG Library for .NET Release 2
DataReader Constructor
DataReader Class See Also Send Feedback
Construct DataReader from filename string

Syntax

C#
public DataReader(
    string filename
)
Visual Basic
Public Sub New ( _
    filename As String _
)
Visual C++
public:
DataReader(
    String^ filename
)
F#
new :
        filename : string -> DataReader

Parameters

filename
Type: System..::..String
Filename

See Also

DataReader Class
DataReader Members


DataReader Methods

[image] [image]

NAG Library for .NET Release 2
DataReader Methods
DataReader Class See Also Send Feedback

The DataReader type exposes the following members.

Methods

Name | Description
Next | Iterator to return the next value
ReadLine | ReadLine, from StreamReader
Reset | Reset the value parser to the next line

See Also

DataReader Class


Next Method

[image]

NAG Library for .NET Release 2
DataReader..::Next Method
DataReader Class See Also Send Feedback
Iterator to return the next value

Syntax

C#
public string Next()
Visual Basic
Public Function Next As String
Visual C++
public:
String^ Next()
F#
member Next : unit -> string

Return Value

the next value

See Also

DataReader Class
DataReader Members


ReadLine Method

[image]

NAG Library for .NET Release 2
DataReader..::ReadLine Method
DataReader Class See Also Send Feedback
ReadLine, from StreamReader

Syntax

C#
public string ReadLine()
Visual Basic
Public Function ReadLine As String
Visual C++
public:
String^ ReadLine()
F#
member ReadLine : unit -> string

Return Value

Line from the stream, as a string.

See Also

DataReader Class
DataReader Members


Reset Method

[image]

NAG Library for .NET Release 2
DataReader..::Reset Method
DataReader Class See Also Send Feedback
Reset the value parser to the next line

Syntax

C#
public void Reset()
Visual Basic
Public Sub Reset
Visual C++
public:
void Reset()
F#
member Reset : unit -> unit

See Also

DataReader Class
DataReader Members


PrintManager Class

[image]

NAG Library for .NET Release 2
PrintManager Class
Members See Also Send Feedback
Utility class to control the output of error messages and monitoring information. See the examples in the Library Introduction.

Syntax

C#
public static class PrintManager
Visual Basic
Public NotInheritable Class PrintManager
Visual C++
public ref class PrintManager abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type PrintManager =  class end

Inheritance Hierarchy

System..::..Object
NagLibrary..::..PrintManager

See Also

PrintManager Members


PrintManager Members

[image] [image]

NAG Library for .NET Release 2
PrintManager Members
PrintManager Class Methods Properties See Also Send Feedback

The PrintManager type exposes the following members.

Methods

Name | Description
debug | Turn on/off debugging output from internal Numerical library.

Properties

Name | Description
Message | Property holding a delegate to use for monitoring messages (defaults to Console.WriteLine).
Warning | Property holding a delegate to use for error and warning messages (defaults to Console.WriteLine).

See Also

PrintManager Class


PrintManager Methods

[image] [image]

NAG Library for .NET Release 2
PrintManager Methods
PrintManager Class See Also Send Feedback

The PrintManager type exposes the following members.

Methods

Name | Description
debug | Turn on/off debugging output from internal Numerical library.

See Also

PrintManager Class


debug Method

[image]

NAG Library for .NET Release 2
PrintManager..::debug Method
PrintManager Class See Also Send Feedback
Turn on/off debugging output from internal Numerical library.

Syntax

C#
public static void debug(
    int printlevel
)
Visual Basic
Public Shared Sub debug ( _
    printlevel As Integer _
)
Visual C++
public:
static void debug(
    int printlevel
)
F#
static member debug :
        printlevel : int -> unit

Parameters

printlevel
Type: System..::..Int32
A value of 0 turns off debugging output, positive integers enable printing.

See Also

PrintManager Class
PrintManager Members


PrintManager Properties

[image] [image]

NAG Library for .NET Release 2
PrintManager Properties
PrintManager Class See Also Send Feedback

The PrintManager type exposes the following members.

Properties

Name | Description
Message | Property holding a delegate to use for monitoring messages (defaults to Console.WriteLine).
Warning | Property holding a delegate to use for error and warning messages (defaults to Console.WriteLine).

See Also

PrintManager Class


Message Property

[image]

NAG Library for .NET Release 2
PrintManager..::Message Property
PrintManager Class See Also Send Feedback
Property holding a delegate to use for monitoring messages (defaults to Console.WriteLine).

Syntax

C#
public static PrintManager..::..MessageLogger Message { get; set; }
Visual Basic
Public Shared Property Message As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
static property PrintManager..::..MessageLogger^ Message {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
static member Message : PrintManager..::..MessageLogger with get, set

See Also

PrintManager Class
PrintManager Members


Warning Property

[image]

NAG Library for .NET Release 2
PrintManager..::Warning Property
PrintManager Class See Also Send Feedback
Property holding a delegate to use for error and warning messages (defaults to Console.WriteLine).

Syntax

C#
public static PrintManager..::..MessageLogger Warning { get; set; }
Visual Basic
Public Shared Property Warning As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
static property PrintManager..::..MessageLogger^ Warning {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
static member Warning : PrintManager..::..MessageLogger with get, set

See Also

PrintManager Class
PrintManager Members


A00 Class

[image]

NAG Library for .NET Release 2
A00 Class
Members See Also Send Feedback
The methods in this chapter provide information about the NAG Library.
a00ac enables you to check if a valid key is available for the library licence management system.
Information about the precise implementation of the NAG Library in use will be needed when communicating with the NAG Response Centre (see the Library Overview).

Syntax

C#
public static class A00
Visual Basic
Public NotInheritable Class A00
Visual C++
public ref class A00 abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type A00 =  class end

Background to the Problems

None.

Recommendations on Choice and Use of Available Methods

None.

Inheritance Hierarchy

System..::..Object
NagLibrary..::..A00

See Also

A00 Members


A00 Members

[image] [image]

NAG Library for .NET Release 2
A00 Members
A00 Class Methods See Also Send Feedback

The A00 type exposes the following members.

Methods

Name | Description
a00aa | a00aa prints information about the version of the NAG Library in use.
a00ac | a00ac provides a convenient means of checking the availability of a valid licence key on licence-managed implementations before starting computations that will use NAG Library methods. In particular, the use of this function is highly recommended in programs that call NAG Library methods within multithreaded sections (e.g., OpenMP parallel regions). The function need only be called once, before the start of the first multithreaded section.

See Also

A00 Class


A00 Methods

[image] [image]

NAG Library for .NET Release 2
A00 Methods
A00 Class See Also Send Feedback

The A00 type exposes the following members.

Methods

Name | Description
a00aa | a00aa prints information about the version of the NAG Library in use.
a00ac | a00ac provides a convenient means of checking the availability of a valid licence key on licence-managed implementations before starting computations that will use NAG Library methods. In particular, the use of this function is highly recommended in programs that call NAG Library methods within multithreaded sections (e.g., OpenMP parallel regions). The function need only be called once, before the start of the first multithreaded section.

See Also

A00 Class


a00aa Method

[image]

NAG Library for .NET Release 2
A00..::a00aa Method
A00 Class See Also Send Feedback
a00aa prints information about the version of the NAG Library in use.

Syntax

C#
public static void a00aa()
Visual Basic
Public Shared Sub a00aa
Visual C++
public:
static void a00aa()
F#
static member a00aa : unit -> unit

Description

The NAG Library is available for use on a number of different computer systems. For each distinct system an implementation of the library is prepared. This includes tested compiled libraries and any necessary system-specific support material. a00aa may be called to print the implementation details and Mark (i.e., maintenance level) of the NAG Library implementation that is being used.

References

None.

Error Indicators and Warnings

None.

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

This example makes a call of a00aa sending output to the current advisory message unit.

Example program (C#): a00aae.cs

Example program results: a00aae.r

See Also

A00 Class
A00 Members


a00ac Method

[image]

NAG Library for .NET Release 2
A00..::a00ac Method
A00 Class See Also Send Feedback
a00ac provides a convenient means of checking the availability of a valid licence key on licence-managed implementations before starting computations that will use NAG Library methods. In particular, the use of this function is highly recommended in programs that call NAG Library methods within multithreaded sections (e.g., OpenMP parallel regions). The function need only be called once, before the start of the first multithreaded section.

Syntax

C#
public static bool a00ac()
Visual Basic
Public Shared Function a00ac As Boolean
Visual C++
public:
static bool a00ac()
F#
static member a00ac : unit -> bool

Return Value

a00ac provides a convenient means of checking the availability of a valid licence key on licence-managed implementations before starting computations that will use NAG Library methods. In particular, the use of this function is highly recommended in programs that call NAG Library methods within multithreaded sections (e.g., OpenMP parallel regions). The function need only be called once, before the start of the first multithreaded section.

Description

a00ac returns the logical value true if a valid licence is found, otherwise false is returned.
On non licence-managed implementations, true is always returned.

References

None.

Error Indicators and Warnings

None.

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

This example prints an appropriate message depending upon the value returned by a00ac.

Example program (C#): a00ace.cs

Example program results: a00ace.r

See Also

A00 Class
A00 Members


C05 Class

[image]

NAG Library for .NET Release 2
C05 Class
Members See Also Send Feedback
This chapter is concerned with the calculation of zeros of continuous functions of one or more variables. The majority of problems considered are for real-valued functions of real variables, in which case complex equations must be expressed in terms of the equivalent larger system of real equations.

Syntax

C#
public static class C05
Visual Basic
Public NotInheritable Class C05
Visual C++
public ref class C05 abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type C05 =  class end

Background to the Problems

The chapter divides naturally into two parts.

A Single Equation

The first deals with the real zeros of a real function of a single variable f x.
There are three methods with simple calling sequences. The first assumes that you can determine an initial interval a,b within which the desired zero lies, (that is, where f a×f b<0), and outside which all other zeros lie. The method then systematically subdivides the interval to produce a final interval containing the zero. This final interval has a length bounded by your specified error requirements; the end of the interval where the function has smallest magnitude is returned as the zero. This method is guaranteed to converge to a simple zero of the function. (Here we define a simple zero as a zero corresponding to a sign-change of the function; none of the available methods are capable of making any finer distinction.) However, as with the other methods described below, a non-simple zero might be determined and it is left to you to check for this. The algorithm used is due to Brent (1973).
The two other methods are both designed for the case where you are unable to specify an interval containing the simple zero. One starts from an initial point and performs a search for an interval containing a simple zero. If such an interval is computed then the method described above is used next to determine the zero accurately. The other method uses a ‘continuation’ method based on a secant iteration. A sequence of subproblems is solved; the first of these is trivial and the last is the actual problem of finding a zero of f x. The intermediate problems employ the solutions of earlier problems to provide initial guesses for the secant iterations used to calculate their solutions.
Three other methods are also supplied. They employ reverse communication and use the same core algorithms as the methods described above.
Finally, two methods are provided to return values of Lambert's W function (sometimes known as the ‘product log’ or ‘Omega’ function), which is the inverse function of
f w=w ew  for  w∈C;
that is, if Lambert's W function W x=a for x,a∈C, then a is a zero of the function F w=w ew-x. One method uses the iterative method described in Barry et al. (1995) to return values from the real branches of W (restricting x,a∈R). The second method enforces no such restriction, and uses the approach described in Corless et al. (1996).

Systems of Equations

The methods in the second part of this chapter are designed to solve a set of nonlinear equations in n unknowns
fi x=0,  i=1,2,…,n,  x=x 1,x 2,…,xn T, (1)
where T stands for transpose.
It is assumed that the functions are continuous and differentiable so that the matrix of first partial derivatives of the functions, the Jacobian matrix J ij x=∂fi∂xj evaluated at the point x, exists, though it may not be possible to calculate it directly.
The functions fi must be independent, otherwise there will be an infinity of solutions and the methods will fail. However, even when the functions are independent the solutions may not be unique. Since the methods are iterative, an initial guess at the solution has to be supplied, and the solution located will usually be the one closest to this initial guess.

Recommendations on Choice and Use of Available Methods

Zeros of Functions of One Variable

The methods can be divided into two classes. There are three methods (c05av, c05ax and c05az) all written in reverse communication form and three (c05au, c05aw and c05ay) written in direct communication form. The direct communication methods are designed for inexperienced users and, in particular, for solving problems where the function f x whose zero is to be calculated, can be coded as a user-supplied (sub)program. These methods find the zero by using the same core algorithms as the reverse communication methods. Experienced users are recommended to use the reverse communication methods directly as they permit you more control of the calculation. Indeed, if the zero-finding process is embedded in a much larger program then the reverse communication methods should always be used.
The recommendation as to which method should be used depends mainly on whether you can supply an interval a,b containing the zero; that is, where f a×f b<0. If the interval can be supplied, then c05ay (or, in reverse communication, c05az) should be used, in general. This recommendation should be qualified in the case when the only interval which can be supplied is very long relative to your error requirements and you can also supply a good approximation to the zero. In this case c05aw (or, in reverse communication, c05ax) may prove more efficient (though these latter methods will not provide the error bound available from c05az).
If an interval containing the zero cannot be supplied then you must choose between c05au (or, in reverse communication, c05av followed by c05az) and c05aw (or, in reverse communication, c05ax). c05au first determines an interval containing the zero, and then proceeds as in c05ay; it is particularly recommended when you do not have a good initial approximation to the zero. If a good initial approximation to the zero is available then c05aw is to be preferred. Since neither of these latter methods has guaranteed convergence to the zero, you are recommended to experiment with both in case of difficulty.

Solution of Sets of Nonlinear Equations

The solution of a set of nonlinear equations
fi x 1,x 2,…,xn=0,  i=1,2,…,n (2)
can be regarded as a special case of the problem of finding a minimum of a sum of squares
s x=∑i=1 m fi x 1,x 2,…,xn 2,  m≥n. (3)
So the methods in E04 class are relevant as well as the special nonlinear equations methods.
The methods for solving a set of nonlinear equations can also be divided into classes. There are five methods ( c05qb c05qc (C05QSF not in this release) c05rb c05rc) all written in direct communication form and two (c05qd and c05rd) written in reverse communication form. The direct communication methods are designed for inexperienced users and, in particular, these methods require the fi (and possibly their derivatives) to be calculated in user-supplied delegates. These should be set up carefully so the Library methods can work as efficiently as possible. Experienced users are recommended to use the reverse communication methods as they permit you more control of the calculation. Indeed, if the zero-finding process is embedded in a much larger program then the reverse communication methods should always be used.
The main decision you have to make is whether to supply the derivatives ∂fi∂xj. It is advisable to do so if possible, since the results obtained by algorithms which use derivatives are generally more reliable than those obtained by algorithms which do not use derivatives.
c05rb, c05rc and c05rd require you to provide the derivatives, whilst c05qb c05qc c05qd (C05QSF not in this release) do not. c05qb c05rb (C05QSF not in this release) are easy-to-use methods; greater flexibility may be obtained using c05qc and c05rc (or, in reverse communication, c05qd and c05rd), but these have longer parameter lists.
(C05QSF not in this release) is an easy-to-use method specially adapted for sparse problems, that is, problems where each function depends on a small subset of the n variables so that the Jacobian matrix has many zeros. It employs sparse linear algebra methods and consequently is expected to take significantly less time to complete than the other methods, especially if n is large.
c05zd is provided for use in conjunction with c05rb, c05rc and c05rd to check the user-supplied derivatives for consistency with the functions themselves. You are strongly advised to make use of this method whenever c05rb, c05rc or c05rd is used.
Firstly, the calculation of the functions and their derivatives should be ordered so that cancellation errors are avoided. This is particularly important in a method that uses these quantities to build up estimates of higher derivatives.
Secondly, scaling of the variables has a considerable effect on the efficiency of a method. The problem should be designed so that the elements of x are of similar magnitude. The same comment applies to the functions, i.e., all the fi should be of comparable size.
The accuracy is usually determined by the accuracy parameters of the methods, but the following points may be useful.
(i) | Greater accuracy in the solution may be requested by choosing smaller input values for the accuracy parameters. However, if unreasonable accuracy is demanded, rounding errors may become important and cause a failure.
(ii) | Some idea of the accuracies of the xi may be obtained by monitoring the progress of the method to see how many figures remain unchanged during the last few iterations.
(iii) An approximation to the error in the solution x is given by e where e is the solution to the set of linear equations
J x e=-f x
where f x=f 1 x,f 2 x,…,fn x T.
Note that the QR decomposition of J is available from c05qc and c05rc (or, in reverse communication, c05qd and c05rd) so that
Re=-QT f
and QT f is also provided by these methods.
(iv) If the functions fi x are changed by small amounts εi, for i=1,2,…,n, then the corresponding change in the solution x is given approximately by σ, where σ is the solution of the set of linear equations
J x σ=-ε.
Thus one can estimate the sensitivity of x to any uncertainties in the specification of fi x, for i=1,2,…,n. As noted above, the sophisticated methods c05qc and c05rc (or, in reverse communication, c05qd and c05rd) provide the QR decomposition of J.

Values of Lambert's W function

If you require purely-real values of W, these will be evaluated marginally more efficiently by (C05BAF not in this release) than (C05BBF not in this release) owing to the differing iterative procedures used by each method.

Decision Trees

Tree 1: Functions of One Variable

Is reverse communication required? | _ yes | Is there available an interval a,b containing a simple zero, and no others? | _ yes | c05az
| |  | no | |
| |  | Is a good approximation to the zero available? | _ yes | c05ax
| |  | no | |
| |  | c05av followed by c05az
no | |
Do you wish to compute the values of Lambert's W function? | _ yes | do you require values from only the real branches? | _ yes | (C05BAF not in this release)
| |  | no | |
| |  | (C05BBF not in this release)
no | |
Is there available an interval a,b containing a simple zero, and no others? | _ yes | c05ay
no | |
Is a good approximation to the zero available? | _ yes | c05aw
no | |
c05au

Tree 2: Functions of several variables

Is the Jacobian matrix sparse? | _ yes | (C05QSF not in this release)
no | |
Is reverse communication required? | _ yes | Is the Jacobian matrix available? | _ yes | c05rd and c05zd
| |  | no | |
| |  | c05qd
no | |
Is the Jacobian matrix available? | _ yes | Is flexibility required? | _ yes | c05rc and c05zd
| |  | no | |
| |  | c05rb and c05zd
no | |
Is flexibility required? | _ yes | c05qc
no | |
c05qb

References

Barry D J, Culligan–Hensley P J, and Barry S J (1995) Real values of the W-function ACM Trans. Math. Software 21(2) 161–171
Brent R P (1973) Algorithms for Minimization Without Derivatives Prentice–Hall
Corless R M, Gonnet G H, Hare D E G, Jeffrey D J and Knuth D E (1996) On the Lambert W function Advances in Comp. Math. 3 329–359
Gill P E and Murray W (1976) Algorithms for the solution of the nonlinear least squares problem Report NAC 71 National Physical Laboratory
Moré J J, Garbow B S and Hillstrom K E (1980) User guide for MINPACK-1 Technical Report ANL-80-74 Argonne National Laboratory
Ortega J M and Rheinboldt W C (1970) Iterative Solution of Nonlinear Equations in Several Variables Academic Press
Rabinowitz P (1970) Numerical Methods for Nonlinear Algebraic Equations Gordon and Breach

Inheritance Hierarchy

System..::..Object
NagLibrary..::..C05

See Also

C05 Members


C05 Members

[image] [image]

NAG Library for .NET Release 2
C05 Members
C05 Class Methods See Also Send Feedback

The C05 type exposes the following members.

Methods

Name | Description
c05au | c05au locates a simple zero of a continuous function from a given starting value. It uses a binary search to locate an interval containing a zero of the function, then Brent's method, which is a combination of nonlinear interpolation, linear extrapolation and bisection, to locate the zero precisely.
c05av | c05av attempts to locate an interval containing a simple zero of a continuous function using a binary search. It uses reverse communication for evaluating the function.
c05aw | c05aw attempts to locate a zero of a continuous function using a continuation method based on a secant iteration.
c05ax | c05ax attempts to locate a zero of a continuous function using a continuation method based on a secant iteration. It uses reverse communication for evaluating the function.
c05ay | c05ay locates a simple zero of a continuous function in a given interval using Brent's method, which is a combination of nonlinear interpolation, linear extrapolation and bisection.
c05az | c05az locates a simple zero of a continuous function in a given interval by using Brent's method, which is a combination of nonlinear interpolation, linear extrapolation and bisection. It uses reverse communication for evaluating the function.
c05qb | c05qb is an easy-to-use method that finds a solution of a system of nonlinear equations by a modification of the Powell hybrid method.
c05qc | c05qc is a comprehensive method that finds a solution of a system of nonlinear equations by a modification of the Powell hybrid method.
c05qd | c05qd is a comprehensive reverse communication method that finds a solution of a system of nonlinear equations by a modification of the Powell hybrid method.
c05rb | c05rb is an easy-to-use method that finds a solution of a system of nonlinear equations by a modification of the Powell hybrid method. You must provide the Jacobian.
c05rc | c05rc is a comprehensive method that finds a solution of a system of nonlinear equations by a modification of the Powell hybrid method. You must provide the Jacobian.
c05rd | c05rd is a comprehensive reverse communication method that finds a solution of a system of nonlinear equations by a modification of the Powell hybrid method. You must provide the Jacobian.
c05zd | c05zd checks the user-supplied gradients of a set of nonlinear functions in several variables, for consistency with the functions themselves. The method must be called twice.

See Also

C05 Class


C05 Delegates

[image]

NAG Library for .NET Release 2
C05 Delegates

C05 Delegate Types

  • C05.C05AU_F Delegate
  • C05.C05AW_F Delegate
  • C05.C05AY_F Delegate
  • C05.C05QB_FCN Delegate
  • C05.C05QC_FCN Delegate
  • C05.C05RB_FCN Delegate
  • C05.C05RC_FCN Delegate


C05.C05AU_F Delegate

[image]

NAG Library for .NET Release 2
C05..::..C05AU_F Delegate
C05 Class See Also Send Feedback
f must evaluate the function f whose zero is to be determined.

Syntax

C#
public delegate double C05AU_F(
    double x
)
Visual Basic
Public Delegate Function C05AU_F ( _
    x As Double _
) As Double
Visual C++
public delegate double C05AU_F(
    double x
)
F#
type C05AU_F =
    delegate of
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the point at which the function must be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
c05au


C05.C05AW_F Delegate

[image]

NAG Library for .NET Release 2
C05..::..C05AW_F Delegate
C05 Class See Also Send Feedback
f must evaluate the function f whose zero is to be determined.

Syntax

C#
public delegate double C05AW_F(
    double x
)
Visual Basic
Public Delegate Function C05AW_F ( _
    x As Double _
) As Double
Visual C++
public delegate double C05AW_F(
    double x
)
F#
type C05AW_F =
    delegate of
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the point at which the function must be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
c05aw


C05.C05AY_F Delegate

[image]

NAG Library for .NET Release 2
C05..::..C05AY_F Delegate
C05 Class See Also Send Feedback
f must evaluate the function f whose zero is to be determined.

Syntax

C#
public delegate double C05AY_F(
    double x
)
Visual Basic
Public Delegate Function C05AY_F ( _
    x As Double _
) As Double
Visual C++
public delegate double C05AY_F(
    double x
)
F#
type C05AY_F =
    delegate of
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the point at which the function must be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
c05ay


C05.C05QB_FCN Delegate

[image]

NAG Library for .NET Release 2
C05..::..C05QB_FCN Delegate
C05 Class See Also Send Feedback
fcn must return the values of the functions fi at a point x.

Syntax

C#
public delegate void C05QB_FCN(
    int n,
    double[] x,
    double[] fvec,
    ref int iflag
)
Visual Basic
Public Delegate Sub C05QB_FCN ( _
    n As Integer, _
    x As Double(), _
    fvec As Double(), _
    ByRef iflag As Integer _
)
Visual C++
public delegate void C05QB_FCN(
    int n,
    array<double>^ x,
    array<double>^ fvec,
    int% iflag
)
F#
type C05QB_FCN =
    delegate of
        n : int *
        x : float[] *
        fvec : float[] *
        iflag : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of equations.
x
Type: array< System..::..Double >[]()[][]
On entry: the components of the point x at which the functions must be evaluated.
fvec
Type: array< System..::..Double >[]()[][]
On exit: the function values fi x (unless iflag is set to a negative value by fcn).
iflag
Type: System..::..Int32 %
On entry: iflag>0.
On exit: in general, iflag should not be reset by fcn. If, however, you wish to terminate execution (perhaps because some illegal point x has been reached), then iflag should be set to a negative integer.

See Also

NagLibrary Namespace
NAG Library Overview
c05qb


C05.C05QC_FCN Delegate

[image]

NAG Library for .NET Release 2
C05..::..C05QC_FCN Delegate
C05 Class See Also Send Feedback
fcn must return the values of the functions fi at a point x, unless iflag=0 on entry to c05qc.

Syntax

C#
public delegate void C05QC_FCN(
    int n,
    double[] x,
    double[] fvec,
    ref int iflag
)
Visual Basic
Public Delegate Sub C05QC_FCN ( _
    n As Integer, _
    x As Double(), _
    fvec As Double(), _
    ByRef iflag As Integer _
)
Visual C++
public delegate void C05QC_FCN(
    int n,
    array<double>^ x,
    array<double>^ fvec,
    int% iflag
)
F#
type C05QC_FCN =
    delegate of
        n : int *
        x : float[] *
        fvec : float[] *
        iflag : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of equations.
x
Type: array< System..::..Double >[]()[][]
On entry: the components of the point x at which the functions must be evaluated.
fvec
Type: array< System..::..Double >[]()[][]
On entry: if iflag=0, fvec contains the function values fi x and must not be changed.
On exit: if iflag>0 on entry, fvec must contain the function values fi x (unless iflag is set to a negative value by fcn).
iflag
Type: System..::..Int32 %
On entry: iflag≥0.
iflag=0
x and fvec are available for printing (see nprint).
iflag>0
fvec must be updated.
On exit: in general, iflag should not be reset by fcn. If, however, you wish to terminate execution (perhaps because some illegal point x has been reached), then iflag should be set to a negative integer.

See Also

NagLibrary Namespace
NAG Library Overview
c05qc


C05.C05RB_FCN Delegate

[image]

NAG Library for .NET Release 2
C05..::..C05RB_FCN Delegate
C05 Class See Also Send Feedback
Depending upon the value of iflag, fcn must either return the values of the functions fi at a point x or return the Jacobian at x.

Syntax

C#
public delegate void C05RB_FCN(
    int n,
    double[] x,
    double[] fvec,
    double[,] fjac,
    ref int iflag
)
Visual Basic
Public Delegate Sub C05RB_FCN ( _
    n As Integer, _
    x As Double(), _
    fvec As Double(), _
    fjac As Double(,), _
    ByRef iflag As Integer _
)
Visual C++
public delegate void C05RB_FCN(
    int n,
    array<double>^ x,
    array<double>^ fvec,
    array<double,2>^ fjac,
    int% iflag
)
F#
type C05RB_FCN =
    delegate of
        n : int *
        x : float[] *
        fvec : float[] *
        fjac : float[,] *
        iflag : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of equations.
x
Type: array< System..::..Double >[]()[][]
On entry: the components of the point x at which the functions or the Jacobian must be evaluated.
fvec
Type: array< System..::..Double >[]()[][]
On entry: if iflag=2, fvec contains the function values fi x and must not be changed.
On exit: if iflag=1 on entry, fvec must contain the function values fi x (unless iflag is set to a negative value by fcn).
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
On entry: if iflag=1, fjac contains the value of ∂fi∂xj at the point x, for i=1,2,…,n and j=1,2,…,n, and must not be changed.
On exit: if iflag=2 on entry, fjac[i-1,j-1] must contain the value of ∂fi∂xj at the point x, for i=1,2,…,n and j=1,2,…,n, (unless iflag is set to a negative value by fcn).
iflag
Type: System..::..Int32 %
On entry: iflag=1 or 2.
iflag=1
fvec is to be updated.
iflag=2
fjac is to be updated.
On exit: in general, iflag should not be reset by fcn. If, however, you wish to terminate execution (perhaps because some illegal point x has been reached), then iflag should be set to a negative integer.

See Also

NagLibrary Namespace
NAG Library Overview
c05rb


C05.C05RC_FCN Delegate

[image]

NAG Library for .NET Release 2
C05..::..C05RC_FCN Delegate
C05 Class See Also Send Feedback
Depending upon the value of iflag, fcn must either return the values of the functions fi at a point x or return the Jacobian at x.

Syntax

C#
public delegate void C05RC_FCN(
    int n,
    double[] x,
    double[] fvec,
    double[,] fjac,
    ref int iflag
)
Visual Basic
Public Delegate Sub C05RC_FCN ( _
    n As Integer, _
    x As Double(), _
    fvec As Double(), _
    fjac As Double(,), _
    ByRef iflag As Integer _
)
Visual C++
public delegate void C05RC_FCN(
    int n,
    array<double>^ x,
    array<double>^ fvec,
    array<double,2>^ fjac,
    int% iflag
)
F#
type C05RC_FCN =
    delegate of
        n : int *
        x : float[] *
        fvec : float[] *
        fjac : float[,] *
        iflag : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of equations.
x
Type: array< System..::..Double >[]()[][]
On entry: the components of the point x at which the functions or the Jacobian must be evaluated.
fvec
Type: array< System..::..Double >[]()[][]
On entry: if iflag=0 or 2, fvec contains the function values fi x and must not be changed.
On exit: if iflag=1 on entry, fvec must contain the function values fi x (unless iflag is set to a negative value by fcn).
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
On entry: if iflag=0, fjac[i-1,j-1] contains the value of ∂fi∂xj at the point x, for i=1,2,…,n and j=1,2,…,n. When iflag=0 or 1, fjac must not be changed.
On exit: if iflag=2 on entry, fjac[i-1,j-1] must contain the value of ∂fi∂xj at the point x, for i=1,2,…,n and j=1,2,…,n, (unless iflag is set to a negative value by fcn).
iflag
Type: System..::..Int32 %
On entry: iflag=0, 1 or 2.
iflag=0
x, fvec and fjac are available for printing (see nprint).
iflag=1
fvec is to be updated.
iflag=2
fjac is to be updated.
On exit: in general, iflag should not be reset by fcn. If, however, you wish to terminate execution (perhaps because some illegal point x has been reached), then iflag should be set to a negative integer value.

See Also

NagLibrary Namespace
NAG Library Overview
c05rc


C05 Classes

[image]

NAG Library for .NET Release 2
C05 Classes

C05 Classes

  • C05.c05qdCommunications Class
  • C05.c05rdCommunications Class


C05.c05qdCommunications Class

[image]

NAG Library for .NET Release 2
C05..::..c05qdCommunications Class
C05 Class Members See Also Send Feedback
Communications Class for c05qd

Syntax

C#
public class c05qdCommunications
Visual Basic
Public Class c05qdCommunications
Visual C++
public ref class c05qdCommunications
F#
type c05qdCommunications =  class end

Inheritance Hierarchy

System..::..Object
NagLibrary..::..C05..::..c05qdCommunications

See Also

C05..::..c05qdCommunications Members
NagLibrary Namespace
NAG Library Overview
c05qd


C05.c05qdCommunications Members

[image] [image]

NAG Library for .NET Release 2
C05..::..c05qdCommunications Members
C05..::..c05qdCommunications Class Constructors Properties See Also Send Feedback

This chapter is concerned with the calculation of zeros of continuous functions of one or more variables. The majority of problems considered are for real-valued functions of real variables, in which case complex equations must be expressed in terms of the equivalent larger system of real equations.

The C05..::..c05qdCommunications type exposes the following members.

Constructors

Name | Description
C05..::..c05qdCommunications | Communications Class constructor.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from c05qd.
Warning | Set the method used for logging any warning or error messages from c05qd.

See Also

C05..::..c05qdCommunications Class


C05.c05qdCommunications Constructor

[image]

NAG Library for .NET Release 2
C05..::..c05qdCommunications Constructor
C05..::..c05qdCommunications Class See Also Send Feedback
Communications Class constructor.

Syntax

C#
public c05qdCommunications(
    int n
)
Visual Basic
Public Sub New ( _
    n As Integer _
)
Visual C++
public:
c05qdCommunications(
    int n
)
F#
new :
        n : int -> c05qdCommunications

Parameters

n
Type: System..::..Int32
n

See Also

C05..::..c05qdCommunications Class
C05..::..c05qdCommunications Members


C05.c05qdCommunications Properties

[image] [image]

NAG Library for .NET Release 2
C05..::..c05qdCommunications Properties
C05..::..c05qdCommunications Class See Also Send Feedback

The C05..::..c05qdCommunications type exposes the following members.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from c05qd.
Warning | Set the method used for logging any warning or error messages from c05qd.

See Also

C05..::..c05qdCommunications Class


Message Property

[image]

NAG Library for .NET Release 2
C05..::..c05qdCommunications..::Message Property
C05..::..c05qdCommunications Class See Also Send Feedback
Set the method used for logging any monitoring messages from c05qd.

Syntax

C#
public PrintManager..::..MessageLogger Message { get; set; }
Visual Basic
Public Property Message As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Message {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Message : PrintManager..::..MessageLogger with get, set

See Also

C05..::..c05qdCommunications Class
C05..::..c05qdCommunications Members


Warning Property

[image]

NAG Library for .NET Release 2
C05..::..c05qdCommunications..::Warning Property
C05..::..c05qdCommunications Class See Also Send Feedback
Set the method used for logging any warning or error messages from c05qd.

Syntax

C#
public PrintManager..::..MessageLogger Warning { get; set; }
Visual Basic
Public Property Warning As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Warning {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Warning : PrintManager..::..MessageLogger with get, set

See Also

C05..::..c05qdCommunications Class
C05..::..c05qdCommunications Members


C05.c05rdCommunications Class

[image]

NAG Library for .NET Release 2
C05..::..c05rdCommunications Class
C05 Class Members See Also Send Feedback
Communications Class for c05rd

Syntax

C#
public class c05rdCommunications
Visual Basic
Public Class c05rdCommunications
Visual C++
public ref class c05rdCommunications
F#
type c05rdCommunications =  class end

Inheritance Hierarchy

System..::..Object
NagLibrary..::..C05..::..c05rdCommunications

See Also

C05..::..c05rdCommunications Members
NagLibrary Namespace
NAG Library Overview
c05rd


C05.c05rdCommunications Members

[image] [image]

NAG Library for .NET Release 2
C05..::..c05rdCommunications Members
C05..::..c05rdCommunications Class Constructors Properties See Also Send Feedback

This chapter is concerned with the calculation of zeros of continuous functions of one or more variables. The majority of problems considered are for real-valued functions of real variables, in which case complex equations must be expressed in terms of the equivalent larger system of real equations.

The C05..::..c05rdCommunications type exposes the following members.

Constructors

Name | Description
C05..::..c05rdCommunications | Communications Class constructor.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from c05rd.
Warning | Set the method used for logging any warning or error messages from c05rd.

See Also

C05..::..c05rdCommunications Class


C05.c05rdCommunications Constructor

[image]

NAG Library for .NET Release 2
C05..::..c05rdCommunications Constructor
C05..::..c05rdCommunications Class See Also Send Feedback
Communications Class constructor.

Syntax

C#
public c05rdCommunications(
    int n
)
Visual Basic
Public Sub New ( _
    n As Integer _
)
Visual C++
public:
c05rdCommunications(
    int n
)
F#
new :
        n : int -> c05rdCommunications

Parameters

n
Type: System..::..Int32
n

See Also

C05..::..c05rdCommunications Class
C05..::..c05rdCommunications Members


C05.c05rdCommunications Properties

[image] [image]

NAG Library for .NET Release 2
C05..::..c05rdCommunications Properties
C05..::..c05rdCommunications Class See Also Send Feedback

The C05..::..c05rdCommunications type exposes the following members.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from c05rd.
Warning | Set the method used for logging any warning or error messages from c05rd.

See Also

C05..::..c05rdCommunications Class


Message Property

[image]

NAG Library for .NET Release 2
C05..::..c05rdCommunications..::Message Property
C05..::..c05rdCommunications Class See Also Send Feedback
Set the method used for logging any monitoring messages from c05rd.

Syntax

C#
public PrintManager..::..MessageLogger Message { get; set; }
Visual Basic
Public Property Message As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Message {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Message : PrintManager..::..MessageLogger with get, set

See Also

C05..::..c05rdCommunications Class
C05..::..c05rdCommunications Members


Warning Property

[image]

NAG Library for .NET Release 2
C05..::..c05rdCommunications..::Warning Property
C05..::..c05rdCommunications Class See Also Send Feedback
Set the method used for logging any warning or error messages from c05rd.

Syntax

C#
public PrintManager..::..MessageLogger Warning { get; set; }
Visual Basic
Public Property Warning As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Warning {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Warning : PrintManager..::..MessageLogger with get, set

See Also

C05..::..c05rdCommunications Class
C05..::..c05rdCommunications Members


C05 Methods

[image] [image]

NAG Library for .NET Release 2
C05 Methods
C05 Class See Also Send Feedback

The C05 type exposes the following members.

Methods

Name | Description
c05au | c05au locates a simple zero of a continuous function from a given starting value. It uses a binary search to locate an interval containing a zero of the function, then Brent's method, which is a combination of nonlinear interpolation, linear extrapolation and bisection, to locate the zero precisely.
c05av | c05av attempts to locate an interval containing a simple zero of a continuous function using a binary search. It uses reverse communication for evaluating the function.
c05aw | c05aw attempts to locate a zero of a continuous function using a continuation method based on a secant iteration.
c05ax | c05ax attempts to locate a zero of a continuous function using a continuation method based on a secant iteration. It uses reverse communication for evaluating the function.
c05ay | c05ay locates a simple zero of a continuous function in a given interval using Brent's method, which is a combination of nonlinear interpolation, linear extrapolation and bisection.
c05az | c05az locates a simple zero of a continuous function in a given interval by using Brent's method, which is a combination of nonlinear interpolation, linear extrapolation and bisection. It uses reverse communication for evaluating the function.
c05qb | c05qb is an easy-to-use method that finds a solution of a system of nonlinear equations by a modification of the Powell hybrid method.
c05qc | c05qc is a comprehensive method that finds a solution of a system of nonlinear equations by a modification of the Powell hybrid method.
c05qd | c05qd is a comprehensive reverse communication method that finds a solution of a system of nonlinear equations by a modification of the Powell hybrid method.
c05rb | c05rb is an easy-to-use method that finds a solution of a system of nonlinear equations by a modification of the Powell hybrid method. You must provide the Jacobian.
c05rc | c05rc is a comprehensive method that finds a solution of a system of nonlinear equations by a modification of the Powell hybrid method. You must provide the Jacobian.
c05rd | c05rd is a comprehensive reverse communication method that finds a solution of a system of nonlinear equations by a modification of the Powell hybrid method. You must provide the Jacobian.
c05zd | c05zd checks the user-supplied gradients of a set of nonlinear functions in several variables, for consistency with the functions themselves. The method must be called twice.

See Also

C05 Class


c05au Method

[image]

NAG Library for .NET Release 2
C05..::c05au Method
C05 Class See Also Send Feedback
c05au locates a simple zero of a continuous function from a given starting value. It uses a binary search to locate an interval containing a zero of the function, then Brent's method, which is a combination of nonlinear interpolation, linear extrapolation and bisection, to locate the zero precisely.

Syntax

C#
public static void c05au(
    ref double x,
    double h,
    double eps,
    double eta,
    C05..::..C05AU_F f,
    out double a,
    out double b,
    out int ifail
)
Visual Basic
Public Shared Sub c05au ( _
    ByRef x As Double, _
    h As Double, _
    eps As Double, _
    eta As Double, _
    f As C05..::..C05AU_F, _
    <OutAttribute> ByRef a As Double, _
    <OutAttribute> ByRef b As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void c05au(
    double% x,
    double h,
    double eps,
    double eta,
    C05..::..C05AU_F^ f,
    [OutAttribute] double% a,
    [OutAttribute] double% b,
    [OutAttribute] int% ifail
)
F#
static member c05au :
        x : float byref *
        h : float *
        eps : float *
        eta : float *
        f : C05..::..C05AU_F *
        a : float byref *
        b : float byref *
        ifail : int byref -> unit

Parameters

x
Type: System..::..Double %
On entry: an initial approximation to the zero.
On exit: if ifail=0 or 4, x is the final approximation to the zero.
If ifail=3, x is likely to be a pole of f x.
Otherwise, x contains no useful information.
h
Type: System..::..Double
On entry: a step length for use in the binary search for an interval containing the zero. The maximum interval searched is x-256.0×h,x+256.0×h.
Constraint: h must be sufficiently large that x+h≠x on the computer.
eps
Type: System..::..Double
On entry: the termination tolerance on x (see [Description]).
Constraint: eps>0.0.
eta
Type: System..::..Double
On entry: a value such that if f x≤eta, x is accepted as the zero. eta may be specified as 0.0 (see [Accuracy]).
f
Type: NagLibrary..::..C05..::..C05AU_F
f must evaluate the function f whose zero is to be determined.

A delegate of type C05AU_F.

a
Type: System..::..Double %
On exit: the lower and upper bounds respectively of the interval resulting from the binary search. If the zero is determined exactly such that f x=0.0 or is determined so that f x≤eta at any stage in the calculation, then on exit a=b=x.
b
Type: System..::..Double %
On exit: the lower and upper bounds respectively of the interval resulting from the binary search. If the zero is determined exactly such that f x=0.0 or is determined so that f x≤eta at any stage in the calculation, then on exit a=b=x.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

c05au attempts to locate an interval a,b containing a simple zero of the function f x by a binary search starting from the initial point x=x and using repeated calls to c05av. If this search succeeds, then the zero is determined to a user-specified accuracy by a call to c05ay. The specifications of methods c05av and c05ay should be consulted for details of the methods used.
The approximation x to the zero α is determined so that at least one of the following criteria is satisfied:
(i) | x-α≤eps,
(ii) | f x≤eta.

References

Brent R P (1973) Algorithms for Minimization Without Derivatives Prentice–Hall

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, eps=value.
Constraint: eps>0.0.
On entry, x=value and h=value.
Constraint: x+h≠x (to machine accuracy).
ifail=2
An interval containing the zero could not be found. Increasing h and calling c05au again will increase the range searched for the zero. Decreasing h and calling c05au again will refine the mesh used in the search for the zero.
ifail=3
Solution may be a pole rather than a zero.
ifail=4
The tolerance eps has been set too small for the problem being solved. However, the value x returned is a good approximation to the zero. eps=value.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The levels of accuracy depend on the values of eps and eta. If full machine accuracy is required, they may be set very small, resulting in an exit with ifail=4, although this may involve many more iterations than a lesser accuracy. You are recommended to set eta=0.0 and to use eps to control the accuracy, unless you have considerable knowledge of the size of f x for values of x near the zero.

Parallelism and Performance

None.

Further Comments

The time taken by c05au depends primarily on the time spent evaluating f (see [Parameters]). The accuracy of the initial approximation x and the value of h will have a somewhat unpredictable effect on the timing.
If it is important to determine an interval of relative length less than 2×eps containing the zero, or if f is expensive to evaluate and the number of calls to f is to be restricted, then use of c05av followed by c05az is recommended. Use of this combination is also recommended when the structure of the problem to be solved does not permit a simple f to be written: the reverse communication facilities of these methods are more flexible than the direct communication of f required by c05au.
If the iteration terminates with successful exit and a=b=x there is no guarantee that the value returned in x corresponds to a simple zero and you should check whether it does.
One way to check this is to compute the derivative of f at the point x, preferably analytically, or, if this is not possible, numerically, perhaps by using a central difference estimate. If f′x=0.0, then x must correspond to a multiple zero of f rather than a simple zero.

Example

This example calculates an approximation to the zero of x-e-x using a tolerance of eps=1.0E−5 starting from x=1.0 and using an initial search step h=0.1.

Example program (C#): c05aue.cs

Example program results: c05aue.r

See Also

C05 Class
C05 Members


c05av Method

[image]

NAG Library for .NET Release 2
C05..::c05av Method
C05 Class See Also Send Feedback
c05av attempts to locate an interval containing a simple zero of a continuous function using a binary search. It uses reverse communication for evaluating the function.

Syntax

C#
public static void c05av(
    ref double x,
    double fx,
    ref double h,
    double boundl,
    double boundu,
    ref double y,
    double[] c,
    ref int ind,
    out int ifail
)
Visual Basic
Public Shared Sub c05av ( _
    ByRef x As Double, _
    fx As Double, _
    ByRef h As Double, _
    boundl As Double, _
    boundu As Double, _
    ByRef y As Double, _
    c As Double(), _
    ByRef ind As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void c05av(
    double% x,
    double fx,
    double% h,
    double boundl,
    double boundu,
    double% y,
    array<double>^ c,
    int% ind,
    [OutAttribute] int% ifail
)
F#
static member c05av :
        x : float byref *
        fx : float *
        h : float byref *
        boundl : float *
        boundu : float *
        y : float byref *
        c : float[] *
        ind : int byref *
        ifail : int byref -> unit

Parameters

x
Type: System..::..Double %
On initial entry: the best available approximation to the zero.
Constraint: x must lie in the closed interval boundl,boundu (see below).
On intermediate exit: contains the point at which f must be evaluated before re-entry to the method.
On final exit: contains one end of an interval containing the zero, the other end being in y, unless an error has occurred. If ifail=4, x and y are the end points of the largest interval searched. If a zero is located exactly, its value is returned in x (and in y).
fx
Type: System..::..Double
On initial entry: if ind=1, fx need not be set.
If ind=-1, fx must contain f x for the initial value of x.
On intermediate re-entry: must contain f x for the current value of x.
h
Type: System..::..Double %
On initial entry: a basic step size which is used in the binary search for an interval containing a zero. The basic step sizes h,0.1×h, 0.01×h and 0.001×h are used in turn when searching for the zero.
Constraint: either x+h or x-h must lie inside the closed interval boundl,boundu.
h must be sufficiently large that x+h≠x on the computer.
On final exit: is undefined.
boundl
Type: System..::..Double
On initial entry: boundl and boundu must contain respectively lower and upper bounds for the interval of search for the zero.
Constraint: boundl<boundu.
boundu
Type: System..::..Double
On initial entry: boundl and boundu must contain respectively lower and upper bounds for the interval of search for the zero.
Constraint: boundl<boundu.
y
Type: System..::..Double %
On initial entry: need not be set.
On final exit: contains the closest point found to the final value of x, such that f x×f y≤0.0. If a value x is found such that f x=0, then y=x. On final exit with ifail=4, x and y are the end points of the largest interval searched.
c
Type: array< System..::..Double >[]()[][]
An array of size [11]
On initial entry: need not be set.
On final exit: if ifail=0 or 4, c[0] contains f y.
ind
Type: System..::..Int32 %
On initial entry: must be set to 1 or -1.
ind=1
fx need not be set.
ind=-1
fx must contain f x.
On intermediate exit: contains 2 or 3. The calling program must evaluate f at x, storing the result in fx, and re-enter c05av with all other parameters unchanged.
On final exit: contains 0.
Constraint: on entry ind=-1, 1, 2 or 3.
ifail
Type: System..::..Int32 %
On initial entry: ifail must be set to 0, -1​ or ​1. If you are unfamiliar with this parameter you should refer to Library Overview for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, because for this method the values of the output parameters may be useful even if ifail≠0 on exit, the recommended value is -1. When the value -1​ or ​1 is used it is essential to test the value of ifail on exit.
On final exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

You must supply an initial point x and a step h. c05av attempts to locate a short interval x,y⊂boundl,boundu containing a simple zero of f x.
(On exit we may have x>y; x is determined as the first point encountered in a binary search where the sign of f x differs from the sign of f x at the initial input point x.) The method attempts to locate a zero of f x using h, 0.1×h, 0.01×h and 0.001×h in turn as its basic step before quitting with an error exit if unsuccessful.
c05av returns to the calling program for each evaluation of f x. On each return you should set fx=f x and call c05av again.

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | boundu≤boundl,
or | x∉boundl,boundu,
or | both x+h and x-h∉boundl,boundu.
ifail=2
On initial entry, h is too small to be used to perturb the initial value of x in the search.
ifail=3
The parameter ind is incorrectly set on initial or intermediate entry.
ifail=4
c05av has been unable to determine an interval containing a simple zero starting from the initial value of x and using the step h. If you have prior knowledge that a simple zero lies in the interval boundl,boundu, you should vary x and h in an attempt to find it. (See also [Further Comments].)
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

c05av is not intended to be used to obtain accurate approximations to the zero of f x but rather to locate an interval containing a zero. This interval can then be used as input to an accurate rootfinder such as c05ay or c05az. The size of the interval determined depends somewhat unpredictably on the choice of x and h. The closer x is to the root and the smaller the initial value of h, then, in general, the smaller (more accurate) the interval determined; however, the accuracy of this statement depends to some extent on the behaviour of f x near x=x and on the size of h.

Parallelism and Performance

None.

Further Comments

For most problems, the time taken on each call to c05av will be negligible compared with the time spent evaluating f x between calls to c05av. However, the initial value of x and h will clearly affect the timing. The closer x is to the root, and the larger the initial value of h then the less time taken. (However taking a large h can affect the accuracy and reliability of the method, see below.)
You are expected to choose boundl and boundu as physically (or mathematically) realistic limits on the interval of search. For example, it may be known, from physical arguments, that no zero of f x of interest will lie outside boundl,boundu. Alternatively, f x may be more expensive to evaluate for some values of x than for others and such expensive evaluations can sometimes be avoided by careful choice of boundl and boundu.
The choice of boundl and boundu affects the search only in that these values provide physical limitations on the search values and that the search is terminated if it seems, from the available information about f x, that the zero lies outside boundl,boundu. In this case (ifail=4 on exit), only one of f boundl and f boundu may have been evaluated and a zero close to the other end of the interval could be missed. The actual interval searched is returned in the parameters x and y and you can call c05av again to search the remainder of the original interval.
Though c05av is intended primarily for determining an interval containing a zero of f x, it may be used to shorten a known interval. This could be useful if, for example, a large interval containing the zero is known and it is also known that the root lies close to one end of the interval; by setting x to this end of the interval and h small, a short interval will usually be determined. However, it is worth noting that once any interval containing a zero has been determined, a call to c05az will usually be the most efficient way to calculate an interval of specified length containing the zero. To assist in this determination, the information in fx and in x, y and c[0] on successful exit from c05av is in the correct form for a call to method c05az with ind=-1.
If the calculation terminates because f x=0.0, then on return y is set to x. (In fact, y=x on return only in this case.) In this case, there is no guarantee that the value in x corresponds to a simple zero and you should check whether it does.
One way to check this is to compute the derivative of f at the point x, preferably analytically, or, if this is not possible, numerically, perhaps by using a central difference estimate. If f′x=0.0, then x must correspond to a multiple zero of f rather than a simple zero.

Example

This example finds a sub-interval of 0.0,4.0 containing a simple zero of x 2-3 x+2. The zero nearest to 3.0 is required and so we set x=3.0 initially.

Example program (C#): c05ave.cs

Example program results: c05ave.r

See Also

C05 Class
C05 Members


c05aw Method

[image]

NAG Library for .NET Release 2
C05..::c05aw Method
C05 Class See Also Send Feedback
c05aw attempts to locate a zero of a continuous function using a continuation method based on a secant iteration.

Syntax

C#
public static void c05aw(
    ref double x,
    double eps,
    double eta,
    C05..::..C05AW_F f,
    int nfmax,
    out int ifail
)
Visual Basic
Public Shared Sub c05aw ( _
    ByRef x As Double, _
    eps As Double, _
    eta As Double, _
    f As C05..::..C05AW_F, _
    nfmax As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void c05aw(
    double% x,
    double eps,
    double eta,
    C05..::..C05AW_F^ f,
    int nfmax,
    [OutAttribute] int% ifail
)
F#
static member c05aw :
        x : float byref *
        eps : float *
        eta : float *
        f : C05..::..C05AW_F *
        nfmax : int *
        ifail : int byref -> unit

Parameters

x
Type: System..::..Double %
On entry: an initial approximation to the zero.
On exit: the final approximation to the zero, unless ifail=1, 2 or 5, in which case it contains no useful information.
eps
Type: System..::..Double
On entry: an absolute tolerance to control the accuracy to which the zero is determined. In general, the smaller the value of eps the more accurate x will be as an approximation to α. Indeed, for very small positive values of eps, it is likely that the final approximation will satisfy x-α<eps. You are advised to call the method with more than one value for eps to check the accuracy obtained.
Constraint: eps>0.0.
eta
Type: System..::..Double
On entry: a value such that if f x<eta, x is accepted as the zero. eta may be specified as 0.0 (see [Accuracy]).
f
Type: NagLibrary..::..C05..::..C05AW_F
f must evaluate the function f whose zero is to be determined.

A delegate of type C05AW_F.

nfmax
Type: System..::..Int32
On entry: the maximum permitted number of calls to f from c05aw. If f is inexpensive to evaluate, nfmax should be given a large value (say >1000).
Constraint: nfmax>0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

c05aw attempts to obtain an approximation to a simple zero α of the function f x given an initial approximation x to α. The zero is found by a call to c05ax whose specification should be consulted for details of the method used.
The approximation x to the zero α is determined so that at least one of the following criteria is satisfied:
(i) | x-α∼eps,
(ii) | f x<eta.

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, eps=value.
Constraint: eps>0.0.
On entry, nfmax=value.
Constraint: nfmax>0.
ifail=2
Internal scale factor invalid for this problem. Consider using c05ax instead and setting scal.
ifail=3
Either f has no zero near x or too much accuracy has been requested. Check the coding of f or increase eps.
ifail=4
More than nfmax calls have been made to f.
nfmax may be too small for the problem (because x is too far away from the zero), or f has no zero near x, or too much accuracy has been requested in calculating the zero. Increase nfmax, check the coding of f or increase eps.
ifail=5
A serious error occurred in an internal call to an auxiliary method.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The levels of accuracy depend on the values of eps and eta. If full machine accuracy is required, they may be set very small, resulting in an exit with ifail=3 or 4, although this may involve many more iterations than a lesser accuracy. You are recommended to set eta=0.0 and to use eps to control the accuracy, unless you have considerable knowledge of the size of f x for values of x near the zero.

Parallelism and Performance

None.

Further Comments

The time taken by c05aw depends primarily on the time spent evaluating the function f (see [Parameters]) and on how close the initial value of x is to the zero.
If a more flexible way of specifying the function f is required or if you wish to have closer control of the calculation, then the reverse communication method c05ax is recommended instead of c05aw.

Example

This example calculates the zero of f x=e-x-x from a starting value x=1.0. Two calculations are made with eps=1.0E−3 and 1.0E−4 for comparison purposes, with eta=0.0 in both cases.

Example program (C#): c05awe.cs

Example program results: c05awe.r

See Also

C05 Class
C05 Members


c05ax Method

[image]

NAG Library for .NET Release 2
C05..::c05ax Method
C05 Class See Also Send Feedback
c05ax attempts to locate a zero of a continuous function using a continuation method based on a secant iteration. It uses reverse communication for evaluating the function.

Syntax

C#
public static void c05ax(
    ref double x,
    double fx,
    double tol,
    int ir,
    double scal,
    double[] c,
    ref int ind,
    out int ifail
)
Visual Basic
Public Shared Sub c05ax ( _
    ByRef x As Double, _
    fx As Double, _
    tol As Double, _
    ir As Integer, _
    scal As Double, _
    c As Double(), _
    ByRef ind As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void c05ax(
    double% x,
    double fx,
    double tol,
    int ir,
    double scal,
    array<double>^ c,
    int% ind,
    [OutAttribute] int% ifail
)
F#
static member c05ax :
        x : float byref *
        fx : float *
        tol : float *
        ir : int *
        scal : float *
        c : float[] *
        ind : int byref *
        ifail : int byref -> unit

Parameters

x
Type: System..::..Double %
On initial entry: an initial approximation to the zero.
On intermediate exit: the point at which f must be evaluated before re-entry to the method.
On final exit: the final approximation to the zero.
fx
Type: System..::..Double
On initial entry: if ind=1, fx need not be set.
If ind=-1, fx must contain f x for the initial value of x.
On intermediate re-entry: must contain f x for the current value of x.
tol
Type: System..::..Double
On initial entry: a value that controls the accuracy to which the zero is determined. tol is used in determining the convergence of the secant iteration used at each stage of the continuation process. It is used directly when solving the last problem (θm=0 in [Description]), and tol is used for the problem defined by θr, r<m. Convergence to the accuracy specified by tol is not guaranteed, and so you are recommended to find the zero using at least two values for tol to check the accuracy obtained.
Constraint: tol>0.0.
ir
Type: System..::..Int32
On initial entry: indicates the type of error test required, as follows. Solving the problem defined by θr, 1≤r≤m, involves computing a sequence of secant iterates xr 0,xr 1,…. This sequence will be considered to have converged only if:
for ir=0,
xr i+1-xr i≤eps×max 1.0,xr i,
for ir=1,
xr i+1-xr i≤eps,
for ir=2,
xr i+1-xr i≤eps×xr i,
for some i>1; here eps is either tol or tol as discussed above. Note that there are other subsidiary conditions (not given here) which must also be satisfied before the secant iteration is considered to have converged.
Constraint: ir=0, 1 or 2.
scal
Type: System..::..Double
On initial entry: a factor for use in determining a significant approximation to the derivative of f x at x=x 0, the initial value. A number of difference approximations to f′x 0 are calculated using
f′x 0∼f x 0+h-f x 0/h
where h<scal and h has the same sign as scal. A significance (cancellation) check is made on each difference approximation and the approximation is rejected if insignificant.
Suggested value: ε, where ε is the machine precision returned by x02aj.
Constraint: scal must be sufficiently large that x+scal≠x on the computer.
c
Type: array< System..::..Double >[]()[][]
An array of size [26]
(c[4] contains the current θr, this value may be useful in the event of an error exit.)
ind
Type: System..::..Int32 %
On initial entry: must be set to 1 or -1.
ind=1
fx need not be set.
ind=-1
fx must contain f x.
On intermediate exit: contains 2, 3 or 4. The calling program must evaluate f at x, storing the result in fx, and re-enter c05ax with all other parameters unchanged.
On final exit: contains 0.
Constraint: on entry ind=-1, 1, 2, 3 or 4.
ifail
Type: System..::..Int32 %
On initial entry: ifail must be set to 0, -1​ or ​1. If you are unfamiliar with this parameter you should refer to Library Overview for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, because for this method the values of the output parameters may be useful even if ifail≠0 on exit, the recommended value is -1. When the value -1​ or ​1 is used it is essential to test the value of ifail on exit.
On final exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

c05ax uses a modified version of an algorithm given in Swift and Lindfield (1978) to compute a zero α of a continuous function f x. The algorithm used is based on a continuation method in which a sequence of problems
f x-θr f x 0,  r=0,1,…,m
are solved, where 1=θ 0>θ 1>⋯>θm=0 (the value of m is determined as the algorithm proceeds) and where x 0 is your initial estimate for the zero of f x. For each θr the current problem is solved by a robust secant iteration using the solution from earlier problems to compute an initial estimate.
You must supply an error tolerance tol. tol is used directly to control the accuracy of solution of the final problem (θm=0) in the continuation method, and tol is used to control the accuracy in the intermediate problems (θ 1,θ 2,…,θ m-1).

References

Swift A and Lindfield G R (1978) Comparison of a continuation method for the numerical solution of a single nonlinear equation Comput. J. 21 359–362

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | tol≤0.0,
or | ir≠0, 1 or 2.
ifail=2
The parameter ind is incorrectly set on initial or intermediate entry.
ifail=3
scal is too small, or significant derivatives of f cannot be computed (this can happen when f is almost constant and nonzero, for any value of scal).
ifail=4
The current problem in the continuation sequence cannot be solved, see c[4] for the value of θr. The most likely explanation is that the current problem has no solution, either because the original problem had no solution or because the continuation path passes through a set of insoluble problems. This latter reason for failure should occur rarely, and not at all if the initial approximation to the zero is sufficiently close. Other possible explanations are that tol is too small and hence the accuracy requirement is too stringent, or that tol is too large and the initial approximation too poor, leading to successively worse intermediate solutions.
ifail=5
Continuation away from the initial point is not possible. This error exit will usually occur if the problem has not been properly posed or the error requirement is extremely stringent.
ifail=6
The final problem (with θm=0) cannot be solved. It is likely that too much accuracy has been requested, or that the zero is at α=0 and ir=2.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The accuracy of the approximation to the zero depends on tol and ir. In general decreasing tol will give more accurate results. Care must be exercised when using the relative error criterion (ir=2).
If the zero is at x=0, or if the initial value of x and the zero bracket the point x=0, it is likely that an error exit with ifail=4, 5 or 6 will occur.
It is possible to request too much or too little accuracy. Since it is not possible to achieve more than machine accuracy, a value of tol≪machine precision should not be input and may lead to an error exit with ifail=4, 5 or 6. For the reasons discussed under ifail=4 in [Error Indicators and Warnings], tol should not be taken too large, say no larger than tol=1.0E−3.

Parallelism and Performance

None.

Further Comments

For most problems, the time taken on each call to c05ax will be negligible compared with the time spent evaluating f x between calls to c05ax. However, the initial value of x and the choice of tol will clearly affect the timing. The closer that x is to the root, the less evaluations of f required. The effect of the choice of tol will not be large, in general, unless tol is very small, in which case the timing will increase.

Example

This example calculates a zero of x-e-x with initial approximation x 0=1.0, and tol=1.0E−3 and 1.0E−4.

Example program (C#): c05axe.cs

Example program results: c05axe.r

See Also

C05 Class
C05 Members


c05ay Method

[image]

NAG Library for .NET Release 2
C05..::c05ay Method
C05 Class See Also Send Feedback
c05ay locates a simple zero of a continuous function in a given interval using Brent's method, which is a combination of nonlinear interpolation, linear extrapolation and bisection.

Syntax

C#
public static void c05ay(
    double a,
    double b,
    double eps,
    double eta,
    C05..::..C05AY_F f,
    out double x,
    out int ifail
)
Visual Basic
Public Shared Sub c05ay ( _
    a As Double, _
    b As Double, _
    eps As Double, _
    eta As Double, _
    f As C05..::..C05AY_F, _
    <OutAttribute> ByRef x As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void c05ay(
    double a,
    double b,
    double eps,
    double eta,
    C05..::..C05AY_F^ f,
    [OutAttribute] double% x,
    [OutAttribute] int% ifail
)
F#
static member c05ay :
        a : float *
        b : float *
        eps : float *
        eta : float *
        f : C05..::..C05AY_F *
        x : float byref *
        ifail : int byref -> unit

Parameters

a
Type: System..::..Double
On entry: a, the lower bound of the interval.
b
Type: System..::..Double
On entry: b, the upper bound of the interval.
Constraint: b≠a.
eps
Type: System..::..Double
On entry: the termination tolerance on x (see [Description]).
Constraint: eps>0.0.
eta
Type: System..::..Double
On entry: a value such that if f x≤eta, x is accepted as the zero. eta may be specified as 0.0 (see [Accuracy]).
f
Type: NagLibrary..::..C05..::..C05AY_F
f must evaluate the function f whose zero is to be determined.

A delegate of type C05AY_F.

x
Type: System..::..Double %
On exit: if ifail=0 or 2, x is the final approximation to the zero. If ifail=3, x is likely to be a pole of f x. Otherwise, x contains no useful information.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

c05ay attempts to obtain an approximation to a simple zero of the function f x given an initial interval a,b such that f a×f b≤0. The same core algorithm is used by c05az whose specification should be consulted for details of the method used.
The approximation x to the zero α is determined so that at least one of the following criteria is satisfied:
(i) | x-α≤eps,
(ii) | f x≤eta.

References

Brent R P (1973) Algorithms for Minimization Without Derivatives Prentice–Hall

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, a=value and b=value.
Constraint: a≠b.
On entry, eps=value.
Constraint: eps>0.0.
On entry, f a and f b have the same sign with neither equalling 0.0: f a=value and f b=value.
ifail=2
No further improvement in the solution is possible. eps is too small: eps=value. The final value of x returned is an accurate approximation to the zero.
ifail=3
The function values in the interval a,b might contain a pole rather than a zero. Reducing eps may help in distinguishing between a pole and a zero.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The levels of accuracy depend on the values of eps and eta. If full machine accuracy is required, they may be set very small, resulting in an exit with ifail=2, although this may involve many more iterations than a lesser accuracy. You are recommended to set eta=0.0 and to use eps to control the accuracy, unless you have considerable knowledge of the size of f x for values of x near the zero.

Parallelism and Performance

None.

Further Comments

The time taken by c05ay depends primarily on the time spent evaluating f (see [Parameters]).
If it is important to determine an interval of relative length less than 2×eps containing the zero, or if f is expensive to evaluate and the number of calls to f is to be restricted, then use of c05az is recommended. Use of c05az is also recommended when the structure of the problem to be solved does not permit a simple f to be written: the reverse communication facilities of c05az are more flexible than the direct communication of f required by c05ay.

Example

This example calculates an approximation to the zero of e-x-x within the interval 0,1 using a tolerance of eps=1.0E−5.

Example program (C#): c05aye.cs

Example program results: c05aye.r

See Also

C05 Class
C05 Members


c05az Method

[image]

NAG Library for .NET Release 2
C05..::c05az Method
C05 Class See Also Send Feedback
c05az locates a simple zero of a continuous function in a given interval by using Brent's method, which is a combination of nonlinear interpolation, linear extrapolation and bisection. It uses reverse communication for evaluating the function.

Syntax

C#
public static void c05az(
    ref double x,
    ref double y,
    double fx,
    double tolx,
    int ir,
    double[] c,
    ref int ind,
    out int ifail
)
Visual Basic
Public Shared Sub c05az ( _
    ByRef x As Double, _
    ByRef y As Double, _
    fx As Double, _
    tolx As Double, _
    ir As Integer, _
    c As Double(), _
    ByRef ind As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void c05az(
    double% x,
    double% y,
    double fx,
    double tolx,
    int ir,
    array<double>^ c,
    int% ind,
    [OutAttribute] int% ifail
)
F#
static member c05az :
        x : float byref *
        y : float byref *
        fx : float *
        tolx : float *
        ir : int *
        c : float[] *
        ind : int byref *
        ifail : int byref -> unit

Parameters

x
Type: System..::..Double %
On initial entry: x and y must define an initial interval a,b containing the zero, such that f x×f y≤0.0. It is not necessary that x<y.
On intermediate exit: x contains the point at which f must be evaluated before re-entry to the method.
On final exit: x and y define a smaller interval containing the zero, such that f x×f y≤0.0, and x-y satisfies the accuracy specified by tolx and ir, unless an error has occurred. If ifail=4, x and y generally contain very good approximations to a pole; if ifail=5, x and y generally contain very good approximations to the zero (see [Error Indicators and Warnings]). If a point x is found such that f x=0.0, then on final exit x=y (in this case there is no guarantee that x is a simple zero). In all cases, the value returned in x is the better approximation to the zero.
y
Type: System..::..Double %
On initial entry: x and y must define an initial interval a,b containing the zero, such that f x×f y≤0.0. It is not necessary that x<y.
On intermediate exit: x contains the point at which f must be evaluated before re-entry to the method.
On final exit: x and y define a smaller interval containing the zero, such that f x×f y≤0.0, and x-y satisfies the accuracy specified by tolx and ir, unless an error has occurred. If ifail=4, x and y generally contain very good approximations to a pole; if ifail=5, x and y generally contain very good approximations to the zero (see [Error Indicators and Warnings]). If a point x is found such that f x=0.0, then on final exit x=y (in this case there is no guarantee that x is a simple zero). In all cases, the value returned in x is the better approximation to the zero.
fx
Type: System..::..Double
On initial entry: if ind=1, fx need not be set.
If ind=-1, fx must contain f x for the initial value of x.
On intermediate re-entry: must contain f x for the current value of x.
tolx
Type: System..::..Double
On initial entry: the accuracy to which the zero is required. The type of error test is specified by ir.
Constraint: tolx>0.0.
ir
Type: System..::..Int32
On initial entry: indicates the type of error test.
ir=0
The test is: x-y≤2.0×tolx×max 1.0,x.
ir=1
The test is: x-y≤2.0×tolx.
ir=2
The test is: x-y≤2.0×tolx×x.
Suggested value: ir=0.
Constraint: ir=0, 1 or 2.
c
Type: array< System..::..Double >[]()[][]
An array of size [17]
On initial entry: if ind=1, no elements of c need be set.
If ind=-1, c[0] must contain f y, other elements of c need not be set.
On final exit: is undefined.
ind
Type: System..::..Int32 %
On initial entry: must be set to 1 or -1.
ind=1
fx and c[0] need not be set.
ind=-1
fx and c[0] must contain f x and f y respectively.
On intermediate exit: contains 2, 3 or 4. The calling program must evaluate f at x, storing the result in fx, and re-enter c05az with all other parameters unchanged.
On final exit: contains 0.
Constraint: on entry ind=-1, 1, 2, 3 or 4.
ifail
Type: System..::..Int32 %
On initial entry: ifail must be set to 0, -1​ or ​1. If you are unfamiliar with this parameter you should refer to Library Overview for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, because for this method the values of the output parameters may be useful even if ifail≠0 on exit, the recommended value is -1. When the value -1​ or ​1 is used it is essential to test the value of ifail on exit.
On final exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

You must supply x and y to define an initial interval a,b containing a simple zero of the function f x (the choice of x and y must be such that f x×f y≤0.0). The method combines the methods of bisection, nonlinear interpolation and linear extrapolation (see Dahlquist and Björck (1974)), to find a sequence of sub-intervals of the initial interval such that the final interval x,y contains the zero and x-y is less than some tolerance specified by tolx and ir (see [Parameters]). In fact, since the intermediate intervals x,y are determined only so that f x×f y≤0.0, it is possible that the final interval may contain a discontinuity or a pole of f (violating the requirement that f be continuous). c05az checks if the sign change is likely to correspond to a pole of f and gives an error return in this case.
A feature of the algorithm used by this method is that unlike some other methods it guarantees convergence within about log 2 b-a/δ 2 function evaluations, where δ is related to the parameter tolx. See Brent (1973) for more details.
c05az returns to the calling program for each evaluation of f x. On each return you should set fx=f x and call c05az again.
The method is a modified version of procedure ‘zeroin’ given by Brent (1973).

References

Brent R P (1973) Algorithms for Minimization Without Derivatives Prentice–Hall
Bus J C P and Dekker T J (1975) Two efficient algorithms with guaranteed convergence for finding a zero of a function ACM Trans. Math. Software 1 330–345
Dahlquist G and Björck Å (1974) Numerical Methods Prentice–Hall

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, f x and f y have the same sign with neither equalling 0.0.
ifail=2
On entry, ind≠-1, 1, 2, 3 or 4.
ifail=3
On entry, | tolx≤0.0,
or | ir≠0, 1 or 2.
ifail=4
An interval x,y has been determined satisfying the error tolerance specified by tolx and ir and such that f x×f y≤0. However, from observation of the values of f during the calculation of x,y, it seems that the interval x,y contains a pole rather than a zero. Note that this error exit is not completely reliable: the error exit may be taken in extreme cases when x,y contains a zero, or the error exit may not be taken when x,y contains a pole. Both these cases occur most frequently when tolx is large.
ifail=5
The tolerance tolx is too small for the problem being solved. This indicator is only set when the interval containing the zero has been reduced to one of relative length at most 2 ε, where ε is the machine precision, but the exit condition specified by ir is not satisfied. It is unsafe to continue reducing the interval beyond this point, but the final values of x and y returned are accurate approximations to the zero.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The accuracy of the final value x as an approximation of the zero is determined by tolx and ir (see [Parameters]). A relative accuracy criterion (ir=2) should not be used when the initial values x and y are of different orders of magnitude. In this case a change of origin of the independent variable may be appropriate. For example, if the initial interval x,y is transformed linearly to the interval 1,2, then the zero can be determined to a precise number of figures using an absolute (ir=1) or relative (ir=2) error test and the effect of the transformation back to the original interval can also be determined. Except for the accuracy check, such a transformation has no effect on the calculation of the zero.

Parallelism and Performance

None.

Further Comments

For most problems, the time taken on each call to c05az will be negligible compared with the time spent evaluating f x between calls to c05az.
If the calculation terminates because f x=0.0, then on return y is set to x. (In fact, y=x on return only in this case and, possibly, when ifail=5.) There is no guarantee that the value returned in x corresponds to a simple root and you should check whether it does. One way to check this is to compute the derivative of f at the point x, preferably analytically, or, if this is not possible, numerically, perhaps by using a central difference estimate. If f′x=0.0, then x must correspond to a multiple zero of f rather than a simple zero.

Example

This example calculates a zero of e-x-x with an initial interval 0,1, tolx=1.0E−5 and a mixed error test.

Example program (C#): c05aze.cs

Example program results: c05aze.r

See Also

C05 Class
C05 Members


c05qb Method

[image]

NAG Library for .NET Release 2
C05..::c05qb Method
C05 Class See Also Send Feedback
c05qb is an easy-to-use method that finds a solution of a system of nonlinear equations by a modification of the Powell hybrid method.

Syntax

C#
public static void c05qb(
    C05..::..C05QB_FCN fcn,
    int n,
    double[] x,
    double[] fvec,
    double xtol,
    out int ifail
)
Visual Basic
Public Shared Sub c05qb ( _
    fcn As C05..::..C05QB_FCN, _
    n As Integer, _
    x As Double(), _
    fvec As Double(), _
    xtol As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void c05qb(
    C05..::..C05QB_FCN^ fcn,
    int n,
    array<double>^ x,
    array<double>^ fvec,
    double xtol,
    [OutAttribute] int% ifail
)
F#
static member c05qb :
        fcn : C05..::..C05QB_FCN *
        n : int *
        x : float[] *
        fvec : float[] *
        xtol : float *
        ifail : int byref -> unit

Parameters

fcn
Type: NagLibrary..::..C05..::..C05QB_FCN
fcn must return the values of the functions fi at a point x.

A delegate of type C05QB_FCN.

n
Type: System..::..Int32
On entry: n, the number of equations.
Constraint: n>0.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: an initial guess at the solution vector.
On exit: the final estimate of the solution vector.
fvec
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the function values at the final point returned in x.
xtol
Type: System..::..Double
On entry: the accuracy in x to which the solution is required.
Suggested value: ε, where ε is the machine precision returned by x02aj.
Constraint: xtol≥0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The system of equations is defined as:
fi x 1,x 2,…,xn=0,   ​i=1,2,…,n.
c05qb is based on the MINPACK routine HYBRD1 (see Moré et al. (1980)). It chooses the correction at each step as a convex combination of the Newton and scaled gradient directions. The Jacobian is updated by the rank-1 method of Broyden. At the starting point, the Jacobian is approximated by forward differences, but these are not used again until the rank-1 method fails to produce satisfactory progress. For more details see Powell (1970).

References

Moré J J, Garbow B S and Hillstrom K E (1980) User guide for MINPACK-1 Technical Report ANL-80-74 Argonne National Laboratory
Powell M J D (1970) A hybrid method for nonlinear algebraic equations Numerical Methods for Nonlinear Algebraic Equations (ed P Rabinowitz) Gordon and Breach

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=2
There have been at least 200×n+1 calls to fcn. Consider restarting the calculation from the point held in x.
ifail=3
No further improvement in the solution is possible. xtol is too small: xtol=value.
ifail=4
The iteration is not making good progress. This failure exit may indicate that the system does not have a zero, or that the solution is very close to the origin (see [Accuracy]). Otherwise, rerunning c05qb from a different starting point may avoid the region of difficulty.
ifail=5
iflag was set negative in fcn. iflag=value.
ifail=11
On entry, n=value.
Constraint: n>0.
ifail=12
On entry, xtol=value.
Constraint: xtol≥0.0.
ifail=-999
Dynamic memory allocation failed.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

If x^ is the true solution, c05qb tries to ensure that
x-x^2≤xtol×x^2.
If this condition is satisfied with xtol=10-k, then the larger components of x have k significant decimal digits. There is a danger that the smaller components of x may have large relative errors, but the fast rate of convergence of c05qb usually obviates this possibility.
If xtol is less than machine precision and the above test is satisfied with the machine precision in place of xtol, then the method exits with ifail=3.
Note: this convergence test is based purely on relative error, and may not indicate convergence if the solution is very close to the origin.
The convergence test assumes that the functions are reasonably well behaved. If this condition is not satisfied, then c05qb may incorrectly indicate convergence. The validity of the answer can be checked, for example, by rerunning c05qb with a lower value for xtol.

Parallelism and Performance

None.

Further Comments

Local workspace arrays of fixed lengths are allocated internally by c05qb. The total size of these arrays amounts to n×3×n+13/2 real elements.
The time required by c05qb to solve a given problem depends on n, the behaviour of the functions, the accuracy requested and the starting point. The number of arithmetic operations executed by c05qb to process each evaluation of the functions is approximately 11.5×n 2. The timing of c05qb is strongly influenced by the time spent evaluating the functions.
Ideally the problem should be scaled so that, at the solution, the function values are of comparable magnitude.

Example

This example determines the values x 1,…,x 9 which satisfy the tridiagonal equations:
3-2 x 1 x 1-2 x 2=-1,-x i-1+3-2 xi xi-2 x i+1=-1,  i=2,3,…,8-x 8+3-2 x 9 x 9=-1.

Example program (C#): c05qbe.cs

Example program results: c05qbe.r

See Also

C05 Class
C05 Members


c05qc Method

[image]

NAG Library for .NET Release 2
C05..::c05qc Method
C05 Class See Also Send Feedback
c05qc is a comprehensive method that finds a solution of a system of nonlinear equations by a modification of the Powell hybrid method.

Syntax

C#
public static void c05qc(
    C05..::..C05QC_FCN fcn,
    int n,
    double[] x,
    double[] fvec,
    double xtol,
    int maxfev,
    int ml,
    int mu,
    double epsfcn,
    int mode,
    double[] diag,
    double factor,
    int nprint,
    out int nfev,
    double[,] fjac,
    double[] r,
    double[] qtf,
    out int ifail
)
Visual Basic
Public Shared Sub c05qc ( _
    fcn As C05..::..C05QC_FCN, _
    n As Integer, _
    x As Double(), _
    fvec As Double(), _
    xtol As Double, _
    maxfev As Integer, _
    ml As Integer, _
    mu As Integer, _
    epsfcn As Double, _
    mode As Integer, _
    diag As Double(), _
    factor As Double, _
    nprint As Integer, _
    <OutAttribute> ByRef nfev As Integer, _
    fjac As Double(,), _
    r As Double(), _
    qtf As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void c05qc(
    C05..::..C05QC_FCN^ fcn,
    int n,
    array<double>^ x,
    array<double>^ fvec,
    double xtol,
    int maxfev,
    int ml,
    int mu,
    double epsfcn,
    int mode,
    array<double>^ diag,
    double factor,
    int nprint,
    [OutAttribute] int% nfev,
    array<double,2>^ fjac,
    array<double>^ r,
    array<double>^ qtf,
    [OutAttribute] int% ifail
)
F#
static member c05qc :
        fcn : C05..::..C05QC_FCN *
        n : int *
        x : float[] *
        fvec : float[] *
        xtol : float *
        maxfev : int *
        ml : int *
        mu : int *
        epsfcn : float *
        mode : int *
        diag : float[] *
        factor : float *
        nprint : int *
        nfev : int byref *
        fjac : float[,] *
        r : float[] *
        qtf : float[] *
        ifail : int byref -> unit

Parameters

fcn
Type: NagLibrary..::..C05..::..C05QC_FCN
fcn must return the values of the functions fi at a point x, unless iflag=0 on entry to c05qc.

A delegate of type C05QC_FCN.

n
Type: System..::..Int32
On entry: n, the number of equations.
Constraint: n>0.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: an initial guess at the solution vector.
On exit: the final estimate of the solution vector.
fvec
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the function values at the final point returned in x.
xtol
Type: System..::..Double
On entry: the accuracy in x to which the solution is required.
Suggested value: ε, where ε is the machine precision returned by x02aj.
Constraint: xtol≥0.0.
maxfev
Type: System..::..Int32
On entry: the maximum number of calls to fcn with iflag≠0. c05qc will exit with ifail=2, if, at the end of an iteration, the number of calls to fcn exceeds maxfev.
Suggested value: maxfev=200×n+1.
Constraint: maxfev>0.
ml
Type: System..::..Int32
On entry: the number of subdiagonals within the band of the Jacobian matrix. (If the Jacobian is not banded, or you are unsure, set ml=n-1.)
Constraint: ml≥0.
mu
Type: System..::..Int32
On entry: the number of superdiagonals within the band of the Jacobian matrix. (If the Jacobian is not banded, or you are unsure, set mu=n-1.)
Constraint: mu≥0.
epsfcn
Type: System..::..Double
On entry: a rough estimate of the largest relative error in the functions. It is used in determining a suitable step for a forward difference approximation to the Jacobian. If epsfcn is less than machine precision (returned by x02aj) then machine precision is used. Consequently a value of 0.0 will often be suitable.
Suggested value: epsfcn=0.0.
mode
Type: System..::..Int32
On entry: indicates whether or not you have provided scaling factors in diag.
If mode=2 the scaling must have been specified in diag.
Otherwise, if mode=1, the variables will be scaled internally.
Constraint: mode=1 or 2.
diag
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: if mode=2, diag must contain multiplicative scale factors for the variables.
If mode=1, diag need not be set.
Constraint: if mode=2, diag[i-1]>0.0, for i=1,2,…,n.
On exit: the scale factors actually used (computed internally if mode=1).
factor
Type: System..::..Double
On entry: a quantity to be used in determining the initial step bound. In most cases, factor should lie between 0.1 and 100.0. (The step bound is factor×diag×x 2 if this is nonzero; otherwise the bound is factor.)
Suggested value: factor=100.0.
Constraint: factor>0.0.
nprint
Type: System..::..Int32
On entry: indicates whether (and how often) special calls to fcn, with iflag set to 0, are to be made for printing purposes.
nprint≤0
No calls are made.
nprint>0
fcn is called at the beginning of the first iteration, every nprint iterations thereafter and immediately before the return from c05qc.
nfev
Type: System..::..Int32 %
On exit: the number of calls made to fcn with iflag>0.
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint:
On exit: the orthogonal matrix Q produced by the QR factorisation of the final approximate Jacobian.
r
Type: array< System..::..Double >[]()[][]
An array of size [n×n+1/2]
On exit: the upper triangular matrix R produced by the QR factorization of the final approximate Jacobian, stored row-wise.
qtf
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the vector QT f.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The system of equations is defined as:
fi x 1,x 2,…,xn=0,   ​i=1,2,…,n.
c05qc is based on the MINPACK routine HYBRD (see Moré et al. (1980)). It chooses the correction at each step as a convex combination of the Newton and scaled gradient directions. The Jacobian is updated by the rank-1 method of Broyden. At the starting point, the Jacobian is approximated by forward differences, but these are not used again until the rank-1 method fails to produce satisfactory progress. For more details see Powell (1970).

References

Moré J J, Garbow B S and Hillstrom K E (1980) User guide for MINPACK-1 Technical Report ANL-80-74 Argonne National Laboratory
Powell M J D (1970) A hybrid method for nonlinear algebraic equations Numerical Methods for Nonlinear Algebraic Equations (ed P Rabinowitz) Gordon and Breach

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDFJAC) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=2
There have been at least maxfev calls to fcn: maxfev=value. Consider restarting the calculation from the final point held in x.
ifail=3
No further improvement in the solution is possible. xtol is too small: xtol=value.
ifail=4
The iteration is not making good progress, as measured by the improvement from the last value Jacobian evaluations.
ifail=5
The iteration is not making good progress, as measured by the improvement from the last value iterations.
ifail=6
iflag was set negative in fcn. iflag=value.
ifail=11
On entry, n=value.
Constraint: n>0.
ifail=12
On entry, xtol=value.
Constraint: xtol≥0.0.
ifail=13
On entry, mode=value.
Constraint: mode=1 or 2.
ifail=14
On entry, factor=value.
Constraint: factor>0.0.
ifail=15
On entry, mode=2 and diag contained a non-positive element.
ifail=16
On entry, ml=value.
Constraint: ml≥0.
ifail=17
On entry, mu=value.
Constraint: mu≥0.
ifail=18
On entry, maxfev=value.
Constraint: maxfev>0.
ifail=-999
Dynamic memory allocation failed.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

If x^ is the true solution and D denotes the diagonal matrix whose entries are defined by the array diag, then c05qc tries to ensure that
D x-x^2≤xtol×D x^2.
If this condition is satisfied with xtol=10-k, then the larger components of Dx have k significant decimal digits. There is a danger that the smaller components of Dx may have large relative errors, but the fast rate of convergence of c05qc usually obviates this possibility.
If xtol is less than machine precision and the above test is satisfied with the machine precision in place of xtol, then the method exits with ifail=3.
Note: this convergence test is based purely on relative error, and may not indicate convergence if the solution is very close to the origin.
The convergence test assumes that the functions are reasonably well behaved. If this condition is not satisfied, then c05qc may incorrectly indicate convergence. The validity of the answer can be checked, for example, by rerunning c05qc with a lower value for xtol.

Parallelism and Performance

None.

Further Comments

Local workspace arrays of fixed lengths are allocated internally by c05qc. The total size of these arrays amounts to 4×n real elements.
The time required by c05qc to solve a given problem depends on n, the behaviour of the functions, the accuracy requested and the starting point. The number of arithmetic operations executed by c05qc to process each evaluation of the functions is approximately 11.5×n 2. The timing of c05qc is strongly influenced by the time spent evaluating the functions.
Ideally the problem should be scaled so that, at the solution, the function values are of comparable magnitude.
The number of function evaluations required to evaluate the Jacobian may be reduced if you can specify ml and mu accurately.

Example

This example determines the values x 1,…,x 9 which satisfy the tridiagonal equations:
3-2 x 1 x 1-2 x 2=-1,-x i-1+3-2 xi xi-2 x i+1=-1,  i=2,3,…,8-x 8+3-2 x 9 x 9=-1.

Example program (C#): c05qce.cs

Example program results: c05qce.r

See Also

C05 Class
C05 Members


c05qd Method

[image]

NAG Library for .NET Release 2
C05..::c05qd Method
C05 Class See Also Send Feedback
c05qd is a comprehensive reverse communication method that finds a solution of a system of nonlinear equations by a modification of the Powell hybrid method.

Syntax

C#
public static void c05qd(
    ref int irevcm,
    int n,
    double[] x,
    double[] fvec,
    double xtol,
    int ml,
    int mu,
    double epsfcn,
    int mode,
    double[] diag,
    double factor,
    double[,] fjac,
    double[] r,
    double[] qtf,
    C05..::..c05qdCommunications communications,
    out int ifail
)
Visual Basic
Public Shared Sub c05qd ( _
    ByRef irevcm As Integer, _
    n As Integer, _
    x As Double(), _
    fvec As Double(), _
    xtol As Double, _
    ml As Integer, _
    mu As Integer, _
    epsfcn As Double, _
    mode As Integer, _
    diag As Double(), _
    factor As Double, _
    fjac As Double(,), _
    r As Double(), _
    qtf As Double(), _
    communications As C05..::..c05qdCommunications, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void c05qd(
    int% irevcm,
    int n,
    array<double>^ x,
    array<double>^ fvec,
    double xtol,
    int ml,
    int mu,
    double epsfcn,
    int mode,
    array<double>^ diag,
    double factor,
    array<double,2>^ fjac,
    array<double>^ r,
    array<double>^ qtf,
    C05..::..c05qdCommunications^ communications,
    [OutAttribute] int% ifail
)
F#
static member c05qd :
        irevcm : int byref *
        n : int *
        x : float[] *
        fvec : float[] *
        xtol : float *
        ml : int *
        mu : int *
        epsfcn : float *
        mode : int *
        diag : float[] *
        factor : float *
        fjac : float[,] *
        r : float[] *
        qtf : float[] *
        communications : C05..::..c05qdCommunications *
        ifail : int byref -> unit

Parameters

irevcm
Type: System..::..Int32 %
On initial entry: must have the value 0.
On intermediate exit: specifies what action you must take before re-entering c05qd with irevcm unchanged. The value of irevcm should be interpreted as follows:
irevcm=1
Indicates the start of a new iteration. No action is required by you, but x and fvec are available for printing.
irevcm=2
Indicates that before re-entry to c05qd, fvec must contain the function values fi x.
On final exit: irevcm=0, and the algorithm has terminated.
Constraint: irevcm=0, 1 or 2.
n
Type: System..::..Int32
On entry: n, the number of equations.
Constraint: n>0.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On initial entry: an initial guess at the solution vector.
On intermediate exit: contains the current point.
On final exit: the final estimate of the solution vector.
fvec
Type: array< System..::..Double >[]()[][]
An array of size [n]
On initial entry: need not be set.
On intermediate re-entry: if irevcm=1, fvec must not be changed.
If irevcm=2, fvec must be set to the values of the functions computed at the current point x.
On final exit: the function values at the final point, x.
xtol
Type: System..::..Double
On initial entry: the accuracy in x to which the solution is required.
Suggested value: ε, where ε is the machine precision returned by x02aj.
Constraint: xtol≥0.0.
ml
Type: System..::..Int32
On initial entry: the number of subdiagonals within the band of the Jacobian matrix. (If the Jacobian is not banded, or you are unsure, set ml=n-1.)
Constraint: ml≥0.
mu
Type: System..::..Int32
On initial entry: the number of superdiagonals within the band of the Jacobian matrix. (If the Jacobian is not banded, or you are unsure, set mu=n-1.)
Constraint: mu≥0.
epsfcn
Type: System..::..Double
On initial entry: the order of the largest relative error in the functions. It is used in determining a suitable step for a forward difference approximation to the Jacobian. If epsfcn is less than machine precision (returned by x02aj) then machine precision is used. Consequently a value of 0.0 will often be suitable.
Suggested value: epsfcn=0.0.
mode
Type: System..::..Int32
On initial entry: indicates whether or not you have provided scaling factors in diag.
If mode=2 the scaling must have been supplied in diag.
Otherwise, if mode=1, the variables will be scaled internally.
Constraint: mode=1 or 2.
diag
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: if mode=2, diag must contain multiplicative scale factors for the variables.
If mode=1, diag need not be set.
Constraint: if mode=2, diag[i-1]>0.0, for i=1,2,…,n.
On exit: the scale factors actually used (computed internally if mode=1).
factor
Type: System..::..Double
On initial entry: a quantity to be used in determining the initial step bound. In most cases, factor should lie between 0.1 and 100.0. (The step bound is factor×diag×x 2 if this is nonzero; otherwise the bound is factor.)
Suggested value: factor=100.0.
Constraint: factor>0.0.
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [n, n]
On initial entry: need not be set.
On intermediate exit: must not be changed.
On final exit: the orthogonal matrix Q produced by the QR factorization of the final approximate Jacobian.
r
Type: array< System..::..Double >[]()[][]
An array of size [n×n+1/2]
On initial entry: need not be set.
On intermediate exit: must not be changed.
On final exit: the upper triangular matrix R produced by the QR factorization of the final approximate Jacobian, stored row-wise.
qtf
Type: array< System..::..Double >[]()[][]
An array of size [n]
On initial entry: need not be set.
On intermediate exit: must not be changed.
On final exit: the vector QT f.
communications
Type: NagLibrary..::..C05..::..c05qdCommunications
An Object of type C05.c05qdCommunications.
ifail
Type: System..::..Int32 %
On initial entry: ifail must be set to 0, -1​ or ​1. If you are unfamiliar with this parameter you should refer to Library Overview for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, because for this method the values of the output parameters may be useful even if ifail≠0 on exit, the recommended value is -1. When the value -1​ or ​1 is used it is essential to test the value of ifail on exit.
On final exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The system of equations is defined as:
fi x 1,x 2,…,xn=0,  i=1,2,…,n.
c05qd is based on the MINPACK routine HYBRD (see Moré et al. (1980)). It chooses the correction at each step as a convex combination of the Newton and scaled gradient directions. The Jacobian is updated by the rank-1 method of Broyden. At the starting point, the Jacobian is approximated by forward differences, but these are not used again until the rank-1 method fails to produce satisfactory progress. For more details see Powell (1970).

References

Moré J J, Garbow B S and Hillstrom K E (1980) User guide for MINPACK-1 Technical Report ANL-80-74 Argonne National Laboratory
Powell M J D (1970) A hybrid method for nonlinear algebraic equations Numerical Methods for Nonlinear Algebraic Equations (ed P Rabinowitz) Gordon and Breach

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=2
On entry, irevcm=value.
Constraint: irevcm=0, 1 or 2.
ifail=3
No further improvement in the solution is possible. xtol is too small: xtol=value.
ifail=4
The iteration is not making good progress, as measured by the improvement from the last value Jacobian evaluations.
ifail=5
The iteration is not making good progress, as measured by the improvement from the last value iterations.
ifail=11
On entry, n=value.
Constraint: n>0.
ifail=12
On entry, xtol=value.
Constraint: xtol≥0.0.
ifail=13
On entry, mode=value.
Constraint: mode=1 or 2.
ifail=14
On entry, factor=value.
Constraint: factor>0.0.
ifail=15
On entry, mode=2 and diag contained a non-positive element.
ifail=16
On entry, ml=value.
Constraint: ml≥0.
ifail=17
On entry, mu=value.
Constraint: mu≥0.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-3001
parameter : n passed into the options/communications class constructor is invalid
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

If x^ is the true solution and D denotes the diagonal matrix whose entries are defined by the array diag, then c05qd tries to ensure that
D x-x^2≤xtol×D x^2.
If this condition is satisfied with xtol=10-k, then the larger components of Dx have k significant decimal digits. There is a danger that the smaller components of Dx may have large relative errors, but the fast rate of convergence of c05qd usually obviates this possibility.
If xtol is less than machine precision and the above test is satisfied with the machine precision in place of xtol, then the method exits with ifail=3.
Note: this convergence test is based purely on relative error, and may not indicate convergence if the solution is very close to the origin.
The convergence test assumes that the functions are reasonably well behaved. If this condition is not satisfied, then c05qd may incorrectly indicate convergence. The validity of the answer can be checked, for example, by rerunning c05qd with a lower value for xtol.

Parallelism and Performance

None.

Further Comments

The time required by c05qd to solve a given problem depends on n, the behaviour of the functions, the accuracy requested and the starting point. The number of arithmetic operations executed by c05qd to process the evaluation of functions in the main program in each exit is approximately 11.5×n 2. The timing of c05qd is strongly influenced by the time spent evaluating the functions.
Ideally the problem should be scaled so that, at the solution, the function values are of comparable magnitude.
The number of function evaluations required to evaluate the Jacobian may be reduced if you can specify ml and mu accurately.

Example

This example determines the values x 1,…,x 9 which satisfy the tridiagonal equations:
3-2 x 1 x 1-2 x 2=-1,-x i-1+3-2 xi xi-2 x i+1=-1,  i=2,3,…,8-x 8+3-2 x 9 x 9=-1.

Example program (C#): c05qde.cs

Example program results: c05qde.r

See Also

C05 Class
C05 Members


c05rb Method

[image]

NAG Library for .NET Release 2
C05..::c05rb Method
C05 Class See Also Send Feedback
c05rb is an easy-to-use method that finds a solution of a system of nonlinear equations by a modification of the Powell hybrid method. You must provide the Jacobian.

Syntax

C#
public static void c05rb(
    C05..::..C05RB_FCN fcn,
    int n,
    double[] x,
    double[] fvec,
    double[,] fjac,
    double xtol,
    out int ifail
)
Visual Basic
Public Shared Sub c05rb ( _
    fcn As C05..::..C05RB_FCN, _
    n As Integer, _
    x As Double(), _
    fvec As Double(), _
    fjac As Double(,), _
    xtol As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void c05rb(
    C05..::..C05RB_FCN^ fcn,
    int n,
    array<double>^ x,
    array<double>^ fvec,
    array<double,2>^ fjac,
    double xtol,
    [OutAttribute] int% ifail
)
F#
static member c05rb :
        fcn : C05..::..C05RB_FCN *
        n : int *
        x : float[] *
        fvec : float[] *
        fjac : float[,] *
        xtol : float *
        ifail : int byref -> unit

Parameters

fcn
Type: NagLibrary..::..C05..::..C05RB_FCN
Depending upon the value of iflag, fcn must either return the values of the functions fi at a point x or return the Jacobian at x.

A delegate of type C05RB_FCN.

n
Type: System..::..Int32
On entry: n, the number of equations.
Constraint: n>0.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: an initial guess at the solution vector.
On exit: the final estimate of the solution vector.
fvec
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the function values at the final point returned in x.
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint:
On exit: the orthogonal matrix Q produced by the QR factorization of the final approximate Jacobian.
xtol
Type: System..::..Double
On entry: the accuracy in x to which the solution is required.
Suggested value: ε, where ε is the machine precision returned by x02aj.
Constraint: xtol≥0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The system of equations is defined as:
fi x 1,x 2,…,xn=0,  i=1,2,…,n.
c05rb is based on the MINPACK routine HYBRJ1 (see Moré et al. (1980)). It chooses the correction at each step as a convex combination of the Newton and scaled gradient directions. The Jacobian is updated by the rank-1 method of Broyden. At the starting point, the Jacobian is requested, but it is not asked for again until the rank-1 method fails to produce satisfactory progress. For more details see Powell (1970).

References

Moré J J, Garbow B S and Hillstrom K E (1980) User guide for MINPACK-1 Technical Report ANL-80-74 Argonne National Laboratory
Powell M J D (1970) A hybrid method for nonlinear algebraic equations Numerical Methods for Nonlinear Algebraic Equations (ed P Rabinowitz) Gordon and Breach

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDFJAC) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=2
There have been at least 100×n+1 calls to fcn. Consider restarting the calculation from the point held in x.
ifail=3
No further improvement in the solution is possible. xtol is too small: xtol=value.
ifail=4
The iteration is not making good progress. This failure exit may indicate that the system does not have a zero, or that the solution is very close to the origin (see [Accuracy]). Otherwise, rerunning c05rb from a different starting point may avoid the region of difficulty.
ifail=5
iflag was set negative in fcn. iflag=value.
ifail=11
On entry, n=value.
Constraint: n>0.
ifail=12
On entry, xtol=value.
Constraint: xtol≥0.0.
ifail=-999
Dynamic memory allocation failed.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

If x^ is the true solution, c05rb tries to ensure that
x-x^2≤xtol×x^2.
If this condition is satisfied with xtol=10-k, then the larger components of x have k significant decimal digits. There is a danger that the smaller components of x may have large relative errors, but the fast rate of convergence of c05rb usually obviates this possibility.
If xtol is less than machine precision and the above test is satisfied with the machine precision in place of xtol, then the method exits with ifail=3.
Note: this convergence test is based purely on relative error, and may not indicate convergence if the solution is very close to the origin.
The convergence test assumes that the functions and the Jacobian are coded consistently and that the functions are reasonably well behaved. If these conditions are not satisfied, then c05rb may incorrectly indicate convergence. The coding of the Jacobian can be checked using c05zd. If the Jacobian is coded correctly, then the validity of the answer can be checked by rerunning c05rb with a lower value for xtol.

Parallelism and Performance

None.

Further Comments

Local workspace arrays of fixed lengths are allocated internally by c05rb. The total size of these arrays amounts to n×n+13/2 real elements.
The time required by c05rb to solve a given problem depends on n, the behaviour of the functions, the accuracy requested and the starting point. The number of arithmetic operations executed by c05rb is approximately 11.5×n 2 to process each evaluation of the functions and approximately 1.3×n 3 to process each evaluation of the Jacobian. The timing of c05rb is strongly influenced by the time spent evaluating the functions.
Ideally the problem should be scaled so that, at the solution, the function values are of comparable magnitude.

Example

This example determines the values x 1,…,x 9 which satisfy the tridiagonal equations:
3-2 x 1 x 1-2 x 2=-1,-x i-1+3-2 xi xi-2 x i+1=-1,  i=2,3,…,8-x 8+3-2 x 9 x 9=-1.

Example program (C#): c05rbe.cs

Example program results: c05rbe.r

See Also

C05 Class
C05 Members


c05rc Method

[image]

NAG Library for .NET Release 2
C05..::c05rc Method
C05 Class See Also Send Feedback
c05rc is a comprehensive method that finds a solution of a system of nonlinear equations by a modification of the Powell hybrid method. You must provide the Jacobian.

Syntax

C#
public static void c05rc(
    C05..::..C05RC_FCN fcn,
    int n,
    double[] x,
    double[] fvec,
    double[,] fjac,
    double xtol,
    int maxfev,
    int mode,
    double[] diag,
    double factor,
    int nprint,
    out int nfev,
    out int njev,
    double[] r,
    double[] qtf,
    out int ifail
)
Visual Basic
Public Shared Sub c05rc ( _
    fcn As C05..::..C05RC_FCN, _
    n As Integer, _
    x As Double(), _
    fvec As Double(), _
    fjac As Double(,), _
    xtol As Double, _
    maxfev As Integer, _
    mode As Integer, _
    diag As Double(), _
    factor As Double, _
    nprint As Integer, _
    <OutAttribute> ByRef nfev As Integer, _
    <OutAttribute> ByRef njev As Integer, _
    r As Double(), _
    qtf As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void c05rc(
    C05..::..C05RC_FCN^ fcn,
    int n,
    array<double>^ x,
    array<double>^ fvec,
    array<double,2>^ fjac,
    double xtol,
    int maxfev,
    int mode,
    array<double>^ diag,
    double factor,
    int nprint,
    [OutAttribute] int% nfev,
    [OutAttribute] int% njev,
    array<double>^ r,
    array<double>^ qtf,
    [OutAttribute] int% ifail
)
F#
static member c05rc :
        fcn : C05..::..C05RC_FCN *
        n : int *
        x : float[] *
        fvec : float[] *
        fjac : float[,] *
        xtol : float *
        maxfev : int *
        mode : int *
        diag : float[] *
        factor : float *
        nprint : int *
        nfev : int byref *
        njev : int byref *
        r : float[] *
        qtf : float[] *
        ifail : int byref -> unit

Parameters

fcn
Type: NagLibrary..::..C05..::..C05RC_FCN
Depending upon the value of iflag, fcn must either return the values of the functions fi at a point x or return the Jacobian at x.

A delegate of type C05RC_FCN.

n
Type: System..::..Int32
On entry: n, the number of equations.
Constraint: n>0.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: an initial guess at the solution vector.
On exit: the final estimate of the solution vector.
fvec
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the function values at the final point returned in x.
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint:
On exit: the orthogonal matrix Q produced by the QR factorization of the final approximate Jacobian.
xtol
Type: System..::..Double
On entry: the accuracy in x to which the solution is required.
Suggested value: ε, where ε is the machine precision returned by x02aj.
Constraint: xtol≥0.0.
maxfev
Type: System..::..Int32
On entry: the maximum number of calls to fcn with iflag≠0. c05rc will exit with ifail=2, if, at the end of an iteration, the number of calls to fcn exceeds maxfev.
Suggested value: maxfev=100×n+1.
Constraint: maxfev>0.
mode
Type: System..::..Int32
On entry: indicates whether or not you have provided scaling factors in diag.
If mode=2 the scaling must have been specified in diag.
Otherwise, if mode=1, the variables will be scaled internally.
Constraint: mode=1 or 2.
diag
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: if mode=2, diag must contain multiplicative scale factors for the variables.
If mode=1, diag need not be set.
Constraint: if mode=2, diag[i-1]>0.0, for i=1,2,…,n.
On exit: the scale factors actually used (computed internally if mode=1).
factor
Type: System..::..Double
On entry: a quantity to be used in determining the initial step bound. In most cases, factor should lie between 0.1 and 100.0. (The step bound is factor×diag×x 2 if this is nonzero; otherwise the bound is factor.)
Suggested value: factor=100.0.
Constraint: factor>0.0.
nprint
Type: System..::..Int32
On entry: indicates whether (and how often) special calls to fcn, with iflag set to 0, are to be made for printing purposes.
nprint≤0
No calls are made.
nprint>0
fcn is called at the beginning of the first iteration, every nprint iterations thereafter and immediately before the return from c05rc.
nfev
Type: System..::..Int32 %
On exit: the number of calls made to fcn to evaluate the functions.
njev
Type: System..::..Int32 %
On exit: the number of calls made to fcn to evaluate the Jacobian.
r
Type: array< System..::..Double >[]()[][]
An array of size [n×n+1/2]
On exit: the upper triangular matrix R produced by the QR factorization of the final approximate Jacobian, stored row-wise.
qtf
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the vector QT f.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The system of equations is defined as:
fi x 1,x 2,…,xn=0,   ​i=1,2,…,n.
c05rc is based on the MINPACK routine HYBRJ (see Moré et al. (1980)). It chooses the correction at each step as a convex combination of the Newton and scaled gradient directions. The Jacobian is updated by the rank-1 method of Broyden. At the starting point, the Jacobian is requested, but it is not asked for again until the rank-1 method fails to produce satisfactory progress. For more details see Powell (1970).

References

Moré J J, Garbow B S and Hillstrom K E (1980) User guide for MINPACK-1 Technical Report ANL-80-74 Argonne National Laboratory
Powell M J D (1970) A hybrid method for nonlinear algebraic equations Numerical Methods for Nonlinear Algebraic Equations (ed P Rabinowitz) Gordon and Breach

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDFJAC) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=2
There have been at least maxfev calls to fcn: maxfev=value. Consider restarting the calculation from the final point held in x.
ifail=3
No further improvement in the solution is possible. xtol is too small: xtol=value.
ifail=4
The iteration is not making good progress, as measured by the improvement from the last value Jacobian evaluations. This failure exit may indicate that the system does not have a zero, or that the solution is very close to the origin (see [Accuracy]). Otherwise, rerunning c05rc from a different starting point may avoid the region of difficulty.
ifail=5
The iteration is not making good progress, as measured by the improvement from the last value iterations. This failure exit may indicate that the system does not have a zero, or that the solution is very close to the origin (see [Accuracy]). Otherwise, rerunning c05rc from a different starting point may avoid the region of difficulty.
ifail=6
iflag was set negative in fcn. iflag=value.
ifail=11
On entry, n=value.
Constraint: n>0.
ifail=12
On entry, xtol=value.
Constraint: xtol≥0.0.
ifail=13
On entry, mode=value.
Constraint: mode=1 or 2.
ifail=14
On entry, factor=value.
Constraint: factor>0.0.
ifail=15
On entry, mode=2 and diag contained a non-positive element.
ifail=18
On entry, maxfev=value.
Constraint: maxfev>0.
ifail=-999
Dynamic memory allocation failed.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

If x^ is the true solution and D denotes the diagonal matrix whose entries are defined by the array diag, then c05rc tries to ensure that
D x-x^2≤xtol×D x^2.
If this condition is satisfied with xtol=10-k, then the larger components of Dx have k significant decimal digits. There is a danger that the smaller components of Dx may have large relative errors, but the fast rate of convergence of c05rc usually obviates this possibility.
If xtol is less than machine precision and the above test is satisfied with the machine precision in place of xtol, then the method exits with ifail=3.
Note: this convergence test is based purely on relative error, and may not indicate convergence if the solution is very close to the origin.
The convergence test assumes that the functions and the Jacobian are coded consistently and that the functions are reasonably well behaved. If these conditions are not satisfied, then c05rc may incorrectly indicate convergence. The coding of the Jacobian can be checked using c05zd. If the Jacobian is coded correctly, then the validity of the answer can be checked by rerunning c05rc with a lower value for xtol.

Parallelism and Performance

None.

Further Comments

Local workspace arrays of fixed lengths are allocated internally by c05rc. The total size of these arrays amounts to 4×n real elements.
The time required by c05rc to solve a given problem depends on n, the behaviour of the functions, the accuracy requested and the starting point. The number of arithmetic operations executed by c05rc is approximately 11.5×n 2 to process each evaluation of the functions and approximately 1.3×n 3 to process each evaluation of the Jacobian. The timing of c05rc is strongly influenced by the time spent evaluating the functions.
Ideally the problem should be scaled so that, at the solution, the function values are of comparable magnitude.

Example

This example determines the values x 1,…,x 9 which satisfy the tridiagonal equations:
3-2 x 1 x 1-2 x 2=-1,-x i-1+3-2 xi xi-2 x i+1=-1,  i=2,3,…,8-x 8+3-2 x 9 x 9=-1.

Example program (C#): c05rce.cs

Example program results: c05rce.r

See Also

C05 Class
C05 Members


c05rd Method

[image]

NAG Library for .NET Release 2
C05..::c05rd Method
C05 Class See Also Send Feedback
c05rd is a comprehensive reverse communication method that finds a solution of a system of nonlinear equations by a modification of the Powell hybrid method. You must provide the Jacobian.

Syntax

C#
public static void c05rd(
    ref int irevcm,
    int n,
    double[] x,
    double[] fvec,
    double[,] fjac,
    double xtol,
    int mode,
    double[] diag,
    double factor,
    double[] r,
    double[] qtf,
    C05..::..c05rdCommunications communications,
    out int ifail
)
Visual Basic
Public Shared Sub c05rd ( _
    ByRef irevcm As Integer, _
    n As Integer, _
    x As Double(), _
    fvec As Double(), _
    fjac As Double(,), _
    xtol As Double, _
    mode As Integer, _
    diag As Double(), _
    factor As Double, _
    r As Double(), _
    qtf As Double(), _
    communications As C05..::..c05rdCommunications, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void c05rd(
    int% irevcm,
    int n,
    array<double>^ x,
    array<double>^ fvec,
    array<double,2>^ fjac,
    double xtol,
    int mode,
    array<double>^ diag,
    double factor,
    array<double>^ r,
    array<double>^ qtf,
    C05..::..c05rdCommunications^ communications,
    [OutAttribute] int% ifail
)
F#
static member c05rd :
        irevcm : int byref *
        n : int *
        x : float[] *
        fvec : float[] *
        fjac : float[,] *
        xtol : float *
        mode : int *
        diag : float[] *
        factor : float *
        r : float[] *
        qtf : float[] *
        communications : C05..::..c05rdCommunications *
        ifail : int byref -> unit

Parameters

irevcm
Type: System..::..Int32 %
On initial entry: must have the value 0.
On intermediate exit: specifies what action you must take before re-entering c05rd with irevcm unchanged. The value of irevcm should be interpreted as follows:
irevcm=1
Indicates the start of a new iteration. No action is required by you, but x and fvec are available for printing.
irevcm=2
Indicates that before re-entry to c05rd, fvec must contain the function values fi x.
irevcm=3
Indicates that before re-entry to c05rd, fjac[i-1,j-1] must contain the value of ∂fi∂xj at the point x, for i=1,2,…,n and j=1,2,…,n.
On final exit: irevcm=0, and the algorithm has terminated.
Constraint: irevcm=0, 1, 2 or 3.
n
Type: System..::..Int32
On entry: n, the number of equations.
Constraint: n>0.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On initial entry: an initial guess at the solution vector.
On intermediate exit: contains the current point.
On final exit: the final estimate of the solution vector.
fvec
Type: array< System..::..Double >[]()[][]
An array of size [n]
On initial entry: need not be set.
On intermediate re-entry: if irevcm≠2, fvec must not be changed.
If irevcm=2, fvec must be set to the values of the functions computed at the current point x.
On final exit: the function values at the final point, x.
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [n, n]
On initial entry: need not be set.
On intermediate re-entry: if irevcm≠3, fjac must not be changed.
If irevcm=3, fjac[i-1,j-1] must contain the value of ∂fi∂xj at the point x, for i=1,2,…,n and j=1,2,…,n.
On final exit: the orthogonal matrix Q produced by the QR factorization of the final approximate Jacobian.
xtol
Type: System..::..Double
On initial entry: the accuracy in x to which the solution is required.
Suggested value: ε, where ε is the machine precision returned by x02aj.
Constraint: xtol≥0.0.
mode
Type: System..::..Int32
On initial entry: indicates whether or not you have provided scaling factors in diag.
If mode=2 the scaling must have been supplied in diag.
Otherwise, if mode=1, the variables will be scaled internally.
Constraint: mode=1 or 2.
diag
Type: array< System..::..Double >[]()[][]
An array of size [n]
On initial entry: if mode=2, diag must contain multiplicative scale factors for the variables.
If mode=1, diag need not be set.
Constraint: if mode=2, diag[i-1]>0.0, for i=1,2,…,n.
On intermediate exit: diag must not be changed.
On final exit: the scale factors actually used (computed internally if mode=1).
factor
Type: System..::..Double
On initial entry: a quantity to be used in determining the initial step bound. In most cases, factor should lie between 0.1 and 100.0. (The step bound is factor×diag×x 2 if this is nonzero; otherwise the bound is factor.)
Suggested value: factor=100.0.
Constraint: factor>0.0.
r
Type: array< System..::..Double >[]()[][]
An array of size [n×n+1/2]
On initial entry: need not be set.
On intermediate exit: must not be changed.
On final exit: the upper triangular matrix R produced by the QR factorization of the final approximate Jacobian, stored row-wise.
qtf
Type: array< System..::..Double >[]()[][]
An array of size [n]
On initial entry: need not be set.
On intermediate exit: must not be changed.
On final exit: the vector QT f.
communications
Type: NagLibrary..::..C05..::..c05rdCommunications
An Object of type C05.c05rdCommunications.
ifail
Type: System..::..Int32 %
On initial entry: ifail must be set to 0, -1​ or ​1. If you are unfamiliar with this parameter you should refer to Library Overview for details.
For environments where it might be inappropriate to halt program execution when an error is detected, the value -1​ or ​1 is recommended. If the output of error messages is undesirable, then the value 1 is recommended. Otherwise, because for this method the values of the output parameters may be useful even if ifail≠0 on exit, the recommended value is -1. When the value -1​ or ​1 is used it is essential to test the value of ifail on exit.
On final exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The system of equations is defined as:
fi x 1,x 2,…,xn=0,  i=1,2,…,n.
c05rd is based on the MINPACK routine HYBRJ (see Moré et al. (1980)). It chooses the correction at each step as a convex combination of the Newton and scaled gradient directions. The Jacobian is updated by the rank-1 method of Broyden. For more details see Powell (1970).

References

Moré J J, Garbow B S and Hillstrom K E (1980) User guide for MINPACK-1 Technical Report ANL-80-74 Argonne National Laboratory
Powell M J D (1970) A hybrid method for nonlinear algebraic equations Numerical Methods for Nonlinear Algebraic Equations (ed P Rabinowitz) Gordon and Breach

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=2
On entry, irevcm=value.
Constraint: irevcm=0, 1, 2 or 3.
ifail=3
No further improvement in the solution is possible. xtol is too small: xtol=value.
ifail=4
The iteration is not making good progress, as measured by the improvement from the last value Jacobian evaluations. This failure exit may indicate that the system does not have a zero, or that the solution is very close to the origin (see [Accuracy]). Otherwise, rerunning c05rd from a different starting point may avoid the region of difficulty.
ifail=5
The iteration is not making good progress, as measured by the improvement from the last value iterations. This failure exit may indicate that the system does not have a zero, or that the solution is very close to the origin (see [Accuracy]). Otherwise, rerunning c05rd from a different starting point may avoid the region of difficulty.
ifail=11
On entry, n=value.
Constraint: n>0.
ifail=12
On entry, xtol=value.
Constraint: xtol≥0.0.
ifail=13
On entry, mode=value.
Constraint: mode=1 or 2.
ifail=14
On entry, factor=value.
Constraint: factor>0.0.
ifail=15
On entry, mode=2 and diag contained a non-positive element.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-3001
parameter : n passed into the options/communications class constructor is invalid
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

If x^ is the true solution and D denotes the diagonal matrix whose entries are defined by the array diag, then c05rd tries to ensure that
D x-x^2≤xtol×D x^2.
If this condition is satisfied with xtol=10-k, then the larger components of Dx have k significant decimal digits. There is a danger that the smaller components of Dx may have large relative errors, but the fast rate of convergence of c05rd usually obviates this possibility.
If xtol is less than machine precision and the above test is satisfied with the machine precision in place of xtol, then the method exits with ifail=3.
Note: this convergence test is based purely on relative error, and may not indicate convergence if the solution is very close to the origin.
The convergence test assumes that the functions and the Jacobian are coded consistently and that the functions are reasonably well behaved. If these conditions are not satisfied, then c05rd may incorrectly indicate convergence. The coding of the Jacobian can be checked using c05zd. If the Jacobian is coded correctly, then the validity of the answer can be checked by rerunning c05rd with a lower value for xtol.

Parallelism and Performance

None.

Further Comments

The time required by c05rd to solve a given problem depends on n, the behaviour of the functions, the accuracy requested and the starting point. The number of arithmetic operations executed by c05rd is approximately 11.5×n 2 to process each evaluation of the functions and approximately 1.3×n 3 to process each evaluation of the Jacobian. The timing of c05rd is strongly influenced by the time spent evaluating the functions.
Ideally the problem should be scaled so that, at the solution, the function values are of comparable magnitude.

Example

This example determines the values x 1,…,x 9 which satisfy the tridiagonal equations:
3-2 x 1 x 1-2 x 2=-1,-x i-1+3-2 xi xi-2 x i+1=-1,  i=2,3,…,8-x 8+3-2 x 9 x 9=-1.

Example program (C#): c05rde.cs

Example program results: c05rde.r

See Also

C05 Class
C05 Members


c05zd Method

[image]

NAG Library for .NET Release 2
C05..::c05zd Method
C05 Class See Also Send Feedback
c05zd checks the user-supplied gradients of a set of nonlinear functions in several variables, for consistency with the functions themselves. The method must be called twice.

Syntax

C#
public static void c05zd(
    int mode,
    int m,
    int n,
    double[] x,
    double[] fvec,
    double[,] fjac,
    double[] xp,
    double[] fvecp,
    double[] err,
    out int ifail
)
Visual Basic
Public Shared Sub c05zd ( _
    mode As Integer, _
    m As Integer, _
    n As Integer, _
    x As Double(), _
    fvec As Double(), _
    fjac As Double(,), _
    xp As Double(), _
    fvecp As Double(), _
    err As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void c05zd(
    int mode,
    int m,
    int n,
    array<double>^ x,
    array<double>^ fvec,
    array<double,2>^ fjac,
    array<double>^ xp,
    array<double>^ fvecp,
    array<double>^ err,
    [OutAttribute] int% ifail
)
F#
static member c05zd :
        mode : int *
        m : int *
        n : int *
        x : float[] *
        fvec : float[] *
        fjac : float[,] *
        xp : float[] *
        fvecp : float[] *
        err : float[] *
        ifail : int byref -> unit

Parameters

mode
Type: System..::..Int32
On entry: the value 1 on the first call and the value 2 on the second call of c05zd.
Constraint: mode=1 or 2.
m
Type: System..::..Int32
On entry: m, the number of functions.
Constraint: m≥1.
n
Type: System..::..Int32
On entry: n, the number of variables. For use with c05rb, c05rc and c05rd, m=n.
Constraint: n≥1.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the components of a point x, at which the consistency check is to be made. (See [Accuracy].)
fvec
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: if mode=2, fvec must contain the value of the functions evaluated at x. If mode=1, fvec is not referenced.
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [m, n]
On entry: if mode=2, fjac must contain the value of ∂fi∂xj at the point x, for i=1,2,…,m and j=1,2,…,n. If mode=1, fjac is not referenced.
xp
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: if mode=1, xp is set to a point neighbouring x. If mode=2, xp is undefined.
fvecp
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: if mode=2, fvecp must contain the value of the functions evaluated at xp (as output by a preceding call to c05zd with mode=1). If mode=1, fvecp is not referenced.
err
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: if mode=2, err contains measures of correctness of the respective gradients. If mode=1, err is undefined. If there is no loss of significance (see [Accuracy]), then if err[i-1] is 1.0 the ith user-supplied gradient ∂fi∂xj, for j=1,2,…,n is correct, whilst if err[i-1] is 0.0 the ith gradient is incorrect. For values of err[i-1] between 0.0 and 1.0 the categorisation is less certain. In general, a value of err[i-1]>0.5 indicates that the ith gradient is probably correct.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

c05zd is based on the MINPACK routine CHKDER (see Moré et al. (1980)). It checks the ith gradient for consistency with the ith function by computing a forward-difference approximation along a suitably chosen direction and comparing this approximation with the user-supplied gradient along the same direction. The principal characteristic of c05zd is its invariance under changes in scale of the variables or functions.

References

Moré J J, Garbow B S and Hillstrom K E (1980) User guide for MINPACK-1 Technical Report ANL-80-74 Argonne National Laboratory

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, mode=value.
Constraint: mode=1 or 2.
ifail=2
On entry, m=value.
Constraint: m≥1.
ifail=3
On entry, n=value.
Constraint: n≥1.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

c05zd does not perform reliably if cancellation or rounding errors cause a severe loss of significance in the evaluation of a function. Therefore, none of the components of x should be unusually small (in particular, zero) or any other value which may cause loss of significance. The relative differences between corresponding elements of fvecp and fvec should be at least two orders of magnitude greater than the machine precision returned by x02aj.

Parallelism and Performance

None.

Further Comments

The time required by c05zd increases with m and n.

Example

This example checks the Jacobian matrix for a problem with 15 functions of 3 variables (sometimes referred to as the Bard problem).

Example program (C#): c05zde.cs

Example program results: c05zde.r

See Also

C05 Class
C05 Members


C06 Class

[image]

NAG Library for .NET Release 2
C06 Class
Members See Also Send Feedback
This chapter is concerned with the following tasks.
(a) | Calculating the discrete Fourier transform of a sequence of real or complex data values.
(b) | Calculating the discrete convolution or the discrete correlation of two sequences of real or complex data values using discrete Fourier transforms.
(c) | Calculating the inverse Laplace transform of a user-supplied method.
(d) | Direct summation of orthogonal series.
(e) | Acceleration of convergence of a seuqnce of real values.

Syntax

C#
public static class C06
Visual Basic
Public NotInheritable Class C06
Visual C++
public ref class C06 abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type C06 =  class end

Background to the Problems

Discrete Fourier Transforms

Complex transforms

Most of the methods in this chapter calculate the finite discrete Fourier transform (DFT) of a sequence of n complex numbers zj, for j=0,1,…,n-1. The direct transform is defined by
z^k=1 n∑j=0n-1 zj exp-i 2 πjk n (1)
for k=0,1,…,n-1. Note that equation (1) makes sense for all integral k and with this extension z^k is periodic with period n, i.e., z^k=z^k±n, and in particular z^-k=z^n-k. Note also that the scale-factor of 1 n may be omitted in the definition of the DFT, and replaced by 1 n in the definition of the inverse.
If we write zj=xj+i yj and z^k=ak+i bk, then the definition of z^k may be written in terms of sines and cosines as
ak=1 n∑j=0n-1 xj cos 2 πjk n+yj sin 2 πjk n
bk=1 n∑j=0n-1 yj cos 2 πjk n-xj sin 2 πjk n.
The original data values zj may conversely be recovered from the transform z^k by an inverse discrete Fourier transform:
zj=1 n∑k=0n-1 z^k exp+i 2 πjk n (2)
for j=0,1,…,n-1. If we take the complex conjugate of (2), we find that the sequence z-j is the DFT of the sequence z^-k. Hence the inverse DFT of the sequence z^k may be obtained by taking the complex conjugates of the z^k; performing a DFT, and taking the complex conjugates of the result. (Note that the terms forward transform and backward transform are also used to mean the direct and inverse transforms respectively.)
The definition (1) of a one-dimensional transform can easily be extended to multidimensional transforms. For example, in two dimensions we have
z^k 1k 2=1 n 1n 2∑j 1=0n 1-1∑j 2=0n 2-1 z j 1j 2 exp-i 2 π j 1k 1 n 1exp-i 2 π j 2k 2 n 2. (3)
Note: definitions of the discrete Fourier transform vary. Sometimes (2) is used as the definition of the DFT, and (1) as the definition of the inverse.

Real transforms

If the original sequence is purely real valued, i.e., zj=xj, then
z^k=ak+i bk=1 n∑j=0n-1 xj exp-i 2 πjk n
and z^n-k is the complex conjugate of z^k. Thus the DFT of a real sequence is a particular type of complex sequence, called a Hermitian sequence, or half-complex or conjugate symmetric, with the properties
a n-k=ak b n-k=-b k b 0=0
and, if n is even, b n/2=0.
Thus a Hermitian sequence of n complex data values can be represented by only n, rather than 2 n, independent real values. This can obviously lead to economies in storage, with two schemes being used in this chapter. In the first (deprecated) scheme, which will be referred to as the real storage format for Hermitian sequences, the real parts ak for 0≤k≤n/2 are stored in normal order in the first n/2+1 locations of an array x of length n; the corresponding nonzero imaginary parts are stored in reverse order in the remaining locations of x. To clarify, if x is declared with bounds 0:n-1 in your calling method, the following two tables illustrate the storage of the real and imaginary parts of z^k for the two cases: n even and n odd.
If n is even then the sequence has two purely real elements and is stored as follows:
Index of x | 0 | 1 | 2 | … | n/2 | … | n-2 | n-1
Sequence | a 0 | a 1+ib 1 | a 2+ib 2 | … | a n/2 | … | a 2-ib 2 | a 1-ib 1
Stored values | a 0 | a 1 | a 2 | … | a n/2 | … | b 2 | b 1
x[k]=ak,for ​k=0,1,…,n/2, andx[n-k]=bk,for ​k=1,2,…,n/2-1.
If n is odd then the sequence has one purely real element and, letting n=2 s+1, is stored as follows:
Index of x | 0 | 1 | 2 | … | s | s+1 | … | n-2 | n-1
Sequence | a 0 | a 1+ib 1 | a 2+ib 2 | … | as+i bs | as-i bs | … | a 2-ib 2 | a 1-ib 1
Stored values | a 0 | a 1 | a 2 | … | as | bs | … | b 2 | b 1
x[k]=ak,for ​k=0,1,…,s, andx[n-k]=bk,for ​k=1,2,…,s.
The second (recommended) storage scheme, referred to in this chapter as the complex storage format for Hermitian sequences, stores the real and imaginary parts ak,bk, for 0≤k≤n/2, in consecutive locations of an array x of length n+2. If x is declared with bounds 0:n+1 in your calling method, the following two tables illustrate the storage of the real and imaginary parts of z^k for the two cases: n even and n odd.
If n is even then the sequence has two purely real elements and is stored as follows:
Index of x | 0 | 1 | 2 | 3 | … | n-2 | n-1 | n | n+1
Stored values | a 0 | b 0=0 | a 1 | b 1 | … | a n/2-1 | b n/2-1 | a n/2 | b n/2=0
x[2×k-1]=ak,for ​k=0,1,…,n/2, andx[2×k+1-1]=bk,for ​k=0,1,…,n/2.
If n is odd then the sequence has one purely real element and, letting n=2 s+1, is stored as follows:
Index of x | 0 | 1 | 2 | 3 | … | n-2 | n-1 | n | n+1
Stored values | a 0 | b 0=0 | a 1 | b 1 | … | b s-1 | as | bs | 0
x[2×k-1]=ak,for ​k=0,1,…,s, andx[2×k+1-1]=bk,for ​k=0,1,…,s.
Also, given a Hermitian sequence, the inverse (or backward) discrete transform produces a real sequence. That is,
xj=1 n a 0+2∑k=1n/2-1 ak cos 2 πjk n-bk sin 2 πjk n+a n/2
where a n/2=0 if n is odd.
For real data that is two-dimensional or higher, the symmetry in the transform persists for the leading dimension only. So, using the notation of equation (3) for the complex two-dimensional discrete transform, we have that z^k 1k 2 is the complex conjugate of z^n 1-k 1 k 2. It is more convenient for transformed data of two or more dimensions to be stored as a complex sequence of length n 1/2+1×n 2×⋯×nd where d is the number of dimensions. The inverse discrete Fourier transform operating on such a complex sequence (Hermitian in the leading dimension) returns a real array of full dimension (n 1×n 2×⋯×nd).

Real symmetric transforms

In many applications the sequence xj will not only be real, but may also possess additional symmetries which we may exploit to reduce further the computing time and storage requirements. For example, if the sequence xj is odd, xj=-xn-j, then the discrete Fourier transform of xj contains only sine terms. Rather than compute the transform of an odd sequence, we define the sine transform of a real sequence by
x^k=2 n∑j=1n-1 xj sin πjk n,
which could have been computed using the Fourier transform of a real odd sequence of length 2 n. In this case the xj are arbitrary, and the symmetry only becomes apparent when the sequence is extended. Similarly we define the cosine transform of a real sequence by
x^k=2 n 12 x 0+∑j=1n-1 xj cos πjk n+12-1 k xn
which could have been computed using the Fourier transform of a real even sequence of length 2 n.
In addition to these ‘half-wave’ symmetries described above, sequences arise in practice with ‘quarter-wave’ symmetries. We define the quarter-wave sine transform by
x^k=1 n∑j=1n-1 xj sin πj 2 k-12 n+12-1 k-1 xn
which could have been computed using the Fourier transform of a real sequence of length 4 n of the form
0,x 1,…,xn,x n-1,…,x 1,0,-x 1,…,-x n,-xn-1,…,-x 1.
Similarly we may define the quarter-wave cosine transform by
x^k=1 n 12 x 0+∑j=1n-1 xj cos πj 2 k-12 n
which could have been computed using the Fourier transform of a real sequence of length 4 n of the form
x 0,x 1,…,x n-1,0,-xn-1,…,-x 0,-x 1,…,-xn-1,0,x n-1,…,x 1.

Fourier integral transforms

The usual application of the discrete Fourier transform is that of obtaining an approximation of the Fourier integral transform
F s=∫-∞∞f t exp-i 2 πstdt
when f t is negligible outside some region 0,c. Dividing the region into n equal intervals we have
F s≅cn∑j=0n-1 fj exp-i 2 πsjcn
and so
Fk≅cn∑j=0n-1 fj exp-i 2 π jkn
for k=0,1,…,n-1, where fj=f jc/n and Fk=F k/c.
Hence the discrete Fourier transform gives an approximation to the Fourier integral transform in the region s=0 to s=n/c.
If the function f t is defined over some more general interval a,b, then the integral transform can still be approximated by the discrete transform provided a shift is applied to move the point a to the origin.

Convolutions and correlations

One of the most important applications of the discrete Fourier transform is to the computation of the discrete convolution or correlation of two vectors x and y defined (as in Brigham (1974)) by
  • convolution: zk=∑j=0n-1 xjy k-j
  • correlation: wk=∑j=0n-1 x-jy k+j
(Here x and y are assumed to be periodic with period n.)
Under certain circumstances (see Brigham (1974)) these can be used as approximations to the convolution or correlation integrals defined by
z s=∫-∞∞x t y s-t dt
and
w s=∫-∞∞x-t y s+t dt,  -∞<s<∞.
For more general advice on the use of Fourier transforms, see Hamming (1962); more detailed information on the fast Fourier transform algorithm can be found in Gentleman and Sande (1966) and Brigham (1974).

Applications to solving partial differential equations (PDEs)

A further application of the fast Fourier transform, and in particular of the Fourier transforms of symmetric sequences, is in the solution of elliptic PDEs. If an equation is discretized using finite differences, then it is possible to reduce the problem of solving the resulting large system of linear equations to that of solving a number of tridiagonal systems of linear equations. This is accomplished by uncoupling the equations using Fourier transforms, where the nature of the boundary conditions determines the choice of transforms – see [Application to Elliptic Partial Differential Equations]. Full details of the Fourier method for the solution of PDEs may be found in Swarztrauber (1977) and Swarztrauber (1984).

Inverse Laplace Transforms

Let f t be a real function of t, with f t=0 for t<0, and be piecewise continuous and of exponential order α, i.e.,
f t≤M e αt
for large t, where α is the minimal such exponent.
The Laplace transform of f t is given by
F s=∫0∞e-st f t dt,  t>0
where F s is defined for Re s>α.
The inverse transform is defined by the Bromwich integral
f t=1 2 πi∫a-i∞a+i∞e st F s ds,  t>0.
The integration is performed along the line s=a in the complex plane, where a>α. This is equivalent to saying that the line s=a lies to the right of all singularities of F s. For this reason, the value of α is crucial to the correct evaluation of the inverse. It is not essential to know α exactly, but an upper bound must be known.
The problem of determining an inverse Laplace transform may be classified according to whether (a) F s is known for real values only, or (b) F s is known in functional form and can therefore be calculated for complex values of s. Problem (a) is very ill-defined and no methods are provided. Two methods are provided for problem (b).

Direct Summation of Orthogonal Series

For any series of functions ϕi which satisfy a recurrence
ϕ r+1 x+αr x ϕr x+βr x ϕ r-1 x=0
the sum
∑r=0 n arϕr x
is given by
∑r=0 n arϕr x=b 0 x ϕ 0 x+b 1 xϕ 1 x+α 0 x ϕ 0 x
where
br x+αr x b r+1 x+β r+1 x b r+2 x=arb n+1 x=b n+2 x=0.
This may be used to compute the sum of the series. For further reading, see Hamming (1962).

Acceleration of Convergence

This device has applications in a large number of fields, such as summation of series, calculation of integrals with oscillatory integrands (including, for example, Hankel transforms), and root-finding. The mathematical description is as follows. Given a sequence of values sn, for n=m,…,m+2 l, then, except in certain singular cases, parameters, a, bi, ci may be determined such that
sn=a+∑i=1 l bi cin.
If the sequence sn converges, then a may be taken as an estimate of the limit. The method will also find a pseudo-limit of certain divergent sequences – see Shanks (1955) for details.
To use the method to sum a series, the terms sn of the sequence should be the partial sums of the series, e.g., sn=∑k=1 n tk, where tk is the kth term of the series. The algorithm can also be used to some advantage to evaluate integrals with oscillatory integrands; one approach is to write the integral (in this case over a semi-infinite interval) as
∫0∞f x dx=∫0 a 1 f x dx+∫a 1a 2 f x dx+∫a 2a 3 f x dx+…
and to consider the sequence of values
s 1=∫0 a 1 f x dx,  s 2=∫0 a 2 f x dx=s 1+∫a 1a 2 f x dx, etc.,
where the integrals are evaluated using standard quadrature methods. In choosing the values of the ak, it is worth bearing in mind that (C06BAF not in this release) converges much more rapidly for sequences whose values oscillate about a limit. The ak should thus be chosen to be (close to) the zeros of f x, so that successive contributions to the integral are of opposite sign. As an example, consider the case where f x=M x sin x and M x>0: convergence will be much improved if ak=kπ rather than ak=2 kπ.

References

Brigham E O (1974) The Fast Fourier Transform Prentice–Hall
Davies S B and Martin B (1979) Numerical inversion of the Laplace transform: A survey and comparison of methods J. Comput. Phys. 33 1–32
Fox L and Parker I B (1968) Chebyshev Polynomials in Numerical Analysis Oxford University Press
Gentleman W S and Sande G (1966) Fast Fourier transforms for fun and profit Proc. Joint Computer Conference, AFIPS 29 563–578
Hamming R W (1962) Numerical Methods for Scientists and Engineers McGraw–Hill
Shanks D (1955) Nonlinear transformations of divergent and slowly convergent sequences J. Math. Phys. 34 1–42
Swarztrauber P N (1977) The methods of cyclic reduction, Fourier analysis and the FACR algorithm for the discrete solution of Poisson's equation on a rectangle SIAM Rev. 19(3) 490–501
Swarztrauber P N (1984) Fast Poisson solvers Studies in Numerical Analysis (ed G H Golub) Mathematical Association of America
Swarztrauber P N (1986) Symmetric FFT's Math. Comput. 47(175) 323–346
Wynn P (1956) On a device for computing the em Sn transformation Math. Tables Aids Comput. 10 91–96

Inheritance Hierarchy

System..::..Object
NagLibrary..::..C06

See Also

C06 Members


C06 Members

[image] [image]

NAG Library for .NET Release 2
C06 Members
C06 Class Methods See Also Send Feedback

The C06 type exposes the following members.

Methods

Name | Description
c06ea | c06ea calculates the discrete Fourier transform of a sequence of n real data values. (No extra workspace required.)
c06eb | c06eb calculates the discrete Fourier transform of a Hermitian sequence of n complex data values. (No extra workspace required.)
c06fp | c06fp computes the discrete Fourier transforms of m sequences, each containing n real data values. This method is designed to be particularly efficient on vector processors.
c06fq | c06fq computes the discrete Fourier transforms of m Hermitian sequences, each containing n complex data values. This method is designed to be particularly efficient on vector processors.
c06gb | c06gb forms the complex conjugate of a Hermitian sequence of n data values.
c06gq | c06gq forms the complex conjugates of m Hermitian sequences, each containing n data values.
c06gs | c06gs takes m Hermitian sequences, each containing n data values, and forms the real and imaginary parts of the m corresponding complex sequences.

See Also

C06 Class


C06 Methods

[image] [image]

NAG Library for .NET Release 2
C06 Methods
C06 Class See Also Send Feedback

The C06 type exposes the following members.

Methods

Name | Description
c06ea | c06ea calculates the discrete Fourier transform of a sequence of n real data values. (No extra workspace required.)
c06eb | c06eb calculates the discrete Fourier transform of a Hermitian sequence of n complex data values. (No extra workspace required.)
c06fp | c06fp computes the discrete Fourier transforms of m sequences, each containing n real data values. This method is designed to be particularly efficient on vector processors.
c06fq | c06fq computes the discrete Fourier transforms of m Hermitian sequences, each containing n complex data values. This method is designed to be particularly efficient on vector processors.
c06gb | c06gb forms the complex conjugate of a Hermitian sequence of n data values.
c06gq | c06gq forms the complex conjugates of m Hermitian sequences, each containing n data values.
c06gs | c06gs takes m Hermitian sequences, each containing n data values, and forms the real and imaginary parts of the m corresponding complex sequences.

See Also

C06 Class


c06ea Method

[image]

NAG Library for .NET Release 2
C06..::c06ea Method
C06 Class See Also Send Feedback
c06ea calculates the discrete Fourier transform of a sequence of n real data values. (No extra workspace required.)

Syntax

C#
public static void c06ea(
    double[] x,
    int n,
    out int ifail
)
Visual Basic
Public Shared Sub c06ea ( _
    x As Double(), _
    n As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void c06ea(
    array<double>^ x,
    int n,
    [OutAttribute] int% ifail
)
F#
static member c06ea :
        x : float[] *
        n : int *
        ifail : int byref -> unit

Parameters

x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: if x is declared with bounds 0:n-1 in the method from which c06ea is called, then x[j] must contain xj, for j=0,1,…,n-1.
On exit: the discrete Fourier transform stored in Hermitian form. If the components of the transform z^k are written as ak+i bk, and if x is declared with bounds 0:n-1 in the method from which c06ea is called, then for 0≤k≤n/2, ak is contained in x[k-1], and for 1≤k≤n-1/2, bk is contained in x[n-k]. (See also [] in the C06 class Chapter Introduction and [Example].)
n
Type: System..::..Int32
On entry: n, the number of data values. The largest prime factor of n must not exceed 19, and the total number of prime factors of n, counting repetitions, must not exceed 20.
Constraint: n>1.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Given a sequence of n real data values xj, for j=0,1,…,n-1, c06ea calculates their discrete Fourier transform defined by
z^k=1 n∑j=0n-1 xj×exp-i 2 πjk n,  k=0,1,…,n-1.
(Note the scale factor of 1 n in this definition.) The transformed values z^k are complex, but they form a Hermitian sequence (i.e., z^n-k is the complex conjugate of z^k), so they are completely determined by n real numbers (see also the C06 class).
To compute the inverse discrete Fourier transform defined by
w^k=1 n∑j=0n-1 xj×exp+i 2 πjk n,
this method should be followed by a call of c06gb to form the complex conjugates of the z^k.
c06ea uses the fast Fourier transform (FFT) algorithm (see Brigham (1974)). There are some restrictions on the value of n (see [Parameters]).

References

Brigham E O (1974) The Fast Fourier Transform Prentice–Hall

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
At least one of the prime factors of n is greater than 19.
ifail=2
n has more than 20 prime factors.
ifail=3
On entry, n≤1.
ifail=4
An unexpected error has occurred in an internal call. Check all method calls and array dimensions. Seek expert help.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Some indication of accuracy can be obtained by performing a subsequent inverse transform and comparing the results with the original sequence (in exact arithmetic they would be identical).

Parallelism and Performance

None.

Further Comments

The time taken is approximately proportional to n×log n, but also depends on the factorization of n. c06ea is faster if the only prime factors of n are 2, 3 or 5; and fastest of all if n is a power of 2.
On the other hand, c06ea is particularly slow if n has several unpaired prime factors, i.e., if the ‘square-free’ part of n has several factors. For such values of n, (C06FAF not in this release) (which requires additional real workspace) is considerably faster.

Example

Example program (C#): c06eae.cs

Example program data: c06eae.d

Example program results: c06eae.r

See Also

C06 Class
C06 Members


c06eb Method

[image]

NAG Library for .NET Release 2
C06..::c06eb Method
C06 Class See Also Send Feedback
c06eb calculates the discrete Fourier transform of a Hermitian sequence of n complex data values. (No extra workspace required.)

Syntax

C#
public static void c06eb(
    double[] x,
    int n,
    out int ifail
)
Visual Basic
Public Shared Sub c06eb ( _
    x As Double(), _
    n As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void c06eb(
    array<double>^ x,
    int n,
    [OutAttribute] int% ifail
)
F#
static member c06eb :
        x : float[] *
        n : int *
        ifail : int byref -> unit

Parameters

x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the sequence to be transformed stored in Hermitian form. If the data values zj are written as xj+i yj, and if x is declared with bounds 0:n-1 in the method from which c06eb is called, then for 0≤j≤n/2, xj is contained in x[j-1], and for 1≤j≤n-1/2, yj is contained in x[n-j]. (See also [] in the C06 class Chapter Introduction and [Example].)
On exit: the components of the discrete Fourier transform x^k. If x is declared with bounds 0:n-1 in the method from which c06eb is called, then x^k is stored in x[k], for k=0,1,…,n-1.
n
Type: System..::..Int32
On entry: n, the number of data values. The largest prime factor of n must not exceed 19, and the total number of prime factors of n, counting repetitions, must not exceed 20.
Constraint: n>1.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Given a Hermitian sequence of n complex data values zj (i.e., a sequence such that z 0 is real and z n-j is the complex conjugate of zj, for j=1,2,…,n-1), c06eb calculates their discrete Fourier transform defined by
x^k=1 n∑j=0n-1 zj×exp-i 2 πjk n,  k=0,1,…,n-1.
(Note the scale factor of 1 n in this definition.) The transformed values x^k are purely real (see also the C06 class).
To compute the inverse discrete Fourier transform defined by
y^k=1 n∑j=0n-1 zj×exp+i 2 πjk n,
this method should be preceded by a call of c06gb to form the complex conjugates of the zj.
c06eb uses the fast Fourier transform (FFT) algorithm (see Brigham (1974)). There are some restrictions on the value of n (see [Parameters]).

References

Brigham E O (1974) The Fast Fourier Transform Prentice–Hall

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
At least one of the prime factors of n is greater than 19.
ifail=2
n has more than 20 prime factors.
ifail=3
On entry, n≤1.
ifail=4
An unexpected error has occurred in an internal call. Check all method calls and array dimensions. Seek expert help.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Some indication of accuracy can be obtained by performing a subsequent inverse transform and comparing the results with the original sequence (in exact arithmetic they would be identical).

Parallelism and Performance

None.

Further Comments

The time taken is approximately proportional to n×log n, but also depends on the factorization of n. c06eb is faster if the only prime factors of n are 2, 3 or 5; and fastest of all if n is a power of 2.
On the other hand, c06eb is particularly slow if n has several unpaired prime factors, i.e., if the ‘square-free’ part of n has several factors. For such values of n, (C06FBF not in this release) (which requires an additional n elements of workspace) is considerably faster.

Example

Example program (C#): c06ebe.cs

Example program data: c06ebe.d

Example program results: c06ebe.r

See Also

C06 Class
C06 Members


c06fp Method

[image]

NAG Library for .NET Release 2
C06..::c06fp Method
C06 Class See Also Send Feedback
c06fp computes the discrete Fourier transforms of m sequences, each containing n real data values. This method is designed to be particularly efficient on vector processors.

Syntax

C#
public static void c06fp(
    int m,
    int n,
    double[] x,
    string init,
    double[] trig,
    out int ifail
)
Visual Basic
Public Shared Sub c06fp ( _
    m As Integer, _
    n As Integer, _
    x As Double(), _
    init As String, _
    trig As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void c06fp(
    int m,
    int n,
    array<double>^ x,
    String^ init,
    array<double>^ trig,
    [OutAttribute] int% ifail
)
F#
static member c06fp :
        m : int *
        n : int *
        x : float[] *
        init : string *
        trig : float[] *
        ifail : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: m, the number of sequences to be transformed.
Constraint: m≥1.
n
Type: System..::..Int32
On entry: n, the number of real values in each sequence.
Constraint: n≥1.
x
Type: array< System..::..Double >[]()[][]
An array of size [m×n]
On entry: the data must be stored in x as if in a two-dimensional array of dimension 1:m,0:n-1; each of the m sequences is stored in a row of the array. In other words, if the data values of the pth sequence to be transformed are denoted by xjp, for j=0,1,…,n-1, then the mn elements of the array x must contain the values
x 01,x 02,…,x 0 m,x 11,x 12,…,x 1 m,…,x n-1 1,x n-1 2,…,x n-1 m.
On exit: the m discrete Fourier transforms stored as if in a two-dimensional array of dimension 1:m,0:n-1. Each of the m transforms is stored in a row of the array in Hermitian form, overwriting the corresponding original sequence. If the n components of the discrete Fourier transform z^kp are written as akp+i bkp, then for 0≤k≤n/2, akp is contained in x[p-1,k-1], and for 1≤k≤n-1/2, bkp is contained in x[p-1,n-k-1]. (See also [] in the C06 class Chapter Introduction.)
init
Type: System..::..String
On entry: indicates whether trigonometric coefficients are to be calculated.
init="I"
Calculate the required trigonometric coefficients for the given value of n, and store in the array trig.
init="S" or "R"
The required trigonometric coefficients are assumed to have been calculated and stored in the array trig in a prior call to one of c06fp, c06fq or c06fr. The method performs a simple check that the current value of n is consistent with the values stored in trig.
Constraint: init="I", "S" or "R".
trig
Type: array< System..::..Double >[]()[][]
An array of size [2×n]
On entry: if init="S" or "R", trig must contain the required trigonometric coefficients that have been previously calculated. Otherwise trig need not be set.
On exit: contains the required coefficients (computed by the method if init="I").
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Given m sequences of n real data values xjp, for j=0,1,…,n-1 and p=1,2,…,m, c06fp simultaneously calculates the Fourier transforms of all the sequences defined by
z^kp=1 n∑j=0n-1 xjp×exp-i 2 πjk n,  k=0,1,…,n-1​ and ​p=1,2,…,m.
(Note the scale factor 1 n in this definition.)
The transformed values z^kp are complex, but for each value of p the z^kp form a Hermitian sequence (i.e., z^n-k p is the complex conjugate of z^kp), so they are completely determined by mn real numbers (see also the C06 class).
The discrete Fourier transform is sometimes defined using a positive sign in the exponential term:
z^kp=1 n∑j=0n-1 xjp×exp+i 2 πjk n.
To compute this form, this method should be followed by forming the complex conjugates of the z^kp; that is x k=-x k, for k=n/2+1×m+1,…,m×n.
The method uses a variant of the fast Fourier transform (FFT) algorithm (see Brigham (1974)) known as the Stockham self-sorting algorithm, which is described in Temperton (1983). Special coding is provided for the factors 2, 3, 4, 5 and 6. This method is designed to be particularly efficient on vector processors, and it becomes especially fast as m, the number of transforms to be computed in parallel, increases.

References

Brigham E O (1974) The Fast Fourier Transform Prentice–Hall
Temperton C (1983) Fast mixed-radix real Fourier transforms J. Comput. Phys. 52 340–350

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, m<1.
ifail=2
On entry, n<1.
ifail=3
On entry, init≠"I", "S" or "R".
ifail=4
Not used at this Mark.
ifail=5
On entry, init="S" or "R", but the array trig and the current value of n are inconsistent.
ifail=6
An unexpected error has occurred in an internal call. Check all method calls and array dimensions. Seek expert help.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Some indication of accuracy can be obtained by performing a subsequent inverse transform and comparing the results with the original sequence (in exact arithmetic they would be identical).

Parallelism and Performance

None.

Further Comments

The time taken by c06fp is approximately proportional to nmlog n, but also depends on the factors of n. c06fp is fastest if the only prime factors of n are 2, 3 and 5, and is particularly slow if n is a large prime, or has large prime factors.

Example

Example program (C#): c06fpe.cs

Example program data: c06fpe.d

Example program results: c06fpe.r

See Also

C06 Class
C06 Members


c06fq Method

[image]

NAG Library for .NET Release 2
C06..::c06fq Method
C06 Class See Also Send Feedback
c06fq computes the discrete Fourier transforms of m Hermitian sequences, each containing n complex data values. This method is designed to be particularly efficient on vector processors.

Syntax

C#
public static void c06fq(
    int m,
    int n,
    double[] x,
    string init,
    double[] trig,
    out int ifail
)
Visual Basic
Public Shared Sub c06fq ( _
    m As Integer, _
    n As Integer, _
    x As Double(), _
    init As String, _
    trig As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void c06fq(
    int m,
    int n,
    array<double>^ x,
    String^ init,
    array<double>^ trig,
    [OutAttribute] int% ifail
)
F#
static member c06fq :
        m : int *
        n : int *
        x : float[] *
        init : string *
        trig : float[] *
        ifail : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: m, the number of sequences to be transformed.
Constraint: m≥1.
n
Type: System..::..Int32
On entry: n, the number of data values in each sequence.
Constraint: n≥1.
x
Type: array< System..::..Double >[]()[][]
An array of size [m×n]
On entry: the data must be stored in x as if in a two-dimensional array of dimension 1:m,0:n-1; each of the m sequences is stored in a row of the array in Hermitian form. If the n data values zjp are written as xjp+i yjp, then for 0≤j≤n/2, xjp is contained in x[p-1,j], and for 1≤j≤n-1/2, yjp is contained in x[p,n-j]. (See also [] in the C06 class Chapter Introduction.)
On exit: the components of the m discrete Fourier transforms, stored as if in a two-dimensional array of dimension 1:m,0:n-1. Each of the m transforms is stored as a row of the array, overwriting the corresponding original sequence. If the n components of the discrete Fourier transform are denoted by x^kp, for k=0,1,…,n-1, then the mn elements of the array x contain the values
x^01,x^02,…,x^0 m,x^11,x^12,…,x^1 m,…,x^n-1 1,x^n-1 2,…,x^n-1 m.
init
Type: System..::..String
On entry: indicates whether trigonometric coefficients are to be calculated.
init="I"
Calculate the required trigonometric coefficients for the given value of n, and store in the array trig.
init="S" or "R"
The required trigonometric coefficients are assumed to have been calculated and stored in the array trig in a prior call to one of c06fp, c06fq or c06fr. The method performs a simple check that the current value of n is consistent with the values stored in trig.
Constraint: init="I", "S" or "R".
trig
Type: array< System..::..Double >[]()[][]
An array of size [2×n]
On entry: if init="S" or "R", trig must contain the required trigonometric coefficients that have been previously calculated. Otherwise trig need not be set.
On exit: contains the required coefficients (computed by the method if init="I").
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Given m Hermitian sequences of n complex data values zjp, for j=0,1,…,n-1 and p=1,2,…,m, c06fq simultaneously calculates the Fourier transforms of all the sequences defined by
x^kp=1 n∑j=0n-1 zjp×exp-i 2 πjk n,  k=0,1,…,n-1​ and ​p=1,2,…,m.
(Note the scale factor 1 n in this definition.)
The transformed values are purely real (see also the C06 class).
The discrete Fourier transform is sometimes defined using a positive sign in the exponential term
x^kp=1 n∑j=0n-1 zjp×exp+i 2 πjk n.
To compute this form, this method should be preceded by forming the complex conjugates of the z^kp; that is x k=-x k, for k=n/2+1×m+1,…,m×n.
The method uses a variant of the fast Fourier transform (FFT) algorithm (see Brigham (1974)) known as the Stockham self-sorting algorithm, which is described in Temperton (1983). Special coding is provided for the factors 2, 3, 4, 5 and 6. This method is designed to be particularly efficient on vector processors, and it becomes especially fast as m, the number of transforms to be computed in parallel, increases.

References

Brigham E O (1974) The Fast Fourier Transform Prentice–Hall
Temperton C (1983) Fast mixed-radix real Fourier transforms J. Comput. Phys. 52 340–350

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, m<1.
ifail=2
On entry, n<1.
ifail=3
On entry, init≠"I", "S" or "R".
ifail=4
Not used at this Mark.
ifail=5
On entry, init="S" or "R", but the array trig and the current value of n are inconsistent.
ifail=6
An unexpected error has occurred in an internal call. Check all method calls and array dimensions. Seek expert help.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Some indication of accuracy can be obtained by performing a subsequent inverse transform and comparing the results with the original sequence (in exact arithmetic they would be identical).

Parallelism and Performance

None.

Further Comments

The time taken by c06fq is approximately proportional to nmlog n, but also depends on the factors of n. c06fq is fastest if the only prime factors of n are 2, 3 and 5, and is particularly slow if n is a large prime, or has large prime factors.

Example

Example program (C#): c06fqe.cs

Example program data: c06fqe.d

Example program results: c06fqe.r

See Also

C06 Class
C06 Members


c06gb Method

[image]

NAG Library for .NET Release 2
C06..::c06gb Method
C06 Class See Also Send Feedback
c06gb forms the complex conjugate of a Hermitian sequence of n data values.

Syntax

C#
public static void c06gb(
    double[] x,
    int n,
    out int ifail
)
Visual Basic
Public Shared Sub c06gb ( _
    x As Double(), _
    n As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void c06gb(
    array<double>^ x,
    int n,
    [OutAttribute] int% ifail
)
F#
static member c06gb :
        x : float[] *
        n : int *
        ifail : int byref -> unit

Parameters

x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: if the data values zj are written as xj+i yj and if x is declared with bounds 0:n-1 in the method from which c06gb is called, then for 0≤j≤n/2, x[j-1] must contain xj (=x n-j), while for n/2<j≤n-1, x[j-1] must contain -y j (=y n-j). In other words, x must contain the Hermitian sequence in Hermitian form. (See also [] in the C06 class Chapter Introduction.)
On exit: the imaginary parts yj are negated. The real parts xj are not referenced.
n
Type: System..::..Int32
On entry: n, the number of data values.
Constraint: n≥1.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

This is a utility method for use in conjunction with c06ea c06eb (C06FAF not in this release) (C06FBF not in this release) to calculate inverse discrete Fourier transforms (see the C06 class).

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<1.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Exact.

Parallelism and Performance

None.

Further Comments

The time taken by c06gb is negligible.

Example

Example program (C#): c06gbe.cs

Example program data: c06gbe.d

Example program results: c06gbe.r

See Also

C06 Class
C06 Members


c06gq Method

[image]

NAG Library for .NET Release 2
C06..::c06gq Method
C06 Class See Also Send Feedback
c06gq forms the complex conjugates of m Hermitian sequences, each containing n data values.

Syntax

C#
public static void c06gq(
    int m,
    int n,
    double[] x,
    out int ifail
)
Visual Basic
Public Shared Sub c06gq ( _
    m As Integer, _
    n As Integer, _
    x As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void c06gq(
    int m,
    int n,
    array<double>^ x,
    [OutAttribute] int% ifail
)
F#
static member c06gq :
        m : int *
        n : int *
        x : float[] *
        ifail : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: m, the number of Hermitian sequences to be conjugated.
Constraint: m≥1.
n
Type: System..::..Int32
On entry: n, the number of data values in each Hermitian sequence.
Constraint: n≥1.
x
Type: array< System..::..Double >[]()[][]
An array of size [m×n]
On entry: the data must be stored in x as if in a two-dimensional array of dimension 1:m,0:n-1; each of the m sequences is stored in a row of the array in Hermitian form. If the n data values zjp are written as xjp+i yjp, then for 0≤j≤n/2, xjp is contained in x[p-1,j], and for 1≤j≤n-1/2, yjp is contained in x[p,n-j]. (See also [] in the C06 class Chapter Introduction.)
On exit: the imaginary parts yjp are negated. The real parts xjp are not referenced.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

This is a utility method for use in conjunction with c06fp and c06fq to calculate inverse discrete Fourier transforms (see the C06 class).

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, m<1.
ifail=2
On entry, n<1.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Exact.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): c06gqe.cs

Example program data: c06gqe.d

Example program results: c06gqe.r

See Also

C06 Class
C06 Members


c06gs Method

[image]

NAG Library for .NET Release 2
C06..::c06gs Method
C06 Class See Also Send Feedback
c06gs takes m Hermitian sequences, each containing n data values, and forms the real and imaginary parts of the m corresponding complex sequences.

Syntax

C#
public static void c06gs(
    int m,
    int n,
    double[] x,
    double[] u,
    double[] v,
    out int ifail
)
Visual Basic
Public Shared Sub c06gs ( _
    m As Integer, _
    n As Integer, _
    x As Double(), _
    u As Double(), _
    v As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void c06gs(
    int m,
    int n,
    array<double>^ x,
    array<double>^ u,
    array<double>^ v,
    [OutAttribute] int% ifail
)
F#
static member c06gs :
        m : int *
        n : int *
        x : float[] *
        u : float[] *
        v : float[] *
        ifail : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: m, the number of Hermitian sequences to be converted into complex form.
Constraint: m≥1.
n
Type: System..::..Int32
On entry: n, the number of data values in each Hermitian sequence.
Constraint: n≥1.
x
Type: array< System..::..Double >[]()[][]
An array of size [m×n]
On entry: the data must be stored in x as if in a two-dimensional array of dimension 1:m,0:n-1; each of the m sequences is stored in a row of the array in Hermitian form. If the n data values zjp are written as xjp+i yjp, then for 0≤j≤n/2, xjp is contained in x[p-1,j], and for 1≤j≤n-1/2, yjp is contained in x[p,n-j]. (See also [] in the C06 class Chapter Introduction.)
u
Type: array< System..::..Double >[]()[][]
An array of size [m×n]
On exit: the real and imaginary parts of the m sequences of length n, are stored in u and v respectively, as if in two-dimensional arrays of dimension 1:m,0:n-1; each of the m sequences is stored as if in a row of each array. In other words, if the real parts of the pth sequence are denoted by xjp, for j=0,1,…,n-1 then the mn elements of the array u contain the values
x 01,x 02,…,x 0 m,x 11,x 12,…,x 1 m,…,x n-1 1,x n-1 2,…,x n-1 m
v
Type: array< System..::..Double >[]()[][]
An array of size [m×n]
On exit: the real and imaginary parts of the m sequences of length n, are stored in u and v respectively, as if in two-dimensional arrays of dimension 1:m,0:n-1; each of the m sequences is stored as if in a row of each array. In other words, if the real parts of the pth sequence are denoted by xjp, for j=0,1,…,n-1 then the mn elements of the array u contain the values
x 01,x 02,…,x 0 m,x 11,x 12,…,x 1 m,…,x n-1 1,x n-1 2,…,x n-1 m
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

This is a utility method for use in conjunction with c06fp and c06fq (see the C06 class).

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, m<1.
ifail=2
On entry, n<1.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Exact.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads in sequences of real data values which are assumed to be Hermitian sequences of complex data stored in Hermitian form. The sequences are then expanded into full complex form using c06gs and printed.

Example program (C#): c06gse.cs

Example program data: c06gse.d

Example program results: c06gse.r

See Also

C06 Class
C06 Members


C09 Class

[image]

NAG Library for .NET Release 2
C09 Class
Members See Also Send Feedback
This chapter is concerned with the analysis of datasets (or functions or operators) in terms of frequency and scale components using wavelet transforms. Wavelet transforms have been applied in many fields from time series analysis to image processing and the localization in either frequency or scale that they provide is useful for data compression or denoising. In general the standard wavelet transform uses dilation and scaling of a chosen function, ψ t, (called the mother wavelet) such that
ψ a,b t=1 a ψ t-b a
where a gives the scaling and b determines the translation. Wavelet methods can be divided into continuous transforms and discrete transforms. In the continuous case, the pair a and b are real numbers with a>0. For the discrete transform, a and b can be chosen as a=2-j, b=k 2-j for integers j, k
ψ j,k t=2 j/2 ψ 2 j t-k.
The continuous real valued, one-dimensional wavelet transform (CWT) is included in this chapter. The discrete wavelet transform (DWT) at a single level together with its inverse and the multi-level DWT with inverse are also provided for one, two and three dimensions. The Maximal Overlap DWT (MODWT) together with its inverse and the multi-level MODWT with inverse are provided for one dimension. The choice of wavelet for CWT includes the Morlet wavelet and derivatives of a Gaussian while the DWT and MODWT offer the orthogonal wavelets of Daubechies and a selection of biorthogonal wavelets.

Syntax

C#
public static class C09
Visual Basic
Public NotInheritable Class C09
Visual C++
public ref class C09 abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type C09 =  class end

Background to the Problems

The CWT computes a time-frequency analysis of a signal, x t, which can yield high localization in time of the high frequency features present. It is defined as
C a,b=∫-∞+∞1 a ψ*t-b a x t dt
where ψ* denotes the complex conjugate of the wavelet function, a is the dilation parameter and b is the localization parameter. (Currently only the real valued transform is offered.)
The discrete wavelet transform (DWT) is defined by a mother wavelet function ψ t, and a related scaling function, ϕ t, where
ϕ t=∑k gk 2 ϕ 2 t-k.ψ t=∑k hk 2 ϕ 2 t-k.
These in turn are represented as a pair of filters with finite support. They can be viewed as a high pass filter, hk, for k=1,2,…,m, paired with a low pass filter, gk, for k=1,2,…,n. The DWT at a single level is carried out by convolution of the filter with the input data, followed by downsampling by two. The MODWT at a single level is carried out by convolution of the filter with the input data only; no downsampling is used in the MODWT. In order to obtain exact reconstruction of the original input these filters must satisfy certain conditions. For orthogonal wavelets, n=m, these are,
∑k=1 m hk=0,∑k=1 m hk 2=1,∑k=-∞∞hkh k+2 l=0,∑k=1 m gk=2,∑k=1 m gk 2=1,∑k=-∞∞gkg k+2 l=0.
for all nonzero integers, l.
The DWT reconstruction algorithm convolves the inverse filters with the wavelet coefficients previously computed together with upsampling and summation to return to the original input. The MODWT reconstructs in the same way, except without upsampling. For orthogonal wavelets the inverse filters are the same as those for the forward DWT.
In the simplest case, the Haar wavelet, the nonzero filter coefficients are
h=-1 2,1 2g=1 2,1 2
while for the Daubechies wavelet with two vanishing moments and four nonzero coefficients, the filter coefficients are
h=-1+34 2,3+34 2,-3+34 2,1-34 2g=1-34 2,3-34 2,3+34 2,1+34 2
In the orthogonal case the same filters are used for both decomposition and reconstruction.
Relaxing the orthogonality requirement allows for biorthogonal wavelets which consist of two dual wavelet bases. For example, the biorthogonal 2.2 filters are,
h=2 14,-12,14,g=2-18,14,34,14,-18h′=2 18,14,-34,14,18g′=2 14,12,14.
Note that there are several possible interpretations of orthogonal and biorthorgonal wavelet filters which satisfy the requirements. These differ in the sign of the coefficients and the ordering of the filters.
In order to obtain exact reconstruction when applying the DWT or MODWT and its inverse to a finite dataset, say xt, for t=1,2,…,N, some method of extending the input at its end is required. Several methods which are in general use are: periodic extension, half-point symmetric extension, whole-point symmetric extension and zero end extension where the added data points are taken to be zero. The two types of symmetric end extension reflect the given data values from the end points for whole-point extension or else by repeating the end points and reflecting from points halfway between the end point and its repeat for half-point extension. Each of these end extension methods are available for the DWT. Only the periodic end extension is currently available for the MODWT.

Multiresolution and higher dimensional DWT

Rather than simply applying the wavelet transform at a single level the process is commonly repeated to give a multiresolution analysis. For the DWT, multiresolution is implemented as the pyramid (or cascade) algorithm. Applying the DWT at a given level, L, the detail coefficients (which are the output from the high pass filter) are stored while the approximation coefficients resulting from convolution with the low pass filter are passed to the next level and the processs is repeated. When the length of the initial data input is an array of length N=2 J, for some integer J (and assuming that the dataset is extended by periodic repetition) this can be continued until, at level J, there is a single detail coefficient from the high pass filter. The final coefficient from the action of the low pass filter is also stored. The result is an array of coefficients of the same length, N, as the input.
For the multi-level MODWT it is, in theory, possible to continue for any number of levels. However, in practice it is common to not exceed log 2 N levels in order to avoid scales that exceed the length of the input data, N. This restriction is enforced for the one-dimensional mutli-level MODWT method in this chapter.
For two-dimensional data sets the DWT is computed as a series of one-dimensional DWTs, first over columns of the input data, and then over rows of the intermediate result. This produces four types of output coefficients: one set of approximation coefficients and three types of detail coefficients, containing information about the horizontal, vertical and diagonal components of the input data. The approximation coefficients are the result of applying convolution and downsampling with the low pass filter over both columns and rows; the horizontal detail coefficients are the result of applying convolution and downsampling with the high pass filter over columns and then the low pass filter over rows; the vertical detail coefficients are the result of applying convolution and downsampling with the low pass filter over columns and the high pass filter over rows; and the diagonal detail coefficients are the result of applying convolution and downsampling with the high pass filter over both columns and rows. An example of the single level decomposition of an image performed using (C09EAF not in this release) is given in Figure 1.
Figure 1: The original image (top, 996×1332 pixels) is transformed using method (C09EAF not in this release) into the four coefficient (approximation, horizontal, vertical and diagonal) matrices (501×669) displayed below the original. The transformation was performed using the Daubechies wavelet with four vanishing moments and half-point end extension. Note that the approximation coefficients are a very close representation of the original image, while the horizontal, vertical and diagonal features of the image are visible in the respective coefficient matrices.
Similarly, for three-dimensional data sets the DWT is also computed as a series of three one-dimensional DWTs, first over columns of the input data, and then over rows of the intermediate result and finally over frames of the second intermediate result. This produces eight types of output coefficients: one set of approximation coefficients (labelled LLL since the low pass filter is applied over columns, rows and frames) and seven types of detail coefficients, labelled similarly according to whether the low pass (L) or high pass filter (H) is applied in each of the three dimensions. For convenience, where methods (C09ECF not in this release) (two-dimensional multi-level DWT), (C09FAF not in this release) (three-dimensional DWT) and (C09FCF not in this release) (three-dimensional multi-level DWT) return coefficients packed into one-dimensional arrays, coefficient extraction methods (C09EYF not in this release) (two-dimensional) and (C09FYF not in this release) (three-dimensional) are provided which will return a selected set of coefficients into two and three-dimensional arrays, respectively. For the three-dimensional DWT this process is represented by Figure 2.
As in the one-dimensional case, the multi-level DWT in two and three dimensions is also implemented as the pyramid (or cascade) algorithm, where at a given level, L, all detail coefficients are stored, while the approximation coefficients are passed as input to the next level.
Figure 2: The three-dimensional DWT filter bank. The original input is downsampled by 2 and the high pass (H) and low pass (L) filters are applied along columns. This process is repeated along the rows and then frames to produce 8 sets of output coefficients – one set of approximation coefficients and 7 sets of detail coefficients.

Recommendations on Choice and Use of Available Methods

The one-dimensional real valued continuous wavelet transform is provided by (C09BAF not in this release). It is useful for resolving discontinuities and high frequency features in a signal. It is a redundant representation of the input data containing repeated information and the set of coefficients produced as output is larger than the input data set.
The one-dimensional discrete wavelet transform at a single level is performed by c09ca. The inverse or reconstruction is carried out by c09cb.
The one-dimensional multi-level discrete wavelet transform is computed by c09cc and the inverse or reconstruction is given by c09cd. The discrete wavelet transform is widely used for image processing and data compression.
The one-dimensional maximal overlap discrete wavelet transform at a single level is performed by (C09DAF not in this release). The inverse or reconstruction is carried out by (C09DBF not in this release).
The one-dimensional multi-level maximal overlap discrete wavelet transform is performed by (C09DCF not in this release). The inverse or reconstruction routine is (C09DDF not in this release). The maximal overlap discrete wavelet transform overcomes the lack of translation invariance inherent in the DWT, and thus there are advantages to using the MODWT when carrying out multiresolution analysis.
C09 Communication class constructor is provided to determine some of the input parameters for the one-dimensional discrete wavelet transform and maximal overlap discrete wavelet transform methods and must be called before the one-dimensional transform methods.
The two-dimensional discrete wavelet transform at a single level is performed by (C09EAF not in this release). The inverse or reconstruction is carried out by (C09EBF not in this release).
The two-dimensional multi-level discrete wavelet transform is computed by (C09ECF not in this release) and the inverse or reconstruction is given by (C09EDF not in this release).
(C09ECF not in this release) (C09EDF not in this release) use a one-dimensional array to store the discrete wavelet transform coefficients. These may be extracted into two-dimensional arrays using (C09EYF not in this release). A complementary method (C09EZF not in this release) allows for the insertion of coefficients held in a two-dimensional array back into the one-dimensional array.
(C09ABF not in this release) is provided to determine some of the input parameters for the two-dimensional discrete wavelet transform methods and must be called before the two-dimensional transform methods.
(C09EYF not in this release) is provided to extract selected sets of coefficients returned by (C09ECF not in this release) in a one-dimensional array into two-dimensional arrays.
The three-dimensional discrete wavelet transform at a single level is performed by (C09FAF not in this release). The inverse or reconstruction is carried out by (C09FBF not in this release).
The three-dimensional multi-level discrete wavelet transform is computed by (C09FCF not in this release) and the inverse or reconstruction is given by (C09FDF not in this release).
(C09FAF not in this release) (C09FBF not in this release) (C09FCF not in this release) (C09FDF not in this release) use a one-dimensional array to store the discrete wavelet transform coefficients. These may be extracted into three-dimensional arrays using (C09FYF not in this release). A complementary method (C09FZF not in this release) allows for the insertion of coefficients held in a three-dimensional array back into the one-dimensional array.
(C09ACF not in this release) is provided to determine some of the input parameters for the three-dimensional discrete wavelet transform methods and must be called before the three-dimensional transform methods.
(C09FYF not in this release) is provided to extract selected sets of coefficients returned by (C09FAF not in this release) and (C09FCF not in this release) in a one-dimensional array into three-dimensional arrays.

References

Daubechies I (1992) Ten Lectures on Wavelets SIAM, Philadelphia
Mallat S G (1998) A Wavelet Tour of Signal Processing Academic Press
Percival D B and Walden A T (2000) Wavelet Methods for Time Series Analysis Cambridge University Press
Strang G and Nguyen T (1996) Wavelets and Filter Banks Wellesley-Cambridge Press
Vidakovic B (1999) Statistical Modeling by Wavelets John Wiley and Sons Inc.
Wickerhauser M V (1994) Adapted Wavelet Analysis from Theory to Software A K Peters Ltd

Inheritance Hierarchy

System..::..Object
NagLibrary..::..C09

See Also

C09 Members


C09 Members

[image] [image]

NAG Library for .NET Release 2
C09 Members
C09 Class Methods See Also Send Feedback

The C09 type exposes the following members.

Methods

Name | Description
c09ca | c09ca computes the one-dimensional discrete wavelet transform (DWT) at a single level. The initialization method C09 Communication class constructor must be called first to set up the DWT options.
c09cb | c09cb computes the inverse one-dimensional discrete wavelet transform (DWT) at a single level. The initialization method C09 Communication class constructor must be called first to set up the DWT options.
c09cc | c09cc computes the one-dimensional multi-level discrete wavelet transform (DWT). The initialization method C09 Communication class constructor must be called first to set up the DWT options.
c09cd | c09cd computes the inverse one-dimensional multi-level discrete wavelet transform (DWT). This method reconstructs data from (possibly filtered or otherwise manipulated) wavelet transform coefficients calculated by c09cc from an original set of data. The initialization method C09 Communication class constructor must be called first to set up the DWT options.

See Also

C09 Class


C09 Classes

[image]

NAG Library for .NET Release 2
C09 Classes

C09 Classes

  • C09.C09Communications Class


C09.C09Communications Class

[image]

NAG Library for .NET Release 2
C09..::..C09Communications Class
C09 Class Members See Also Send Feedback
Communications Class

Syntax

C#
public class C09Communications
Visual Basic
Public Class C09Communications
Visual C++
public ref class C09Communications
F#
type C09Communications =  class end

Inheritance Hierarchy

System..::..Object
NagLibrary..::..C09..::..C09Communications

See Also

C09..::..C09Communications Members


C09.C09Communications Members

[image] [image]

NAG Library for .NET Release 2
C09..::..C09Communications Members
C09..::..C09Communications Class Constructors Properties See Also Send Feedback

This chapter is concerned with the analysis of datasets (or functions or operators) in terms of frequency and scale components using wavelet transforms. Wavelet transforms have been applied in many fields from time series analysis to image processing and the localization in either frequency or scale that they provide is useful for data compression or denoising. In general the standard wavelet transform uses dilation and scaling of a chosen function, ψ t, (called the mother wavelet) such that
ψ a,b t=1 a ψ t-b a
where a gives the scaling and b determines the translation. Wavelet methods can be divided into continuous transforms and discrete transforms. In the continuous case, the pair a and b are real numbers with a>0. For the discrete transform, a and b can be chosen as a=2-j, b=k 2-j for integers j, k
ψ j,k t=2 j/2 ψ 2 j t-k.
The continuous real valued, one-dimensional wavelet transform (CWT) is included in this chapter. The discrete wavelet transform (DWT) at a single level together with its inverse and the multi-level DWT with inverse are also provided for one, two and three dimensions. The Maximal Overlap DWT (MODWT) together with its inverse and the multi-level MODWT with inverse are provided for one dimension. The choice of wavelet for CWT includes the Morlet wavelet and derivatives of a Gaussian while the DWT and MODWT offer the orthogonal wavelets of Daubechies and a selection of biorthogonal wavelets.

The C09..::..C09Communications type exposes the following members.

Constructors

Name | Description
C09..::..C09Communications | Communications Class constructor

Properties

Name | Description
ApproximateCoeffCount | Th number of approximation coefficients that would be generated for the given problem size, mother wavelet, extension method and type of transform; this is also the corresponding number of detail coefficients.
FilterLength | The filter length for the supplied mother wavelet. This is used to determine the number of coefficients to be generated by the chosen transform.
Message | Set the method used for logging any monitoring messages.
ResolutionLevelCount | The number of levels in the multi-level resolution to be performed.
Warning | Set the method used for logging any warning or error messages.

See Also

C09..::..C09Communications Class


C09.C09Communications Constructor

[image]

NAG Library for .NET Release 2
C09..::..C09Communications Constructor
C09..::..C09Communications Class See Also Send Feedback
Communications Class constructor

Syntax

C#
public C09Communications(
    string wavnam,
    string wtrans,
    string mode,
    int n,
    out int ifail
)
Visual Basic
Public Sub New ( _
    wavnam As String, _
    wtrans As String, _
    mode As String, _
    n As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
C09Communications(
    String^ wavnam,
    String^ wtrans,
    String^ mode,
    int n,
    [OutAttribute] int% ifail
)
F#
new :
        wavnam : string *
        wtrans : string *
        mode : string *
        n : int *
        ifail : int byref -> C09Communications

Parameters

wavnam
Type: System..::..String
wavnam
wtrans
Type: System..::..String
wtrans
mode
Type: System..::..String
mode
n
Type: System..::..Int32
n
ifail
Type: System..::..Int32 %
ifail

See Also

C09..::..C09Communications Class
C09..::..C09Communications Members


C09.C09Communications Properties

[image] [image]

NAG Library for .NET Release 2
C09..::..C09Communications Properties
C09..::..C09Communications Class See Also Send Feedback

The C09..::..C09Communications type exposes the following members.

Properties

Name | Description
ApproximateCoeffCount | Th number of approximation coefficients that would be generated for the given problem size, mother wavelet, extension method and type of transform; this is also the corresponding number of detail coefficients.
FilterLength | The filter length for the supplied mother wavelet. This is used to determine the number of coefficients to be generated by the chosen transform.
Message | Set the method used for logging any monitoring messages.
ResolutionLevelCount | The number of levels in the multi-level resolution to be performed.
Warning | Set the method used for logging any warning or error messages.

See Also

C09..::..C09Communications Class


ApproximateCoeffCount Property

[image]

NAG Library for .NET Release 2
C09..::..C09Communications..::ApproximateCoeffCount Property
C09..::..C09Communications Class See Also Send Feedback
Th number of approximation coefficients that would be generated for the given problem size, mother wavelet, extension method and type of transform; this is also the corresponding number of detail coefficients.

Syntax

C#
public int ApproximateCoeffCount { get; }
Visual Basic
Public ReadOnly Property ApproximateCoeffCount As Integer
    Get
Visual C++
public:
property int ApproximateCoeffCount {
    int get ();
}
F#
member ApproximateCoeffCount : int with get

See Also

C09..::..C09Communications Class
C09..::..C09Communications Members


FilterLength Property

[image]

NAG Library for .NET Release 2
C09..::..C09Communications..::FilterLength Property
C09..::..C09Communications Class See Also Send Feedback
The filter length for the supplied mother wavelet. This is used to determine the number of coefficients to be generated by the chosen transform.

Syntax

C#
public int FilterLength { get; }
Visual Basic
Public ReadOnly Property FilterLength As Integer
    Get
Visual C++
public:
property int FilterLength {
    int get ();
}
F#
member FilterLength : int with get

See Also

C09..::..C09Communications Class
C09..::..C09Communications Members


Message Property

[image]

NAG Library for .NET Release 2
C09..::..C09Communications..::Message Property
C09..::..C09Communications Class See Also Send Feedback
Set the method used for logging any monitoring messages.

Syntax

C#
public PrintManager..::..MessageLogger Message { get; set; }
Visual Basic
Public Property Message As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Message {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Message : PrintManager..::..MessageLogger with get, set

See Also

C09..::..C09Communications Class
C09..::..C09Communications Members


ResolutionLevelCount Property

[image]

NAG Library for .NET Release 2
C09..::..C09Communications..::ResolutionLevelCount Property
C09..::..C09Communications Class See Also Send Feedback
The number of levels in the multi-level resolution to be performed.

Syntax

C#
public int ResolutionLevelCount { get; }
Visual Basic
Public ReadOnly Property ResolutionLevelCount As Integer
    Get
Visual C++
public:
property int ResolutionLevelCount {
    int get ();
}
F#
member ResolutionLevelCount : int with get

See Also

C09..::..C09Communications Class
C09..::..C09Communications Members


Warning Property

[image]

NAG Library for .NET Release 2
C09..::..C09Communications..::Warning Property
C09..::..C09Communications Class See Also Send Feedback
Set the method used for logging any warning or error messages.

Syntax

C#
public PrintManager..::..MessageLogger Warning { get; set; }
Visual Basic
Public Property Warning As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Warning {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Warning : PrintManager..::..MessageLogger with get, set

See Also

C09..::..C09Communications Class
C09..::..C09Communications Members


C09 Methods

[image] [image]

NAG Library for .NET Release 2
C09 Methods
C09 Class See Also Send Feedback

The C09 type exposes the following members.

Methods

Name | Description
c09ca | c09ca computes the one-dimensional discrete wavelet transform (DWT) at a single level. The initialization method C09 Communication class constructor must be called first to set up the DWT options.
c09cb | c09cb computes the inverse one-dimensional discrete wavelet transform (DWT) at a single level. The initialization method C09 Communication class constructor must be called first to set up the DWT options.
c09cc | c09cc computes the one-dimensional multi-level discrete wavelet transform (DWT). The initialization method C09 Communication class constructor must be called first to set up the DWT options.
c09cd | c09cd computes the inverse one-dimensional multi-level discrete wavelet transform (DWT). This method reconstructs data from (possibly filtered or otherwise manipulated) wavelet transform coefficients calculated by c09cc from an original set of data. The initialization method C09 Communication class constructor must be called first to set up the DWT options.

See Also

C09 Class


c09ca Method

[image]

NAG Library for .NET Release 2
C09..::c09ca Method
C09 Class See Also Send Feedback
c09ca computes the one-dimensional discrete wavelet transform (DWT) at a single level. The initialization method C09 Communication class constructor must be called first to set up the DWT options.

Syntax

C#
public static void c09ca(
    int n,
    double[] x,
    double[] ca,
    double[] cd,
    C09..::..C09Communications communications,
    out int ifail
)
Visual Basic
Public Shared Sub c09ca ( _
    n As Integer, _
    x As Double(), _
    ca As Double(), _
    cd As Double(), _
    communications As C09..::..C09Communications, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void c09ca(
    int n,
    array<double>^ x,
    array<double>^ ca,
    array<double>^ cd,
    C09..::..C09Communications^ communications,
    [OutAttribute] int% ifail
)
F#
static member c09ca :
        n : int *
        x : float[] *
        ca : float[] *
        cd : float[] *
        communications : C09..::..C09Communications *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: the number of elements, n, in the data array x.
Constraint: this must be the same as the value n passed to the initialization method c09aa.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x contains the input dataset xi, for i=1,2,…,n.
ca
Type: array< System..::..Double >[]()[][]
An array of size [lenc]
On exit: ca[i-1] contains the ith approximation coefficient, Ca i, for i=1,2,…,nc.
cd
Type: array< System..::..Double >[]()[][]
An array of size [lenc]
On exit: cd[i-1] contains the ith detail coefficient, Cd i, for i=1,2,…,nc.
communications
Type: NagLibrary..::..C09..::..C09Communications
An Object of type C09.c09caCommunications.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

c09ca computes the one-dimensional DWT of a given input data array, xi, for i=1,2,…,n, at a single level. For a chosen wavelet filter pair, the output coefficients are obtained by applying convolution and downsampling by two to the input, x. The approximation (or smooth) coefficients, Ca, are produced by the low pass filter and the detail coefficients, Cd, by the high pass filter. To reduce distortion effects at the ends of the data array, several end extension methods are commonly used. Those provided are: periodic or circular convolution end extension, half-point symmetric end extension, whole-point symmetric end extension or zero end extension. The number nc, of coefficients Ca or Cd is returned by the initialization method C09 Communication class constructor.

References

Daubechies I (1992) Ten Lectures on Wavelets SIAM, Philadelphia

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n is inconsistent with the value passed to the initialization method C09 Communication class constructor.
ifail=2
On entry, lenc<nc, where nc is the value returned in nwc by the call to the initialization method C09 Communication class constructor.
ifail=6
On entry, the initialization method C09 Communication class constructor has not been called first or it has been called with wtrans="M", or the communication array icomm has become corrupted.
ifail=-9000
An error occured, see message report.
ifail=-1000
The array lengths are not the same for arrays
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The accuracy of the wavelet transform depends only on the floating-point operations used in the convolution and downsampling and should thus be close to machine precision.

Parallelism and Performance

None.

Further Comments

None.

Example

This example computes the one-dimensional discrete wavelet decomposition for 8 values using the Daubechies wavelet, wavnam="DB4", with zero end extension.

Example program (C#): c09cae.cs

Example program data: c09cae.d

Example program results: c09cae.r

See Also

C09 Class
C09 Members


c09cb Method

[image]

NAG Library for .NET Release 2
C09..::c09cb Method
C09 Class See Also Send Feedback
c09cb computes the inverse one-dimensional discrete wavelet transform (DWT) at a single level. The initialization method C09 Communication class constructor must be called first to set up the DWT options.

Syntax

C#
public static void c09cb(
    double[] ca,
    double[] cd,
    int n,
    double[] y,
    C09..::..C09Communications communications,
    out int ifail
)
Visual Basic
Public Shared Sub c09cb ( _
    ca As Double(), _
    cd As Double(), _
    n As Integer, _
    y As Double(), _
    communications As C09..::..C09Communications, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void c09cb(
    array<double>^ ca,
    array<double>^ cd,
    int n,
    array<double>^ y,
    C09..::..C09Communications^ communications,
    [OutAttribute] int% ifail
)
F#
static member c09cb :
        ca : float[] *
        cd : float[] *
        n : int *
        y : float[] *
        communications : C09..::..C09Communications *
        ifail : int byref -> unit

Parameters

ca
Type: array< System..::..Double >[]()[][]
An array of size [lenc]
On entry: the nc approximation coefficients, Ca. These will normally be the result of some transformation on the coefficients computed by c09ca.
cd
Type: array< System..::..Double >[]()[][]
An array of size [lenc]
On entry: the nc detail coefficients, Cd. These will normally be the result of some transformation on the coefficients computed by c09ca.
n
Type: System..::..Int32
On entry: n, the length of the original data array from which the wavelet coefficients were computed by c09ca and the length of the data array y that is to be reconstructed by this method.
Constraint: This must be the same as the value n passed to the initialization method c09aa.
y
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the reconstructed data based on approximation and detail coefficients Ca and Cd and the transform options supplied to the initialization method c09aa.
communications
Type: NagLibrary..::..C09..::..C09Communications
An Object of type C09.c09cbCommunications.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

c09cb performs the inverse operation of c09ca. That is, given sets of nc approximation coefficients and detail coefficients, computed by c09ca using a DWT as set up by the initialization method C09 Communication class constructor, on a real data array of length n, c09cb will reconstruct the data array yi, for i=1,2,…,n, from which the coefficients were derived.

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, lenc<nc, where nc is the value returned in nwc by the call to the initialization method C09 Communication class constructor.
ifail=4
On entry, n is inconsistent with the value passed to the initialization method C09 Communication class constructor.
ifail=6
On entry, the initialization method C09 Communication class constructor has not been called first or it has been called with wtrans="M", or the communication array icomm has become corrupted.
ifail=-9000
An error occured, see message report.
ifail=-1000
The array lengths are not the same for arrays
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The accuracy of the wavelet transform depends only on the floating-point operations used in the convolution and downsampling and should thus be close to machine precision.

Parallelism and Performance

None.

Further Comments

None.

Example

See [Example] in c09ca.

See Also

C09 Class
C09 Members


c09cc Method

[image]

NAG Library for .NET Release 2
C09..::c09cc Method
C09 Class See Also Send Feedback
c09cc computes the one-dimensional multi-level discrete wavelet transform (DWT). The initialization method C09 Communication class constructor must be called first to set up the DWT options.

Syntax

C#
public static void c09cc(
    int n,
    double[] x,
    double[] c,
    int[] dwtlev,
    C09..::..C09Communications communications,
    out int ifail
)
Visual Basic
Public Shared Sub c09cc ( _
    n As Integer, _
    x As Double(), _
    c As Double(), _
    dwtlev As Integer(), _
    communications As C09..::..C09Communications, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void c09cc(
    int n,
    array<double>^ x,
    array<double>^ c,
    array<int>^ dwtlev,
    C09..::..C09Communications^ communications,
    [OutAttribute] int% ifail
)
F#
static member c09cc :
        n : int *
        x : float[] *
        c : float[] *
        dwtlev : int[] *
        communications : C09..::..C09Communications *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: the number of elements, n, in the data array x.
Constraint: this must be the same as the value n passed to the initialization method c09aa.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x contains the one-dimensional input dataset xi, for i=1,2,…,n.
c
Type: array< System..::..Double >[]()[][]
An array of size [lenc]
On exit: let q i denote the number of coefficients (of each type) produced by the wavelet transform at level i, for i=nfwd,nfwd-1,…,1. These values are returned in dwtlev. Setting k 1=q nfwd and k j+1=kj+q nfwd-j+1, for j=1,2,…,nfwd, the coefficients are stored as follows:
c[i-1], for i=1,2,…,k 1
Contains the level nfwd approximation coefficients, a nfwd.
c[i-1], for i=k 1+1,…,k 2
Contains the level nfwd detail coefficients d nfwd.
c[i-1], for i=kj+1,…,k j+1
Contains the level nfwd-j+1 detail coefficients, for j=2,3,…,nfwd.
dwtlev
Type: array< System..::..Int32 >[]()[][]
An array of size [nwl+1]
On exit: the number of transform coefficients at each level. dwtlev[0] and dwtlev[1] contain the number, q nfwd, of approximation and detail coefficients respectively, for the final level of resolution (these are equal); dwtlev[i-1] contains the number of detail coefficients, q nfwd-i+2, for the (nfwd-i+2)th level, for i=3,4,…,nfwd+1.
communications
Type: NagLibrary..::..C09..::..C09Communications
An Object of type C09.c09ccCommunications.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

c09cc computes the multi-level DWT of one-dimensional data. For a given wavelet and end extension method, c09cc will compute a multi-level transform of a data array, xi, for i=1,2,…,n, using a specified number, nfwd, of levels. The number of levels specified, nfwd, must be no more than the value lmax returned in nwlmax by the initialization method C09 Communication class constructor for the given problem. The transform is returned as a set of coefficients for the different levels (packed into a single array) and a representation of the multi-level structure.
The notation used here assigns level 0 to the input dataset, x, with level 1 being the first set of coefficients computed, with the detail coefficients, d 1, being stored while the approximation coefficients, a 1, are used as the input to a repeat of the wavelet transform. This process is continued until, at level nfwd, both the detail coefficients, d nfwd, and the approximation coefficients, a nfwd are retained. The output array, C, stores these sets of coefficients in reverse order, starting with a nfwd followed by d nfwd,d nfwd-1,…,d 1.

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n is inconsistent with the value passed to the initialization method: n=value, n should be value.
ifail=3
On entry, lenc is set too small: lenc=value.
Constraint: lenc≥value.
ifail=5
On entry, nwl=value.
Constraint: nwl≥1.
On entry, nwl is larger than the maximum number of levels returned by the initialization method: nwl=value, maximum =value.
ifail=7
Either the initialization method has not been called first or array icomm has been corrupted.
Either the initialization method was called with wtrans="S" or array icomm has been corrupted.
ifail=-999
Dynamic memory allocation failed.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The accuracy of the wavelet transform depends only on the floating-point operations used in the convolution and downsampling and should thus be close to machine precision.

Parallelism and Performance

None.

Further Comments

The wavelet coefficients at each level can be extracted from the output array c using the information contained in dwtlev on exit (see the descriptions of c and dwtlev in [Parameters]). For example, given an input data set, x, denoising can be carried out by applying a thresholding operation to the detail coefficients at every level. The elements c[i-1], for i=k 1+1,…,k nfwd+1, as described in [Parameters], contain the detail coefficients, d^ij, for i=nfwd,nfwd-1,…,1 and j=1,2,…,q i, where d^ij=d ij+σ ε ij and σ ε ij is the transformed noise term. If some threshold parameter α is chosen, a simple hard thresholding rule can be applied as
d-ij=0,if ​d^ij≤αd^ij,if ​d^ij>α,
taking d-ij to be an approximation to the required detail coefficient without noise, d ij. The resulting coefficients can then be used as input to c09cd in order to reconstruct the denoised signal.
See the references given in the introduction to this chapter for a more complete account of wavelet denoising and other applications.

Example

Example program (C#): c09cce.cs

Example program data: c09cce.d

Example program results: c09cce.r

See Also

C09 Class
C09 Members


c09cd Method

[image]

NAG Library for .NET Release 2
C09..::c09cd Method
C09 Class See Also Send Feedback
c09cd computes the inverse one-dimensional multi-level discrete wavelet transform (DWT). This method reconstructs data from (possibly filtered or otherwise manipulated) wavelet transform coefficients calculated by c09cc from an original set of data. The initialization method C09 Communication class constructor must be called first to set up the DWT options.

Syntax

C#
public static void c09cd(
    int nwlinv,
    double[] c,
    int n,
    double[] y,
    C09..::..C09Communications communications,
    out int ifail
)
Visual Basic
Public Shared Sub c09cd ( _
    nwlinv As Integer, _
    c As Double(), _
    n As Integer, _
    y As Double(), _
    communications As C09..::..C09Communications, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void c09cd(
    int nwlinv,
    array<double>^ c,
    int n,
    array<double>^ y,
    C09..::..C09Communications^ communications,
    [OutAttribute] int% ifail
)
F#
static member c09cd :
        nwlinv : int *
        c : float[] *
        n : int *
        y : float[] *
        communications : C09..::..C09Communications *
        ifail : int byref -> unit

Parameters

nwlinv
Type: System..::..Int32
On entry: the number of levels to be used in the inverse multi-level transform. The number of levels must be less than or equal to nfwd, which has the value of parameter nwl as used in the computation of the wavelet coefficients using c09cc. The data will be reconstructed to level nwl-nwlinv, where level 0 is the original input dataset provided to c09cc.
Constraint: 1≤nwlinv≤nwl, where nwl is the value used in a preceding call to c09cc.
c
Type: array< System..::..Double >[]()[][]
An array of size [lenc]
On entry: the coefficients of a multi-level wavelet transform of the dataset.
Let q i be the number of coefficients (of each type) at level i, for i=nfwd,nfwd-1,…,1. Then, setting k 1=q nfwd and k j+1=kj+q nfwd-j+1, for j=1,2,…,nfwd, the coefficients are stored in c as follows:
c[i-1], for i=1,2,…,k 1
Contains the level nfwd approximation coefficients, a nfwd.
c[i-1], for i=k 1+1,…,k 2
Contains the level nfwd detail coefficients d nfwd.
c[i-1], for i=kj+1,…,k j+1
Contains the level nfwd-j+1 detail coefficients, for j=2,3,…,nfwd.
The values q i, for i=nfwd,nfwd-1,…,1, are contained in dwtlev which is produced as output by a preceding call to c09cc. See c09cc for details.
n
Type: System..::..Int32
On entry: n, the length of the data array, y, to be reconstructed. For a full reconstruction of nwl levels, where nwl is as supplied to c09cc, this must be the same as parameter n used in the call to c09cc. For a partial reconstruction of nwlinv<nwl, this must be equal to dwtlev[nwlinv+1], as returned from c09cc.
y
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the dataset reconstructed from the multi-level wavelet transform coefficients and the transformation options supplied to the initialization method c09aa.
communications
Type: NagLibrary..::..C09..::..C09Communications
An Object of type C09.c09cdCommunications.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

c09cd performs the inverse operation of c09cc. That is, given a set of wavelet coefficients, computed up to level nfwd by c09cc using a DWT as set up by the initialization method C09 Communication class constructor, on a real data array of length n, c09cd will reconstruct the data array yi, for i=1,2,…,n, from which the coefficients were derived. If the original input dataset is level 0, then it is possible to terminate reconstruction at a higher level by specifying fewer than the number of levels used in the call to c09cc. This results in a partial reconstruction.

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, nwlinv=value.
Constraint: nwlinv≥1.
On entry, nwlinv is larger than the number of levels computed by the preceding call to c09cc: nwlinv=value, expected =value.
ifail=2
On entry, lenc is set too small: lenc=value.
Constraint: lenc≥value.
ifail=4
On entry, n is inconsistent with the value passed to the initialization method: n=value, n should be value.
ifail=6
Either the initialization method has not been called first or array icomm has been corrupted.
Either the initialization method was called with wtrans="S" or array icomm has been corrupted.
ifail=-999
Dynamic memory allocation failed.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The accuracy of the wavelet transform depends only on the floating-point operations used in the convolution and downsampling and should thus be close to machine precision.

Parallelism and Performance

None.

Further Comments

None.

Example

See [Example] in c09cc.

See Also

C09 Class
C09 Members


D01 Class

[image]

NAG Library for .NET Release 2
D01 Class
Members See Also Send Feedback
This chapter provides methods for the numerical evaluation of definite integrals in one or more dimensions and for evaluating weights and abscissae of integration rules.

Syntax

C#
public static class D01
Visual Basic
Public NotInheritable Class D01
Visual C++
public ref class D01 abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type D01 =  class end

Background to the Problems

The methods in this chapter are designed to estimate:
(a) the value of a one-dimensional definite integral of the form
∫ab f x dx (1)
where f x is defined by you, either at a set of points xi,f xi, for i=1,2,…,n, where a=x 1<x 2<⋯<xn=b, or in the form of a function; and the limits of integration a,b may be finite or infinite.
Some methods are specially designed for integrands of the form
f x=w x g x (2)
which contain a factor w x, called the weight-function, of a specific form. These methods take full account of any peculiar behaviour attributable to the w x factor.
(b) the values of the one-dimensional indefinite integrals arising from (1) where the ranges of integration are interior to the interval a,b.
(c) the value of a multidimensional definite integral of the form
∫Rn f x 1,x 2,…,xn d xn⋯d x 2 d x 1 (3)
where f x 1,x 2,…,xn is a function defined by you and Rn is some region of n-dimensional space.
The simplest form of Rn is the n-rectangle defined by
ai≤xi≤bi,  i=1,2,…,n (4)
where ai and bi are constants. When ai and bi are functions of xj (j<i), the region can easily be transformed to the rectangular form (see page 266 of Davis and Rabinowitz (1975)). Some of the methods described incorporate the transformation procedure.

One-dimensional Integrals

To estimate the value of a one-dimensional integral, a quadrature rule uses an approximation in the form of a weighted sum of integrand values, i.e.,
∫ab f x dx≃∑i=1 N wi f xi. (5)
The points xi within the interval a,b are known as the abscissae, and the wi are known as the weights.
More generally, if the integrand has the form (2), the corresponding formula is
∫ab w x g x dx≃∑i=1 N wi g xi. (6)
If the integrand is known only at a fixed set of points, these points must be used as the abscissae, and the weighted sum is calculated using finite difference methods. However, if the functional form of the integrand is known, so that its value at any abscissa is easily obtained, then a wide variety of quadrature rules are available, each characterised by its choice of abscissae and the corresponding weights.
The appropriate rule to use will depend on the interval a,b – whether finite or otherwise – and on the form of any w x factor in the integrand. A suitable value of N depends on the general behaviour of f x; or of g x, if there is a w x factor present.
Among possible rules, we mention particularly the Gaussian formulae, which employ a distribution of abscissae which is optimal for f x or g x of polynomial form.
The choice of basic rules constitutes one of the principles on which methods for one-dimensional integrals may be classified. The other major basis of classification is the implementation strategy, of which some types are now presented.
(a) Single rule evaluation procedures
A fixed number of abscissae, N, is used. This number and the particular rule chosen uniquely determine the weights and abscissae. No estimate is made of the accuracy of the result.
(b) Automatic procedures
The number of abscissae, N, within a,b is gradually increased until consistency is achieved to within a level of accuracy (absolute or relative) you requested. There are essentially two ways of doing this; hybrid forms of these two methods are also possible:
(i) whole interval procedures (non-adaptive)
A series of rules using increasing values of N are successively applied over the whole interval a,b. It is clearly more economical if abscissae already used for a lower value of N can be used again as part of a higher-order formula. This principle is known as optimal extension. There is no overlap between the abscissae used in Gaussian formulae of different orders. However, the Kronrod formulae are designed to give an optimal 2 N+1-point formula by adding N+1 points to an N-point Gauss formula. Further extensions have been developed by Patterson.
(ii) adaptive procedures
The interval a,b is repeatedly divided into a number of sub-intervals, and integration rules are applied separately to each sub-interval. Typically, the subdivision process will be carried further in the neighbourhood of a sharp peak in the integrand than where the curve is smooth. Thus, the distribution of abscissae is adapted to the shape of the integrand.
Subdivision raises the problem of what constitutes an acceptable accuracy in each sub-interval. The usual global acceptability criterion demands that the sum of the absolute values of the error estimates in the sub-intervals should meet the conditions required of the error over the whole interval. Automatic extrapolation over several levels of subdivision may eliminate the effects of some types of singularities.
An ideal general-purpose method would be an automatic method which could be used for a wide variety of integrands, was efficient (i.e., required the use of as few abscissae as possible), and was reliable (i.e., always gave results to within the requested accuracy). Complete reliability is unobtainable, and generally higher reliability is obtained at the expense of efficiency, and vice versa. It must therefore be emphasized that the automatic methods in this chapter cannot be assumed to be 100% reliable. In general, however, the reliability is very high.

Multidimensional Integrals

A distinction must be made between cases of moderately low dimensionality (say, up to 4 or 5 dimensions), and those of higher dimensionality. Where the number of dimensions is limited, a one-dimensional method may be applied to each dimension, according to some suitable strategy, and high accuracy may be obtainable (using product rules). However, the number of integrand evaluations rises very rapidly with the number of dimensions, so that the accuracy obtainable with an acceptable amount of computational labour is limited; for example a product of 3-point rules in 20 dimensions would require more than 109 integrand evaluations. Special techniques such as the Monte–Carlo methods can be used to deal with high dimensions.
(a) Products of one-dimensional rules
Using a two-dimensional integral as an example, we have
∫a 1 b 1∫a 2 b 2 f x,y dydx≃∑i=1 N wi∫a 2 b 2 f xi,y dy (7)
∫a 1 b 1∫a 2 b 2 f x,y dydx≃∑i=1 N∑j=1 N wivj f xi,yj (8)
where wi,xi and vi,yi are the weights and abscissae of the rules used in the respective dimensions.
A different one-dimensional rule may be used for each dimension, as appropriate to the range and any weight function present, and a different strategy may be used, as appropriate to the integrand behaviour as a function of each independent variable.
For a rule-evaluation strategy in all dimensions, the formula (8) is applied in a straightforward manner. For automatic strategies (i.e., attempting to attain a requested accuracy), there is a problem in deciding what accuracy must be requested in the inner integral(s). Reference to formula (7) shows that the presence of a limited but random error in the y-integration for different values of xi can produce a ‘jagged’ function of x, which may be difficult to integrate to the desired accuracy and for this reason products of automatic one-dimensional methods should be used with caution (see Lyness (1983)).
(b) Monte–Carlo methods
These are based on estimating the mean value of the integrand sampled at points chosen from an appropriate statistical distribution function. Usually a variance reducing procedure is incorporated to combat the fundamentally slow rate of convergence of the rudimentary form of the technique. These methods can be effective by comparison with alternative methods when the integrand contains singularities or is erratic in some way, but they are of quite limited accuracy.
(c) Number theoretic methods
These are based on the work of Korobov and Conroy and operate by exploiting implicitly the properties of the Fourier expansion of the integrand. Special rules, constructed from so-called optimal coefficients, give a particularly uniform distribution of the points throughout n-dimensional space and from their number theoretic properties minimize the error on a prescribed class of integrals. The method can be combined with the Monte–Carlo procedure.
(d) Sag–Szekeres method
By transformation this method seeks to induce properties into the integrand which make it accurately integrable by the trapezoidal rule. The transformation also allows effective control over the number of integrand evaluations.
(e) Sparse grid methods
Given a set of one-dimensional quadrature rules of increasing levels of accuracy, the sparse grid method constructs an approximation to a multidimensional integral using ndim dimensional tensor products of the differences between rules of adjacent levels. This provides a lower theoretical accuracy than the methods in (a), the full grid approach, however this is still sufficient for various classes of sufficiently smooth integrands. Furthermore, it requries substantially fewer evaluations than the full grid approach. Specifically, if a one-dimensional quadrature rule has N∼O 2 ℓ points, the full grid will require O N ndim function evaluations, whereas the sparse grid of level ℓ will require O 2 ℓndim ℓ-1. Hence a sparse grid approach is computationally feasible even for integrals over ndim∼O 100.
Sparse grid methods are deterministic, and may be viewed as automatic whole domain procedures if their level ℓ is allowed to increase.
(f) Automatic adaptive procedures
An automatic adaptive strategy in several dimensions normally involves division of the region into subregions, concentrating the divisions in those parts of the region where the integrand is worst behaved. It is difficult to arrange with any generality for variable limits in the inner integral(s). For this reason, some methods use a region where all the limits are constants; this is called a hyper-rectangle. Integrals over regions defined by variable or infinite limits may be handled by transformation to a hyper-rectangle. Integrals over regions so irregular that such a transformation is not feasible may be handled by surrounding the region by an appropriate hyper-rectangle and defining the integrand to be zero outside the desired region. Such a technique should always be followed by a Monte–Carlo method for integration.
The method used locally in each subregion produced by the adaptive subdivision process is usually one of three types: Monte–Carlo, number theoretic or deterministic. Deterministic methods are usually the most rapidly convergent but are often expensive to use for high dimensionality and not as robust as the other techniques.

References

Davis P J and Rabinowitz P (1975) Methods of Numerical Integration Academic Press
Gonnet P (2010) Increasing the reliability of adaptive quadrature using explicit interpolants ACM Trans. Math. software 37 26
Lyness J N (1983) When not to use an automatic quadrature routine SIAM Rev. 25 63–87
Patterson T N L (1968) The Optimum addition of points to quadrature formulae Math. Comput. 22 847–856
Piessens R, de Doncker–Kapenga E, Überhuber C and Kahaner D (1983) QUADPACK, A Subroutine Package for Automatic Integration Springer–Verlag
Sobol I M (1974) The Monte Carlo Method The University of Chicago Press
Stroud A H (1971) Approximate Calculation of Multiple Integrals Prentice–Hall
Wynn P (1956) On a device for computing the em Sn transformation Math. Tables Aids Comput. 10 91–96

Inheritance Hierarchy

System..::..Object
NagLibrary..::..D01

See Also

D01 Members


D01 Members

[image] [image]

NAG Library for .NET Release 2
D01 Members
D01 Class Methods See Also Send Feedback

The D01 type exposes the following members.

Methods

Name Description
d01ah
d01ah computes a definite integral over a finite range to a specified relative accuracy using a method described by Patterson.
d01aj
d01aj is a general purpose integrator which calculates an approximation to the integral of a function f x over a finite interval a,b:
I=∫ab f x dx.
d01ak
d01ak is an adaptive integrator, especially suited to oscillating, nonsingular integrands, which calculates an approximation to the integral of a function f x over a finite interval a,b:
I=∫ab f x dx.
d01al
d01al is a general purpose integrator which calculates an approximation to the integral of a function f x over a finite interval a,b:
I=∫ab f x dx
where the integrand may have local singular behaviour at a finite number of points within the integration interval.
d01am
d01am calculates an approximation to the integral of a function f x over an infinite or semi-infinite interval a,b:
I=∫ab f x dx.
d01an
d01an calculates an approximation to the sine or the cosine transform of a function g over a,b:
I=∫ab g x sin ωxdx  or  I=∫ab g x cos ωxdx
(for a user-specified value of ω).
d01ap
d01ap is an adaptive integrator which calculates an approximation to the integral of a function g x w x over a finite interval a,b:
I=∫ab g x w x dx
where the weight function w has end point singularities of algebraico-logarithmic type.
d01aq
d01aq calculates an approximation to the Hilbert transform of a function g x over a,b:
I=∫ab g xx-c dx
for user-specified values of a, b and c.
d01ar
d01ar computes definite and indefinite integrals over a finite range to a specified relative or absolute accuracy, using the method described in Patterson (1968).
d01as
d01as calculates an approximation to the sine or the cosine transform of a function g over a,∞:
I=∫a∞g x sin ωxdx  or  I=∫a∞g x cos ωxdx
(for a user-specified value of ω).
d01bc
d01bc returns the weights (normal or adjusted) and abscissae for a Gaussian integration rule with a specified number of abscissae. Six different types of Gauss rule are allowed.
d01bd
d01bd calculates an approximation to the integral of a function over a finite interval a,b:
I=∫ab f x dx.
It is non-adaptive and as such is recommended for the integration of ‘smooth’ functions. These exclude integrands with singularities, derivative singularities or high peaks on a,b, or which oscillate too strongly on a,b.
d01da
d01da attempts to evaluate a double integral to a specified absolute accuracy by repeated applications of the method described by Patterson (1968) and Patterson (1969) .
d01fc
d01fc attempts to evaluate a multidimensional integral (up to 15 dimensions), with constant and finite limits, to a specified relative accuracy, using an adaptive subdivision strategy.
d01gd
d01gd calculates an approximation to a definite integral in up to 20 dimensions, using the Korobov–Conroy number theoretic method. This method is designed to be particularly efficient on vector processors.
d01gy
d01gy calculates the optimal coefficients for use by (D01GCF not in this release) d01gd, for prime numbers of points.
d01gz
d01gz calculates the optimal coefficients for use by (D01GCF not in this release) d01gd, when the number of points is the product of two primes.
d01ja
d01ja attempts to evaluate an integral over an n-dimensional sphere (n=2, 3, or 4), to a user-specified absolute or relative accuracy, by means of a modified Sag–Szekeres method. The method can handle singularities on the surface or at the centre of the sphere, and returns an error estimate.
d01pa
d01pa returns a sequence of approximations to the integral of a function over a multidimensional simplex, together with an error estimate for the last approximation.

See Also

D01 Class


D01 Delegates

[image]

NAG Library for .NET Release 2
D01 Delegates

D01 Delegate Types

  • D01.D01AH_F Delegate
  • D01.D01AJ_F Delegate
  • D01.D01AK_F Delegate
  • D01.D01AL_F Delegate
  • D01.D01AM_F Delegate
  • D01.D01AN_G Delegate
  • D01.D01AP_G Delegate
  • D01.D01AQ_G Delegate
  • D01.D01AR_FUN Delegate
  • D01.D01AS_G Delegate
  • D01.D01BD_F Delegate
  • D01.D01DA_F Delegate
  • D01.D01DA_PHI1 Delegate
  • D01.D01DA_PHI2 Delegate
  • D01.D01FC_FUNCTN Delegate
  • D01.D01GD_VECFUN Delegate
  • D01.D01GD_VECREG Delegate
  • D01.D01JA_F Delegate
  • D01.D01PA_FUNCTN Delegate


D01.D01AH_F Delegate

[image]

NAG Library for .NET Release 2
D01..::..D01AH_F Delegate
D01 Class See Also Send Feedback
f must return the value of the integrand f at a given point.

Syntax

C#
public delegate double D01AH_F(
    double x
)
Visual Basic
Public Delegate Function D01AH_F ( _
    x As Double _
) As Double
Visual C++
public delegate double D01AH_F(
    double x
)
F#
type D01AH_F =
    delegate of
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the point at which the integrand f must be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
d01ah


D01.D01AJ_F Delegate

[image]

NAG Library for .NET Release 2
D01..::..D01AJ_F Delegate
D01 Class See Also Send Feedback
f must return the value of the integrand f at a given point.

Syntax

C#
public delegate double D01AJ_F(
    double x
)
Visual Basic
Public Delegate Function D01AJ_F ( _
    x As Double _
) As Double
Visual C++
public delegate double D01AJ_F(
    double x
)
F#
type D01AJ_F =
    delegate of
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the point at which the integrand f must be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
d01aj


D01.D01AK_F Delegate

[image]

NAG Library for .NET Release 2
D01..::..D01AK_F Delegate
D01 Class See Also Send Feedback
f must return the value of the integrand f at a given point.

Syntax

C#
public delegate double D01AK_F(
    double x
)
Visual Basic
Public Delegate Function D01AK_F ( _
    x As Double _
) As Double
Visual C++
public delegate double D01AK_F(
    double x
)
F#
type D01AK_F =
    delegate of
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the point at which the integrand f must be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
d01ak


D01.D01AL_F Delegate

[image]

NAG Library for .NET Release 2
D01..::..D01AL_F Delegate
D01 Class See Also Send Feedback
f must return the value of the integrand f at a given point.

Syntax

C#
public delegate double D01AL_F(
    double x
)
Visual Basic
Public Delegate Function D01AL_F ( _
    x As Double _
) As Double
Visual C++
public delegate double D01AL_F(
    double x
)
F#
type D01AL_F =
    delegate of
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the point at which the integrand f must be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
d01al


D01.D01AM_F Delegate

[image]

NAG Library for .NET Release 2
D01..::..D01AM_F Delegate
D01 Class See Also Send Feedback
f must return the value of the integrand f at a given point.

Syntax

C#
public delegate double D01AM_F(
    double x
)
Visual Basic
Public Delegate Function D01AM_F ( _
    x As Double _
) As Double
Visual C++
public delegate double D01AM_F(
    double x
)
F#
type D01AM_F =
    delegate of
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the point at which the integrand f must be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
d01am


D01.D01AN_G Delegate

[image]

NAG Library for .NET Release 2
D01..::..D01AN_G Delegate
D01 Class See Also Send Feedback
g must return the value of the function g at a given point x.

Syntax

C#
public delegate double D01AN_G(
    double x
)
Visual Basic
Public Delegate Function D01AN_G ( _
    x As Double _
) As Double
Visual C++
public delegate double D01AN_G(
    double x
)
F#
type D01AN_G =
    delegate of
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the point at which the function g must be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
d01an


D01.D01AP_G Delegate

[image]

NAG Library for .NET Release 2
D01..::..D01AP_G Delegate
D01 Class See Also Send Feedback
g must return the value of the function g at a given point x.

Syntax

C#
public delegate double D01AP_G(
    double x
)
Visual Basic
Public Delegate Function D01AP_G ( _
    x As Double _
) As Double
Visual C++
public delegate double D01AP_G(
    double x
)
F#
type D01AP_G =
    delegate of
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the point at which the function g must be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
d01ap


D01.D01AQ_G Delegate

[image]

NAG Library for .NET Release 2
D01..::..D01AQ_G Delegate
D01 Class See Also Send Feedback
g must return the value of the function g at a given point x.

Syntax

C#
public delegate double D01AQ_G(
    double x
)
Visual Basic
Public Delegate Function D01AQ_G ( _
    x As Double _
) As Double
Visual C++
public delegate double D01AQ_G(
    double x
)
F#
type D01AQ_G =
    delegate of
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the point at which the function g must be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
d01aq


D01.D01AR_FUN Delegate

[image]

NAG Library for .NET Release 2
D01..::..D01AR_FUN Delegate
D01 Class See Also Send Feedback
fun must return the value of the integrand f at a specified point.

Syntax

C#
public delegate double D01AR_FUN(
    double x
)
Visual Basic
Public Delegate Function D01AR_FUN ( _
    x As Double _
) As Double
Visual C++
public delegate double D01AR_FUN(
    double x
)
F#
type D01AR_FUN =
    delegate of
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the point in a,b at which the integrand f must be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
d01ar


D01.D01AS_G Delegate

[image]

NAG Library for .NET Release 2
D01..::..D01AS_G Delegate
D01 Class See Also Send Feedback
g must return the value of the function g at a given point x.

Syntax

C#
public delegate double D01AS_G(
    double x
)
Visual Basic
Public Delegate Function D01AS_G ( _
    x As Double _
) As Double
Visual C++
public delegate double D01AS_G(
    double x
)
F#
type D01AS_G =
    delegate of
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the point at which the function g must be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
d01as


D01.D01BD_F Delegate

[image]

NAG Library for .NET Release 2
D01..::..D01BD_F Delegate
D01 Class See Also Send Feedback
f must return the value of the integrand f at a given point.

Syntax

C#
public delegate double D01BD_F(
    double x
)
Visual Basic
Public Delegate Function D01BD_F ( _
    x As Double _
) As Double
Visual C++
public delegate double D01BD_F(
    double x
)
F#
type D01BD_F =
    delegate of
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the point at which the integrand f must be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
d01bd


D01.D01DA_F Delegate

[image]

NAG Library for .NET Release 2
D01..::..D01DA_F Delegate
D01 Class See Also Send Feedback
f must return the value of the integrand f at a given point.

Syntax

C#
public delegate double D01DA_F(
    double x,
    double y
)
Visual Basic
Public Delegate Function D01DA_F ( _
    x As Double, _
    y As Double _
) As Double
Visual C++
public delegate double D01DA_F(
    double x,
    double y
)
F#
type D01DA_F =
    delegate of
        x : float *
        y : float -> float

Parameters

x
Type: System..::..Double
On entry: the coordinates of the point x,y at which the integrand f must be evaluated.
y
Type: System..::..Double
On entry: the coordinates of the point x,y at which the integrand f must be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
d01da


D01.D01DA_PHI1 Delegate

[image]

NAG Library for .NET Release 2
D01..::..D01DA_PHI1 Delegate
D01 Class See Also Send Feedback
phi1 must return the lower limit of the inner integral for a given value of y.

Syntax

C#
public delegate double D01DA_PHI1(
    double y
)
Visual Basic
Public Delegate Function D01DA_PHI1 ( _
    y As Double _
) As Double
Visual C++
public delegate double D01DA_PHI1(
    double y
)
F#
type D01DA_PHI1 =
    delegate of
        y : float -> float

Parameters

y
Type: System..::..Double
On entry: the value of y for which the lower limit must be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
d01da


D01.D01DA_PHI2 Delegate

[image]

NAG Library for .NET Release 2
D01..::..D01DA_PHI2 Delegate
D01 Class See Also Send Feedback
phi2 must return the upper limit of the inner integral for a given value of y.

Syntax

C#
public delegate double D01DA_PHI2(
    double y
)
Visual Basic
Public Delegate Function D01DA_PHI2 ( _
    y As Double _
) As Double
Visual C++
public delegate double D01DA_PHI2(
    double y
)
F#
type D01DA_PHI2 =
    delegate of
        y : float -> float

Parameters

y
Type: System..::..Double
On entry: the value of y for which the upper limit must be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
d01da


D01.D01FC_FUNCTN Delegate

[image]

NAG Library for .NET Release 2
D01..::..D01FC_FUNCTN Delegate
D01 Class See Also Send Feedback
functn must return the value of the integrand f at a given point.

Syntax

C#
public delegate double D01FC_FUNCTN(
    int ndim,
    double[] z
)
Visual Basic
Public Delegate Function D01FC_FUNCTN ( _
    ndim As Integer, _
    z As Double() _
) As Double
Visual C++
public delegate double D01FC_FUNCTN(
    int ndim,
    array<double>^ z
)
F#
type D01FC_FUNCTN =
    delegate of
        ndim : int *
        z : float[] -> float

Parameters

ndim
Type: System..::..Int32
On entry: n, the number of dimensions of the integral.
z
Type: array< System..::..Double >[]()[][]
On entry: the coordinates of the point at which the integrand f must be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
d01fc


D01.D01GD_VECFUN Delegate

[image]

NAG Library for .NET Release 2
D01..::..D01GD_VECFUN Delegate
D01 Class See Also Send Feedback
vecfun must evaluate the integrand at a specified set of points.

Syntax

C#
public delegate void D01GD_VECFUN(
    int ndim,
    double[,] x,
    double[] fv,
    int m
)
Visual Basic
Public Delegate Sub D01GD_VECFUN ( _
    ndim As Integer, _
    x As Double(,), _
    fv As Double(), _
    m As Integer _
)
Visual C++
public delegate void D01GD_VECFUN(
    int ndim,
    array<double,2>^ x,
    array<double>^ fv,
    int m
)
F#
type D01GD_VECFUN =
    delegate of
        ndim : int *
        x : float[,] *
        fv : float[] *
        m : int -> unit

Parameters

ndim
Type: System..::..Int32
On entry: n, the number of dimensions of the integral.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
On entry: the coordinates of the m points at which the integrand must be evaluated. x[i-1,j-1] contains the jth coordinate of the ith point.
fv
Type: array< System..::..Double >[]()[][]
On exit: fv[i-1] must contain the value of the integrand of the ith point, i.e., fv[i-1]=f x[i-1,0],x[i-1,1],…,x[i-1,ndim-1], for i=1,2,…,m.
m
Type: System..::..Int32
On entry: the number of points m at which the integrand is to be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
d01gd


D01.D01GD_VECREG Delegate

[image]

NAG Library for .NET Release 2
D01..::..D01GD_VECREG Delegate
D01 Class See Also Send Feedback
vecreg must evaluate the limits of integration in any dimension for a set of points.

Syntax

C#
public delegate void D01GD_VECREG(
    int ndim,
    double[,] x,
    int j,
    double[] c,
    double[] d,
    int m
)
Visual Basic
Public Delegate Sub D01GD_VECREG ( _
    ndim As Integer, _
    x As Double(,), _
    j As Integer, _
    c As Double(), _
    d As Double(), _
    m As Integer _
)
Visual C++
public delegate void D01GD_VECREG(
    int ndim,
    array<double,2>^ x,
    int j,
    array<double>^ c,
    array<double>^ d,
    int m
)
F#
type D01GD_VECREG =
    delegate of
        ndim : int *
        x : float[,] *
        j : int *
        c : float[] *
        d : float[] *
        m : int -> unit

Parameters

ndim
Type: System..::..Int32
On entry: n, the number of dimensions of the integral.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
On entry: for i=1,2,…,m, x[i-1,0], x[i-1,1],…,x[i-1,j-2] contain the current values of the first j-1 coordinates of the ith point, which may be used if necessary in calculating the m values of cj and dj.
j
Type: System..::..Int32
On entry: the index j for which the limits of the range of integration are required.
c
Type: array< System..::..Double >[]()[][]
On exit: c[i-1] must be set to the lower limit of the range for x[i-1,j-1], for i=1,2,…,m.
d
Type: array< System..::..Double >[]()[][]
On exit: d[i-1] must be set to the upper limit of the range for x[i-1,j-1], for i=1,2,…,m.
m
Type: System..::..Int32
On entry: the number of points m at which the limits of integration must be specified.

See Also

NagLibrary Namespace
NAG Library Overview
d01gd


D01.D01JA_F Delegate

[image]

NAG Library for .NET Release 2
D01..::..D01JA_F Delegate
D01 Class See Also Send Feedback
f must return the value of the integrand f at a given point.

Syntax

C#
public delegate double D01JA_F(
    int ndim,
    double[] x
)
Visual Basic
Public Delegate Function D01JA_F ( _
    ndim As Integer, _
    x As Double() _
) As Double
Visual C++
public delegate double D01JA_F(
    int ndim,
    array<double>^ x
)
F#
type D01JA_F =
    delegate of
        ndim : int *
        x : float[] -> float

Parameters

ndim
Type: System..::..Int32
On entry: n, the number of dimensions of the integral.
x
Type: array< System..::..Double >[]()[][]
On entry: the coordinates of the point at which the integrand f must be evaluated. These coordinates are given in Cartesian or spherical polar form according to the value of icoord.

See Also

NagLibrary Namespace
NAG Library Overview
d01ja


D01.D01PA_FUNCTN Delegate

[image]

NAG Library for .NET Release 2
D01..::..D01PA_FUNCTN Delegate
D01 Class See Also Send Feedback
functn must return the value of the integrand f at a given point.

Syntax

C#
public delegate double D01PA_FUNCTN(
    int ndim,
    double[] x
)
Visual Basic
Public Delegate Function D01PA_FUNCTN ( _
    ndim As Integer, _
    x As Double() _
) As Double
Visual C++
public delegate double D01PA_FUNCTN(
    int ndim,
    array<double>^ x
)
F#
type D01PA_FUNCTN =
    delegate of
        ndim : int *
        x : float[] -> float

Parameters

ndim
Type: System..::..Int32
On entry: n, the number of dimensions of the integral.
x
Type: array< System..::..Double >[]()[][]
On entry: the coordinates of the point at which the integrand f must be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
d01pa


D01 Methods

[image] [image]

NAG Library for .NET Release 2
D01 Methods
D01 Class See Also Send Feedback

The D01 type exposes the following members.

Methods

Name Description
d01ah
d01ah computes a definite integral over a finite range to a specified relative accuracy using a method described by Patterson.
d01aj
d01aj is a general purpose integrator which calculates an approximation to the integral of a function f x over a finite interval a,b:
I=∫ab f x dx.
d01ak
d01ak is an adaptive integrator, especially suited to oscillating, nonsingular integrands, which calculates an approximation to the integral of a function f x over a finite interval a,b:
I=∫ab f x dx.
d01al
d01al is a general purpose integrator which calculates an approximation to the integral of a function f x over a finite interval a,b:
I=∫ab f x dx
where the integrand may have local singular behaviour at a finite number of points within the integration interval.
d01am
d01am calculates an approximation to the integral of a function f x over an infinite or semi-infinite interval a,b:
I=∫ab f x dx.
d01an
d01an calculates an approximation to the sine or the cosine transform of a function g over a,b:
I=∫ab g x sin ωxdx  or  I=∫ab g x cos ωxdx
(for a user-specified value of ω).
d01ap
d01ap is an adaptive integrator which calculates an approximation to the integral of a function g x w x over a finite interval a,b:
I=∫ab g x w x dx
where the weight function w has end point singularities of algebraico-logarithmic type.
d01aq
d01aq calculates an approximation to the Hilbert transform of a function g x over a,b:
I=∫ab g xx-c dx
for user-specified values of a, b and c.
d01ar
d01ar computes definite and indefinite integrals over a finite range to a specified relative or absolute accuracy, using the method described in Patterson (1968).
d01as
d01as calculates an approximation to the sine or the cosine transform of a function g over a,∞:
I=∫a∞g x sin ωxdx  or  I=∫a∞g x cos ωxdx
(for a user-specified value of ω).
d01bc
d01bc returns the weights (normal or adjusted) and abscissae for a Gaussian integration rule with a specified number of abscissae. Six different types of Gauss rule are allowed.
d01bd
d01bd calculates an approximation to the integral of a function over a finite interval a,b:
I=∫ab f x dx.
It is non-adaptive and as such is recommended for the integration of ‘smooth’ functions. These exclude integrands with singularities, derivative singularities or high peaks on a,b, or which oscillate too strongly on a,b.
d01da
d01da attempts to evaluate a double integral to a specified absolute accuracy by repeated applications of the method described by Patterson (1968) and Patterson (1969).
d01fc
d01fc attempts to evaluate a multidimensional integral (up to 15 dimensions), with constant and finite limits, to a specified relative accuracy, using an adaptive subdivision strategy.
d01gd
d01gd calculates an approximation to a definite integral in up to 20 dimensions, using the Korobov–Conroy number theoretic method. This method is designed to be particularly efficient on vector processors.
d01gy
d01gy calculates the optimal coefficients for use by (D01GCF not in this release) d01gd, for prime numbers of points.
d01gz
d01gz calculates the optimal coefficients for use by (D01GCF not in this release) d01gd, when the number of points is the product of two primes.
d01ja
d01ja attempts to evaluate an integral over an n-dimensional sphere (n=2, 3, or 4), to a user-specified absolute or relative accuracy, by means of a modified Sag–Szekeres method. The method can handle singularities on the surface or at the centre of the sphere, and returns an error estimate.
d01pa
d01pa returns a sequence of approximations to the integral of a function over a multidimensional simplex, together with an error estimate for the last approximation.

See Also

D01 Class


d01ah Method

[image]

NAG Library for .NET Release 2
D01..::d01ah Method
D01 Class See Also Send Feedback
d01ah computes a definite integral over a finite range to a specified relative accuracy using a method described by Patterson.

Syntax

C#
public static double d01ah(
    double a,
    double b,
    double epsr,
    out int npts,
    out double relerr,
    D01..::..D01AH_F f,
    int nlimit,
    out int ifail
)
Visual Basic
Public Shared Function d01ah ( _
    a As Double, _
    b As Double, _
    epsr As Double, _
    <OutAttribute> ByRef npts As Integer, _
    <OutAttribute> ByRef relerr As Double, _
    f As D01..::..D01AH_F, _
    nlimit As Integer, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double d01ah(
    double a,
    double b,
    double epsr,
    [OutAttribute] int% npts,
    [OutAttribute] double% relerr,
    D01..::..D01AH_F^ f,
    int nlimit,
    [OutAttribute] int% ifail
)
F#
static member d01ah :
        a : float *
        b : float *
        epsr : float *
        npts : int byref *
        relerr : float byref *
        f : D01..::..D01AH_F *
        nlimit : int *
        ifail : int byref -> float

Parameters

a
Type: System..::..Double
On entry: a, the lower limit of integration.
b
Type: System..::..Double
On entry: b, the upper limit of integration. It is not necessary that a<b.
epsr
Type: System..::..Double
On entry: the relative accuracy required.
Constraint: epsr>0.0.
npts
Type: System..::..Int32 %
On exit: the number of function evaluations used in the calculation of the integral.
relerr
Type: System..::..Double %
On exit: a rough estimate of the relative error achieved.
f
Type: NagLibrary..::..D01..::..D01AH_F
f must return the value of the integrand f at a given point.

A delegate of type D01AH_F.

nlimit
Type: System..::..Int32
On entry: a limit to the number of function evaluations. If nlimit≤0, the method uses a default limit of 10000.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

d01ah computes a definite integral over a finite range to a specified relative accuracy using a method described by Patterson.

Description

d01ah computes a definite integral of the form
∫ab f x dx.
The method uses as its basis a family of interlacing high precision rules (see Patterson (1968)) using 1, 3, 7, 15, 31, 63, 127 and 255 nodes. Initially the family is applied in sequence to the integrand. When two successive rules differ relatively by less than the required relative accuracy, the last rule used is taken as the value of the integral and the operation is regarded as successful. If all rules in the family have been applied unsuccessfully, subdivision is invoked. The subdivision strategy is as follows. The interval under scrutiny is divided into two sub-intervals (not always equal). The basic family is then applied to the first sub-interval. If the required accuracy is not obtained, the interval is stored for future examination (see ifail=2) and the second sub-interval is examined. Should the basic family again be unsuccessful, then the sub-interval is further subdivided and the whole process repeated. Successful integrations are accumulated as the partial value of the integral. When all possible successful integrations have been completed, those previously unsuccessful sub-intervals placed in store are examined.
A large number of refinements are incorporated to improve the performance. Some of these are:
(a) | The rate of convergence of the basic family is monitored and used to make a decision to abort and subdivide before the full sequence has been applied.
(b) | The ε-algorithm is applied to the basic results in an attempt to increase the convergence rate. See Wynn (1956).
(c) | An attempt is made to detect sharp end point peaks and singularities in each sub-interval and to apply appropriate transformations to smooth the integrand. This consideration is also used to select interval sizes in the subdivision process.
(d) | The relative accuracy sought in each sub-interval is adjusted in accordance with its likely contribution to the total integral.
(e) | Random transformations of the integrand are applied to improve reliability in some instances.

References

Patterson T N L (1968) The Optimum addition of points to quadrature formulae Math. Comput. 22 847–856
Wynn P (1956) On a device for computing the em Sn transformation Math. Tables Aids Comput. 10 91–96

Error Indicators and Warnings

Note: d01ah may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail=1
The integral has not converged to the accuracy requested. It may be worthwhile to try increasing nlimit.
ifail=2
Too many unsuccessful levels of subdivision have been invoked.
ifail=3
On entry, epsr≤0.0.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
When ifail=1 or 2 a result may be obtained by continuing without further subdivision, but this is likely to be inaccurate.

Accuracy

The relative accuracy required is specified by you in the variable epsr. The method will terminate whenever the relative accuracy specified by epsr is judged to have been reached.
If on exit, ifail=0, then it is most likely that the result is correct to the specified accuracy. If, on exit, ifail=1 or 2, then it is likely that the specified accuracy has not been reached.
relerr is a rough estimate of the relative error achieved. It is a by-product of the computation and is not used to effect the termination of the method. The outcome of the integration must be judged by the value of ifail.

Parallelism and Performance

None.

Further Comments

The time taken by d01ah depends on the complexity of the integrand and the accuracy required.

Example

This example evaluates the integral to a requested relative accuracy of 10-5
∫01 4 1+x 2 dx=π.

Example program (C#): d01ahe.cs

Example program data: d01ahe.d

Example program results: d01ahe.r

See Also

D01 Class
D01 Members


d01aj Method

[image]

NAG Library for .NET Release 2
D01..::d01aj Method
D01 Class See Also Send Feedback
d01aj is a general purpose integrator which calculates an approximation to the integral of a function f x over a finite interval a,b:
I=∫ab f x dx.

Syntax

C#
public static void d01aj(
    D01..::..D01AJ_F f,
    double a,
    double b,
    double epsabs,
    double epsrel,
    out double result,
    out double abserr,
    double[] w,
    out int subintvls,
    out int ifail
)
Visual Basic
Public Shared Sub d01aj ( _
    f As D01..::..D01AJ_F, _
    a As Double, _
    b As Double, _
    epsabs As Double, _
    epsrel As Double, _
    <OutAttribute> ByRef result As Double, _
    <OutAttribute> ByRef abserr As Double, _
    w As Double(), _
    <OutAttribute> ByRef subintvls As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void d01aj(
    D01..::..D01AJ_F^ f,
    double a,
    double b,
    double epsabs,
    double epsrel,
    [OutAttribute] double% result,
    [OutAttribute] double% abserr,
    array<double>^ w,
    [OutAttribute] int% subintvls,
    [OutAttribute] int% ifail
)
F#
static member d01aj :
        f : D01..::..D01AJ_F *
        a : float *
        b : float *
        epsabs : float *
        epsrel : float *
        result : float byref *
        abserr : float byref *
        w : float[] *
        subintvls : int byref *
        ifail : int byref -> unit

Parameters

f
Type: NagLibrary..::..D01..::..D01AJ_F
f must return the value of the integrand f at a given point.

A delegate of type D01AJ_F.

a
Type: System..::..Double
On entry: a, the lower limit of integration.
b
Type: System..::..Double
On entry: b, the upper limit of integration. It is not necessary that a<b.
epsabs
Type: System..::..Double
On entry: the absolute accuracy required. If epsabs is negative, the absolute value is used. See [Accuracy].
epsrel
Type: System..::..Double
On entry: the relative accuracy required. If epsrel is negative, the absolute value is used. See [Accuracy].
result
Type: System..::..Double %
On exit: the approximation to the integral I.
abserr
Type: System..::..Double %
On exit: an estimate of the modulus of the absolute error, which should be an upper bound for I-result.
w
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: dim1 must satisfy the constraint: _lw≥4
On exit: details of the computation see [Further Comments] for more information.
subintvls
Type: System..::..Int32 %
On exit: subintvls contains the actual number of sub-intervals used.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

d01aj is based on the QUADPACK routine QAGS (see Piessens et al. (1983)). It is an adaptive method, using the Gauss 10-point and Kronrod 21-point rules. The algorithm, described in de Doncker (1978), incorporates a global acceptance criterion (as defined by Malcolm and Simpson (1976)) together with the ε-algorithm (see Wynn (1956)) to perform extrapolation. The local error estimation is described in Piessens et al. (1983).
The method is suitable as a general purpose integrator, and can be used when the integrand has singularities, especially when these are of algebraic or logarithmic type.
d01aj requires you to supply a function to evaluate the integrand at a single point.
The method (D01ATF not in this release) uses an identical algorithm but requires you to supply a method to evaluate the integrand at an array of points. Therefore (D01ATF not in this release) may be more efficient for some problem types and some machine architectures.

References

de Doncker E (1978) An adaptive extrapolation algorithm for automatic integration ACM SIGNUM Newsl. 13(2) 12–18
Malcolm M A and Simpson R B (1976) Local versus global strategies for adaptive quadrature ACM Trans. Math. Software 1 129–146
Piessens R, de Doncker–Kapenga E, Überhuber C and Kahaner D (1983) QUADPACK, A Subroutine Package for Automatic Integration Springer–Verlag
Wynn P (1956) On a device for computing the em Sn transformation Math. Tables Aids Comput. 10 91–96

Error Indicators and Warnings

Note: d01aj may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LW, IW) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
The maximum number of subdivisions allowed with the given workspace has been reached without the accuracy requirements being achieved. Look at the integrand in order to determine the integration difficulties. If the position of a local difficulty within the interval can be determined (e.g., a singularity of the integrand or its derivative, a peak, a discontinuity, etc.) you will probably gain from splitting up the interval at this point and calling the integrator on the subranges. If necessary, another integrator, which is designed for handling the type of difficulty involved, must be used. Alternatively, consider relaxing the accuracy requirements specified by epsabs and epsrel, or increasing the amount of workspace.
ifail=2
Round-off error prevents the requested tolerance from being achieved. Consider requesting less accuracy.
ifail=3
Extremely bad local integrand behaviour causes a very strong subdivision around one (or more) points of the interval. The same advice applies as in the case of ifail=1.
ifail=4
The requested tolerance cannot be achieved because the extrapolation does not increase the accuracy satisfactorily; the returned result is the best which can be obtained. The same advice applies as in the case of ifail=1.
ifail=5
The integral is probably divergent, or slowly convergent. Please note that divergence can occur with any nonzero value of ifail.
ifail=6
On entry, liw<1.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

d01aj cannot guarantee, but in practice usually achieves, the following accuracy:
I-result≤tol,
where
tol=max epsabs,epsrel×I,
and epsabs and epsrel are user-specified absolute and relative error tolerances. Moreover, it returns the quantity abserr which, in normal circumstances, satisfies
I-result≤abserr≤tol.

Parallelism and Performance

None.

Further Comments

The time taken by d01aj depends on the integrand and the accuracy required.
If ifail≠0 on exit, then you may wish to examine the contents of the array w, which contains the end points of the sub-intervals used by d01aj along with the integral contributions and error estimates over the sub-intervals.
Specifically, for i=1,2,…,n, let ri denote the approximation to the value of the integral over the sub-interval ai,bi in the partition of a,b and ei be the corresponding absolute error estimate. Then, ∫aibi f x dx≃ri and result=∑i=1 n ri, unless d01aj terminates while testing for divergence of the integral (see Section 3.4.3 of Piessens et al. (1983)). In this case, result (and abserr) are taken to be the values returned from the extrapolation process. The value of n is returned in _iw[0], and the values ai, bi, ei and ri are stored consecutively in the array w, that is:
  • ai=w[i-1],
  • bi=w[n+i-1],
  • ei=w[2 n+i-1] and
  • ri=w[3 n+i-1].

Example

This example computes
∫0 2 π x sin 30 x1-x/2 π 2 dx.

Example program (C#): d01aje.cs

Example program results: d01aje.r

See Also

D01 Class
D01 Members


d01ak Method

[image]

NAG Library for .NET Release 2
D01..::d01ak Method
D01 Class See Also Send Feedback
d01ak is an adaptive integrator, especially suited to oscillating, nonsingular integrands, which calculates an approximation to the integral of a function f x over a finite interval a,b:
I=∫ab f x dx.

Syntax

C#
public static void d01ak(
    D01..::..D01AK_F f,
    double a,
    double b,
    double epsabs,
    double epsrel,
    out double result,
    out double abserr,
    double[] w,
    out int subintvls,
    out int ifail
)
Visual Basic
Public Shared Sub d01ak ( _
    f As D01..::..D01AK_F, _
    a As Double, _
    b As Double, _
    epsabs As Double, _
    epsrel As Double, _
    <OutAttribute> ByRef result As Double, _
    <OutAttribute> ByRef abserr As Double, _
    w As Double(), _
    <OutAttribute> ByRef subintvls As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void d01ak(
    D01..::..D01AK_F^ f,
    double a,
    double b,
    double epsabs,
    double epsrel,
    [OutAttribute] double% result,
    [OutAttribute] double% abserr,
    array<double>^ w,
    [OutAttribute] int% subintvls,
    [OutAttribute] int% ifail
)
F#
static member d01ak :
        f : D01..::..D01AK_F *
        a : float *
        b : float *
        epsabs : float *
        epsrel : float *
        result : float byref *
        abserr : float byref *
        w : float[] *
        subintvls : int byref *
        ifail : int byref -> unit

Parameters

f
Type: NagLibrary..::..D01..::..D01AK_F
f must return the value of the integrand f at a given point.

A delegate of type D01AK_F.

a
Type: System..::..Double
On entry: a, the lower limit of integration.
b
Type: System..::..Double
On entry: b, the upper limit of integration. It is not necessary that a<b.
epsabs
Type: System..::..Double
On entry: the absolute accuracy required. If epsabs is negative, the absolute value is used. See [Accuracy].
epsrel
Type: System..::..Double
On entry: the relative accuracy required. If epsrel is negative, the absolute value is used. See [Accuracy].
result
Type: System..::..Double %
On exit: the approximation to the integral I.
abserr
Type: System..::..Double %
On exit: an estimate of the modulus of the absolute error, which should be an upper bound for I-result.
w
Type: array< System..::..Double >[]()[][]
An array of size [lw]
On exit: details of the computation see [Further Comments] for more information.
subintvls
Type: System..::..Int32 %
On exit: subintvls contains the actual number of sub-intervals used.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

d01ak is based on the QUADPACK routine QAG (see Piessens et al. (1983)). It is an adaptive method, using the Gauss 30-point and Kronrod 61-point rules. A ‘global’ acceptance criterion (as defined by Malcolm and Simpson (1976)) is used. The local error estimation is described in Piessens et al. (1983).
Because d01ak is based on integration rules of high order, it is especially suitable for nonsingular oscillating integrands.
d01ak requires you to supply a function to evaluate the integrand at a single point.
The method (D01AUF not in this release) uses an identical algorithm but requires you to supply a method to evaluate the integrand at an array of points. Therefore (D01AUF not in this release) will be more efficient if the evaluation can be performed in vector mode on a vector-processing machine.

References

Malcolm M A and Simpson R B (1976) Local versus global strategies for adaptive quadrature ACM Trans. Math. Software 1 129–146
Piessens R (1973) An algorithm for automatic integration Angew. Inf. 15 399–401
Piessens R, de Doncker–Kapenga E, Überhuber C and Kahaner D (1983) QUADPACK, A Subroutine Package for Automatic Integration Springer–Verlag

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (IW) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
The maximum number of subdivisions allowed with the given workspace has been reached without the accuracy requirements being achieved. Look at the integrand in order to determine the integration difficulties. If necessary, another integrator, which is designed for handling the type of difficulty involved, must be used. Alternatively, consider relaxing the accuracy requirements specified by epsabs and epsrel, or increasing the amount of workspace.
ifail=2
Round-off error prevents the requested tolerance from being achieved. Consider requesting less accuracy.
ifail=3
Extremely bad local integrand behaviour causes a very strong subdivision around one (or more) points of the interval. The same advice applies as in the case of ifail=1.
ifail=4
On entry, | lw<4,
or | liw<1.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

d01ak cannot guarantee, but in practice usually achieves, the following accuracy:
I-result≤tol,
where
tol=max epsabs,epsrel×I,
and epsabs and epsrel are user-specified absolute and relative error tolerances. Moreover, it returns the quantity abserr which, in normal circumstances, satisfies
I-result≤abserr≤tol.

Parallelism and Performance

None.

Further Comments

The time taken by d01ak depends on the integrand and the accuracy required.
If ifail≠0 on exit, then you may wish to examine the contents of the array w, which contains the end points of the sub-intervals used by d01ak along with the integral contributions and error estimates over these sub-intervals.
Specifically, for i=1,2,…,n, let ri denote the approximation to the value of the integral over the sub-interval ai,bi in the partition of a,b and ei be the corresponding absolute error estimate. Then, ∫aibi f x dx≃ri and result=∑i=1 n ri. The value of n is returned in _iw[0], and the values ai, bi, ei and ri are stored consecutively in the array w, that is:
  • ai=w[i-1],
  • bi=w[n+i-1],
  • ei=w[2 n+i-1] and
  • ri=w[3 n+i-1].

Example

This example computes
∫0 2 π x sin 30 xcos x dx.

Example program (C#): d01ake.cs

Example program results: d01ake.r

See Also

D01 Class
D01 Members


d01al Method

[image]

NAG Library for .NET Release 2
D01..::d01al Method
D01 Class See Also Send Feedback
d01al is a general purpose integrator which calculates an approximation to the integral of a function f x over a finite interval a,b:
I=∫ab f x dx
where the integrand may have local singular behaviour at a finite number of points within the integration interval.

Syntax

C#
public static void d01al(
    D01..::..D01AL_F f,
    double a,
    double b,
    int npts,
    double[] points,
    double epsabs,
    double epsrel,
    out double result,
    out double abserr,
    double[] w,
    out int subintvls,
    out int ifail
)
Visual Basic
Public Shared Sub d01al ( _
    f As D01..::..D01AL_F, _
    a As Double, _
    b As Double, _
    npts As Integer, _
    points As Double(), _
    epsabs As Double, _
    epsrel As Double, _
    <OutAttribute> ByRef result As Double, _
    <OutAttribute> ByRef abserr As Double, _
    w As Double(), _
    <OutAttribute> ByRef subintvls As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void d01al(
    D01..::..D01AL_F^ f,
    double a,
    double b,
    int npts,
    array<double>^ points,
    double epsabs,
    double epsrel,
    [OutAttribute] double% result,
    [OutAttribute] double% abserr,
    array<double>^ w,
    [OutAttribute] int% subintvls,
    [OutAttribute] int% ifail
)
F#
static member d01al :
        f : D01..::..D01AL_F *
        a : float *
        b : float *
        npts : int *
        points : float[] *
        epsabs : float *
        epsrel : float *
        result : float byref *
        abserr : float byref *
        w : float[] *
        subintvls : int byref *
        ifail : int byref -> unit

Parameters

f
Type: NagLibrary..::..D01..::..D01AL_F
f must return the value of the integrand f at a given point.

A delegate of type D01AL_F.

a
Type: System..::..Double
On entry: a, the lower limit of integration.
b
Type: System..::..Double
On entry: b, the upper limit of integration. It is not necessary that a<b.
npts
Type: System..::..Int32
On entry: the number of user-supplied break-points within the integration interval.
Constraint: npts≥0 and npts<min lw-2×npts-4/4,liw-npts-2/2.
points
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array points must be at least max 1,npts.
On entry: the user-specified break-points.
Constraint: the break-points must all lie within the interval of integration (but may be supplied in any order).
epsabs
Type: System..::..Double
On entry: the absolute accuracy required. If epsabs is negative, the absolute value is used. See [Accuracy].
epsrel
Type: System..::..Double
On entry: the relative accuracy required. If epsrel is negative, the absolute value is used. See [Accuracy].
result
Type: System..::..Double %
On exit: the approximation to the integral I.
abserr
Type: System..::..Double %
On exit: an estimate of the modulus of the absolute error, which should be an upper bound for I-result.
w
Type: array< System..::..Double >[]()[][]
An array of size [lw]
On exit: details of the computation see [Further Comments] for more information.
subintvls
Type: System..::..Int32 %
On exit: subintvls contains the actual number of sub-intervals used.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

d01al is based on the QUADPACK routine QAGP (see Piessens et al. (1983)). It is very similar to d01aj, but allows you to supply ‘break-points’, points at which the integrand is known to be difficult. It employs an adaptive algorithm, using the Gauss 10-point and Kronrod 21-point rules. The algorithm, described in de Doncker (1978), incorporates a global acceptance criterion (as defined by Malcolm and Simpson (1976)) together with the ε-algorithm (see Wynn (1956)) to perform extrapolation. The user-supplied ‘break-points’ always occur as the end points of some sub-interval during the adaptive process. The local error estimation is described in Piessens et al. (1983).

References

de Doncker E (1978) An adaptive extrapolation algorithm for automatic integration ACM SIGNUM Newsl. 13(2) 12–18
Malcolm M A and Simpson R B (1976) Local versus global strategies for adaptive quadrature ACM Trans. Math. Software 1 129–146
Piessens R, de Doncker–Kapenga E, Überhuber C and Kahaner D (1983) QUADPACK, A Subroutine Package for Automatic Integration Springer–Verlag
Wynn P (1956) On a device for computing the em Sn transformation Math. Tables Aids Comput. 10 91–96

Error Indicators and Warnings

Note: d01al may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (IW) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
The maximum number of subdivisions allowed with the given workspace has been reached without the accuracy requirements being achieved. Look at the integrand in order to determine the integration difficulties. If the position of a local difficulty within the interval can be determined (e.g., a singularity of the integrand or its derivative, a peak, a discontinuity, etc.) it should be supplied to the method as an element of the vector points. If necessary, another integrator, which is designed for handling the type of difficulty involved, must be used. Alternatively, consider relaxing the accuracy requirements specified by epsabs and epsrel, or increasing the amount of workspace.
ifail=2
Round-off error prevents the requested tolerance from being achieved. Consider requesting less accuracy.
ifail=3
Extremely bad local integrand behaviour causes a very strong subdivision around one (or more) points of the interval. The same advice applies as in the case of ifail=1.
ifail=4
The requested tolerance cannot be achieved because the extrapolation does not increase the accuracy satisfactorily; the returned result is the best which can be obtained. The same advice applies as in the case of ifail=1.
ifail=5
The integral is probably divergent, or slowly convergent. Please note that divergence can occur with any nonzero value of ifail.
ifail=6
The input is invalid: break-points are specified outside the integration range, npts>min lw-2×npts-4/4,liw-npts-2/2 or npts<0. result and abserr are set to zero.
ifail=7
On entry, | lw<2×npts+8,
or | liw<npts+4.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

d01al cannot guarantee, but in practice usually achieves, the following accuracy:
I-result≤tol,
where
tol=max epsabs,epsrel×I,
and epsabs and epsrel are user-specified absolute and relative error tolerances. Moreover, it returns the quantity abserr which, in normal circumstances, satisfies
I-result≤abserr≤tol.

Parallelism and Performance

None.

Further Comments

The time taken by d01al depends on the integrand and the accuracy required.
If ifail≠0 on exit, then you may wish to examine the contents of the array w, which contains the end points of the sub-intervals used by d01al along with the integral contributions and error estimates over these sub-intervals.
Specifically, for i=1,2,…,n, let ri denote the approximation to the value of the integral over the sub-interval ai,bi in the partition of a,b and ei be the corresponding absolute error estimate. Then, ∫aibi f x dx≃ri and result=∑i=1 n ri unless d01al terminates while testing for divergence of the integral (see Section 3.4.3 of Piessens et al. (1983)). In this case, result (and abserr) are taken to be the values returned from the extrapolation process. The value of n is returned in _iw[0], and the values ai, bi, ei and ri are stored consecutively in the array w, that is:
  • ai=w[i-1],
  • bi=w[n+i-1],
  • ei=w[2 n+i-1] and
  • ri=w[3 n+i-1].

Example

This example computes
∫01 1 x-1/7 dx.
A break-point is specified at x=1/7, at which point the integrand is infinite. (For definiteness the function FST returns the value 0.0 at this point.)

Example program (C#): d01ale.cs

Example program results: d01ale.r

See Also

D01 Class
D01 Members


d01am Method

[image]

NAG Library for .NET Release 2
D01..::d01am Method
D01 Class See Also Send Feedback
d01am calculates an approximation to the integral of a function f x over an infinite or semi-infinite interval a,b:
I=∫ab f x dx.

Syntax

C#
public static void d01am(
    D01..::..D01AM_F f,
    double bound,
    int inf,
    double epsabs,
    double epsrel,
    out double result,
    out double abserr,
    double[] w,
    out int subintvls,
    out int ifail
)
Visual Basic
Public Shared Sub d01am ( _
    f As D01..::..D01AM_F, _
    bound As Double, _
    inf As Integer, _
    epsabs As Double, _
    epsrel As Double, _
    <OutAttribute> ByRef result As Double, _
    <OutAttribute> ByRef abserr As Double, _
    w As Double(), _
    <OutAttribute> ByRef subintvls As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void d01am(
    D01..::..D01AM_F^ f,
    double bound,
    int inf,
    double epsabs,
    double epsrel,
    [OutAttribute] double% result,
    [OutAttribute] double% abserr,
    array<double>^ w,
    [OutAttribute] int% subintvls,
    [OutAttribute] int% ifail
)
F#
static member d01am :
        f : D01..::..D01AM_F *
        bound : float *
        inf : int *
        epsabs : float *
        epsrel : float *
        result : float byref *
        abserr : float byref *
        w : float[] *
        subintvls : int byref *
        ifail : int byref -> unit

Parameters

f
Type: NagLibrary..::..D01..::..D01AM_F
f must return the value of the integrand f at a given point.

A delegate of type D01AM_F.

bound
Type: System..::..Double
On entry: the finite limit of the integration range (if present). bound is not used if the interval is doubly infinite.
inf
Type: System..::..Int32
On entry: indicates the kind of integration range.
inf=1
The range is bound,+∞.
inf=-1
The range is -∞,bound.
inf=2
The range is -∞,+∞.
Constraint: inf=-1, 1 or 2.
epsabs
Type: System..::..Double
On entry: the absolute accuracy required. If epsabs is negative, the absolute value is used. See [Accuracy].
epsrel
Type: System..::..Double
On entry: the relative accuracy required. If epsrel is negative, the absolute value is used. See [Accuracy].
result
Type: System..::..Double %
On exit: the approximation to the integral I.
abserr
Type: System..::..Double %
On exit: an estimate of the modulus of the absolute error, which should be an upper bound for I-result.
w
Type: array< System..::..Double >[]()[][]
An array of size [lw]
On exit: details of the computation see [Further Comments] for more information.
subintvls
Type: System..::..Int32 %
On exit: subintvls contains the actual number of sub-intervals used.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

d01am is based on the QUADPACK routine QAGI (see Piessens et al. (1983)). The entire infinite integration range is first transformed to 0,1 using one of the identities:
∫-∞a f x dx=∫01 f a-1-t t 1 t 2 dt
∫a∞f x dx=∫01 f a+1-t t 1 t 2 dt
∫-∞∞f x dx=∫0∞f x+f-x dx=∫01​ ​f 1-t t+f-1+t t 1 t 2 dt
where a represents a finite integration limit. An adaptive procedure, based on the Gauss 7-point and Kronrod 15-point rules, is then employed on the transformed integral. The algorithm, described in de Doncker (1978), incorporates a global acceptance criterion (as defined by Malcolm and Simpson (1976)) together with the ε-algorithm (see Wynn (1956)) to perform extrapolation. The local error estimation is described in Piessens et al. (1983).

References

de Doncker E (1978) An adaptive extrapolation algorithm for automatic integration ACM SIGNUM Newsl. 13(2) 12–18
Malcolm M A and Simpson R B (1976) Local versus global strategies for adaptive quadrature ACM Trans. Math. Software 1 129–146
Piessens R, de Doncker–Kapenga E, Überhuber C and Kahaner D (1983) QUADPACK, A Subroutine Package for Automatic Integration Springer–Verlag
Wynn P (1956) On a device for computing the em Sn transformation Math. Tables Aids Comput. 10 91–96

Error Indicators and Warnings

Note: d01am may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (IW) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
The maximum number of subdivisions allowed with the given workspace has been reached without the accuracy requirements being achieved. Look at the integrand in order to determine the integration difficulties. If the position of a local difficulty within the interval can be determined (e.g., a singularity of the integrand or its derivative, a peak, a discontinuity, etc.) you will probably gain from splitting up the interval at this point and calling d01am on the infinite subrange and an appropriate integrator on the finite subrange. Alternatively, consider relaxing the accuracy requirements specified by epsabs and epsrel, or increasing the amount of workspace.
ifail=2
Round-off error prevents the requested tolerance from being achieved. Consider requesting less accuracy.
ifail=3
Extremely bad local integrand behaviour causes a very strong subdivision around one (or more) points of the interval. The same advice applies as in the case of ifail=1.
ifail=4
The requested tolerance cannot be achieved because the extrapolation does not increase the accuracy satisfactorily; the returned result is the best which can be obtained. The same advice applies as in the case of ifail=1.
ifail=5
The integral is probably divergent, or slowly convergent. Please note that divergence can occur with any nonzero value of ifail.
ifail=6
On entry, | lw<4,
or | liw<1,
or | inf≠-1, 1 or 2.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

d01am cannot guarantee, but in practice usually achieves, the following accuracy:
I-result≤tol,
where
tol=max epsabs,epsrel×I,
and epsabs and epsrel are user-specified absolute and relative error tolerances. Moreover, it returns the quantity abserr which, in normal circumstances, satisfies
I-result≤abserr≤tol.

Parallelism and Performance

None.

Further Comments

The time taken by d01am depends on the integrand and the accuracy required.
If ifail≠0 on exit, then you may wish to examine the contents of the array w, which contains the end points of the sub-intervals used by d01am along with the integral contributions and error estimates over these sub-intervals.
Specifically, for i=1,2,…,n, let ri denote the approximation to the value of the integral over the sub-interval ai,bi in the partition of a,b and ei be the corresponding absolute error estimate. Then, ∫aibi f x dx≃ri and result=∑i=1 n ri, unless d01am terminates while testing for divergence of the integral (see Section 3.4.3 of Piessens et al. (1983)). In this case, result (and abserr) are taken to be the values returned from the extrapolation process. The value of n is returned in _iw[0], and the values ai, bi, ei and ri are stored consecutively in the array w, that is:
  • ai=w[i-1],
  • bi=w[n+i-1],
  • ei=w[2 n+i-1] and
  • ri=w[3 n+i-1].
Note: this information applies to the integral transformed to 0,1 as described in [Description], not to the original integral.

Example

This example computes
∫0∞1 x+1 x dx.
The exact answer is π.

Example program (C#): d01ame.cs

Example program results: d01ame.r

See Also

D01 Class
D01 Members


d01an Method

[image]

NAG Library for .NET Release 2
D01..::d01an Method
D01 Class See Also Send Feedback
d01an calculates an approximation to the sine or the cosine transform of a function g over a,b:
I=∫ab g x sin ωxdx  or  I=∫ab g x cos ωxdx
(for a user-specified value of ω).

Syntax

C#
public static void d01an(
    D01..::..D01AN_G g,
    double a,
    double b,
    double omega,
    int key,
    double epsabs,
    double epsrel,
    out double result,
    out double abserr,
    double[] w,
    out int subintvls,
    out int ifail
)
Visual Basic
Public Shared Sub d01an ( _
    g As D01..::..D01AN_G, _
    a As Double, _
    b As Double, _
    omega As Double, _
    key As Integer, _
    epsabs As Double, _
    epsrel As Double, _
    <OutAttribute> ByRef result As Double, _
    <OutAttribute> ByRef abserr As Double, _
    w As Double(), _
    <OutAttribute> ByRef subintvls As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void d01an(
    D01..::..D01AN_G^ g,
    double a,
    double b,
    double omega,
    int key,
    double epsabs,
    double epsrel,
    [OutAttribute] double% result,
    [OutAttribute] double% abserr,
    array<double>^ w,
    [OutAttribute] int% subintvls,
    [OutAttribute] int% ifail
)
F#
static member d01an :
        g : D01..::..D01AN_G *
        a : float *
        b : float *
        omega : float *
        key : int *
        epsabs : float *
        epsrel : float *
        result : float byref *
        abserr : float byref *
        w : float[] *
        subintvls : int byref *
        ifail : int byref -> unit

Parameters

g
Type: NagLibrary..::..D01..::..D01AN_G
g must return the value of the function g at a given point x.

A delegate of type D01AN_G.

a
Type: System..::..Double
On entry: a, the lower limit of integration.
b
Type: System..::..Double
On entry: b, the upper limit of integration. It is not necessary that a<b.
omega
Type: System..::..Double
On entry: the parameter ω in the weight function of the transform.
key
Type: System..::..Int32
On entry: indicates which integral is to be computed.
key=1
w x=cos ωx.
key=2
w x=sin ωx.
Constraint: key=1 or 2.
epsabs
Type: System..::..Double
On entry: the absolute accuracy required. If epsabs is negative, the absolute value is used. See [Accuracy].
epsrel
Type: System..::..Double
On entry: the relative accuracy required. If epsrel is negative, the absolute value is used. See [Accuracy].
result
Type: System..::..Double %
On exit: the approximation to the integral I.
abserr
Type: System..::..Double %
On exit: an estimate of the modulus of the absolute error, which should be an upper bound for I-result.
w
Type: array< System..::..Double >[]()[][]
An array of size [lw]
On exit: details of the computation see [Further Comments] for more information.
subintvls
Type: System..::..Int32 %
On exit: subintvls contains the actual number of sub-intervals used.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

d01an is based on the QUADPACK routine QFOUR (see Piessens et al. (1983)). It is an adaptive method, designed to integrate a function of the form g x w x, where w x is either sin ωx or cos ωx. If a sub-interval has length
L=b-a 2-l
then the integration over this sub-interval is performed by means of a modified Clenshaw–Curtis procedure (see Piessens and Branders (1975)) if Lω>4 and l≤20. In this case a Chebyshev series approximation of degree 24 is used to approximate g x, while an error estimate is computed from this approximation together with that obtained using Chebyshev series of degree 12. If the above conditions do not hold then Gauss 7-point and Kronrod 15-point rules are used. The algorithm, described in Piessens et al. (1983), incorporates a global acceptance criterion (as defined in Malcolm and Simpson (1976)) together with the
ε-algorithm (see Wynn (1956)) to perform extrapolation. The local error estimation is described in
Piessens et al. (1983).

References

Malcolm M A and Simpson R B (1976) Local versus global strategies for adaptive quadrature ACM Trans. Math. Software 1 129–146
Piessens R and Branders M (1975) Algorithm 002: computation of oscillating integrals J. Comput. Appl. Math. 1 153–164
Piessens R, de Doncker–Kapenga E, Überhuber C and Kahaner D (1983) QUADPACK, A Subroutine Package for Automatic Integration Springer–Verlag
Wynn P (1956) On a device for computing the em Sn transformation Math. Tables Aids Comput. 10 91–96

Error Indicators and Warnings

Note: d01an may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (IW) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
The maximum number of subdivisions allowed with the given workspace has been reached without the accuracy requirements being achieved. Look at the integrand in order to determine the integration difficulties. If the position of a local difficulty within the interval can be determined (e.g., a singularity of the integrand or its derivative, a peak, a discontinuity, etc.) you will probably gain from splitting up the interval at this point and calling the integrator on the subranges. If necessary, another integrator, which is designed for handling the type of difficulty involved, must be used. Alternatively, consider relaxing the accuracy requirements specified by epsabs and epsrel, or increasing the amount of workspace.
ifail=2
Round-off error prevents the requested tolerance from being achieved. Consider requesting less accuracy.
ifail=3
Extremely bad local behaviour of g x causes a very strong subdivision around one (or more) points of the interval. The same advice applies as in the case of ifail=1.
ifail=4
The requested tolerance cannot be achieved because the extrapolation does not increase the accuracy satisfactorily; the returned result is the best which can be obtained. The same advice applies as in the case of ifail=1.
ifail=5
The integral is probably divergent, or slowly convergent. Please note that divergence can occur with any nonzero value of ifail.
ifail=6
On entry, key≠1 or 2.
ifail=7
On entry, | lw<4,
or | liw<2.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

d01an cannot guarantee, but in practice usually achieves, the following accuracy:
I-result≤tol,
where
tol=max epsabs,epsrel×I,
and epsabs and epsrel are user-specified absolute and relative tolerances. Moreover, it returns the quantity abserr which in normal circumstances, satisfies
I-result≤abserr≤tol.

Parallelism and Performance

None.

Further Comments

The time taken by d01an depends on the integrand and the accuracy required.
If ifail≠0 on exit, then you may wish to examine the contents of the array w, which contains the end points of the sub-intervals used by d01an along with the integral contributions and error estimates over these sub-intervals.
Specifically, for i=1,2,…,n, let ri denote the approximation to the value of the integral over the sub-interval ai,bi in the partition of a,b and ei be the corresponding absolute error estimate. Then, ∫ai bi g x w x dx≃ri and result=∑i=1 n ri unless d01an terminates while testing for divergence of the integral (see Section 3.4.3 of Piessens et al. (1983)). In this case, result (and abserr) are taken to be the values returned from the extrapolation process. The value of n is returned in _iw[0], and the values ai, bi, ei and ri are stored consecutively in the array w, that is:
  • ai=w[i-1],
  • bi=w[n+i-1],
  • ei=w[2 n+i-1] and
  • ri=w[3 n+i-1].

Example

This example computes
∫01 ln xsin 10 πxdx.

Example program (C#): d01ane.cs

Example program results: d01ane.r

See Also

D01 Class
D01 Members


d01ap Method

[image]

NAG Library for .NET Release 2
D01..::d01ap Method
D01 Class See Also Send Feedback
d01ap is an adaptive integrator which calculates an approximation to the integral of a function g x w x over a finite interval a,b:
I=∫ab g x w x dx
where the weight function w has end point singularities of algebraico-logarithmic type.

Syntax

C#
public static void d01ap(
    D01..::..D01AP_G g,
    double a,
    double b,
    double alfa,
    double beta,
    int key,
    double epsabs,
    double epsrel,
    out double result,
    out double abserr,
    double[] w,
    out int subintvls,
    out int ifail
)
Visual Basic
Public Shared Sub d01ap ( _
    g As D01..::..D01AP_G, _
    a As Double, _
    b As Double, _
    alfa As Double, _
    beta As Double, _
    key As Integer, _
    epsabs As Double, _
    epsrel As Double, _
    <OutAttribute> ByRef result As Double, _
    <OutAttribute> ByRef abserr As Double, _
    w As Double(), _
    <OutAttribute> ByRef subintvls As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void d01ap(
    D01..::..D01AP_G^ g,
    double a,
    double b,
    double alfa,
    double beta,
    int key,
    double epsabs,
    double epsrel,
    [OutAttribute] double% result,
    [OutAttribute] double% abserr,
    array<double>^ w,
    [OutAttribute] int% subintvls,
    [OutAttribute] int% ifail
)
F#
static member d01ap :
        g : D01..::..D01AP_G *
        a : float *
        b : float *
        alfa : float *
        beta : float *
        key : int *
        epsabs : float *
        epsrel : float *
        result : float byref *
        abserr : float byref *
        w : float[] *
        subintvls : int byref *
        ifail : int byref -> unit

Parameters

g
Type: NagLibrary..::..D01..::..D01AP_G
g must return the value of the function g at a given point x.

A delegate of type D01AP_G.

a
Type: System..::..Double
On entry: a, the lower limit of integration.
b
Type: System..::..Double
On entry: b, the upper limit of integration.
Constraint: b>a.
alfa
Type: System..::..Double
On entry: the parameter α in the weight function.
Constraint: alfa>-1.0.
beta
Type: System..::..Double
On entry: the parameter β in the weight function.
Constraint: beta>-1.0.
key
Type: System..::..Int32
On entry: indicates which weight function is to be used.
key=1
w x=x-a αb-x β.
key=2
w x=x-a αb-x β ln x-a.
key=3
w x=x-a αb-x β ln b-x.
key=4
w x=x-a αb-x β ln x-aln b-x.
Constraint: key=1, 2, 3 or 4.
epsabs
Type: System..::..Double
On entry: the absolute accuracy required. If epsabs is negative, the absolute value is used. See [Accuracy].
epsrel
Type: System..::..Double
On entry: the relative accuracy required. If epsrel is negative, the absolute value is used. See [Accuracy].
result
Type: System..::..Double %
On exit: the approximation to the integral I.
abserr
Type: System..::..Double %
On exit: an estimate of the modulus of the absolute error, which should be an upper bound for I-result.
w
Type: array< System..::..Double >[]()[][]
An array of size [lw]
On exit: details of the computation see [Further Comments] for more information.
subintvls
Type: System..::..Int32 %
On exit: subintvls contains the actual number of sub-intervals used.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

d01ap is based on the QUADPACK routine QAWSE (see Piessens et al. (1983)) and integrates a function of the form g x w x, where the weight function w x may have algebraico-logarithmic singularities at the end points a and/or b. The strategy is a modification of that in d01ak. We start by bisecting the original interval and applying modified Clenshaw–Curtis integration of orders 12 and 24 to both halves. Clenshaw–Curtis integration is then used on all sub-intervals which have a or b as one of their end points (see Piessens et al. (1974)). On the other sub-intervals Gauss–Kronrod (7–15 point) integration is carried out.
A ‘global’ acceptance criterion (as defined by Malcolm and Simpson (1976)) is used. The local error estimation control is described in Piessens et al. (1983).

References

Malcolm M A and Simpson R B (1976) Local versus global strategies for adaptive quadrature ACM Trans. Math. Software 1 129–146
Piessens R, de Doncker–Kapenga E, Überhuber C and Kahaner D (1983) QUADPACK, A Subroutine Package for Automatic Integration Springer–Verlag
Piessens R, Mertens I and Branders M (1974) Integration of functions having end-point singularities Angew. Inf. 16 65–68

Error Indicators and Warnings

Note: d01ap may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (IW) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
The maximum number of subdivisions allowed with the given workspace has been reached without the accuracy requirements being achieved. Look at the integrand in order to determine the integration difficulties. If the position of a discontinuity or a singularity of algebraico-logarithmic type within the interval can be determined, the interval must be split up at this point and the integrator called on the subranges. If necessary, another integrator, which is designed for handling the type of difficulty involved, must be used. Alternatively, consider relaxing the accuracy requirements specified by epsabs and epsrel, or increasing the amount of workspace.
ifail=2
Round-off error prevents the requested tolerance from being achieved. Consider requesting less accuracy.
ifail=3
Extremely bad local integrand behaviour causes a very strong subdivision around one (or more) points of the interval. The same advice applies as in the case of ifail=1.
ifail=4
On entry, | b≤a,
or | alfa≤-1.0,
or | beta≤-1.0,
or | key≠1, 2, 3 or 4.
ifail=5
On entry, | lw<8,
or | liw<2.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

d01ap cannot guarantee, but in practice usually achieves, the following accuracy:
I-result≤tol,
where
tol=max epsabs,epsrel×I,
and epsabs and epsrel are user-specified absolute and relative error tolerances. Moreover, it returns the quantity abserr which, in normal circumstances, satisfies
I-result≤abserr≤tol.

Parallelism and Performance

None.

Further Comments

The time taken by d01ap depends on the integrand and the accuracy required.
If ifail≠0 on exit, then you may wish to examine the contents of the array w, which contains the end points of the sub-intervals used by d01ap along with the integral contributions and error estimates over these sub-intervals.
Specifically, for i=1,2,…,n, let ri denote the approximation to the value of the integral over the sub-interval ai,bi in the partition of a,b and ei be the corresponding absolute error estimate. Then, ∫aibi f x w x dx≃ri and result=∑i=1 n ri. The value of n is returned in _iw[0], and the values ai, bi, ei and ri are stored consecutively in the array w, that is:
  • ai=w[i-1],
  • bi=w[n+i-1],
  • ei=w[2 n+i-1] and
  • ri=w[3 n+i-1].

Example

This example computes
∫01 ln xcos 10 πxdx  and  ∫01 sin 10 x x 1-x dx.

Example program (C#): d01ape.cs

Example program results: d01ape.r

See Also

D01 Class
D01 Members


d01aq Method

[image]

NAG Library for .NET Release 2
D01..::d01aq Method
D01 Class See Also Send Feedback
d01aq calculates an approximation to the Hilbert transform of a function g x over a,b:
I=∫ab g xx-c dx
for user-specified values of a, b and c.

Syntax

C#
public static void d01aq(
    D01..::..D01AQ_G g,
    double a,
    double b,
    double c,
    double epsabs,
    double epsrel,
    out double result,
    out double abserr,
    double[] w,
    out int subintvls,
    out int ifail
)
Visual Basic
Public Shared Sub d01aq ( _
    g As D01..::..D01AQ_G, _
    a As Double, _
    b As Double, _
    c As Double, _
    epsabs As Double, _
    epsrel As Double, _
    <OutAttribute> ByRef result As Double, _
    <OutAttribute> ByRef abserr As Double, _
    w As Double(), _
    <OutAttribute> ByRef subintvls As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void d01aq(
    D01..::..D01AQ_G^ g,
    double a,
    double b,
    double c,
    double epsabs,
    double epsrel,
    [OutAttribute] double% result,
    [OutAttribute] double% abserr,
    array<double>^ w,
    [OutAttribute] int% subintvls,
    [OutAttribute] int% ifail
)
F#
static member d01aq :
        g : D01..::..D01AQ_G *
        a : float *
        b : float *
        c : float *
        epsabs : float *
        epsrel : float *
        result : float byref *
        abserr : float byref *
        w : float[] *
        subintvls : int byref *
        ifail : int byref -> unit

Parameters

g
Type: NagLibrary..::..D01..::..D01AQ_G
g must return the value of the function g at a given point x.

A delegate of type D01AQ_G.

a
Type: System..::..Double
On entry: a, the lower limit of integration.
b
Type: System..::..Double
On entry: b, the upper limit of integration. It is not necessary that a<b.
c
Type: System..::..Double
On entry: the parameter c in the weight function.
Constraint: c must not equal a or b.
epsabs
Type: System..::..Double
On entry: the absolute accuracy required. If epsabs is negative, the absolute value is used. See [Accuracy].
epsrel
Type: System..::..Double
On entry: the relative accuracy required. If epsrel is negative, the absolute value is used. See [Accuracy].
result
Type: System..::..Double %
On exit: the approximation to the integral I.
abserr
Type: System..::..Double %
On exit: an estimate of the modulus of the absolute error, which should be an upper bound for I-result.
w
Type: array< System..::..Double >[]()[][]
An array of size [lw]
On exit: details of the computation see [Further Comments] for more information.
subintvls
Type: System..::..Int32 %
On exit: subintvls contains the actual number of sub-intervals used.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

d01aq is based on the QUADPACK routine QAWC (see Piessens et al. (1983)) and integrates a function of the form g x w x, where the weight function
w x=1 x-c
is that of the Hilbert transform. (If a<c<b the integral has to be interpreted in the sense of a Cauchy principal value.) It is an adaptive method which employs a ‘global’ acceptance criterion (as defined by Malcolm and Simpson (1976)). Special care is taken to ensure that c is never the end point of a sub-interval (see Piessens et al. (1976)). On each sub-interval c 1,c 2 modified Clenshaw–Curtis integration of orders 12 and 24 is performed if c 1-d≤c≤c 2+d where d=c 2-c 1/20. Otherwise the Gauss
7-point and Kronrod 15-point rules are used. The local error estimation is described by
Piessens et al. (1983).

References

Malcolm M A and Simpson R B (1976) Local versus global strategies for adaptive quadrature ACM Trans. Math. Software 1 129–146
Piessens R, de Doncker–Kapenga E, Überhuber C and Kahaner D (1983) QUADPACK, A Subroutine Package for Automatic Integration Springer–Verlag
Piessens R, van Roy–Branders M and Mertens I (1976) The automatic evaluation of Cauchy principal value integrals Angew. Inf. 18 31–35

Error Indicators and Warnings

Note: d01aq may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (IW) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
The maximum number of subdivisions allowed with the given workspace has been reached without the accuracy requirements being achieved. Look at the integrand in order to determine the integration difficulties. If necessary, another integrator, which is designed for handling the type of difficulty involved, must be used. Alternatively, consider relaxing the accuracy requirements specified by epsabs and epsrel, or increasing the amount of workspace.
ifail=2
Round-off error prevents the requested tolerance from being achieved. Consider requesting less accuracy.
ifail=3
Extremely bad local behaviour of g x causes a very strong subdivision around one (or more) points of the interval. The same advice applies as in the case of ifail=1.
ifail=4
On entry, c=a or c=b.
ifail=5
On entry, | lw<4,
or | liw<1.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

d01aq cannot guarantee, but in practice usually achieves, the following accuracy:
I-result≤tol,
where
tol=max epsabs,epsrel×I,
and epsabs and epsrel are user-specified absolute and relative error tolerances. Moreover, it returns the quantity abserr which, in normal circumstances satisfies:
I-result≤abserr≤tol.

Parallelism and Performance

None.

Further Comments

The time taken by d01aq depends on the integrand and the accuracy required.
If ifail≠0 on exit, then you may wish to examine the contents of the array w, which contains the end points of the sub-intervals used by d01aq along with the integral contributions and error estimates over these sub-intervals.
Specifically, for i=1,2,…,n, let ri denote the approximation to the value of the integral over the sub-interval [ai,bi] in the partition of a,b and ei be the corresponding absolute error estimate. Then, ∫ai bi g x w x dx≃ri and result=∑i=1 n ri. The value of n is returned in _iw[0], and the values ai, bi, ei and ri are stored consecutively in the array w, that is:
  • ai=w[i-1],
  • bi=w[n+i-1],
  • ei=w[2 n+i-1] and
  • ri=w[3 n+i-1].

Example

This example computes the Cauchy principal value of
∫-1 1 dxx 2+0.012x-12.

Example program (C#): d01aqe.cs

Example program results: d01aqe.r

See Also

D01 Class
D01 Members


d01ar Method

[image]

NAG Library for .NET Release 2
D01..::d01ar Method
D01 Class See Also Send Feedback
d01ar computes definite and indefinite integrals over a finite range to a specified relative or absolute accuracy, using the method described in Patterson (1968).

Syntax

C#
public static void d01ar(
    double a,
    double b,
    D01..::..D01AR_FUN fun,
    double relacc,
    double absacc,
    int maxrul,
    int iparm,
    out double acc,
    out double ans,
    out int n,
    double[] alpha,
    out int ifail
)
Visual Basic
Public Shared Sub d01ar ( _
    a As Double, _
    b As Double, _
    fun As D01..::..D01AR_FUN, _
    relacc As Double, _
    absacc As Double, _
    maxrul As Integer, _
    iparm As Integer, _
    <OutAttribute> ByRef acc As Double, _
    <OutAttribute> ByRef ans As Double, _
    <OutAttribute> ByRef n As Integer, _
    alpha As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void d01ar(
    double a,
    double b,
    D01..::..D01AR_FUN^ fun,
    double relacc,
    double absacc,
    int maxrul,
    int iparm,
    [OutAttribute] double% acc,
    [OutAttribute] double% ans,
    [OutAttribute] int% n,
    array<double>^ alpha,
    [OutAttribute] int% ifail
)
F#
static member d01ar :
        a : float *
        b : float *
        fun : D01..::..D01AR_FUN *
        relacc : float *
        absacc : float *
        maxrul : int *
        iparm : int *
        acc : float byref *
        ans : float byref *
        n : int byref *
        alpha : float[] *
        ifail : int byref -> unit

Parameters

a
Type: System..::..Double
On entry: a, the lower limit of integration.
b
Type: System..::..Double
On entry: b, the upper limit of integration. It is not necessary that a<b.
fun
Type: NagLibrary..::..D01..::..D01AR_FUN
fun must return the value of the integrand f at a specified point.

A delegate of type D01AR_FUN.

If iparm=2, fun is not called.
relacc
Type: System..::..Double
On entry: the relative accuracy required. If convergence according to absolute accuracy is required, relacc should be set to zero (but see also [Accuracy]). If relacc<0.0, its absolute value is used.
If iparm=2, relacc is not used.
absacc
Type: System..::..Double
On entry: the absolute accuracy required. If convergence according to relative accuracy is required, absacc should be set to zero (but see also [Accuracy]). If absacc<0.0, its absolute value is used.
If iparm=2, absacc is not used.
maxrul
Type: System..::..Int32
On entry: the maximum number of successive rules that may be used.
Constraint: 1≤maxrul≤9. If maxrul is outside these limits, the value 9 is assumed.
If iparm=2, maxrul is not used.
iparm
Type: System..::..Int32
On entry: indicates the task to be performed by the method.
iparm=0
Only the definite integral over a,b is evaluated.
iparm=1
As well as the definite integral, the expansion of the integrand in Legendre polynomials over a,b is calculated, using the same values of the integrand as used to compute the integral. The expansion coefficients, and some other quantities, are returned in alpha for later use in computing indefinite integrals.
iparm=2
f t is integrated analytically over a,b using the previously computed expansion, stored in alpha. No further evaluations of the integrand are required. The method must previously have been called with iparm=1 and the interval a,b must lie within that specified for the previous call. In this case only the arguments a, b, iparm, ans, alpha and ifail are used.
Constraint: iparm=0, 1 or 2.
acc
Type: System..::..Double %
On exit: if iparm=0 or 1, acc contains the absolute value of the difference between the last two successive estimates of the integral. This may be used as a measure of the accuracy actually achieved.
If iparm=2, acc is not used.
ans
Type: System..::..Double %
On exit: the estimated value of the integral.
n
Type: System..::..Int32 %
On exit: when iparm=0 or 1, n contains the number of integrand evaluations used in the calculation of the integral.
If iparm=2, n is not used.
alpha
Type: array< System..::..Double >[]()[][]
An array of size [390]
On entry: if iparm=2, alpha must contain the coefficients of the Legendre expansions of the integrand, as returned by a previous call of d01ar with iparm=1 and a range containing the present range.
If iparm=0 or 1, alpha need not be set on entry.
On exit: if iparm=1, the first m elements of alpha hold the coefficients of the Legendre expansion of the integrand, and the value of m is stored in alpha[389]. alpha must not be changed between a call with iparm=1 and subsequent calls with iparm=2.
If iparm=2, the first m elements of alpha are unchanged on exit.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

d01ar evaluates definite and indefinite integrals of the form:
∫ab f t dt
using the method described in Patterson (1968).

Definite Integrals

In this case d01ar must be called with iparm=0. By linear transformation the integral is changed to
I=∫-1+1 F x dx
where
F x=b-a 2 f b+a+b-a x 2
and is then approximated by an n-point quadrature rule
I=∑k=1 n wk F xk
where wk are the weights and xk are the abscissae.
The method uses a family of nine interlacing rules based on the optimal extension of the three-point Gauss rule. These rules use 1, 3, 7, 15, 31, 63, 127, 255 and 511 points and have respective polynomial integrating degrees 1, 5, 11, 23, 47, 95, 191, 383 and 767. Each rule has the property that the next in sequence includes all the points of its predecessor and has the greatest possible increase in integrating degree.
The integration method is based on the successive application of these rules until the absolute value of the difference of two successive results differs by not more than absacc, or relatively by not more than relacc. The result of the last rule used is taken as the value of the integral (ans), and the absolute difference of the results of the last two rules used is taken as an estimate of the absolute error (acc). Due to their interlacing form no integrand evaluations are wasted in passing from one rule to the next.

Indefinite Integrals

Suppose the value of the integral
∫cd f t dt
is required for a number of sub-intervals c,d, all of which lie in an interval a,b.
In this case d01ar should first be called with the parameter iparm=1 and the interval set to a,b. The method then calculates the integral over a,b and the Legendre expansion of the integrand, using the same integrand values. If the method is subsequently called with iparm=2 and the interval set to c,d, the integral over c,d is calculated by analytical integration of the Legendre expansion, without further evaluations of the integrand.
For the interval -1,1 the expansion takes the form
F x=∑i=0∞αiPi x
where Pi x is the order i Legendre polynomial. Assuming that the integral over the full range -1,1 was evaluated to the required accuracy using an n-point rule, then the coefficients
αi=12 2 i-1∫-1+1 Pi x F x dx,  i=0,1,…,m
are evaluated by that same rule, up to
m=3 n-1/4.
The accuracy for indefinite integration should be of the same order as that obtained for the definite integral over the full range. The indefinite integrals will be exact when F x is a polynomial of degree ≤m.

References

Patterson T N L (1968) The Optimum addition of points to quadrature formulae Math. Comput. 22 847–856

Error Indicators and Warnings

Note: d01ar may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail=1
If iparm=0 or 1, this indicates that all maxrul rules have been used and the integral has not converged to the accuracy requested. In this case ans contains the last approximation to the integral, and acc contains the difference between the last two approximations. To check this estimate of the integral, d01ar could be called again to evaluate
∫ab f t dt  as  ∫ac f t dt+∫cb f t dt  for some ​a<c<b.
If iparm=2, this indicates failure of convergence during the run with iparm=1 in which the Legendre expansion was created.
ifail=2
On entry, iparm≠0, 1 or 2
ifail=3
The method is called with iparm=2 but a previous call with iparm=1 has been omitted or was invoked with an integration interval of length zero.
ifail=4
On entry, with iparm=2, the interval for indefinite integration is not contained within the interval specified when d01ar was previously called with iparm=1.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The relative or absolute accuracy required is specified by you in the variables relacc or absacc. d01ar will terminate whenever either the relative accuracy specified by relacc or the absolute accuracy specified by absacc is reached. One or other of these criteria may be ‘forced’ by setting the parameter for the other to zero. If both relacc and absacc are specified as zero, then the method uses the value 10.0×machine precision for relacc.
If on exit ifail=0, then it is likely that the result is correct to one or other of these accuracies. If on exit ifail=1, then it is likely that neither of the requested accuracies has been reached.
When you have no prior idea of the magnitude of the integral, it is possible that an unreasonable accuracy may be requested, e.g., a relative accuracy for an integral which turns out to be zero, or a small absolute accuracy for an integral which turns out to be very large. Even if failure is reported in such a case, the value of the integral may still be satisfactory. The device of setting the other ‘unused’ accuracy parameter to a small positive value (e.g., 10-9 for an implementation of 11-digit precision) rather than zero, may prevent excessive calculation in such a situation.
To avoid spurious convergence, it is recommended that relative accuracies larger than about 10-3 be avoided.

Parallelism and Performance

None.

Further Comments

The time taken by d01ar depends on the complexity of the integrand and the accuracy required.
This method uses the Patterson method over the whole integration interval and should therefore be suitable for well behaved functions. However, for very irregular functions it would be more efficient to submit the differently behaved regions separately for integration.

Example

This example evaluates the following integrals
(i) Definite integral only iparm=0 for
∫01 4 1+x 2 dx absacc=10-5.
(ii) Definite integral together with expansion coefficients iparm=1 for
∫12 x 8 dx absacc=10-5.
(iii) Indefinite integral using previous expansion iparm=2 for
∫1.21.8 x 8 dx absacc=10-5.

Example program (C#): d01are.cs

Example program results: d01are.r

See Also

D01 Class
D01 Members


d01as Method

[image]

NAG Library for .NET Release 2
D01..::d01as Method
D01 Class See Also Send Feedback
d01as calculates an approximation to the sine or the cosine transform of a function g over a,∞:
I=∫a∞g x sin ωxdx  or  I=∫a∞g x cos ωxdx
(for a user-specified value of ω).

Syntax

C#
public static void d01as(
    D01..::..D01AS_G g,
    double a,
    double omega,
    int key,
    double epsabs,
    out double result,
    out double abserr,
    int limlst,
    out int lst,
    double[] erlst,
    double[] rslst,
    int[] ierlst,
    out int subintvls,
    out int ifail
)
Visual Basic
Public Shared Sub d01as ( _
    g As D01..::..D01AS_G, _
    a As Double, _
    omega As Double, _
    key As Integer, _
    epsabs As Double, _
    <OutAttribute> ByRef result As Double, _
    <OutAttribute> ByRef abserr As Double, _
    limlst As Integer, _
    <OutAttribute> ByRef lst As Integer, _
    erlst As Double(), _
    rslst As Double(), _
    ierlst As Integer(), _
    <OutAttribute> ByRef subintvls As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void d01as(
    D01..::..D01AS_G^ g,
    double a,
    double omega,
    int key,
    double epsabs,
    [OutAttribute] double% result,
    [OutAttribute] double% abserr,
    int limlst,
    [OutAttribute] int% lst,
    array<double>^ erlst,
    array<double>^ rslst,
    array<int>^ ierlst,
    [OutAttribute] int% subintvls,
    [OutAttribute] int% ifail
)
F#
static member d01as :
        g : D01..::..D01AS_G *
        a : float *
        omega : float *
        key : int *
        epsabs : float *
        result : float byref *
        abserr : float byref *
        limlst : int *
        lst : int byref *
        erlst : float[] *
        rslst : float[] *
        ierlst : int[] *
        subintvls : int byref *
        ifail : int byref -> unit

Parameters

g
Type: NagLibrary..::..D01..::..D01AS_G
g must return the value of the function g at a given point x.

A delegate of type D01AS_G.

a
Type: System..::..Double
On entry: a, the lower limit of integration.
omega
Type: System..::..Double
On entry: the parameter ω in the weight function of the transform.
key
Type: System..::..Int32
On entry: indicates which integral is to be computed.
key=1
w x=cos ωx.
key=2
w x=sin ωx.
Constraint: key=1 or 2.
epsabs
Type: System..::..Double
On entry: the absolute accuracy required. If epsabs is negative, the absolute value is used. See [Accuracy].
result
Type: System..::..Double %
On exit: the approximation to the integral I.
abserr
Type: System..::..Double %
On exit: an estimate of the modulus of the absolute error, which should be an upper bound for I-result.
limlst
Type: System..::..Int32
On entry: an upper bound on the number of intervals Ck needed for the integration.
Suggested value: limlst=50 is adequate for most problems.
Constraint: limlst≥3.
lst
Type: System..::..Int32 %
On exit: the number of intervals Ck actually used for the integration.
erlst
Type: array< System..::..Double >[]()[][]
An array of size [limlst]
On exit: erlst[k-1] contains the error estimate corresponding to the integral contribution over the interval Ck, for k=1,2,…,lst.
rslst
Type: array< System..::..Double >[]()[][]
An array of size [limlst]
On exit: rslst[k-1] contains the integral contribution over the interval Ck, for k=1,2,…,lst.
ierlst
Type: array< System..::..Int32 >[]()[][]
An array of size [limlst]
On exit: ierlst[k-1] contains the error flag corresponding to rslst[k-1], for k=1,2,…,lst. See [Error Indicators and Warnings].
subintvls
Type: System..::..Int32 %
On exit: subintvls contains the actual number of sub-intervals used.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

d01as is based on the QUADPACK routine QAWFE (see Piessens et al. (1983)). It is an adaptive method, designed to integrate a function of the form g x w x over a semi-infinite interval, where w x is either sin ωx or cos ωx.
Over successive intervals
Ck=a+k-1 c,a+kc,  k=1,2,…,lst
integration is performed by the same algorithm as is used by d01an. The intervals Ck are of constant length
c=2 ω+1 π/ω,  ω≠0,
where ω represents the largest integer less than or equal to ω. Since c equals an odd number of half periods, the integral contributions over succeeding intervals will alternate in sign when the function g is positive and monotonically decreasing over a,∞. The algorithm, described in Piessens et al. (1983), incorporates a global acceptance criterion (as defined by Malcolm and Simpson (1976)) together with the ε-algorithm (see Wynn (1956)) to perform extrapolation. The local error estimation is described by Piessens et al. (1983).
If ω=0 and key=1, the method uses the same algorithm as d01am (with epsrel=0.0).
In contrast to the other methods in D01 class, d01as works only with an absolute error tolerance (epsabs). Over the interval Ck it attempts to satisfy the absolute accuracy requirement
EPSAk=Uk×epsabs,
where Uk=1-p p k-1, for k=1,2,… and p=0.9.
However, when difficulties occur during the integration over the kth sub-interval Ck such that the error flag ierlst[k-1] is nonzero, the accuracy requirement over subsequent intervals is relaxed. See Piessens et al. (1983) for more details.

References

Malcolm M A and Simpson R B (1976) Local versus global strategies for adaptive quadrature ACM Trans. Math. Software 1 129–146
Piessens R, de Doncker–Kapenga E, Überhuber C and Kahaner D (1983) QUADPACK, A Subroutine Package for Automatic Integration Springer–Verlag
Wynn P (1956) On a device for computing the em Sn transformation Math. Tables Aids Comput. 10 91–96

Error Indicators and Warnings

Note: d01as may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (W, LW, IW) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
The maximum number of subdivisions allowed with the given workspace has been reached without the accuracy requirements being achieved. Look at the integrand in order to determine the integration difficulties. If the position of a local difficulty within the interval can be determined (e.g., a singularity of the integrand or its derivative, a peak, a discontinuity, etc.) you will probably gain from splitting up the interval at this point and calling d01as on the infinite subrange and an appropriate integrator on the finite subrange. Alternatively, consider relaxing the accuracy requirements specified by epsabs or increasing the amount of workspace.
ifail=2
Round-off error prevents the requested tolerance from being achieved. Consider requesting less accuracy.
ifail=3
Extremely bad local integrand behaviour causes a very strong subdivision around one (or more) points of the interval. The same advice applies as in the case of ifail=1.
ifail=4
The requested tolerance cannot be achieved because the extrapolation does not increase the accuracy satisfactorily; the returned result is the best which can be obtained. The same advice applies as in the case of ifail=1.
Look at the integrand in order to determine the integration difficulties. If the position of a local difficulty within the interval can be determined (e.g., a singularity of the integrand or its derivative, a peak, a discontinuity etc.) you will probably gain from splitting up the interval at this point and calling d01as on the infinite subrange and an appropriate integrator on the finite subrange. Alternatively, consider relaxing the accuracy requirements specified by epsabs or increasing the amount of workspace.
Please note that divergence can occur with any nonzero value of ifail.
ifail=5
The integral is probably divergent, or slowly convergent. Please note that divergence can occur with any nonzero value of ifail.
ifail=6
On entry, | key≠1 or 2,
or | limlst<3.
ifail=7
Bad integration behaviour occurs within one or more of the intervals Ck. Location and type of the difficulty involved can be determined from the vector ierlst.
ifail=8
Maximum number of intervals Ck (=limlst) allowed has been achieved. Increase the value of limlst to allow more cycles.
ifail=9
The extrapolation table constructed for convergence acceleration of the series formed by the integral contribution over the intervals Ck, does not converge to the required accuracy.
ifail=10
On entry, liw<2.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
In the cases ifail=7, 8 or 9, additional information about the cause of the error can be obtained from the array ierlst, as follows:
ierlst[k-1]=1
The maximum number of subdivisions=min_lw/4,liw/2 has been achieved on the kth interval.
ierlst[k-1]=2
Occurrence of round-off error is detected and prevents the tolerance imposed on the kth interval from being achieved.
ierlst[k-1]=3
Extremely bad integrand behaviour occurs at some points of the kth interval.
ierlst[k-1]=4
The integration procedure over the kth interval does not converge (to within the required accuracy) due to round-off in the extrapolation procedure invoked on this interval. It is assumed that the result on this interval is the best which can be obtained.
ierlst[k-1]=5
The integral over the kth interval is probably divergent or slowly convergent. It must be noted that divergence can occur with any other value of ierlst[k-1].

Accuracy

d01as cannot guarantee, but in practice usually achieves, the following accuracy:
I-result≤epsabs,
where epsabs is the user-specified absolute error tolerance. Moreover, it returns the quantity abserr, which, in normal circumstances, satisfies
I-result≤abserr≤epsabs.

Parallelism and Performance

None.

Further Comments

None.

Example

This example computes
∫0∞1 x cos πx/2dx.

Example program (C#): d01ase.cs

Example program results: d01ase.r

See Also

D01 Class
D01 Members


d01bc Method

[image]

NAG Library for .NET Release 2
D01..::d01bc Method
D01 Class See Also Send Feedback
d01bc returns the weights (normal or adjusted) and abscissae for a Gaussian integration rule with a specified number of abscissae. Six different types of Gauss rule are allowed.

Syntax

C#
public static void d01bc(
    int itype,
    double a,
    double b,
    double c,
    double d,
    int n,
    double[] weight,
    double[] abscis,
    out int ifail
)
Visual Basic
Public Shared Sub d01bc ( _
    itype As Integer, _
    a As Double, _
    b As Double, _
    c As Double, _
    d As Double, _
    n As Integer, _
    weight As Double(), _
    abscis As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void d01bc(
    int itype,
    double a,
    double b,
    double c,
    double d,
    int n,
    array<double>^ weight,
    array<double>^ abscis,
    [OutAttribute] int% ifail
)
F#
static member d01bc :
        itype : int *
        a : float *
        b : float *
        c : float *
        d : float *
        n : int *
        weight : float[] *
        abscis : float[] *
        ifail : int byref -> unit

Parameters

itype
Type: System..::..Int32
On entry: indicates the type of quadrature rule.
itype=0
Gauss–Legendre, with normal weights.
itype=1
Gauss–Jacobi, with normal weights.
itype=-1
Gauss–Jacobi, with adjusted weights.
itype=2
Exponential Gauss, with normal weights.
itype=-2
Exponential Gauss, with adjusted weights.
itype=3
Gauss–Laguerre, with normal weights.
itype=-3
Gauss–Laguerre, with adjusted weights.
itype=4
Gauss–Hermite, with normal weights.
itype=-4
Gauss–Hermite, with adjusted weights.
itype=5
Rational Gauss, with normal weights.
itype=-5
Rational Gauss, with adjusted weights.
Constraint: itype=0, 1, -1, 2, -2, 3, -3, 4, -4, 5 or -5.
a
Type: System..::..Double
On entry: the parameters a, b, c and d which occur in the quadrature formulae. c is not used if itype=0; d is not used unless itype=1, -1, 5 or -5. For some rules c and d must not be too large (see [Error Indicators and Warnings]).
b
Type: System..::..Double
On entry: the parameters a, b, c and d which occur in the quadrature formulae. c is not used if itype=0; d is not used unless itype=1, -1, 5 or -5. For some rules c and d must not be too large (see [Error Indicators and Warnings]).
c
Type: System..::..Double
On entry: the parameters a, b, c and d which occur in the quadrature formulae. c is not used if itype=0; d is not used unless itype=1, -1, 5 or -5. For some rules c and d must not be too large (see [Error Indicators and Warnings]).
d
Type: System..::..Double
On entry: the parameters a, b, c and d which occur in the quadrature formulae. c is not used if itype=0; d is not used unless itype=1, -1, 5 or -5. For some rules c and d must not be too large (see [Error Indicators and Warnings]).
n
Type: System..::..Int32
On entry: n, the number of weights and abscissae to be returned. If itype=-2 or -4 and c≠0.0, an odd value of n may raise problems (see ifail=6).
Constraint: n>0.
weight
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the n weights.
abscis
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the n abscissae.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

d01bc returns the weights wi and abscissae xi for use in the summation
S=∑i=1 n wi f xi
which approximates a definite integral (see Davis and Rabinowitz (1975) or Stroud and Secrest (1966)). The following types are provided:
(a) Gauss–Legendre
S≃∫ab f x dx,   exact for ​f x=P 2 n-1 x.
Constraint: b>a.
(b) Gauss–Jacobi
normal weights:
S≃∫ab b-x cx-a d f x dx,   exact for ​f x=P 2 n-1 x,
adjusted weights:
S≃∫ab f x dx,   exact for ​f x=b-x cx-a d P 2 n-1 x.
Constraint: c>-1, d>-1, b>a.
(c) Exponential Gauss
normal weights:
S≃∫ab x-a+b 2 c f x dx,   exact for ​f x=P 2 n-1 x,
adjusted weights:
S≃∫ab f x dx,   exact for ​f x=x-a+b 2 c P 2 n-1 x.
Constraint: c>-1, b>a.
(d) Gauss–Laguerre
normal weights:
S≃∫a∞x-a ce-bx f x dx b>0,≃∫-∞a x-a ce-bx f x dx b<0,   exact for ​f x=P 2 n-1 x,
adjusted weights:
S≃∫a∞f x dx b>0,≃∫-∞a f x dx b<0,   exact for ​f x=x-a ce-bx P 2 n-1 x.
Constraint: c>-1, b≠0.
(e) Gauss–Hermite
normal weights:
S≃∫-∞+∞x-a ce-b x-a 2 f x dx,   exact for ​f x=P 2 n-1 x,
adjusted weights:
S≃∫-∞+∞f x dx,   exact for ​f x=x-a ce-b x-a 2 P 2 n-1 x.
Constraint: c>-1, b>0.
(f) Rational Gauss
normal weights:
S≃∫a∞x-a cx+b d f x dx a+b>0,≃∫-∞a x-a cx+b d f x dx a+b<0,   exact for ​f x=P 2 n-1 1 x+b,
adjusted weights:
S≃∫a∞f x dx a+b>0,≃∫-∞a f x dx a+b<0,   exact for ​f x=x-a cx+b d P 2 n-1 1 x+b.
Constraint: c>-1, d>c+1, a+b≠0.
In the above formulae, P 2 n-1 x stands for any polynomial of degree 2 n-1 or less in x.
The method used to calculate the abscissae involves finding the eigenvalues of the appropriate tridiagonal matrix (see Golub and Welsch (1969)). The weights are then determined by the formula
wi=∑j=0n-1 Pj*xi 2-1
where Pj*x is the jth orthogonal polynomial with respect to the weight function over the appropriate interval.
The weights and abscissae produced by d01bc may be passed to (D01FBF not in this release), which will evaluate the summations in one or more dimensions.

References

Davis P J and Rabinowitz P (1975) Methods of Numerical Integration Academic Press
Golub G H and Welsch J H (1969) Calculation of Gauss quadrature rules Math. Comput. 23 221–230
Stroud A H and Secrest D (1966) Gaussian Quadrature Formulas Prentice–Hall

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
The algorithm for computing eigenvalues of a tridiagonal matrix has failed to obtain convergence. If the soft fail option is used, the values of the weights and abscissae on return are indeterminate.
ifail=2
On entry, | n<1,
or | itype<-5,
or | itype>5.
If the soft fail option is used, weights and abscissae are returned as zero.
ifail=3
a, b, c or d is not in the allowed range:
  • if itype=0, a≥b;
  • if itype=±1, a≥b or c≤-1.0 or d≤-1.0 or c+d+2.0>gmax;
  • if itype=±2, a≥b or c≤-1.0;
  • if itype=±3, b=0.0 or c≤-1.0 or c+1.0>gmax;
  • if itype=±4, b≤0.0 or c≤-1.0 or c+1.0/2.0>gmax;
  • if itype=±5, a+b=0.0 or c≤-1.0 or d≤c+1.0.
Here gmax is the (machine-dependent) largest integer value such that Γ gmax can be computed without overflow (see the Users' Note for your implementation for s14aa).
If the soft fail option is used, weights and abscissae are returned as zero.
ifail=4
One or more of the weights are larger than rmax, the largest floating-point number on this machine. rmax is given by the function x02al. If the soft fail option is used, the overflowing weights are returned as rmax. Possible solutions are to use a smaller value of n; or, if using adjusted weights, to change to normal weights.
ifail=5
One or more of the weights are too small to be distinguished from zero on this machine. If the soft fail option is used, the underflowing weights are returned as zero, which may be a usable approximation. Possible solutions are to use a smaller value of n; or, if using normal weights, to change to adjusted weights.
ifail=6
Exponential Gauss or Gauss–Hermite adjusted weights with n odd and c≠0.0. Theoretically, in these cases:
  • for c>0.0, the central adjusted weight is infinite, and the exact function f x is zero at the central abscissa.
  • for c<0.0, the central adjusted weight is zero, and the exact function f x is infinite at the central abscissa.
In either case, the contribution of the central abscissa to the summation is indeterminate.
In practice, the central weight may not have overflowed or underflowed, if there is sufficient rounding error in the value of the central abscissa.
If the soft fail option is used, the weights and abscissa returned may be usable; you must be particularly careful not to ‘round’ the central abscissa to its true value without simultaneously ‘rounding’ the central weight to zero or ∞ as appropriate, or the summation will suffer. It would be preferable to use normal weights, if possible.
Note: remember that, when switching from normal weights to adjusted weights or vice versa, redefinition of f x is involved.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The accuracy depends mainly on n, with increasing loss of accuracy for larger values of n. Typically, one or two decimal digits may be lost from machine accuracy with n≃20, and three or four decimal digits may be lost for n≃100.

Parallelism and Performance

None.

Further Comments

The major portion of the time is taken up during the calculation of the eigenvalues of the appropriate tridiagonal matrix, where the time is roughly proportional to n 3.

Example

This example returns the abscissae and (adjusted) weights for the seven-point Gauss–Laguerre formula.

Example program (C#): d01bce.cs

Example program results: d01bce.r

See Also

D01 Class
D01 Members


d01bd Method

[image]

NAG Library for .NET Release 2
D01..::d01bd Method
D01 Class See Also Send Feedback
d01bd calculates an approximation to the integral of a function over a finite interval a,b:
I=∫ab f x dx.
It is non-adaptive and as such is recommended for the integration of ‘smooth’ functions. These exclude integrands with singularities, derivative singularities or high peaks on a,b, or which oscillate too strongly on a,b.

Syntax

C#
public static void d01bd(
    D01..::..D01BD_F f,
    double a,
    double b,
    double epsabs,
    double epsrel,
    out double result,
    out double abserr,
    out int ifail
)
Visual Basic
Public Shared Sub d01bd ( _
    f As D01..::..D01BD_F, _
    a As Double, _
    b As Double, _
    epsabs As Double, _
    epsrel As Double, _
    <OutAttribute> ByRef result As Double, _
    <OutAttribute> ByRef abserr As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void d01bd(
    D01..::..D01BD_F^ f,
    double a,
    double b,
    double epsabs,
    double epsrel,
    [OutAttribute] double% result,
    [OutAttribute] double% abserr,
    [OutAttribute] int% ifail
)
F#
static member d01bd :
        f : D01..::..D01BD_F *
        a : float *
        b : float *
        epsabs : float *
        epsrel : float *
        result : float byref *
        abserr : float byref *
        ifail : int byref -> unit

Parameters

f
Type: NagLibrary..::..D01..::..D01BD_F
f must return the value of the integrand f at a given point.

A delegate of type D01BD_F.

a
Type: System..::..Double
On entry: a, the lower limit of integration.
b
Type: System..::..Double
On entry: b, the upper limit of integration. It is not necessary that a<b.
epsabs
Type: System..::..Double
On entry: the absolute accuracy required. If epsabs is negative, the absolute value is used. See [Accuracy].
epsrel
Type: System..::..Double
On entry: the relative accuracy required. If epsrel is negative, the absolute value is used. See [Accuracy].
result
Type: System..::..Double %
On exit: the approximation to the integral I.
abserr
Type: System..::..Double %
On exit: an estimate of the modulus of the absolute error, which should be an upper bound for I-result.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

d01bd is based on the QUADPACK routine QNG (see Piessens et al. (1983)). It is a non-adaptive method which uses as its basic rules, the Gauss 10-point and 21-point formulae. If the accuracy criterion is not met, formulae using 43 and 87 points are used successively, stopping whenever the accuracy criterion is satisfied.
This method is designed for smooth integrands only.

References

Patterson T N L (1968) The Optimum addition of points to quadrature formulae Math. Comput. 22 847–856
Piessens R, de Doncker–Kapenga E, Überhuber C and Kahaner D (1983) QUADPACK, A Subroutine Package for Automatic Integration Springer–Verlag

Error Indicators and Warnings

There are no specific errors detected by d01bd. However, if abserr is greater than
max epsabs,epsrel×result
this indicates that the method has probably failed to achieve the requested accuracy within 87 function evaluations.

Accuracy

d01bd attempts to compute an approximation, result, such that:
I-result≤tol,
where
tol=max epsabs,epsrel×I,
and epsabs and epsrel are user-specified absolute and relative error tolerances. There can be no guarantee that this is achieved, and you are advised to subdivide the interval if you have any doubts about the accuracy obtained. Note that abserr contains an estimated bound on I-result.

Parallelism and Performance

None.

Further Comments

The time taken by d01bd depends on the integrand and the accuracy required.

Example

This example computes
∫01 x 2 sin 10 πxdx.

Example program (C#): d01bde.cs

Example program results: d01bde.r

See Also

D01 Class
D01 Members


d01da Method

[image]

NAG Library for .NET Release 2
D01..::d01da Method
D01 Class See Also Send Feedback
d01da attempts to evaluate a double integral to a specified absolute accuracy by repeated applications of the method described by Patterson (1968) and Patterson (1969).

Syntax

C#
public static void d01da(
    double ya,
    double yb,
    D01..::..D01DA_PHI1 phi1,
    D01..::..D01DA_PHI2 phi2,
    D01..::..D01DA_F f,
    double absacc,
    out double ans,
    out int npts,
    out int ifail
)
Visual Basic
Public Shared Sub d01da ( _
    ya As Double, _
    yb As Double, _
    phi1 As D01..::..D01DA_PHI1, _
    phi2 As D01..::..D01DA_PHI2, _
    f As D01..::..D01DA_F, _
    absacc As Double, _
    <OutAttribute> ByRef ans As Double, _
    <OutAttribute> ByRef npts As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void d01da(
    double ya,
    double yb,
    D01..::..D01DA_PHI1^ phi1,
    D01..::..D01DA_PHI2^ phi2,
    D01..::..D01DA_F^ f,
    double absacc,
    [OutAttribute] double% ans,
    [OutAttribute] int% npts,
    [OutAttribute] int% ifail
)
F#
static member d01da :
        ya : float *
        yb : float *
        phi1 : D01..::..D01DA_PHI1 *
        phi2 : D01..::..D01DA_PHI2 *
        f : D01..::..D01DA_F *
        absacc : float *
        ans : float byref *
        npts : int byref *
        ifail : int byref -> unit

Parameters

ya
Type: System..::..Double
On entry: a, the lower limit of the integral.
yb
Type: System..::..Double
On entry: b, the upper limit of the integral. It is not necessary that a<b.
phi1
Type: NagLibrary..::..D01..::..D01DA_PHI1
phi1 must return the lower limit of the inner integral for a given value of y.

A delegate of type D01DA_PHI1.

phi2
Type: NagLibrary..::..D01..::..D01DA_PHI2
phi2 must return the upper limit of the inner integral for a given value of y.

A delegate of type D01DA_PHI2.

f
Type: NagLibrary..::..D01..::..D01DA_F
f must return the value of the integrand f at a given point.

A delegate of type D01DA_F.

absacc
Type: System..::..Double
On entry: the absolute accuracy requested.
ans
Type: System..::..Double %
On exit: the estimated value of the integral.
npts
Type: System..::..Int32 %
On exit: the total number of function evaluations.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

d01da attempts to evaluate a definite integral of the form
I=∫ab∫ϕ 1 yϕ 2 y f x,y dxdy
where a and b are constants and ϕ 1 y and ϕ 2 y are functions of the variable y.
The integral is evaluated by expressing it as
I=∫ab F y dy,   where  F y=∫ϕ 1 yϕ 2 y f x,y dx.
Both the outer integral I and the inner integrals F y are evaluated by the method, described by Patterson (1968) and Patterson (1969), of the optimum addition of points to Gauss quadrature formulae.
This method uses a family of interlacing common point formulae. Beginning with the 3-point Gauss rule, formulae using 7, 15, 31, 63, 127 and finally 255 points are derived. Each new formula contains all the points of the earlier formulae so that no function evaluations are wasted. Each integral is evaluated by applying these formulae successively until two results are obtained which differ by less than the specified absolute accuracy.

References

Patterson T N L (1968) On some Gauss and Lobatto based integration formulae Math. Comput. 22 877–881
Patterson T N L (1969) The optimum addition of points to quadrature formulae, errata Math. Comput. 23 892

Error Indicators and Warnings

Note: d01da may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail=1
This indicates that 255 points have been used in the outer integral and convergence has not been obtained. All the inner integrals have, however, converged. In this case ans may still contain an approximate estimate of the integral.
ifail=10×n
This indicates that the outer integral has converged but n inner integrals have failed to converge with the use of 255 points. In this case ans may still contain an approximate estimate of the integral, but its reliability will decrease as n increases.
ifail=10×n+1
This indicates that both the outer integral and n of the inner integrals have not converged. ans may still contain an approximate estimate of the integral, but its reliability will decrease as n increases.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The absolute accuracy is specified by the variable absacc. If, on exit, ifail=0 then the result is most likely correct to this accuracy. Even if ifail is nonzero on exit, it is still possible that the calculated result could differ from the true value by less than the given accuracy.

Parallelism and Performance

None.

Further Comments

The time taken by d01da depends upon the complexity of the integrand and the accuracy requested.
With Patterson's method accidental convergence may occasionally occur, when two estimates of an integral agree to within the requested accuracy, but both estimates differ considerably from the true result. This could occur in either the outer integral or in one or more of the inner integrals.
If it occurs in the outer integral then apparent convergence is likely to be obtained with considerably fewer integrand evaluations than may be expected. If it occurs in an inner integral, the incorrect value could make the function F y appear to be badly behaved, in which case a very large number of pivots may be needed for the overall evaluation of the integral. Thus both unexpectedly small and unexpectedly large numbers of integrand evaluations should be considered as indicating possible trouble. If accidental convergence is suspected, the integral may be recomputed, requesting better accuracy; if the new request is more stringent than the degree of accidental agreement (which is of course unknown), improved results should be obtained. This is only possible when the accidental agreement is not better than machine accuracy. It should be noted that the method requests the same accuracy for the inner integrals as for the outer integral. In practice it has been found that in the vast majority of cases this has proved to be adequate for the overall result of the double integral to be accurate to within the specified value.
The method is not well-suited to non-smooth integrands, i.e., integrands having some kind of analytic discontinuity (such as a discontinuous or infinite partial derivative of some low-order) in, on the boundary of, or near, the region of integration. Warning: such singularities may be induced by incautiously presenting an apparently smooth interval over the positive quadrant of the unit circle, R
I=∫R x+y dxdy.
This may be presented to d01da as
I=∫01 dy∫0 1-y 2 x+y dx=∫01 12 1-y 2+y⁢1-y 2 dy
but here the outer integral has an induced square-root singularity stemming from the way the region has been presented to d01da. This situation should be avoided by re-casting the problem. For the example given, the use of polar coordinates would avoid the difficulty:
I=∫01 dr∫0 π 2 r 2 cos υ+sin υ dυ.

Example

This example evaluates the integral discussed in [Further Comments], presenting it to d01da first as
∫01∫0 1-y 2 x+y dxdy
and then as
∫01∫0 π 2 r 2 cos υ+sin υ dυdr.
Note the difference in the number of function evaluations.

Example program (C#): d01dae.cs

Example program results: d01dae.r

See Also

D01 Class
D01 Members


d01fc Method

[image]

NAG Library for .NET Release 2
D01..::d01fc Method
D01 Class See Also Send Feedback
d01fc attempts to evaluate a multidimensional integral (up to 15 dimensions), with constant and finite limits, to a specified relative accuracy, using an adaptive subdivision strategy.

Syntax

C#
public static void d01fc(
    int ndim,
    double[] a,
    double[] b,
    ref int minpts,
    int maxpts,
    D01..::..D01FC_FUNCTN functn,
    double eps,
    out double acc,
    out double finval,
    out int ifail
)
Visual Basic
Public Shared Sub d01fc ( _
    ndim As Integer, _
    a As Double(), _
    b As Double(), _
    ByRef minpts As Integer, _
    maxpts As Integer, _
    functn As D01..::..D01FC_FUNCTN, _
    eps As Double, _
    <OutAttribute> ByRef acc As Double, _
    <OutAttribute> ByRef finval As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void d01fc(
    int ndim,
    array<double>^ a,
    array<double>^ b,
    int% minpts,
    int maxpts,
    D01..::..D01FC_FUNCTN^ functn,
    double eps,
    [OutAttribute] double% acc,
    [OutAttribute] double% finval,
    [OutAttribute] int% ifail
)
F#
static member d01fc :
        ndim : int *
        a : float[] *
        b : float[] *
        minpts : int byref *
        maxpts : int *
        functn : D01..::..D01FC_FUNCTN *
        eps : float *
        acc : float byref *
        finval : float byref *
        ifail : int byref -> unit

Parameters

ndim
Type: System..::..Int32
On entry: n, the number of dimensions of the integral.
Constraint: 2≤ndim≤15.
a
Type: array< System..::..Double >[]()[][]
An array of size [ndim]
On entry: the lower limits of integration, ai, for i=1,2,…,n.
b
Type: array< System..::..Double >[]()[][]
An array of size [ndim]
On entry: the upper limits of integration, bi, for i=1,2,…,n.
minpts
Type: System..::..Int32 %
On entry: must be set to the minimum number of integrand evaluations to be allowed.
On exit: contains the actual number of integrand evaluations used by d01fc.
maxpts
Type: System..::..Int32
On entry: the maximum number of integrand evaluations to be allowed.
Constraints:
  • maxpts≥minpts;
  • maxpts≥α, where α=2 ndim+2×ndim 2+2×ndim+1.
functn
Type: NagLibrary..::..D01..::..D01FC_FUNCTN
functn must return the value of the integrand f at a given point.

A delegate of type D01FC_FUNCTN.

eps
Type: System..::..Double
On entry: the relative error acceptable to you. When the solution is zero or very small relative accuracy may not be achievable but you may still set eps to a reasonable value and check for the error exit ifail=2.
Constraint: eps>0.0.
acc
Type: System..::..Double %
On exit: the estimated relative error in finval.
finval
Type: System..::..Double %
On exit: the best estimate obtained for the integral.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

d01fc returns an estimate of a multidimensional integral over a hyper-rectangle (i.e., with constant limits), and also an estimate of the relative error. You set the relative accuracy required, return values for the integrand via a method argument functn, and also set the minimum and maximum acceptable number of calls to functn (in minpts and maxpts).
The method operates by repeated subdivision of the hyper-rectangular region into smaller hyper-rectangles. In each subregion, the integral is estimated using a seventh-degree rule, and an error estimate is obtained by comparison with a fifth-degree rule which uses a subset of the same points. The fourth differences of the integrand along each coordinate axis are evaluated, and the subregion is marked for possible future subdivision in half along that coordinate axis which has the largest absolute fourth difference.
If the estimated errors, totalled over the subregions, exceed the requested relative error (or if fewer than minpts calls to functn have been made), further subdivision is necessary, and is performed on the subregion with the largest estimated error, that subregion being halved along the appropriate coordinate axis.
The method will fail if the requested relative error level has not been attained by the time maxpts calls to functn have been made; or, if the amount lenwrk of working storage is insufficient. A formula for the recommended value of lenwrk is given in [Parameters]. If a smaller value is used, and is exhausted in the course of execution, the method switches to a less efficient mode of operation; only if this mode also breaks down is insufficient storage reported.
d01fc is based on the HALF method developed by van Dooren and de Ridder (1976). It uses a different basic rule, described in Genz and Malik (1980).

References

Genz A C and Malik A A (1980) An adaptive algorithm for numerical integration over an N-dimensional rectangular region J. Comput. Appl. Math. 6 295–302
van Dooren P and de Ridder L (1976) An adaptive algorithm for numerical integration over an N-dimensional cube J. Comput. Appl. Math. 2 207–217

Error Indicators and Warnings

Note: d01fc may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail=1
On entry, | ndim<2,
or | ndim>15,
or | maxpts is too small,
or | lenwrk<2×ndim+4,
or | eps≤0.0.
ifail=2
maxpts was too small to obtain the required relative accuracy eps. On soft failure, finval and acc contain estimates of the integral and the relative error, but acc will be greater than eps.
ifail=3
lenwrk was too small. On soft failure, finval and acc contain estimates of the integral and the relative error, but acc will be greater than eps.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

A relative error estimate is output through the parameter acc.

Parallelism and Performance

None.

Further Comments

Execution time will usually be dominated by the time taken to evaluate functn, and hence the maximum time that could be taken will be proportional to maxpts.

Example

This example estimates the integral
∫01∫01∫01∫01 4 z 1 z 32 exp 2 z 1z 3 1+z 2+z 4 2 d z 4 d z 3 d z 2 d z 1=0.575364.
The accuracy requested is one part in 10000.

Example program (C#): d01fce.cs

Example program results: d01fce.r

See Also

D01 Class
D01 Members


d01gd Method

[image]

NAG Library for .NET Release 2
D01..::d01gd Method
D01 Class See Also Send Feedback
d01gd calculates an approximation to a definite integral in up to 20 dimensions, using the Korobov–Conroy number theoretic method. This method is designed to be particularly efficient on vector processors.

Syntax

C#
public static void d01gd(
    int ndim,
    D01..::..D01GD_VECFUN vecfun,
    D01..::..D01GD_VECREG vecreg,
    int npts,
    double[] vk,
    int nrand,
    int itrans,
    out double res,
    out double err,
    out int ifail
)
Visual Basic
Public Shared Sub d01gd ( _
    ndim As Integer, _
    vecfun As D01..::..D01GD_VECFUN, _
    vecreg As D01..::..D01GD_VECREG, _
    npts As Integer, _
    vk As Double(), _
    nrand As Integer, _
    itrans As Integer, _
    <OutAttribute> ByRef res As Double, _
    <OutAttribute> ByRef err As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void d01gd(
    int ndim,
    D01..::..D01GD_VECFUN^ vecfun,
    D01..::..D01GD_VECREG^ vecreg,
    int npts,
    array<double>^ vk,
    int nrand,
    int itrans,
    [OutAttribute] double% res,
    [OutAttribute] double% err,
    [OutAttribute] int% ifail
)
F#
static member d01gd :
        ndim : int *
        vecfun : D01..::..D01GD_VECFUN *
        vecreg : D01..::..D01GD_VECREG *
        npts : int *
        vk : float[] *
        nrand : int *
        itrans : int *
        res : float byref *
        err : float byref *
        ifail : int byref -> unit

Parameters

ndim
Type: System..::..Int32
On entry: n, the number of dimensions of the integral.
Constraint: 1≤ndim≤20.
vecfun
Type: NagLibrary..::..D01..::..D01GD_VECFUN
vecfun must evaluate the integrand at a specified set of points.

A delegate of type D01GD_VECFUN.

vecreg
Type: NagLibrary..::..D01..::..D01GD_VECREG
vecreg must evaluate the limits of integration in any dimension for a set of points.

A delegate of type D01GD_VECREG.

npts
Type: System..::..Int32
On entry: the Korobov rule to be used. There are two alternatives depending on the value of npts.
(i) 1≤npts≤6.
In this case one of six preset rules is chosen using 2129, 5003, 10007, 20011, 40009 or 80021 points depending on the respective value of npts being 1, 2, 3, 4, 5 or 6.
(ii) npts>6.
npts is the number of actual points to be used with corresponding optimal coefficients supplied in the array vk.
Constraint: npts≥1.
vk
Type: array< System..::..Double >[]()[][]
An array of size [ndim]
On entry: if npts>6, vk must contain the n optimal coefficients (which may be calculated using d01gy or d01gz).
If npts≤6, vk need not be set.
On exit: if npts>6, vk is unchanged.
If npts≤6, vk contains the n optimal coefficients used by the preset rule.
nrand
Type: System..::..Int32
On entry: the number of random samples to be generated (generally a small value, say 3 to 5, is sufficient). The estimate, res, of the value of the integral returned by the method is then the average of nrand calculations with different random origin shifts. If npts>6, the total number of integrand evaluations will be nrand×npts. If 1≤npts≤6, then the number of integrand evaluations will be nrand×p, where p is the number of points corresponding to the six preset rules. For reasons of efficiency, these values are calculated a number at a time in vecfun.
Constraint: nrand≥1.
itrans
Type: System..::..Int32
On entry: indicates whether the periodising transformation is to be used.
itrans=0
The transformation is to be used.
itrans=1
The transformation is to be suppressed (to cover cases where the integrand may already be periodic or where you want to specify a particular transformation in the definition of vecfun).
Suggested value: itrans=0.
res
Type: System..::..Double %
On exit: the approximation to the integral I.
err
Type: System..::..Double %
On exit: the standard error as computed from nrand sample values. If nrand=1, then err contains zero.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

d01gd calculates an approximation to the integral
I=∫c 1d 1⋯∫cndn f x 1,…,xn d xn…d x 1 (1)
using the Korobov–Conroy number theoretic method (see Korobov (1957), Korobov (1963) and Conroy (1967)). The region of integration defined in (1) is such that generally ci and di may be functions of x 1,x 2,…,x i-1, for i=2,3,…,n, with c 1 and d 1 constants. The integral is first of all transformed to an integral over the n-cube 0,1 n by the change of variables
xi=ci+di-ci yi,  i=1,2,…,n.
The method then uses as its basis the number theoretic formula for the n-cube, 0,1 n:
∫01⋯∫01 g x 1,…,xn d xn⋯d x 1=1 p∑k=1 p g k a 1 p,…,k an p-E (2)
where x denotes the fractional part of x, a 1,…,an are the so-called optimal coefficients, E is the error, and p is a prime integer. (It is strictly only necessary that p be relatively prime to all a 1,…,an and is in fact chosen to be even for some cases in Conroy (1967).) The method makes use of properties of the Fourier expansion of g x 1,…,xn which is assumed to have some degree of periodicity. Depending on the choice of a 1,…,an the contributions from certain groups of Fourier coefficients are eliminated from the error, E. Korobov shows that a 1,…,an can be chosen so that the error satisfies
E≤CK p-α ln αβ p (3)
where α and C are real numbers depending on the convergence rate of the Fourier series, β is a constant depending on n, and K is a constant depending on α and n. There are a number of procedures for calculating these optimal coefficients. Korobov imposes the constraint that
a 1=1  and  ai=a i-1 mod p (4)
and gives a procedure for calculating the parameter, a, to satisfy the optimal conditions.
In this method the periodisation is achieved by the simple transformation
xi=yi 2 3-2 yi,  i=1,2,…,n.
More sophisticated periodisation procedures are available but in practice the degree of periodisation does not appear to be a critical requirement of the method.
An easily calculable error estimate is not available apart from repetition with an increasing sequence of values of p which can yield erratic results. The difficulties have been studied by Cranley and Patterson (1976) who have proposed a Monte–Carlo error estimate arising from converting (2) into a stochastic integration rule by the inclusion of a random origin shift which leaves the form of the error (3) unchanged; i.e., in the formula (2), k ai p is replaced by αi+k ai p, for i=1,2,…,n, where each αi, is uniformly distributed over 0,1. Computing the integral for each of a sequence of random vectors α allows a ‘standard error’ to be estimated.
This method provides built-in sets of optimal coefficients, corresponding to six different values of p. Alternatively, the optimal coefficients may be supplied by you. Methods d01gy and d01gz compute the optimal coefficients for the cases where p is a prime number or p is a product of two primes, respectively.
This method is designed to be particularly efficient on vector processors, although it is very important that you also code vecfun and vecreg efficiently.

References

Conroy H (1967) Molecular Shroedinger equation VIII. A new method for evaluting multi-dimensional integrals J. Chem. Phys. 47 5307–5318
Cranley R and Patterson T N L (1976) Randomisation of number theoretic methods for mulitple integration SIAM J. Numer. Anal. 13 904–914
Korobov N M (1957) The approximate calculation of multiple integrals using number theoretic methods Dokl. Acad. Nauk SSSR 115 1062–1065
Korobov N M (1963) Number Theoretic Methods in Approximate Analysis Fizmatgiz, Moscow

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | ndim<1,
or | ndim>20.
ifail=2
On entry, npts<1.
ifail=3
On entry, nrand<1.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

If nrand>1, an estimate of the absolute standard error is given by the value, on exit, of err.

Parallelism and Performance

None.

Further Comments

d01gd performs the same computation as (D01GCF not in this release). However, the interface has been modified so that it can perform more efficiently on machines with vector processing capabilities. In particular, vecfun and vecreg must calculate the integrand and limits of integration at a set of points. For some problems the amount of time spent in these two methods, which must be supplied by you, may account for a significant part of the total computation time. For this reason it is vital that you consider the possibilities for vectorization in the code supplied for these two methods.
The time taken will be approximately proportional to nrand×p, where p is the number of points used, but may depend significantly on the efficiency of the code provided by you in vecfun and vecreg.
The exact values of res and err on return will depend (within statistical limits) on the sequence of random numbers generated within d01gd by calls to g05sa. Separate runs will produce identical answers.

Example

This example calculates the integral
∫01∫01∫01∫01 cos 0.5+2 x 1+x 2+x 3+x 4-4d x 1d x 2d x 3d x 4.

Example program (C#): d01gde.cs

Example program results: d01gde.r

See Also

D01 Class
D01 Members


d01gy Method

[image]

NAG Library for .NET Release 2
D01..::d01gy Method
D01 Class See Also Send Feedback
d01gy calculates the optimal coefficients for use by (D01GCF not in this release) d01gd, for prime numbers of points.

Syntax

C#
public static void d01gy(
    int ndim,
    int npts,
    double[] vk,
    out int ifail
)
Visual Basic
Public Shared Sub d01gy ( _
    ndim As Integer, _
    npts As Integer, _
    vk As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void d01gy(
    int ndim,
    int npts,
    array<double>^ vk,
    [OutAttribute] int% ifail
)
F#
static member d01gy :
        ndim : int *
        npts : int *
        vk : float[] *
        ifail : int byref -> unit

Parameters

ndim
Type: System..::..Int32
On entry: n, the number of dimensions of the integral.
Constraint: ndim≥1.
npts
Type: System..::..Int32
On entry: p, the number of points to be used.
Constraint: npts must be a prime number ≥5.
vk
Type: array< System..::..Double >[]()[][]
An array of size [ndim]
On exit: the n optimal coefficients.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The Korobov (1963) procedure for calculating the optimal coefficients a 1,a 2,…,an for p-point integration over the n-cube 0,1 n imposes the constraint that
a 1=1  and  ai=a i-1 mod p,  i=1,2,…,n (1)
where p is a prime number and a is an adjustable parameter. This parameter is computed to minimize the error in the integral
3 n∫01 d x 1⋯∫01 d xn∏i=1 n 1-2 xi 2, (2)
when computed using the number theoretic rule, and the resulting coefficients can be shown to fit the Korobov definition of optimality.
The computation for large values of p is extremely time consuming (the number of elementary operations varying as p 2) and there is a practical upper limit to the number of points that can be used. Method d01gz is computationally more economical in this respect but the associated error is likely to be larger.

References

Korobov N M (1963) Number Theoretic Methods in Approximate Analysis Fizmatgiz, Moscow

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, ndim<1.
ifail=2
On entry, npts<5.
ifail=3
On entry, npts is not a prime number.
ifail=4
The precision of the machine is insufficient to perform the computation exactly. Try a smaller value of npts, or use an implementation of higher precision.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The optimal coefficients are returned as exact integers (though stored in a real array).

Parallelism and Performance

None.

Further Comments

The time taken is approximately proportional to p 2 (see [Description]).

Example

This example calculates the Korobov optimal coefficients where the number of dimensions is 4 and the number of points is 631.

Example program (C#): d01gye.cs

Example program results: d01gye.r

See Also

D01 Class
D01 Members


d01gz Method

[image]

NAG Library for .NET Release 2
D01..::d01gz Method
D01 Class See Also Send Feedback
d01gz calculates the optimal coefficients for use by (D01GCF not in this release) d01gd, when the number of points is the product of two primes.

Syntax

C#
public static void d01gz(
    int ndim,
    int np1,
    int np2,
    double[] vk,
    out int ifail
)
Visual Basic
Public Shared Sub d01gz ( _
    ndim As Integer, _
    np1 As Integer, _
    np2 As Integer, _
    vk As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void d01gz(
    int ndim,
    int np1,
    int np2,
    array<double>^ vk,
    [OutAttribute] int% ifail
)
F#
static member d01gz :
        ndim : int *
        np1 : int *
        np2 : int *
        vk : float[] *
        ifail : int byref -> unit

Parameters

ndim
Type: System..::..Int32
On entry: n, the number of dimensions of the integral.
Constraint: ndim≥1.
np1
Type: System..::..Int32
On entry: the larger prime factor p 1 of the number of points in the integration rule.
Constraint: np1 must be a prime number ≥5.
np2
Type: System..::..Int32
On entry: the smaller prime factor p 2 of the number of points in the integration rule. For maximum efficiency, p 22 should be close to p 1.
Constraint: np2 must be a prime number such that np1>np2≥2.
vk
Type: array< System..::..Double >[]()[][]
An array of size [ndim]
On exit: the n optimal coefficients.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Korobov (1963) gives a procedure for calculating optimal coefficients for p-point integration over the n-cube 0,1 n, when the number of points is
p=p 1p 2 (1)
where p 1 and p 2 are distinct prime numbers.
The advantage of this procedure is that if p 1 is chosen to be the nearest prime integer to p 22, then the number of elementary operations required to compute the rule is of the order of p 4/3 which grows less rapidly than the number of operations required by d01gy. The associated error is likely to be larger although it may be the only practical alternative for high values of p.

References

Korobov N M (1963) Number Theoretic Methods in Approximate Analysis Fizmatgiz, Moscow

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, ndim<1.
ifail=2
On entry, | np1<5,
or | np2<2,
or | np1≤np2.
ifail=3
The value np1×np2 exceeds the largest integer representable on the machine, and hence the optimal coefficients could not be used in a valid call of (D01GCF not in this release) d01gd.
ifail=4
On entry, np1 is not a prime number.
ifail=5
On entry, np2 is not a prime number.
ifail=6
The precision of the machine is insufficient to perform the computation exactly. Try smaller values of np1 or np2, or use an implementation with higher precision.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The optimal coefficients are returned as exact integers (though stored in a real array).

Parallelism and Performance

None.

Further Comments

The time taken by d01gz grows at least as fast as p 1p 2 4/3. (See [Description].)

Example

This example calculates the Korobov optimal coefficients where the number of dimensons is 4 and the number of points is the product of the two prime numbers, 89 and 11.

Example program (C#): d01gze.cs

Example program results: d01gze.r

See Also

D01 Class
D01 Members


d01ja Method

[image]

NAG Library for .NET Release 2
D01..::d01ja Method
D01 Class See Also Send Feedback
d01ja attempts to evaluate an integral over an n-dimensional sphere (n=2, 3, or 4), to a user-specified absolute or relative accuracy, by means of a modified Sag–Szekeres method. The method can handle singularities on the surface or at the centre of the sphere, and returns an error estimate.

Syntax

C#
public static void d01ja(
    D01..::..D01JA_F f,
    int ndim,
    double radius,
    double epsa,
    double epsr,
    int method,
    int icoord,
    out double result,
    out double esterr,
    out int nevals,
    out int ifail
)
Visual Basic
Public Shared Sub d01ja ( _
    f As D01..::..D01JA_F, _
    ndim As Integer, _
    radius As Double, _
    epsa As Double, _
    epsr As Double, _
    method As Integer, _
    icoord As Integer, _
    <OutAttribute> ByRef result As Double, _
    <OutAttribute> ByRef esterr As Double, _
    <OutAttribute> ByRef nevals As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void d01ja(
    D01..::..D01JA_F^ f,
    int ndim,
    double radius,
    double epsa,
    double epsr,
    int method,
    int icoord,
    [OutAttribute] double% result,
    [OutAttribute] double% esterr,
    [OutAttribute] int% nevals,
    [OutAttribute] int% ifail
)
F#
static member d01ja :
        f : D01..::..D01JA_F *
        ndim : int *
        radius : float *
        epsa : float *
        epsr : float *
        method : int *
        icoord : int *
        result : float byref *
        esterr : float byref *
        nevals : int byref *
        ifail : int byref -> unit

Parameters

f
Type: NagLibrary..::..D01..::..D01JA_F
f must return the value of the integrand f at a given point.

A delegate of type D01JA_F.

See also [Further Comments].
ndim
Type: System..::..Int32
On entry: n, the dimension of the sphere.
Constraint: 2≤ndim≤4.
radius
Type: System..::..Double
On entry: α, the radius of the sphere.
Constraint: radius≥0.0.
epsa
Type: System..::..Double
On entry: the requested absolute tolerance. If epsa<0.0, its absolute value is used. See [Accuracy].
epsr
Type: System..::..Double
On entry: the requested relative tolerance.
epsr<0.0
Its absolute value is used.
epsr<10×machine precision
The latter value is used as epsr by the method. See [Accuracy].
method
Type: System..::..Int32
On entry: must specify the transformation to be used by the method. The choice depends on the behaviour of the integrand and on the required accuracy.
For well-behaved functions and functions with mild singularities on the surface of the sphere only:
method=1
Low accuracy required.
method=2
High accuracy required.
For functions with severe singularities on the surface of the sphere only:
method=3
Low accuracy required.
method=4
High accuracy required.
(in this case icoord must be set to icoord=2, and the function defined in special spherical coordinates).
For functions with a singularity at the centre of the sphere (and possibly with singularities on the surface as well):
method=5
Low accuracy required.
method=6
High accuracy required.
method=0 can be used as a default value and is equivalent to:
  • method=1 if epsr>10-6, and
  • method=2 if epsr≤10-6.
The distinction between low and high required accuracies, as mentioned above, depends also on the behaviour of the function. Roughly one may assume the critical value of epsa and epsr to be 10-6, but the critical value will be smaller for a well-behaved integrand and larger for an integrand with severe singularities.
Suggested value: method=0.
Constraint: method=0, 1, 2, 3, 4, 5 or 6.
If icoord=2, method=3 or 4
icoord
Type: System..::..Int32
On entry: must specify which kind of coordinates are used in f.
icoord=0
Cartesian coordinates xi, for i=1,2,…,n.
icoord=1
Spherical coordinates (see [Spherical Polar Coordinates]): x[0]=ρ; x[i-1]=θ i-1, for i=2,3,…,n.
icoord=2,
Special spherical polar coordinates (see [Machine Dependencies]), with the additional transformation ρ=α-λ: x[0]=λ=α-ρ; x[i-1]=θ i-1, for i=2,3,…,n.
Constraint: icoord=0, 1 or 2.
If method=3 or 4, icoord=2
result
Type: System..::..Double %
On exit: the approximation to the integral I.
esterr
Type: System..::..Double %
On exit: an estimate of the modulus of the absolute error.
nevals
Type: System..::..Int32 %
On exit: the number of function evaluations used.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

d01ja calculates an approximation to the n-dimensional integral
I=∫⋯∫S F x 1,…,xn d x 1⋯d xn,  2≤n≤4,
where S is the hypersphere
x 12+⋯+xn 2≤α<∞
(the integrand function may also be defined in spherical coordinates). The algorithm is based on the Sag–Szekeres method (see Sag and Szekeres (1964)), applying the product trapezoidal formula after a suitable radial transformation. An improved transformation technique is developed: depending on the behaviour of the function and on the required accuracy, different transformations can be used, some of which are ‘double exponential’, as defined by Takahasi and Mori (1974). The resulting technique allows the method to deal with integrand singularities on the surface or at the centre of the sphere. When the estimated error of the approximation with mesh size h is larger than the tolerated error, the trapezoidal formula with mesh size h/2 is calculated. A drawback of this method is the exponential growth of the number of function evaluations in the successive approximations (this number grows with a factor ≈2 n). This introduces the restriction n≤4. Because the convergence rate of the successive approximations is normally better than linear, the error estimate is based on the linear extrapolation of the difference between the successive approximations (see Robinson and de Doncker (1981) and Roose and de Doncker (1981)). For further details of the algorithm, see Roose and de Doncker (1981).

References

Robinson I and de Doncker E (1981) Automatic computation of improper integrals over a bounded or unbounded planar region Computing 27 89–284
Roose D and de Doncker E (1981) Automatic integration over a sphere J. Comput. Appl. Math. 7 203–224
Sag T W and Szekeres G (1964) Numerical evaluation of high-dimensional integrals Math. Comput. 18 245–253
Takahasi H and Mori M (1974) Double Exponential Formulas for Numerical Integration 9 Publ. RIMS, Kyoto University 721–741

Error Indicators and Warnings

Note: d01ja may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail=1
The required accuracy cannot be achieved within a limiting number of function evaluations (which is set by the method).
ifail=2
The required accuracy cannot be achieved because of round-off error.
ifail=3
The required accuracy cannot be achieved because the maximum accuracy with respect to the machine constants x02aj and x02am has been attained. If this maximum accuracy is rather low (compared with x02aj), the cause of the problem is a severe singularity on the boundary or at the centre of the sphere. If method=0, 1 or 2, then setting method=3 or 4 may help.
ifail=4
On entry, | ndim<2 or ndim>4,
or | radius<0.0,
or | method≠0, 1, 2, 3, 4, 5 or 6,
or | icoord≠0, 1 or 2,
or | icoord=2 and method≠3 or 4,
or | method=3 or 4 and icoord≠2.
No calculations have been performed. result and esterr are set to 0.0.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

You can specify an absolute and/or a relative tolerance, setting epsa and epsr. The method attempts to calculate an approximation result such that
I-result≤max epsa,epsr×I.
If 0≤ifail≤3, esterr returns an estimate of, but not necessarily a bound for, I-result.

Parallelism and Performance

None.

Further Comments

Timing

Timing depends on the integrand and the accuracy required.

Spherical Polar Coordinates

Cartesian coordinates are related to the spherical polar coordinates by:
x 1=ρ.sin θ 1⋯sin θ n-2.sin θ n-1x 2=ρ.sin θ 1⋯sin θ n-2.cos θ n-1x 3=ρ.sin θ 1⋯cos θ n-2⋮xn=ρ.cos θ 1
where 0<θi<π, for i=1,2,…,n-2 and 0<θ n-1<2 π.

Machine Dependencies

As a consequence of the transformation technique, the severity of the singularities which can be handled by d01ja depends on the precision and range of real numbers on the machine. method=3 or 4 must be used when the singularity on the surface is ‘severe’ in view of the requested accuracy and machine precision. In practice one has to set method=3 or 4 if d01ja terminates with ifail=3 when called with method=0, 1 or 2.
When integrating a function with a severe singular behaviour on the surface of the sphere, the additional transformation ρ=α-λ helps to avoid the loss of significant figures due to round-off error in the calculation of the integration nodes which are very close to the surface. For these points, the value of λ can be computed more accurately than the value of ρ. Naturally, care must be taken that the function subprogram does not contain expressions of the form α-λ, which could cause a large round-off error in the calculation of the integrand at the boundary of the sphere.
Care should be taken to avoid underflow and/or overflow problems in the function subprogram, because some of the integration nodes used by d01ja may be very close to the surface or to the centre of the sphere.
Example:
  • suppose the function
    f ρ=1-ρ 2-0.7
    is to be integrated over the unit sphere, with method=3 or 4. Then icoord should be set to 2; the transformation ρ=1-λ gives f ρ=2 λ-λ 2-0.7; and f could be coded thus:
Note that d01ja ensures that λ=x[0]>x02am, but underflow could occur in the computation of λ 2.

Example

This example evaluates the integrals
∫⋯∫S 1 1-ρ 2 d x 1⋯d xn
where ρ=∑i=1 n xi 2, and S is the unit sphere of dimension n=2​ or ​4.
The exact values (to 12 decimal places) are 6.28318530718 and 13.1594725348.

Example program (C#): d01jae.cs

Example program results: d01jae.r

See Also

D01 Class
D01 Members


d01pa Method

[image]

NAG Library for .NET Release 2
D01..::d01pa Method
D01 Class See Also Send Feedback
d01pa returns a sequence of approximations to the integral of a function over a multidimensional simplex, together with an error estimate for the last approximation.

Syntax

C#
public static void d01pa(
    int ndim,
    double[,] vert,
    D01..::..D01PA_FUNCTN functn,
    ref int minord,
    int maxord,
    double[] finvls,
    out double esterr,
    out int ifail
)
Visual Basic
Public Shared Sub d01pa ( _
    ndim As Integer, _
    vert As Double(,), _
    functn As D01..::..D01PA_FUNCTN, _
    ByRef minord As Integer, _
    maxord As Integer, _
    finvls As Double(), _
    <OutAttribute> ByRef esterr As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void d01pa(
    int ndim,
    array<double,2>^ vert,
    D01..::..D01PA_FUNCTN^ functn,
    int% minord,
    int maxord,
    array<double>^ finvls,
    [OutAttribute] double% esterr,
    [OutAttribute] int% ifail
)
F#
static member d01pa :
        ndim : int *
        vert : float[,] *
        functn : D01..::..D01PA_FUNCTN *
        minord : int byref *
        maxord : int *
        finvls : float[] *
        esterr : float byref *
        ifail : int byref -> unit

Parameters

ndim
Type: System..::..Int32
On entry: n, the number of dimensions of the integral.
Constraint: ndim≥2.
vert
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, sdvert]
Note: dim1 must satisfy the constraint: dim1≥ndim+1
On entry: vert[i-1,j-1] must be set to the jth component of the ith vertex for the simplex integration region, for i=1,2,…,n+1 and j=1,2,…,n. If minord>0, vert must be unchanged since the previous call of d01pa.
On exit: these values are unchanged. The rest of the array vert is used for workspace and contains information to be used if another call of d01pa is made with minord>0. In particular vert[n,2 n+1] contains the volume of the simplex.
functn
Type: NagLibrary..::..D01..::..D01PA_FUNCTN
functn must return the value of the integrand f at a given point.

A delegate of type D01PA_FUNCTN.

minord
Type: System..::..Int32 %
On entry: must specify the highest order of the approximations currently available in the array finvls. minord=0 indicates an initial call; minord>0 indicates that finvls[0],finvls[1],…,finvls[minord-1] have already been computed in a previous call of d01pa.
Constraint: minord≥0.
On exit: minord=maxord.
maxord
Type: System..::..Int32
On entry: the highest order of approximation to the integral to be computed.
Constraint: maxord>minord.
finvls
Type: array< System..::..Double >[]()[][]
An array of size [maxord]
On entry: if minord>0, finvls[0],finvls[1],…,finvls[minord-1] must contain approximations to the integral previously computed by d01pa.
On exit: contains these values unchanged, and the newly computed values finvls[minord],finvls[minord+1],…,finvls[maxord-1]. finvls[j-1] is an approximation to the integral of polynomial degree 2 j-1.
esterr
Type: System..::..Double %
On exit: an absolute error estimate for finvls[maxord-1].
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

d01pa computes a sequence of approximations finvls[j-1], for j=minord+1,…,maxord, to an integral
∫S f x 1,x 2,…,xn d x 1 d x 2⋯d xn
where S is an n-dimensional simplex defined in terms of its n+1 vertices. finvls[j-1] is an approximation which will be exact (except for rounding errors) whenever the integrand is a polynomial of total degree 2 j-1 or less.
The type of method used has been described in Grundmann and Moller (1978), and is implemented in an extrapolated form using the theory from de Doncker (1979).

References

de Doncker E (1979) New Euler–Maclaurin Expansions and their application to quadrature over the s-dimensional simplex Math. Comput. 33 1003–1018
Grundmann A and Moller H M (1978) Invariant integration formulas for the n-simplex by combinatorial methods SIAM J. Numer. Anal. 15 282–290

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDVERT) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, ldvert=value and ndim=value.
Constraint: ldvert≥ndim+1.
On entry, maxord=value and minord=value.
Constraint: maxord>minord.
On entry, minord=value.
Constraint: minord≥0.
On entry, ndim=value.
Constraint: ndim≥2.
On entry, sdvert=value and ndim=value.
Constraint: sdvert≥2×ndim+1.
ifail=2
The volume of the simplex integration region is too large or too small to be represented on the machine.
ifail=-999
Dynamic memory allocation failed.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

An absolute error estimate is output through the parameter esterr.

Parallelism and Performance

None.

Further Comments

The running time for d01pa will usually be dominated by the time used to evaluate the integrand functn. The maximum time that could be used by d01pa will be approximately given by
T×maxord+ndim!maxord-1!ndim+1!
where T is the time needed for one call of functn.

Example

This example demonstrates the use of the method with the integral
∫01∫0 1-x∫0 1-x-y exp x+y+zcos x+y+zdzdydx=14.

Example program (C#): d01pae.cs

Example program results: d01pae.r

See Also

D01 Class
D01 Members


E01 Class

[image]

NAG Library for .NET Release 2
E01 Class
Members See Also Send Feedback
This chapter is concerned with the interpolation of a function of one or more variables. When provided with the value of the function (and possibly one or more of its lowest-order derivatives) at each of a number of values of the variable(s), the NAG Library methods provide either an interpolating function or an interpolated value. For some of the interpolating functions, there are supporting NAG Library methods to evaluate, differentiate or integrate them.

Syntax

C#
public static class E01
Visual Basic
Public NotInheritable Class E01
Visual C++
public ref class E01 abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type E01 =  class end

Background to the Problems

In motivation and in some of its numerical processes, this chapter has much in common with E02 class (Curve and Surface Fitting). For this reason, we shall adopt the same terminology and refer to dependent variable and independent variable(s) instead of function and variable(s). Where there is only one independent variable, we shall denote it by x and the dependent variable by y. Thus, in the basic problem considered in this chapter, we are given a set of distinct values x 1,x 2,…,xm of x and a corresponding set of values y 1,y 2,…,ym of y, and we shall describe the problem as being one of interpolating the data points xr,yr, rather than interpolating a function. In modern usage, however, interpolation can have either of two rather different meanings, both relevant to methods in this chapter. They are
(a) | the determination of a function of x which takes the value yr at x=xr, for r=1,2,…,m (an interpolating function or interpolant),
(b) | the determination of the value (interpolated value or interpolate) of an interpolating function at any given value, say x^, of x within the range of the xr (so as to estimate the value at x^ of the function underlying the data).
The latter is the older meaning, associated particularly with the use of mathematical tables. The term ‘function underlying the data’, like the other terminology described above, is used so as to cover situations additional to those in which the data points have been computed from a known function, as with a mathematical table. In some contexts, the function may be unknown, perhaps representing the dependency of one physical variable on another, say temperature upon time.
Whether the underlying function is known or unknown, the object of interpolation will usually be to approximate it to acceptable accuracy by a function which is easy to evaluate anywhere in some range of interest. Polynomials, rational functions (ratios of two polynomials) and piecewise polynomials, such as cubic splines (see [] in the E02 class Chapter Introduction for definitions of terms in the latter case), being easy to evaluate and also capable of approximating a wide variety of functions, are the types of function mostly used in this chapter as interpolating functions. An interpolating polynomial is taken to have degree m-1 when there are m data points, and so it is unique. It is called the Lagrange interpolating polynomial. The rational function, in the special form used, is also unique. An interpolating spline, on the other hand, depends on the choice made for the knots.
One way of achieving the objective in (b) above is, of course, through (a), but there are also methods which do not involve the explicit computation of the interpolating function. Everett's formula and Aitken's successive linear interpolation (see Dahlquist and Björck (1974)) provide two such methods. Both are used in this chapter and determine a value of the Lagrange interpolating polynomial.
It is important to appreciate, however, that the Lagrange interpolating polynomial often exhibits unwanted fluctuations between the data points. These tend to occur particularly towards the ends of the data range, and to get larger with increasing number of data points. In severe cases, such as with 30 or 40 equally spaced values of x, the polynomial can take on values several orders of magnitude larger than the data values. (Closer spacing near the ends of the range tends to improve the situation, and wider spacing tends to make it worse.) Clearly, therefore, the Lagrange polynomial often gives a very poor approximation to the function underlying the data. On the other hand, it can be perfectly satisfactory when its use is restricted to providing interpolated values away from the ends of the data range from a reasonably small number of data values.
In contrast, a cubic spline which interpolates a large number of data points can often be used satisfactorily over the whole of the data range. Unwanted fluctuations can still arise but much less frequently and much less severely than with polynomials. Rational functions, when appropriate, would also be used over the whole data range. The main danger with these functions is that their polynomial denominators may take zero values within that range. Unwanted fluctuations are avoided altogether by a method using piecewise cubic polynomials having only first derivative continuity. It is designed especially for monotonic data, but for other data still provides an interpolant which increases, or decreases, over the same intervals as the data.
The concept of interpolation can be generalized in a number of ways. Firstly, at each x, the interpolating function may be required to take on not only a given value but also given values for all its derivatives up to some specified order (which can vary with r). This is the Hermite–Birkoff interpolation problem. Secondly, we may be required to estimate the value of the underlying function at a value x^ outside the range of the data. This is the process of extrapolation. In general, it is a good deal less accurate than interpolation and is to be avoided whenever possible.
Interpolation can also be extended to the case of two or more independent variables. If the data values are given at the intersections of a regular two-dimensional mesh bicubic splines (see [] in the E02 class Chapter Introduction) are very suitable and usually very effective for the problem. For other cases, perhaps where the data values are quite arbitrarily scattered, polynomials and splines are not at all appropriate and special forms of interpolating function have to be employed. Many such forms have been devised and two of the most successful are in methods in this chapter. They both have continuity in first, but not higher, derivatives.

References

Dahlquist G and Björck Å (1974) Numerical Methods Prentice–Hall
Fröberg C E (1970) Introduction to Numerical Analysis Addison–Wesley

Inheritance Hierarchy

System..::..Object
NagLibrary..::..E01

See Also

E01 Members


E01 Members

[image] [image]

NAG Library for .NET Release 2
E01 Members
E01 Class Methods See Also Send Feedback

The E01 type exposes the following members.

Methods

Name | Description
e01ba | e01ba determines a cubic spline interpolant to a given set of data.
e01be | e01be computes a monotonicity-preserving piecewise cubic Hermite interpolant to a set of data points.
e01bf | e01bf evaluates a piecewise cubic Hermite interpolant at a set of points.
e01da | e01da computes a bicubic spline interpolating surface through a set of data values, given on a rectangular grid in the x-y plane.

See Also

E01 Class


E01 Methods

[image] [image]

NAG Library for .NET Release 2
E01 Methods
E01 Class See Also Send Feedback

The E01 type exposes the following members.

Methods

Name | Description
e01ba | e01ba determines a cubic spline interpolant to a given set of data.
e01be | e01be computes a monotonicity-preserving piecewise cubic Hermite interpolant to a set of data points.
e01bf | e01bf evaluates a piecewise cubic Hermite interpolant at a set of points.
e01da | e01da computes a bicubic spline interpolating surface through a set of data values, given on a rectangular grid in the x-y plane.

See Also

E01 Class


e01ba Method

[image]

NAG Library for .NET Release 2
E01..::e01ba Method
E01 Class See Also Send Feedback
e01ba determines a cubic spline interpolant to a given set of data.

Syntax

C#
public static void e01ba(
    int m,
    double[] x,
    double[] y,
    double[] lamda,
    double[] c,
    out int ifail
)
Visual Basic
Public Shared Sub e01ba ( _
    m As Integer, _
    x As Double(), _
    y As Double(), _
    lamda As Double(), _
    c As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e01ba(
    int m,
    array<double>^ x,
    array<double>^ y,
    array<double>^ lamda,
    array<double>^ c,
    [OutAttribute] int% ifail
)
F#
static member e01ba :
        m : int *
        x : float[] *
        y : float[] *
        lamda : float[] *
        c : float[] *
        ifail : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: m, the number of data points.
Constraint: m≥4.
x
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: x[i-1] must be set to xi, the ith data value of the independent variable x, for i=1,2,…,m.
Constraint: x[i-1]<x[i], for i=1,2,…,m-1.
y
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: y[i-1] must be set to yi, the ith data value of the dependent variable y, for i=1,2,…,m.
lamda
Type: array< System..::..Double >[]()[][]
An array of size [lck]
On exit: the value of λi, the ith knot, for i=1,2,…,m+4.
c
Type: array< System..::..Double >[]()[][]
An array of size [lck]
On exit: the coefficient ci of the B-spline Ni x, for i=1,2,…,m. The remaining elements of the array are not used.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e01ba determines a cubic spline s x, defined in the range x 1≤x≤xm, which interpolates (passes exactly through) the set of data points xi,yi, for i=1,2,…,m, where m≥4 and x 1<x 2<⋯<xm. Unlike some other spline interpolation algorithms, derivative end conditions are not imposed. The spline interpolant chosen has m-4 interior knots λ 5,λ 6,…,λm, which are set to the values of x 3,x 4,…,x m-2 respectively. This spline is represented in its B-spline form (see Cox (1975)):
s x=∑i=1 m ciNi x,
where Ni x denotes the normalized B-spline of degree 3, defined upon the knots λi,λ i+1,…,λ i+4, and ci denotes its coefficient, whose value is to be determined by the method.
The use of B-splines requires eight additional knots λ 1, λ 2, λ 3, λ 4, λ m+1, λ m+2, λ m+3 and λ m+4 to be specified; e01ba sets the first four of these to x 1 and the last four to xm.
The algorithm for determining the coefficients is as described in Cox (1975) except that QR factorization is used instead of LU decomposition. The implementation of the algorithm involves setting up appropriate information for the related method (E02BAF not in this release) followed by a call of that method. (See (E02BAF not in this release) for further details.)
Values of the spline interpolant, or of its derivatives or definite integral, can subsequently be computed as detailed in [Further Comments].

References

Cox M G (1975) An algorithm for spline interpolation J. Inst. Math. Appl. 15 95–108
Cox M G (1977) A survey of numerical methods for data and function approximation The State of the Art in Numerical Analysis (ed D A H Jacobs) 627–668 Academic Press

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | m<4,
or | lck<m+4,
or | lwrk<6×m+16.
ifail=2
The x-values fail to satisfy the condition
x[0]<x[1]<x[2]<⋯<x[m-1].
ifail=-9000
An error occured, see message report.
ifail=-1000
The array lengths are not the same for arrays
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The rounding errors incurred are such that the computed spline is an exact interpolant for a slightly perturbed set of ordinates yi+δ yi. The ratio of the root-mean-square value of the δ yi to that of the yi is no greater than a small multiple of the relative machine precision.

Parallelism and Performance

None.

Further Comments

The time taken by e01ba is approximately proportional to m.
All the xi are used as knot positions except x 2 and x m-1. This choice of knots (see Cox (1977)) means that s x is composed of m-3 cubic arcs as follows. If m=4, there is just a single arc space spanning the whole interval x 1 to x 4. If m≥5, the first and last arcs span the intervals x 1 to x 3 and x m-2 to xm respectively. Additionally if m≥6, the ith arc, for i=2,3,…,m-4, spans the interval x i+1 to x i+2.
After the call the following operations may be carried out on the interpolant s x.
The value of s x at x=x can be provided in the real variable s by the call (see e02bb).
The values of s x and its first three derivatives at x=x can be provided in the real array s of dimension 4, by the call (see (E02BCF not in this release)).
Here left must specify whether the left- or right-hand value of the third derivative is required (see (E02BCF not in this release) for details).
The value of the integral of s x over the range x 1 to xm can be provided in the real variable dint by (see (E02BDF not in this release)).

Example

This example sets up data from 7 values of the exponential function in the interval 0 to 1. e01ba is then called to compute a spline interpolant to these data.

Example program (C#): e01bae.cs

Example program results: e01bae.r

See Also

E01 Class
E01 Members


e01be Method

[image]

NAG Library for .NET Release 2
E01..::e01be Method
E01 Class See Also Send Feedback
e01be computes a monotonicity-preserving piecewise cubic Hermite interpolant to a set of data points.

Syntax

C#
public static void e01be(
    int n,
    double[] x,
    double[] f,
    double[] d,
    out int ifail
)
Visual Basic
Public Shared Sub e01be ( _
    n As Integer, _
    x As Double(), _
    f As Double(), _
    d As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e01be(
    int n,
    array<double>^ x,
    array<double>^ f,
    array<double>^ d,
    [OutAttribute] int% ifail
)
F#
static member e01be :
        n : int *
        x : float[] *
        f : float[] *
        d : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of data points.
Constraint: n≥2.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x[r-1] must be set to xr, the rth value of the independent variable (abscissa), for r=1,2,…,n.
Constraint: x[r-1]<x[r].
f
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: f[r-1] must be set to fr, the rth value of the dependent variable (ordinate), for r=1,2,…,n.
d
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: estimates of derivatives at the data points. d[r-1] contains the derivative at x[r-1].
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e01be estimates first derivatives at the set of data points xr,fr, for r=1,2,…,n, which determine a piecewise cubic Hermite interpolant to the data, that preserves monotonicity over ranges where the data points are monotonic. If the data points are only piecewise monotonic, the interpolant will have an extremum at each point where monotonicity switches direction. The estimates of the derivatives are computed by a formula due to Brodlie, which is described in Fritsch and Butland (1984), with suitable changes at the boundary points.
The method is derived from method PCHIM in Fritsch (1982).
Values of the computed interpolant, and of its first derivative and definite integral, can subsequently be computed by calling e01bf (E01BGF not in this release) (E01BHF not in this release), as described in [Further Comments].

References

Fritsch F N (1982) PCHIP final specifications Report UCID-30194 Lawrence Livermore National Laboratory
Fritsch F N and Butland J (1984) A method for constructing local monotone piecewise cubic interpolants SIAM J. Sci. Statist. Comput. 5 300–304

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<2.
ifail=2
The values of x[r-1], for r=1,2,…,n, are not in strictly increasing order.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The computational errors in the array d should be negligible in most practical situations.

Parallelism and Performance

None.

Further Comments

The time taken by e01be is approximately proportional to n.
The values of the computed interpolant at the points px[i-1], for i=1,2,…,m, may be obtained in the real array pf, of length at least m, by the call: where n, x and f are the input parameters to e01be and d is the output parameter from e01be.
The values of the computed interpolant at the points px[i-1], for i=1,2,…,m, together with its first derivatives, may be obtained in the real arrays pf and pd, both of length at least m, by the call: where n, x, f and d are as described above.
The value of the definite integral of the interpolant over the interval a to b can be obtained in the real variable pint by the call: where n, x, f and d are as described above.

Example

Example program (C#): e01bee.cs

Example program data: e01bee.d

Example program results: e01bee.r

See Also

E01 Class
E01 Members


e01bf Method

[image]

NAG Library for .NET Release 2
E01..::e01bf Method
E01 Class See Also Send Feedback
e01bf evaluates a piecewise cubic Hermite interpolant at a set of points.

Syntax

C#
public static void e01bf(
    int n,
    double[] x,
    double[] f,
    double[] d,
    int m,
    double[] px,
    double[] pf,
    out int ifail
)
Visual Basic
Public Shared Sub e01bf ( _
    n As Integer, _
    x As Double(), _
    f As Double(), _
    d As Double(), _
    m As Integer, _
    px As Double(), _
    pf As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e01bf(
    int n,
    array<double>^ x,
    array<double>^ f,
    array<double>^ d,
    int m,
    array<double>^ px,
    array<double>^ pf,
    [OutAttribute] int% ifail
)
F#
static member e01bf :
        n : int *
        x : float[] *
        f : float[] *
        d : float[] *
        m : int *
        px : float[] *
        pf : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
An array of size []
On entry: n, x, f and d must be unchanged from the previous call of e01be.
x
Type: array< System..::..Double >[]()[][]
An array of size []
On entry: n, x, f and d must be unchanged from the previous call of e01be.
f
Type: array< System..::..Double >[]()[][]
An array of size []
On entry: n, x, f and d must be unchanged from the previous call of e01be.
d
Type: array< System..::..Double >[]()[][]
An array of size []
On entry: n, x, f and d must be unchanged from the previous call of e01be.
m
Type: System..::..Int32
On entry: m, the number of points at which the interpolant is to be evaluated.
Constraint: m≥1.
px
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: the m values of x at which the interpolant is to be evaluated.
pf
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: pf[i-1] contains the value of the interpolant evaluated at the point px[i-1], for i=1,2,…,m.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e01bf evaluates a piecewise cubic Hermite interpolant, as computed by e01be, at the points px[i-1], for i=1,2,…,m. If any point lies outside the interval from x[0] to x[n-1], a value is extrapolated from the nearest extreme cubic, and a warning is returned.
The method is derived from method PCHFE in Fritsch (1982).

References

Fritsch F N (1982) PCHIP final specifications Report UCID-30194 Lawrence Livermore National Laboratory

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<2.
ifail=2
The values of x[r-1], for r=1,2,…,n, are not in strictly increasing order.
ifail=3
On entry, m<1.
ifail=4
At least one of the points px[i-1], for i=1,2,…,m, lies outside the interval [x[0],x[n-1]], and extrapolation was performed at all such points. Values computed at such points may be very unreliable.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The computational errors in the array pf should be negligible in most practical situations.

Parallelism and Performance

None.

Further Comments

The time taken by e01bf is approximately proportional to the number of evaluation points, m. The evaluation will be most efficient if the elements of px are in nondecreasing order (or, more generally, if they are grouped in increasing order of the intervals x[r-1],x[r]). A single call of e01bf with m>1 is more efficient than several calls with m=1.

Example

This example reads in values of n, x, f and d, and then calls e01bf to evaluate the interpolant at equally spaced points.

Example program (C#): e01bfe.cs

Example program data: e01bfe.d

Example program results: e01bfe.r

See Also

E01 Class
E01 Members


e01da Method

[image]

NAG Library for .NET Release 2
E01..::e01da Method
E01 Class See Also Send Feedback
e01da computes a bicubic spline interpolating surface through a set of data values, given on a rectangular grid in the x-y plane.

Syntax

C#
public static void e01da(
    int mx,
    int my,
    double[] x,
    double[] y,
    double[] f,
    out int px,
    out int py,
    double[] lamda,
    double[] mu,
    double[] c,
    out int ifail
)
Visual Basic
Public Shared Sub e01da ( _
    mx As Integer, _
    my As Integer, _
    x As Double(), _
    y As Double(), _
    f As Double(), _
    <OutAttribute> ByRef px As Integer, _
    <OutAttribute> ByRef py As Integer, _
    lamda As Double(), _
    mu As Double(), _
    c As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e01da(
    int mx,
    int my,
    array<double>^ x,
    array<double>^ y,
    array<double>^ f,
    [OutAttribute] int% px,
    [OutAttribute] int% py,
    array<double>^ lamda,
    array<double>^ mu,
    array<double>^ c,
    [OutAttribute] int% ifail
)
F#
static member e01da :
        mx : int *
        my : int *
        x : float[] *
        y : float[] *
        f : float[] *
        px : int byref *
        py : int byref *
        lamda : float[] *
        mu : float[] *
        c : float[] *
        ifail : int byref -> unit

Parameters

mx
Type: System..::..Int32
On entry: mx and my must specify mx and my respectively, the number of points along the x and y axis that define the rectangular grid.
Constraint: mx≥4 and my≥4.
my
Type: System..::..Int32
On entry: mx and my must specify mx and my respectively, the number of points along the x and y axis that define the rectangular grid.
Constraint: mx≥4 and my≥4.
x
Type: array< System..::..Double >[]()[][]
An array of size [mx]
On entry: x[q-1] and y[r-1] must contain xq, for q=1,2,…,mx, and yr, for r=1,2,…,my, respectively.
Constraints:
  • x[q-1]<x[q], for q=1,2,…,mx-1;
  • y[r-1]<y[r], for r=1,2,…,my-1.
y
Type: array< System..::..Double >[]()[][]
An array of size [mx]
On entry: x[q-1] and y[r-1] must contain xq, for q=1,2,…,mx, and yr, for r=1,2,…,my, respectively.
Constraints:
  • x[q-1]<x[q], for q=1,2,…,mx-1;
  • y[r-1]<y[r], for r=1,2,…,my-1.
f
Type: array< System..::..Double >[]()[][]
An array of size [mx×my]
On entry: f[my×q-1+r-1] must contain f q,r, for q=1,2,…,mx and r=1,2,…,my.
px
Type: System..::..Int32 %
On exit: px and py contain mx+4 and my+4, the total number of knots of the computed spline with respect to the x and y variables, respectively.
py
Type: System..::..Int32 %
On exit: px and py contain mx+4 and my+4, the total number of knots of the computed spline with respect to the x and y variables, respectively.
lamda
Type: array< System..::..Double >[]()[][]
An array of size [mx+4]
On exit: lamda contains the complete set of knots λi associated with the x variable, i.e., the interior knots lamda[4],lamda[5],…,lamda[px-5], as well as the additional knots
lamda[0]=lamda[1]=lamda[2]=lamda[3]=x[0]
and
lamda[px-4]=lamda[px-3]=lamda[px-2]=lamda[px-1]=x[mx-1]
needed for the B-spline representation.
mu
Type: array< System..::..Double >[]()[][]
An array of size [mx+4]
On exit: lamda contains the complete set of knots λi associated with the x variable, i.e., the interior knots lamda[4],lamda[5],…,lamda[px-5], as well as the additional knots
lamda[0]=lamda[1]=lamda[2]=lamda[3]=x[0]
and
lamda[px-4]=lamda[px-3]=lamda[px-2]=lamda[px-1]=x[mx-1]
needed for the B-spline representation.
c
Type: array< System..::..Double >[]()[][]
An array of size [mx×my]
On exit: the coefficients of the spline interpolant. c[my×i-1+j-1] contains the coefficient c ij described in [Description].
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e01da determines a bicubic spline interpolant to the set of data points xq,yr,f q,r, for q=1,2,…,mx and r=1,2,…,my. The spline is given in the B-spline representation
s x,y=∑i=1 mx∑j=1 my c ijMi x Nj y,
such that
s xq,yr=f q,r,
where Mi x and Nj y denote normalized cubic B-splines, the former defined on the knots λi to λ i+4 and the latter on the knots μj to μ j+4, and the c ij are the spline coefficients. These knots, as well as the coefficients, are determined by the method, which is derived from the method B2IRE in Anthony et al. (1982). The method used is described in [Outline of Method Used].
For further information on splines, see Hayes and Halliday (1974) for bicubic splines and de Boor (1972) for normalized B-splines.
Values and derivatives of the computed spline can subsequently be computed by calling e02de e02df (E02DHF not in this release) as described in [Evaluation of Computed Spline].

References

Anthony G T, Cox M G and Hayes J G (1982) DASL – Data Approximation Subroutine Library National Physical Laboratory
Cox M G (1975) An algorithm for spline interpolation J. Inst. Math. Appl. 15 95–108
de Boor C (1972) On calculating with B-splines J. Approx. Theory 6 50–62
Hayes J G and Halliday J (1974) The least squares fitting of cubic spline surfaces to general data sets J. Inst. Math. Appl. 14 89–103

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | mx<4,
or | my<4.
ifail=2
On entry, either the values in the x array or the values in the y array are not in increasing order if not already there.
ifail=3
A system of linear equations defining the B-spline coefficients was singular; the problem is too ill-conditioned to permit solution.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The main sources of rounding errors are in steps 2, 3, 6 and 7 of the algorithm described in [Outline of Method Used]. It can be shown (see Cox (1975)) that the matrix Ax formed in step 2 has elements differing relatively from their true values by at most a small multiple of 3 ε, where ε is the machine precision. Ax is ‘totally positive’, and a linear system with such a coefficient matrix can be solved quite safely by elimination without pivoting. Similar comments apply to steps 6 and 7. Thus the complete process is numerically stable.

Parallelism and Performance

None.

Further Comments

Timing

The time taken by e01da is approximately proportional to mxmy.

Outline of Method Used

The process of computing the spline consists of the following steps:
1. | choice of the interior x-knots λ 5, λ 6,…,λ mx as λi=x i-2, for i=5,6,…,mx,
2. formation of the system
Ax E=F,
where Ax is a band matrix of order mx and bandwidth 4, containing in its qth row the values at xq of the B-splines in x, f is the mx by my rectangular matrix of values f q,r, and E denotes an mx by my rectangular matrix of intermediate coefficients,
3. | use of Gaussian elimination to reduce this system to band triangular form,
4. | solution of this triangular system for E,
5. | choice of the interior y knots μ 5, μ 6,…,μ my as μi=y i-2, for i=5,6,…,my,
6. formation of the system
Ay CT=ET,
where Ay is the counterpart of Ax for the y variable, and C denotes the mx by my rectangular matrix of values of c ij,
7. | use of Gaussian elimination to reduce this system to band triangular form,
8. | solution of this triangular system for CT and hence C.
For computational convenience, steps 2 and 3, and likewise steps 6 and 7, are combined so that the formation of Ax and Ay and the reductions to triangular form are carried out one row at a time.

Evaluation of Computed Spline

The values of the computed spline at the points xk,yk, for k=1,2,…,m, may be obtained in the real array ff (see e02de), of length at least m, by the following call: where M=m and the coordinates xk, yk are stored in X k, Y k. PX and PY, LAMDA, MU and C have the same values as px and py lamda, mu and c output from e01da. WRK is a real workspace array of length at least PY, and IWRK is an integer workspace array of length at least PY-4. (See e02de.)
To evaluate the computed spline on an mx by my rectangular grid of points in the x-y plane, which is defined by the x coordinates stored in X j, for j=1,2,…,mx, and the y coordinates stored in Y k, for k=1,2,…,my, returning the results in the real array ff (see e02df) which is of length at least mx×my, the following call may be used: where MX=mx, MY=my. PX and PY, LAMDA, MU and C have the same values as px, py, lamda, mu and c output from e01da. WRK is a real workspace array of length at least LWRK=min nwrk1,nwrk2, for nwrk1=MX×4+PX, nwrk2=MY×4+PY, and IWRK is an integer workspace array of length at least LIWRK=MY+PY-4 if nwrk1>nwrk2, or MX+PX-4 otherwise.
The result of the spline evaluated at grid point j,k is returned in element (MY×j-1+k-1) of the array FG.

Example

This example reads in values of mx, xq, for q=1,2,…,mx, my and yr, for r=1,2,…,my, followed by values of the ordinates f q,r defined at the grid points xq,yr.
It then calls e01da to compute a bicubic spline interpolant of the data values, and prints the values of the knots and B-spline coefficients. Finally it evaluates the spline at a small sample of points on a rectangular grid.

Example program (C#): e01dae.cs

Example program data: e01dae.d

Example program results: e01dae.r

See Also

E01 Class
E01 Members


E02 Class

[image]

NAG Library for .NET Release 2
E02 Class
Members See Also Send Feedback
The main aim of this chapter is to assist you in finding a function which approximates a set of data points. Typically the data contain random errors, as of experimental measurement, which need to be smoothed out. To seek an approximation to the data, it is first necessary to specify for the approximating function a mathematical form (a polynomial, for example) which contains a number of unspecified coefficients: the appropriate fitting method then derives for the coefficients the values which provide the best fit of that particular form. The chapter deals mainly with curve and surface fitting (i.e., fitting with functions of one and of two variables) when a polynomial or a cubic spline is used as the fitting function, since these cover the most common needs. However, fitting with other functions and/or more variables can be undertaken by means of general linear or nonlinear methods (some of which are contained in other chapters) depending on whether the coefficients in the function occur linearly or nonlinearly. Cases where a graph rather than a set of data points is given can be treated simply by first reading a suitable set of points from the graph.
The chapter also contains methods for evaluating, differentiating and integrating polynomial and spline curves and surfaces, once the numerical values of their coefficients have been determined.
There is, too, a method for computing a Padé approximant of a mathematical function (see [Padé Approximants] and [Padé Approximants]).

Syntax

C#
public static class E02
Visual Basic
Public NotInheritable Class E02
Visual C++
public ref class E02 abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type E02 =  class end

Background to the Problems

Preliminary Considerations

In the curve-fitting problems considered in this chapter, we have a dependent variable y and an independent variable x, and we are given a set of data points xr,yr, for r=1,2,…,m. The preliminary matters to be considered in this section will, for simplicity, be discussed in this context of curve-fitting problems. In fact, however, these considerations apply equally well to surface and higher-dimensional problems. Indeed, the discussion presented carries over essentially as it stands if, for these cases, we interpret x as a vector of several independent variables and correspondingly each xr as a vector containing the rth data value of each independent variable.
We wish, then, to approximate the set of data points as closely as possible with a specified function, f x say, which is as smooth as possible: f x may, for example, be a polynomial. The requirements of smoothness and closeness conflict, however, and a balance has to be struck between them. Most often, the smoothness requirement is met simply by limiting the number of coefficients allowed in the fitting function – for example, by restricting the degree in the case of a polynomial. Given a particular number of coefficients in the function in question, the fitting methods of this chapter determine the values of the coefficients such that the ‘distance’ of the function from the data points is as small as possible. The necessary balance is struck when you compare a selection of such fits having different numbers of coefficients. If the number of coefficients is too low, the approximation to the data will be poor. If the number is too high, the fit will be too close to the data, essentially following the random errors and tending to have unwanted fluctuations between the data points. Between these extremes, there is often a group of fits all similarly close to the data points and then, particularly when least squares polynomials are used, the choice is clear: it is the fit from this group having the smallest number of coefficients.
You are in effect minimizing the smoothness measure (i.e., the number of coefficients) subject to the distance from the data points being acceptably small. Some of the methods, however, do this task themselves. They use a different measure of smoothness (in each case one that is continuous) and minimize it subject to the distance being less than a threshold specified by you. This is a much more automatic process, requiring only some experimentation with the threshold.

Fitting criteria: norms

A measure of the above ‘distance’ between the set of data points and the function f x is needed. The distance from a single data point xr,yr to the function can simply be taken as
εr=yr-f xr, (1)
and is called the residual of the point. (With this definition, the residual is regarded as a function of the coefficients contained in f x; however, the term is also used to mean the particular value of εr which corresponds to the fitted values of the coefficients.) However, we need a measure of distance for the set of data points as a whole. Three different measures are used in the different methods (which measure to select, according to circumstances, is discussed later in this sub-section). With εr defined in (1), these measures, or norms, are
∑r=1 m εr, (2)
∑r=1 m εr 2, (3)
and
maxr εr, (4)
respectively the ℓ 1 norm, the ℓ 2 norm and the ℓ∞ norm.
Minimization of one or other of these norms usually provides the fitting criterion, the minimization being carried out with respect to the coefficients in the mathematical form used for f x: with respect to the bi for example if the mathematical form is the power series in (8) below. The fit which results from minimizing (2) is known as the ℓ 1 fit, or the fit in the ℓ 1 norm: that which results from minimizing (3) is the ℓ 2 fit, the well-known least squares fit (minimizing (3) is equivalent to minimizing the square of (3), i.e., the sum of squares of residuals, and it is the latter which is used in practice), and that from minimizing (4) is the ℓ∞, or minimax, fit.
Strictly speaking, implicit in the use of the above norms are the statistical assumptions that the random errors in the yr are independent of one another and that any errors in the xr are negligible by comparison. From this point of view, the use of the ℓ 2 norm is appropriate when the random errors in the yr have a Normal distribution, and the ℓ∞ norm is appropriate when they have a rectangular distribution, as when fitting a table of values rounded to a fixed number of decimal places. The ℓ 1 norm is appropriate when the error distribution has its frequency function proportional to the negative exponential of the modulus of the normalized error – not a common situation.
However, it may be that you are indifferent to these statistical considerations, and simply seek a fit which can be assessed by inspection, perhaps visually from a graph of the results. In this event, the ℓ 1 norm is particularly appropriate when the data are thought to contain some ‘wild’ points (since fitting in this norm tends to be unaffected by the presence of a small number of such points), though of course in simple situations you may prefer to identify and reject these points. The ℓ∞ norm should be used only when the maximum residual is of particular concern, as may be the case for example when the data values have been obtained by accurate computation, as of a mathematical function. Generally, however, a method based on least squares should be preferred, as being computationally faster and usually providing more information on which to assess the results. In many problems the three fits will not differ significantly for practical purposes.
Some of the methods based on the ℓ 2 norm do not minimize the norm itself but instead minimize some (intuitively acceptable) measure of smoothness subject to the norm being less than a user-specified threshold. These methods fit with cubic or bicubic splines (see (10) and (14) below) and the smoothing measures relate to the size of the discontinuities in their third derivatives. A much more automatic fitting procedure follows from this approach.

Weighting of data points

The use of the above norms also assumes that the data values yr are of equal (absolute) accuracy. Some of the methods enable an allowance to be made to take account of differing accuracies. The allowance takes the form of ‘weights’ applied to the y values so that those values known to be more accurate have a greater influence on the fit than others. These weights, to be supplied by you, should be calculated from estimates of the absolute accuracies of the y values, these estimates being expressed as standard deviations, probable errors or some other measure which has the same dimensions as y. Specifically, for each yr the corresponding weight wr should be inversely proportional to the accuracy estimate of yr. For example, if the percentage accuracy is the same for all yr, then the absolute accuracy of yr is proportional to yr (assuming yr to be positive, as it usually is in such cases) and so wr=K/yr, for r=1,2,…,m, for an arbitrary positive constant K. (This definition of weight is stressed because often weight is defined as the square of that used here.) The norms (2), (3) and (4) above are then replaced respectively by
∑r=1 m wrεr, (5)
∑r=1 m wr 2εr 2, (6)
and
maxr wrεr. (7)
Again it is the square of (6) which is used in practice rather than (6) itself.

Curve Fitting

When, as is commonly the case, the mathematical form of the fitting function is immaterial to the problem, polynomials and cubic splines are to be preferred because their simplicity and ease of handling confer substantial benefits. The cubic spline is the more versatile of the two. It consists of a number of cubic polynomial segments joined end to end with continuity in first and second derivatives at the joins. The third derivative at the joins is in general discontinuous. The x values of the joins are called knots, or, more precisely, interior knots. Their number determines the number of coefficients in the spline, just as the degree determines the number of coefficients in a polynomial.

Representation of polynomials

Two different forms for representing a polynomial are used in different methods. One is the usual power-series form
f x≡b 0+b 1 x+b 2 x 2+⋯+bk xk. (8)
The other is the Chebyshev series form
f x≡12 a 0T 0 x+a 1T 1 x+a 2T 2 x+⋯+akTk x, (9)
where Ti x is the Chebyshev polynomial of the first kind of degree i (see page 9 of Cox and Hayes (1973)), and where the range of x has been normalized to run from -1 to +1. The use of either form leads theoretically to the same fitted polynomial, but in practice results may differ substantially because of the effects of rounding error. The Chebyshev form is to be preferred, since it leads to much better accuracy in general, both in the computation of the coefficients and in the subsequent evaluation of the fitted polynomial at specified points. This form also has other advantages: for example, since the later terms in (9) generally decrease much more rapidly from left to right than do those in (8), the situation is more often encountered where the last terms are negligible and it is obvious that the degree of the polynomial can be reduced (note that on the interval -1≤x≤1 for all i, Ti x attains the value unity but never exceeds it, so that the coefficient ai gives directly the maximum value of the term containing it). If the power-series form is used it is most advisable to work with the variable x normalized to the range -1 to +1, carrying out the normalization before entering the relevant method. This will often substantially improve computational accuracy.

Representation of cubic splines

A cubic spline is represented in the form
f x≡c 1N 1 x+c 2N 2 x+⋯+cpNp x, (10)
where Ni x, for i=1,2,…,p, is a normalized cubic B-spline (see Hayes (1974)). This form, also, has advantages of computational speed and accuracy over alternative representations.

Surface Fitting

There are now two independent variables, and we shall denote these by x and y. The dependent variable, which was denoted by y in the curve-fitting case, will now be denoted by f. (This is a rather different notation from that indicated for the general-dimensional problem in the first paragraph of [Preliminary Considerations], but it has some advantages in presentation.)
Again, in the absence of contrary indications in the particular application being considered, polynomials and splines are the approximating functions most commonly used.

Representation of bivariate polynomials

The type of bivariate polynomial currently considered in the chapter can be represented in either of the two forms
f x,y≡∑i=0 k∑j=0 ℓ b ij xiyj, (11)
and
f x,y≡∑′i=0 k∑′j=0 ℓ a ijTi x Tj y, (12)
where Ti x is the Chebyshev polynomial of the first kind of degree i in the argument x (see page 9 of Cox and Hayes (1973)), and correspondingly for Tj y. The prime on the two summation signs, following standard convention, indicates that the first term in each sum is halved, as shown for one variable in equation (9). The two forms (11) and (12) are mathematically equivalent, but again the Chebyshev form is to be preferred on numerical grounds, as discussed in [Representation of polynomials].

Bicubic splines: definition and representation

The bicubic spline is defined over a rectangle R in the x,y plane, the sides of R being parallel to the x and y axes. R is divided into rectangular panels, again by lines parallel to the axes. Over each panel the bicubic spline is a bicubic polynomial, that is it takes the form
∑i=0 3∑j=0 3 a ij xiyj. (13)
Each of these polynomials joins the polynomials in adjacent panels with continuity up to the second derivative. The constant x values of the dividing lines parallel to the y-axis form the set of interior knots for the variable x, corresponding precisely to the set of interior knots of a cubic spline. Similarly, the constant y values of dividing lines parallel to the x-axis form the set of interior knots for the variable y. Instead of representing the bicubic spline in terms of the above set of bicubic polynomials, however, it is represented, for the sake of computational speed and accuracy, in the form
f x,y=∑i=1 p∑j=1 q c ijMi x Nj y, (14)
where Mi x, for i=1,2,…,p, and Nj y, for j=1,2,…,q, are normalized B-splines (see Hayes and Halliday (1974) for further details of bicubic splines and Hayes (1974) for normalized B-splines).

General Linear and Nonlinear Fitting Functions

We have indicated earlier that, unless the data-fitting application under consideration specifically requires some other type of fit, a polynomial or a spline is usually to be preferred. Special methods for these types, in one and in two variables, are provided in this chapter. When the application does specify some other form of fitting, however, it may be treated by a method which deals with a general linear function, or by one for a general nonlinear function, depending on whether the coefficients occur linearly or nonlinearly.
The general linear fitting function can be written in the form
f x≡c 1ϕ 1 x+c 2ϕ 2 x+⋯+cpϕp x, (15)
where x is a vector of one or more independent variables, and the ϕi are any given functions of these variables (though they must be linearly independent of one another if there is to be the possibility of a unique solution to the fitting problem). This is not intended to imply that each ϕi is necessarily a function of all the variables: we may have, for example, that each ϕi is a function of a different single variable, and even that one of the ϕi is a constant. All that is required is that a value of each ϕi x can be computed when a value of each independent variable is given.
When the fitting function f x is not linear in its coefficients, no more specific representation is available in general than f x itself. However, we shall find it helpful later on to indicate the fact that f x contains a number of coefficients (to be determined by the fitting process) by using instead the notation f x;c, where c denotes the vector of coefficients. An example of a nonlinear fitting function is
f x;c≡c 1+c 2 exp-c 4 x+c 3 exp-c 5 x, (16)
which is in one variable and contains five coefficients. Note that here, as elsewhere in this Chapter Introduction, we use the term ‘coefficients’ to include all the quantities whose values are to be determined by the fitting process, not just those which occur linearly. We may observe that it is only the presence of the coefficients c 4 and c 5 which makes the form (16) nonlinear. If the values of these two coefficients were known beforehand, (16) would instead be a linear function which, in terms of the general linear form (15), has p=3 and
ϕ 1 x≡1,ϕ 2 x≡exp-c 4 x,and ​ϕ 3 x≡exp-c 5 x.
We may note also that polynomials and splines, such as (9) and (14), are themselves linear in their coefficients. Thus if, when fitting with these functions, a suitable special method is not available (as when more than two independent variables are involved or when fitting in the ℓ 1 norm), it is appropriate to use a method designed for a general linear function.

Constrained Problems

So far, we have considered only fitting processes in which the values of the coefficients in the fitting function are determined by an unconstrained minimization of a particular norm. Some fitting problems, however, require that further restrictions be placed on the determination of the coefficient values. Sometimes these restrictions are contained explicitly in the formulation of the problem in the form of equalities or inequalities which the coefficients, or some function of them, must satisfy. For example, if the fitting function contains a term A exp-kx, it may be required that k≥0. Often, however, the equality or inequality constraints relate to the value of the fitting function or its derivatives at specified values of the independent variable(s), but these too can be expressed in terms of the coefficients of the fitting function, and it is appropriate to do this if a general linear or nonlinear method is being used. For example, if the fitting function is that given in (10), the requirement that the first derivative of the function at x=x 0 be non-negative can be expressed as
c 1 N 1′x 0+c 2 N 2′x 0+⋯+cp Np′x 0≥0, (17)
where the prime denotes differentiation with respect to x and each derivative is evaluated at x=x 0. On the other hand, if the requirement had been that the derivative at x=x 0 be exactly zero, the inequality sign in (17) would be replaced by an equality.

Padé Approximants

A Padé approximant to a function f x is a rational function (ratio of two polynomials) whose Maclaurin series expansion is the same as that of f x up to and including the term in xk, where k is the sum of the degrees of the numerator and denominator of the approximant. Padé approximation can be a useful technique when values of a function are to be obtained from its Maclaurin series but convergence of the series is unacceptably slow or even nonexistent.

References

Baker G A (1975) Essentials of Padé Approximants Academic Press, New York
Cox M G and Hayes J G (1973) Curve fitting: a guide and suite of algorithms for the non-specialist user NPL Report NAC26 National Physical Laboratory
Hayes J G (ed.) (1970) Numerical Approximation to Functions and Data Athlone Press, London
Hayes J G (1974) Numerical methods for curve and surface fitting Bull. Inst. Math. Appl. 10 144–152
Hayes J G and Halliday J (1974) The least squares fitting of cubic spline surfaces to general data sets J. Inst. Math. Appl. 14 89–103

Inheritance Hierarchy

System..::..Object
NagLibrary..::..E02

See Also

E02 Members


E02 Members

[image] [image]

NAG Library for .NET Release 2
E02 Members
E02 Class Methods See Also Send Feedback

The E02 type exposes the following members.

Methods

Name | Description
e02bb | e02bb evaluates a cubic spline from its B-spline representation.
e02de | e02de calculates values of a bicubic spline from its B-spline representation.
e02df | e02df calculates values of a bicubic spline from its B-spline representation. The spline is evaluated at all points on a rectangular grid.

See Also

E02 Class


E02 Methods

[image] [image]

NAG Library for .NET Release 2
E02 Methods
E02 Class See Also Send Feedback

The E02 type exposes the following members.

Methods

Name | Description
e02bb | e02bb evaluates a cubic spline from its B-spline representation.
e02de | e02de calculates values of a bicubic spline from its B-spline representation.
e02df | e02df calculates values of a bicubic spline from its B-spline representation. The spline is evaluated at all points on a rectangular grid.

See Also

E02 Class


e02bb Method

[image]

NAG Library for .NET Release 2
E02..::e02bb Method
E02 Class See Also Send Feedback
e02bb evaluates a cubic spline from its B-spline representation.

Syntax

C#
public static void e02bb(
    int ncap7,
    double[] lamda,
    double[] c,
    double x,
    out double s,
    out int ifail
)
Visual Basic
Public Shared Sub e02bb ( _
    ncap7 As Integer, _
    lamda As Double(), _
    c As Double(), _
    x As Double, _
    <OutAttribute> ByRef s As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e02bb(
    int ncap7,
    array<double>^ lamda,
    array<double>^ c,
    double x,
    [OutAttribute] double% s,
    [OutAttribute] int% ifail
)
F#
static member e02bb :
        ncap7 : int *
        lamda : float[] *
        c : float[] *
        x : float *
        s : float byref *
        ifail : int byref -> unit

Parameters

ncap7
Type: System..::..Int32
On entry: n-+7, where n- is the number of intervals (one greater than the number of interior knots, i.e., the knots strictly within the range λ 4 to λ n-+4) over which the spline is defined.
Constraint: ncap7≥8.
lamda
Type: array< System..::..Double >[]()[][]
An array of size [ncap7]
On entry: lamda[j-1] must be set to the value of the jth member of the complete set of knots, λj, for j=1,2,…,n-+7.
Constraint: the lamda[j-1] must be in nondecreasing order with lamda[ncap7-4]>lamda[3].
c
Type: array< System..::..Double >[]()[][]
An array of size [ncap7]
On entry: the coefficient ci of the B-spline Ni x, for i=1,2,…,n-+3. The remaining elements of the array are not referenced.
x
Type: System..::..Double
On entry: the argument x at which the cubic spline is to be evaluated.
Constraint: lamda[3]≤x≤lamda[ncap7-4].
s
Type: System..::..Double %
On exit: the value of the spline, s x.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e02bb evaluates the cubic spline s x at a prescribed argument x from its augmented knot set λi, for i=1,2,…,n+7, (see (E02BAF not in this release)) and from the coefficients ci, for i=1,2,…,qin its B-spline representation
s x=∑i=1 q ciNi x.
Here q=n-+3, where n- is the number of intervals of the spline, and Ni x denotes the normalized B-spline of degree 3 defined upon the knots λi,λ i+1,…,λ i+4. The prescribed argument x must satisfy λ 4≤x≤λ n-+4.
It is assumed that λj≥λ j-1, for j=2,3,…,n-+7, and λ n-+4>λ 4.
If x is a point at which 4 knots coincide, s x is discontinuous at x; in this case, s contains the value defined as x is approached from the right.
The method employed is that of evaluation by taking convex combinations due to de Boor (1972). For further details of the algorithm and its use see Cox (1972) and Cox and Hayes (1973).
It is expected that a common use of e02bb will be the evaluation of the cubic spline approximations produced by (E02BAF not in this release). A generalization of e02bb which also forms the derivative of s x is (E02BCF not in this release). (E02BCF not in this release) takes about 50% longer than e02bb.

References

Cox M G (1972) The numerical evaluation of B-splines J. Inst. Math. Appl. 10 134–149
Cox M G (1978) The numerical evaluation of a spline from its B-spline representation J. Inst. Math. Appl. 21 135–143
Cox M G and Hayes J G (1973) Curve fitting: a guide and suite of algorithms for the non-specialist user NPL Report NAC26 National Physical Laboratory
de Boor C (1972) On calculating with B-splines J. Approx. Theory 6 50–62

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
The parameter x does not satisfy lamda[3]≤x≤lamda[ncap7-4].
In this case the value of s is set arbitrarily to zero.
ifail=2
ncap7<8, i.e., the number of interior knots is negative.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The computed value of s x has negligible error in most practical situations. Specifically, this value has an absolute error bounded in modulus by 18×cmax×machine precision, where cmax is the largest in modulus of cj,c j+1,c j+2 and c j+3, and j is an integer such that λ j+3≤x≤λ j+4. If cj,c j+1,c j+2 and c j+3 are all of the same sign, then the computed value of s x has a relative error not exceeding 20×machine precision in modulus. For further details see Cox (1978).

Parallelism and Performance

None.

Further Comments

The time taken is approximately c×1+0.1×log n-+7 seconds, where c is a machine-dependent constant.
Note: the method does not test all the conditions on the knots given in the description of lamda in [Parameters], since to do this would result in a computation time approximately linear in n-+7 instead of log n-+7. All the conditions are tested in (E02BAF not in this release), however.

Example

Evaluate at nine equally-spaced points in the interval 1.0≤x≤9.0 the cubic spline with (augmented) knots 1.0, 1.0, 1.0, 1.0, 3.0, 6.0, 8.0, 9.0, 9.0, 9.0, 9.0 and normalized cubic B-spline coefficients 1.0, 2.0, 4.0, 7.0, 6.0, 4.0, 3.0.
The example program is written in a general form that will enable a cubic spline with n- intervals, in its normalized cubic B-spline form, to be evaluated at m equally-spaced points in the interval lamda[3]≤x≤lamda[n-+3]. The program is self-starting in that any number of datasets may be supplied.

Example program (C#): e02bbe.cs

Example program data: e02bbe.d

Example program results: e02bbe.r

See Also

E02 Class
E02 Members


e02de Method

[image]

NAG Library for .NET Release 2
E02..::e02de Method
E02 Class See Also Send Feedback
e02de calculates values of a bicubic spline from its B-spline representation.

Syntax

C#
public static void e02de(
    int m,
    int px,
    int py,
    double[] x,
    double[] y,
    double[] lamda,
    double[] mu,
    double[] c,
    double[] ff,
    out int ifail
)
Visual Basic
Public Shared Sub e02de ( _
    m As Integer, _
    px As Integer, _
    py As Integer, _
    x As Double(), _
    y As Double(), _
    lamda As Double(), _
    mu As Double(), _
    c As Double(), _
    ff As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e02de(
    int m,
    int px,
    int py,
    array<double>^ x,
    array<double>^ y,
    array<double>^ lamda,
    array<double>^ mu,
    array<double>^ c,
    array<double>^ ff,
    [OutAttribute] int% ifail
)
F#
static member e02de :
        m : int *
        px : int *
        py : int *
        x : float[] *
        y : float[] *
        lamda : float[] *
        mu : float[] *
        c : float[] *
        ff : float[] *
        ifail : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: m, the number of points at which values of the spline are required.
Constraint: m≥1.
px
Type: System..::..Int32
On entry: px and py must specify the total number of knots associated with the variables x and y respectively. They are such that px-8 and py-8 are the corresponding numbers of interior knots.
Constraint: px≥8 and py≥8.
py
Type: System..::..Int32
On entry: px and py must specify the total number of knots associated with the variables x and y respectively. They are such that px-8 and py-8 are the corresponding numbers of interior knots.
Constraint: px≥8 and py≥8.
x
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: x and y must contain xr and yr, for r=1,2,…,m, respectively. These are the coordinates of the points at which values of the spline are required. The order of the points is immaterial.
Constraint: x and y must satisfy
lamda[3]≤x[r-1]≤lamda[px-4]
and
mu[3]≤y[r-1]≤mu[py-4],  r=1,2,…,m.
.
The spline representation is not valid outside these intervals.
y
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: x and y must contain xr and yr, for r=1,2,…,m, respectively. These are the coordinates of the points at which values of the spline are required. The order of the points is immaterial.
Constraint: x and y must satisfy
lamda[3]≤x[r-1]≤lamda[px-4]
and
mu[3]≤y[r-1]≤mu[py-4],  r=1,2,…,m.
.
The spline representation is not valid outside these intervals.
lamda
Type: array< System..::..Double >[]()[][]
An array of size [px]
On entry: lamda and mu must contain the complete sets of knots λ and μ associated with the x and y variables respectively.
Constraint: the knots in each set must be in nondecreasing order, with lamda[px-4]>lamda[3] and mu[py-4]>mu[3].
mu
Type: array< System..::..Double >[]()[][]
An array of size [px]
On entry: lamda and mu must contain the complete sets of knots λ and μ associated with the x and y variables respectively.
Constraint: the knots in each set must be in nondecreasing order, with lamda[px-4]>lamda[3] and mu[py-4]>mu[3].
c
Type: array< System..::..Double >[]()[][]
An array of size [px-4×py-4]
On entry: c[py-4×i-1+j-1] must contain the coefficient c ij described in [Description], for i=1,2,…,px-4 and j=1,2,…,py-4.
ff
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: ff[r-1] contains the value of the spline at the point xr,yr, for r=1,2,…,m.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e02de calculates values of the bicubic spline s x,y at prescribed points xr,yr, for r=1,2,…,m, from its augmented knot sets λ and μ and from the coefficients c ij, for i=1,2,…,px-4 and j=1,2,…,py-4, in its B-spline representation
s x,y=∑ij c ijMi x Nj y.
Here Mi x and Nj y denote normalized cubic B-splines, the former defined on the knots λi to λ i+4 and the latter on the knots μj to μ j+4.
This method may be used to calculate values of a bicubic spline given in the form produced by e01da (E02DAF not in this release) (E02DCF not in this release) (E02DDF not in this release). It is derived from the method B2VRE in Anthony et al. (1982).

References

Anthony G T, Cox M G and Hayes J G (1982) DASL – Data Approximation Subroutine Library National Physical Laboratory
Cox M G (1978) The numerical evaluation of a spline from its B-spline representation J. Inst. Math. Appl. 21 135–143

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | m<1,
or | py<8,
or | px<8.
ifail=2
On entry, the knots in array lamda, or those in array mu, are not in nondecreasing order, or lamda[px-4]≤lamda[3], or mu[py-4]≤mu[3].
ifail=3
On entry, at least one of the prescribed points xr,yr lies outside the rectangle defined by lamda[3], lamda[px-4] and mu[3], mu[py-4].
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The method used to evaluate the B-splines is numerically stable, in the sense that each computed value of s xr,yr can be regarded as the value that would have been obtained in exact arithmetic from slightly perturbed B-spline coefficients. See Cox (1978) for details.

Parallelism and Performance

None.

Further Comments

Computation time is approximately proportional to the number of points, m, at which the evaluation is required.

Example

This program reads in knot sets lamda[0],…,lamda[px-1] and mu[0],…,mu[py-1], and a set of bicubic spline coefficients c ij. Following these are a value for m and the coordinates xr,yr, for r=1,2,…,m, at which the spline is to be evaluated.

Example program (C#): e02dee.cs

Example program data: e02dee.d

Example program results: e02dee.r

See Also

E02 Class
E02 Members


e02df Method

[image]

NAG Library for .NET Release 2
E02..::e02df Method
E02 Class See Also Send Feedback
e02df calculates values of a bicubic spline from its B-spline representation. The spline is evaluated at all points on a rectangular grid.

Syntax

C#
public static void e02df(
    int mx,
    int my,
    int px,
    int py,
    double[] x,
    double[] y,
    double[] lamda,
    double[] mu,
    double[] c,
    double[] ff,
    out int ifail
)
Visual Basic
Public Shared Sub e02df ( _
    mx As Integer, _
    my As Integer, _
    px As Integer, _
    py As Integer, _
    x As Double(), _
    y As Double(), _
    lamda As Double(), _
    mu As Double(), _
    c As Double(), _
    ff As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e02df(
    int mx,
    int my,
    int px,
    int py,
    array<double>^ x,
    array<double>^ y,
    array<double>^ lamda,
    array<double>^ mu,
    array<double>^ c,
    array<double>^ ff,
    [OutAttribute] int% ifail
)
F#
static member e02df :
        mx : int *
        my : int *
        px : int *
        py : int *
        x : float[] *
        y : float[] *
        lamda : float[] *
        mu : float[] *
        c : float[] *
        ff : float[] *
        ifail : int byref -> unit

Parameters

mx
Type: System..::..Int32
On entry: mx and my must specify mx and my respectively, the number of points along the x and y axis that define the rectangular grid.
Constraint: mx≥1 and my≥1.
my
Type: System..::..Int32
On entry: mx and my must specify mx and my respectively, the number of points along the x and y axis that define the rectangular grid.
Constraint: mx≥1 and my≥1.
px
Type: System..::..Int32
On entry: px and py must specify the total number of knots associated with the variables x and y respectively. They are such that px-8 and py-8 are the corresponding numbers of interior knots.
Constraint: px≥8 and py≥8.
py
Type: System..::..Int32
On entry: px and py must specify the total number of knots associated with the variables x and y respectively. They are such that px-8 and py-8 are the corresponding numbers of interior knots.
Constraint: px≥8 and py≥8.
x
Type: array< System..::..Double >[]()[][]
An array of size [mx]
On entry: x and y must contain xq, for q=1,2,…,mx, and yr, for r=1,2,…,my, respectively. These are the x and y coordinates that define the rectangular grid of points at which values of the spline are required.
Constraint: x and y must satisfy
lamda[3]≤x[q-1]<x[q]≤lamda[px-4],  q=1,2,…,mx-1
and
mu[3]≤y[r-1]<y[r]≤mu[py-4],  r=1,2,…,my-1.
.
The spline representation is not valid outside these intervals.
y
Type: array< System..::..Double >[]()[][]
An array of size [mx]
On entry: x and y must contain xq, for q=1,2,…,mx, and yr, for r=1,2,…,my, respectively. These are the x and y coordinates that define the rectangular grid of points at which values of the spline are required.
Constraint: x and y must satisfy
lamda[3]≤x[q-1]<x[q]≤lamda[px-4],  q=1,2,…,mx-1
and
mu[3]≤y[r-1]<y[r]≤mu[py-4],  r=1,2,…,my-1.
.
The spline representation is not valid outside these intervals.
lamda
Type: array< System..::..Double >[]()[][]
An array of size [px]
On entry: lamda and mu must contain the complete sets of knots λ and μ associated with the x and y variables respectively.
Constraint: the knots in each set must be in nondecreasing order, with lamda[px-4]>lamda[3] and mu[py-4]>mu[3].
mu
Type: array< System..::..Double >[]()[][]
An array of size [px]
On entry: lamda and mu must contain the complete sets of knots λ and μ associated with the x and y variables respectively.
Constraint: the knots in each set must be in nondecreasing order, with lamda[px-4]>lamda[3] and mu[py-4]>mu[3].
c
Type: array< System..::..Double >[]()[][]
An array of size [px-4×py-4]
On entry: c[py-4×i-1+j-1] must contain the coefficient c ij described in [Description], for i=1,2,…,px-4 and j=1,2,…,py-4.
ff
Type: array< System..::..Double >[]()[][]
An array of size [mx×my]
On exit: ff[my×q-1+r-1] contains the value of the spline at the point xq,yr, for q=1,2,…,mx and r=1,2,…,my.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e02df calculates values of the bicubic spline s x,y on a rectangular grid of points in the x-y plane, from its augmented knot sets λ and μ and from the coefficients c ij, for i=1,2,…,px-4 and j=1,2,…,py-4, in its B-spline representation
s x,y=∑ij c ijMi x Nj y.
Here Mi x and Nj y denote normalized cubic B-splines, the former defined on the knots λi to λ i+4 and the latter on the knots μj to μ j+4.
The points in the grid are defined by coordinates xq, for q=1,2,…,mx, along the x axis, and coordinates yr, for r=1,2,…,my, along the y axis.
This method may be used to calculate values of a bicubic spline given in the form produced by e01da (E02DAF not in this release) (E02DCF not in this release) (E02DDF not in this release). It is derived from the method B2VRE in Anthony et al. (1982).

References

Anthony G T, Cox M G and Hayes J G (1982) DASL – Data Approximation Subroutine Library National Physical Laboratory
Cox M G (1978) The numerical evaluation of a spline from its B-spline representation J. Inst. Math. Appl. 21 135–143

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | mx<1,
or | my<1,
or | py<8,
or | px<8.
ifail=2
On entry, | lwrk is too small,
or | liwrk is too small.
ifail=3
On entry, the knots in array lamda, or those in array mu, are not in nondecreasing order, or lamda[px-4]≤lamda[3], or mu[py-4]≤mu[3].
ifail=4
On entry, the restriction lamda[3]≤x[0]<⋯<x[mx-1]≤lamda[px-4], or the restriction mu[3]≤y[0]<⋯<y[my-1]≤mu[py-4], is violated.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The method used to evaluate the B-splines is numerically stable, in the sense that each computed value of s xr,yr can be regarded as the value that would have been obtained in exact arithmetic from slightly perturbed B-spline coefficients. See Cox (1978) for details.

Parallelism and Performance

None.

Further Comments

Computation time is approximately proportional to mxmy+4 mx+my.

Example

This example reads in knot sets lamda[0],…,lamda[px-1] and mu[0],…,mu[py-1], and a set of bicubic spline coefficients c ij. Following these are values for mx and the x coordinates xq, for q=1,2,…,mx, and values for my and the y coordinates yr, for r=1,2,…,my, defining the grid of points on which the spline is to be evaluated.

Example program (C#): e02dfe.cs

Example program data: e02dfe.d

Example program results: e02dfe.r

See Also

E02 Class
E02 Members


E04 Class

[image]

NAG Library for .NET Release 2
E04 Class
Members See Also Send Feedback
An optimization problem involves minimizing a function (called the objective function) of several variables, possibly subject to restrictions on the values of the variables defined by a set of constraint functions. Most methods in the Library are concerned with function minimization only, since the problem of maximizing a given objective function F(x) is equivalent to minimizing -F x. Some methods allow you to specify whether you are solving a minimization or maximization problem, carrying out the required transformation of the objective function in the latter case.
In general methods in this chapter find a local minimum of a function f, that is a point x* s.t. for all x near x* f x≥f x*.
The E05 class contains methods to find the global minimum of a function f. At a global minimum x* f x≥f x* for all x.
The (H not in this release) contains methods typically regarded as belonging to the field of operations research.
This introduction is only a brief guide to the subject of optimization designed for the casual user. Anyone with a difficult or protracted problem to solve will find it beneficial to consult a more detailed text, such as Gill et al. (1981) or Fletcher (1987).
If you are unfamiliar with the mathematics of the subject you may find some sections difficult at first reading; if so, you should concentrate on [Types of Optimization Problems], [Geometric Representation and Terminology], [Scaling], [Analysis of Computed Results] and [Recommendations on Choice and Use of Available Methods].

Syntax

C#
public static class E04
Visual Basic
Public NotInheritable Class E04
Visual C++
public ref class E04 abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type E04 =  class end

Background to the Problems

Types of Optimization Problems

The solution of optimization problems by a single, all-purpose, method is cumbersome and inefficient. Optimization problems are therefore classified into particular categories, where each category is defined by the properties of the objective and constraint functions, as illustrated by some examples below.
Properties of Objective Function | Properties of Constraints
Nonlinear | Nonlinear
Sums of squares of nonlinear functions | Sparse linear
Quadratic | Linear
Sums of squares of linear functions | Bounds
Linear | None
For instance, a specific problem category involves the minimization of a nonlinear objective function subject to bounds on the variables. In the following sections we define the particular categories of problems that can be solved by methods contained in this chapter. Not every category is given special treatment in the current version of the Library; however, the long-term objective is to provide a comprehensive set of methods to solve problems in all such categories.

Unconstrained minimization

In unconstrained minimization problems there are no constraints on the variables. The problem can be stated mathematically as follows:
minimizex F x
where x∈Rn, that is, x=x 1,x 2,…,xn T.

Nonlinear least squares problems

Special consideration is given to the problem for which the function to be minimized can be expressed as a sum of squared functions. The least squares problem can be stated mathematically as follows:
minimizex fT f=∑i=1 m fi 2 x,  x∈Rn
where the ith element of the m-vector f is the function fi x.

Minimization subject to bounds on the variables

These problems differ from the unconstrained problem in that at least one of the variables is subject to a simple bound (or restriction) on its value, e.g., x 5≤10, but no constraints of a more general form are present.
The problem can be stated mathematically as follows:
minimizex F x,  x∈Rn
subject to li≤xi≤ui, for i=1,2,…,n.
This format assumes that upper and lower bounds exist on all the variables. By conceptually allowing ui=+∞ and li=-∞ all the variables need not be restricted.

Minimization subject to linear constraints

A general linear constraint is defined as a constraint function that is linear in more than one of the variables, e.g., 3 x 1+2 x 2≥4. The various types of linear constraint are reflected in the following mathematical statement of the problem:
minimizex F x,  x∈Rn
subject to the
equality constraints: | aiT x=bi | i=1,2,…,m 1;
inequality constraints: | aiT x≥bi | i=m 1+1,m 1+2,…,m 2;
 | aiT x≤bi | i=m 2+1,m 2+2,…,m 3;
range constraints: | sj≤aiT x≤tj | i=m 3+1,m 3+2,…,m 4;
 |  | j=1,2,…,m 4-m 3;
bounds constraints: | li≤xi≤ui | i=1,2,…,n
where each ai is a vector of length n; bi, sj and tj are constant scalars; and any of the categories may be empty.
Although the bounds on xi could be included in the definition of general linear constraints, we prefer to distinguish between them for reasons of computational efficiency.
If F x is a linear function, the linearly-constrained problem is termed a linear programming problem (LP); if F x is a quadratic function, the problem is termed a quadratic programming problem (QP). For further discussion of LP and QP problems, including the dual formulation of such problems, see Dantzig (1963).

Minimization subject to nonlinear constraints

A problem is included in this category if at least one constraint function is nonlinear, e.g., x 12+x 3+x 4-2≥0. The mathematical statement of the problem is identical to that for the linearly-constrained case, except for the addition of the following constraints:
equality constraints: | ci x=0 | i=1,2,…,m 5;
inequality constraints: | ci x≥0 | i=m 5+1,m 5+2,…,m 6;
range constraints: | vj≤ci x≤wj | i=m 6+1,m 6+2,…,m 7,
 |  | j=1,2,…,m 7-m 6
where each ci is a nonlinear function; vj and wj are constant scalars; and any category may be empty. Note that we do not include a separate category for constraints of the form ci x≤0, since this is equivalent to -ci x≥0.
Although the general linear constraints could be included in the definition of nonlinear constraints, again we prefer to distinguish between them for reasons of computational efficiency.
If F x is a nonlinear function, the nonlinearly-constrained problem is termed a nonlinear programming problem (NLP). For further discussion of NLP problems, see Gill et al. (1981) or Fletcher (1987).

Minimization subject to bounds on the objective function

In all of the above problem categories it is assumed that
a≤F x≤b
where a=-∞ and b=+∞. Problems in which a and/or b are finite can be solved by adding an extra constraint of the appropriate type (i.e., linear or nonlinear) depending on the form of F x. Further advice is given in [Function Evaluations at Infeasible Points].

Multi-objective optimization

Sometimes a problem may have two or more objective functions which are to be optimized at the same time. Such problems are called multi-object, multi-criteria or multi-attribute optimization. If the constraints are linear and the objectives are all linear then the terminology ‘goal programming’ is also used.
Techniques used in this chapter and in E05 class may be employed to address such problems.

Semidefinite Programming

Methods in E04 class can be used to solve linear semidefinite programming problems, that is, linear programming problems which include one or more linear matrix inequality constraints of the form
∑ i=1 n xiAi-A 0⪰0
where the expression S≥0 stands for a non-negativity constraint on the the eigenvalues of the symmetric matrix S, that is, S must be positive semidefinite. The chapter can also deal with problems involving bilinear matrix inequalities
∑ i,j=1 n xixjQ ij⪰0
or a linear matrix inequality constraint extended by bilinear terms.

Geometric Representation and Terminology

To illustrate the nature of optimization problems it is useful to consider the following example in two dimensions:
F x=e x 1 4 x 12+2 x 22+4 x 1x 2+2 x 2+1.
(This function is used as the example function in the documentation for the unconstrained methods.)
Figure 1
Figure 1 is a contour diagram of F x. The contours labelled F 0,F 1,…,F 4 are isovalue contours, or lines along which the function F x takes specific constant values. The point x*=12,-1 T is a local unconstrained minimum, that is, the value of F x* (=0) is less than at all the neighbouring points. A function may have several such minima. The lowest of the local minima is termed a global minimum. In the problem illustrated in Figure 1, x* is the only local minimum. The point xs is said to be a saddle point because it is a minimum along the line AB, but a maximum along CD.
If we add the constraint x 1≥0 (a simple bound) to the problem of minimizing F x, the solution remains unaltered. In Figure 1 this constraint is represented by the straight line passing through x 1=0, and the shading on the line indicates the unacceptable region (i.e., x 1<0). The region in Rn satisfying the constraints of an optimization problem is termed the feasible region. A point satisfying the constraints is defined as a feasible point.
If we add the nonlinear constraint c 1 x:x 1+x 2-x 1x 2-32≥0, represented by the curved shaded line in Figure 1, then x* is not a feasible point because c 1 x*<0. The solution of the new constrained problem is x b≃1.1825,-1.7397 T, the feasible point with the smallest function value (where F x b≃3.0607).

Gradient vector

The vector of first partial derivatives of F x is called the gradient vector, and is denoted by g x, i.e.,
g x=∂F x∂x 1,∂F x∂x 2,…,∂F x∂xn T.
For the function illustrated in Figure 1,
g x=F x+e x 1 8 x 1+4 x 2e x 1 4 x 2+4 x 1+2.
The gradient vector is of importance in optimization because it must be zero at an unconstrained minimum of any function with continuous first derivatives.

Hessian matrix

The matrix of second partial derivatives of a function is termed its Hessian matrix. The Hessian matrix of F x is denoted by G x, and its i,jth element is given by ∂2 F x/∂xi∂xj. If F x has continuous second derivatives, then G x must be positive definite at any unconstrained minimum of F.

Jacobian matrix; matrix of constraint normals

In nonlinear least squares problems, the matrix of first partial derivatives of the vector-valued function f x is termed the Jacobian matrix of f x and its i,jth component is ∂fi/∂xj.
The vector of first partial derivatives of the constraint ci x is denoted by
ai x=∂ci x∂x 1,∂ci x∂x 2,…,∂ci x∂xn T.
The matrix whose columns are the vectors ai is termed the matrix of constraint normals. At a point x^, the vector ai x^ is orthogonal (normal) to the isovalue contour of ci x passing through x^; this relationship is illustrated for a two-dimensional function in Figure 2.
Figure 2
Note that if ci x is a linear constraint involving aiT x, then its vector of first partial derivatives is simply the vector ai.

Sufficient Conditions for a Solution

All nonlinear functions will be assumed to have continuous second derivatives in the neighbourhood of the solution.

Unconstrained minimization

The following conditions are sufficient for the point x* to be an unconstrained local minimum of F x:
(i) | g x*=0; and
(ii) | G x* is positive definite,
where g denotes the Euclidean length of g.

Minimization subject to bounds on the variables

At the solution of a bounds-constrained problem, variables which are not on their bounds are termed free variables. If it is known in advance which variables are on their bounds at the solution, the problem can be solved as an unconstrained problem in just the free variables; thus, the sufficient conditions for a solution are similar to those for the unconstrained case, applied only to the free variables.
Sufficient conditions for a feasible point x* to be the solution of a bounds-constrained problem are as follows:
(i) | g-x*=0; and
(ii) | G-x* is positive definite; and
(iii) | gj x*<0,xj=uj; gj x*>0,xj=lj,
where g-x is the gradient of F x with respect to the free variables, and G-x is the Hessian matrix of F x with respect to the free variables. The extra condition (iii) ensures that F x cannot be reduced by moving off one or more of the bounds.

Linearly-constrained minimization

For the sake of simplicity, the following description does not include a specific treatment of bounds or range constraints, since the results for general linear inequality constraints can be applied directly to these cases.
At a solution x*, of a linearly-constrained problem, the constraints which hold as equalities are called the active or binding constraints. Assume that there are t active constraints at the solution x*, and let A^ denote the matrix whose columns are the columns of A corresponding to the active constraints, with b^ the vector similarly obtained from b; then
A^Tx*=b^.
The matrix Z is defined as an n×n-t matrix satisfying:
A^T Z=0;ZT Z=I.
The columns of Z form an orthogonal basis for the set of vectors orthogonal to the columns of A^.
Define
  • gZ x=ZT g x, the projected gradient vector of F x;
  • GZ x=ZT G x Z, the projected Hessian matrix of F x.
At the solution of a linearly-constrained problem, the projected gradient vector must be zero, which implies that the gradient vector g x* can be written as a linear combination of the columns of A^, i.e., g x*=∑i=1 t λi*a^i=A^λ*. The scalar λi* is defined as the Lagrange multiplier corresponding to the ith active constraint. A simple interpretation of the ith Lagrange multiplier is that it gives the gradient of F x along the ith active constraint normal; a convenient definition of the Lagrange multiplier vector (although not a recommended method for computation) is:
λ*=A^T A^-1A^T g x*.
Sufficient conditions for x* to be the solution of a linearly-constrained problem are:
(i) | x* is feasible, and A^Tx*=b^; and
(ii) | gZ x*=0, or equivalently, g x*=A^λ*; and
(iii) | GZ x* is positive definite; and
(iv) | λi*>0 if λi* corresponds to a constraint a^iT x*≥b^i; λi*<0 if λi* corresponds to a constraint a^iT x*≤b^i. The sign of λi* is immaterial for equality constraints, which by definition are always active.

Nonlinearly-constrained minimization

For nonlinearly-constrained problems, much of the terminology is defined exactly as in the linearly-constrained case. The set of active constraints at x again means the set of constraints that hold as equalities at x, with corresponding definitions of c^ and A^: the vector c^x contains the active constraint functions, and the columns of A^x are the gradient vectors of the active constraints. As before, Z is defined in terms of A^x as a matrix such that:
A^T Z=0;ZT Z=I
where the dependence on x has been suppressed for compactness.
The projected gradient vector gZ x is the vector ZT g x. At the solution x* of a nonlinearly-constrained problem, the projected gradient must be zero, which implies the existence of Lagrange multipliers corresponding to the active constraints, i.e., g x*=A^x*λ*.
The Lagrangian function is given by:
L x,λ=F x-λT c^x.
We define gL x as the gradient of the Lagrangian function; GL x as its Hessian matrix, and G^L x as its projected Hessian matrix, i.e., G^L=ZT GL Z.
Sufficient conditions for x* to be the solution of a nonlinearly-constrained problem are:
(i) | x* is feasible, and c^x*=0; and
(ii) | gZ x*=0, or, equivalently, g x*=A^x*λ*; and
(iii) | G^L x* is positive definite; and
(iv) | λi*>0 if λi* corresponds to a constraint of the form c^i≥0. The sign of λi* is immaterial for equality constraints, which by definition are always active.
Note that condition (ii) implies that the projected gradient of the Lagrangian function must also be zero at x*, since the application of ZT annihilates the matrix A^x*.

Background to Optimization Methods

All the algorithms contained in this chapter generate an iterative sequence x k that converges to the solution x* in the limit, except for some special problem categories (i.e., linear and quadratic programming). To terminate computation of the sequence, a convergence test is performed to determine whether the current estimate of the solution is an adequate approximation. The convergence tests are discussed in [Analysis of Computed Results].
Most of the methods construct a sequence x k satisfying:
x k+1=x k+α kp k,
where the vector p k is termed the direction of search, and α k is the steplength. The steplength α k is chosen so that F x k+1<F x k and is computed using one of the techniques for one-dimensional optimization referred to in [One-dimensional optimization].

One-dimensional optimization

The Library contains two special methods for minimizing a function of a single variable. Both methods are based on safeguarded polynomial approximation. One method requires function evaluations only and fits a quadratic polynomial whilst the other requires function and gradient evaluations and fits a cubic polynomial. See Section 4.1 of Gill et al. (1981).

Methods for unconstrained optimization

The distinctions among methods arise primarily from the need to use varying levels of information about derivatives of F x in defining the search direction. We describe three basic approaches to unconstrained problems, which may be extended to other problem categories. Since a full description of the methods would fill several volumes, the discussion here can do little more than allude to the processes involved, and direct you to other sources for a full explanation.
(a) Newton-type Methods (Modified Newton Methods)
Newton-type methods use the Hessian matrix G x k, or a finite difference approximation to G x k, to define the search direction. The methods in the Library either require a method that computes the elements of G x k directly, or they approximate G x k by finite differences.
Newton-type methods are the most powerful methods available for general problems and will find the minimum of a quadratic function in one iteration. See Sections 4.4 and 4.5.1 of Gill et al. (1981).
(b) Quasi-Newton Methods
Quasi-Newton methods approximate the Hessian G x k by a matrix B k which is modified at each iteration to include information obtained about the curvature of F along the current search direction p k. Although not as robust as Newton-type methods, quasi-Newton methods can be more efficient because G x k is not computed directly, or approximated by finite differences. Quasi-Newton methods minimize a quadratic function in n iterations, where n is the number of variables. See Section 4.5.2 of Gill et al. (1981).
(c) Conjugate-gradient Methods
Unlike Newton-type and quasi-Newton methods, conjugate-gradient methods do not require the storage of an n by n matrix and so are ideally suited to solve large problems. Conjugate-gradient type methods are not usually as reliable or efficient as Newton-type, or quasi-Newton methods. See Section 4.8.3 of Gill et al. (1981).

Methods for nonlinear least squares problems

These methods are similar to those for unconstrained optimization, but exploit the special structure of the Hessian matrix to give improved computational efficiency.
Since
F x=∑i=1 m fi 2 x
the Hessian matrix G x is of the form
G x=2 J x T J x+∑i=1 m fi x Gi x,
where J x is the Jacobian matrix of f x, and Gi x is the Hessian matrix of fi x.
In the neighbourhood of the solution, f x is often small compared to J x T J x (for example, when f x represents the goodness-of-fit of a nonlinear model to observed data). In such cases, 2 J x T J x may be an adequate approximation to G x, thereby avoiding the need to compute or approximate second derivatives of fi x. See Section 4.7 of Gill et al. (1981).

Methods for handling constraints

Bounds on the variables are dealt with by fixing some of the variables on their bounds and adjusting the remaining free variables to minimize the function. By examining estimates of the Lagrange multipliers it is possible to adjust the set of variables fixed on their bounds so that eventually the bounds active at the solution should be correctly identified. This type of method is called an active set method. One feature of such methods is that, given an initial feasible point, all approximations x k are feasible. This approach can be extended to general linear constraints. At a point, x, the set of constraints which hold as equalities being used to predict, or approximate, the set of active constraints is called the working set.
Nonlinear constraints are more difficult to handle. If at all possible, it is usually beneficial to avoid including nonlinear constraints during the formulation of the problem. The methods currently implemented in the Library handle nonlinearly constrained problems by transforming them into a sequence of quadratic programming problems. A feature of such methods is that x k is not guaranteed to be feasible except in the limit, and this is certainly true of the methods currently in the Library. See Chapter 6, particularly Sections 6.4 and 6.5, of Gill et al. (1981).
Anyone interested in a detailed description of methods for optimization should consult the references.

Methods for handling multi-objective optimization

Suppose we have objective functions fi x, i>1, all of which we need to minimize at the same time. There are two main approaches to this problem:
(a) Combine the individual objectives into one composite objective. Typically this might be a weighted sum of the objectives, e.g.,
w 1f 1 x+w 2f 2 x+⋯+wnfn x
Here you choose the weights to express the relative importance of the corresponding objective. Ideally each of the fi x should be of comparable size at a solution.
(b) Order the objectives in order of importance. Suppose fi are ordered such that fi x is more important than f i+1 x, for i=1,2,…,n-1. Then in the lexicographical approach to multi-objective optimization a sequence of subproblems are solved. Firstly solve the problem for objective function f 1 x and denote by r 1 the value of this minimum. If i-1 subproblems have been solved with results r i-1 then subproblem i becomes min fi x subject to rk≤fk x≤rk, for k=1,2,…,i-1 plus the other constraints.
Clearly the bounds on fk might be relaxed at your discretion.
In general, if NAG methods from the E04 class are used then only local minima are found. This means that a better solution to an individual objective might be found without worsening the optimal solutions to the other objectives. Ideally you seek a Pareto solution; one in which an improvement in one objective can only be achieved by a worsening of another objective.
To obtain a Pareto solution methods from E05 class might be used or, alternatively, a pragmatic attempt to derive a global minimum might be tried (see e05uc). In this approach a variety of different minima are computed for each subproblem by starting from a range of different starting points. The best solution achieved is taken to be the global minimum. The more starting points chosen the greater confidence you might have in the computed global minimum.

Scaling

Scaling (in a broadly defined sense) often has a significant influence on the performance of optimization methods. Since convergence tolerances and other criteria are necessarily based on an implicit definition of ‘small’ and ‘large’, problems with unusual or unbalanced scaling may cause difficulties for some algorithms. Although there are currently no user-callable scaling methods in the Library, scaling is automatically performed by default in the methods which solve sparse LP, QP or NLP problems and in some newer dense solver methods. The following sections present some general comments on problem scaling.

Transformation of variables

One method of scaling is to transform the variables from their original representation, which may reflect the physical nature of the problem, to variables that have certain desirable properties in terms of optimization. It is generally helpful for the following conditions to be satisfied:
(i) | the variables are all of similar magnitude in the region of interest;
(ii) | a fixed change in any of the variables results in similar changes in F x. Ideally, a unit change in any variable produces a unit change in F x;
(iii) | the variables are transformed so as to avoid cancellation error in the evaluation of F x.
Normally, you should restrict yourself to linear transformations of variables, although occasionally nonlinear transformations are possible. The most common such transformation (and often the most appropriate) is of the form
xnew=D xold,
where D is a diagonal matrix with constant coefficients. Our experience suggests that more use should be made of the transformation
xnew=D xold+v,
where v is a constant vector.
Consider, for example, a problem in which the variable x 3 represents the position of the peak of a Gaussian curve to be fitted to data for which the extreme values are 150 and 170; therefore x 3 is known to lie in the range 150–170. One possible scaling would be to define a new variable x-3, given by
x-3=x 3 170.
A better transformation, however, is given by defining x-3 as
x-3=x 3-160 10.
Frequently, an improvement in the accuracy of evaluation of F x can result if the variables are scaled before the methods to evaluate F x are coded. For instance, in the above problem just mentioned of Gaussian curve-fitting, x 3 may always occur in terms of the form x 3-xm, where xm is a constant representing the mean peak position.

Scaling the objective function

The objective function has already been mentioned in the discussion of scaling the variables. The solution of a given problem is unaltered if F x is multiplied by a positive constant, or if a constant value is added to F x. It is generally preferable for the objective function to be of the order of unity in the region of interest; thus, if in the original formulation F x is always of the order of 10+5 (say), then the value of F x should be multiplied by 10-5 when evaluating the function within an optimization method. If a constant is added or subtracted in the computation of F x, usually it should be omitted, i.e., it is better to formulate F x as x 12+x 22 rather than as x 12+x 22+1000 or even x 12+x 22+1. The inclusion of such a constant in the calculation of F x can result in a loss of significant figures.

Scaling the constraints

A ‘well scaled’ set of constraints has two main properties. Firstly, each constraint should be well-conditioned with respect to perturbations of the variables. Secondly, the constraints should be balanced with respect to each other, i.e., all the constraints should have ‘equal weight’ in the solution process.
The solution of a linearly- or nonlinearly-constrained problem is unaltered if the ith constraint is multiplied by a positive weight wi. At the approximation of the solution determined by a Library method, any active linear constraints will (in general) be satisfied ‘exactly’ (i.e., to within the tolerance defined by machine precision) if they have been properly scaled. This is in contrast to any active nonlinear constraints, which will not (in general) be satisfied ‘exactly’ but will have ‘small’ values (for example, c^1 x*=10-8, c^2 x*=-10-6, and so on). In general, this discrepancy will be minimized if the constraints are weighted so that a unit change in x produces a similar change in each constraint.
A second reason for introducing weights is related to the effect of the size of the constraints on the Lagrange multiplier estimates and, consequently, on the active set strategy. This means that different sets of weights may cause an algorithm to produce different sequences of iterates. Additional discussion is given in Gill et al. (1981).

Analysis of Computed Results

Convergence criteria

The convergence criteria inevitably vary from method to method, since in some cases more information is available to be checked (for example, is the Hessian matrix positive definite?), and different checks need to be made for different problem categories (for example, in constrained minimization it is necessary to verify whether a trial solution is feasible). Nonetheless, the underlying principles of the various criteria are the same; in non-mathematical terms, they are:
(i) | is the sequence x k converging?
(ii) | is the sequence F k converging?
(iii) | are the necessary and sufficient conditions for the solution satisfied?
The decision as to whether a sequence is converging is necessarily speculative. The criterion used in the present methods is to assume convergence if the relative change occurring between two successive iterations is less than some prescribed quantity. Criterion (iii) is the most reliable but often the conditions cannot be checked fully because not all the required information may be available.

Checking results

Little a priori guidance can be given as to the quality of the solution found by a nonlinear optimization algorithm, since no guarantees can be given that the methods will not fail. Therefore, you should always check the computed solution even if the method reports success. Frequently a ‘solution’ may have been found even when the method does not report a success. The reason for this apparent contradiction is that the method needs to assess the accuracy of the solution. This assessment is not an exact process and consequently may be unduly pessimistic. Any ‘solution’ is in general only an approximation to the exact solution, and it is possible that the accuracy you have specified is too stringent.
Further confirmation can be sought by trying to check whether or not convergence tests are almost satisfied, or whether or not some of the sufficient conditions are nearly satisfied. When it is thought that a method has returned a nonzero value of ifail only because the requirements for ‘success’ were too stringent it may be worth restarting with increased convergence tolerances.
For nonlinearly-constrained problems, check whether the solution returned is feasible, or nearly feasible; if not, the solution returned is not an adequate solution.
Confidence in a solution may be increased by resolving the problem with a different initial approximation to the solution. See Section 8.3 of Gill et al. (1981) for further information.

Monitoring progress

Many of the methods in the chapter have facilities to allow you to monitor the progress of the minimization process, and you are encouraged to make use of these facilities. Monitoring information can be a great aid in assessing whether or not a satisfactory solution has been obtained, and in indicating difficulties in the minimization problem or in the ability of the method to cope with the problem.
The behaviour of the function, the estimated solution and first derivatives can help in deciding whether a solution is acceptable and what to do in the event of a return with a nonzero value of ifail.

Confidence intervals for least squares solutions

When estimates of the parameters in a nonlinear least squares problem have been found, it may be necessary to estimate the variances of the parameters and the fitted function. These can be calculated from the Hessian of F x at the solution.
In many least squares problems, the Hessian is adequately approximated at the solution by G=2 JT J (see [Methods for nonlinear least squares problems]). The Jacobian, J, or a factorization of J is returned by all the comprehensive least squares methods and, in addition, a method is available in the Library to estimate variances of the parameters following the use of most of the nonlinear least squares methods, in the case that G=2 JT J is an adequate approximation.
Let H be the inverse of G, and S be the sum of squares, both calculated at the solution x-; an unbiased estimate of the variance of the ith parameter xi is
var x-i=2 Sm-n H ii
and an unbiased estimate of the covariance of x-i and x-j is
covar x-i,x-j=2 Sm-n H ij.
If x* is the true solution, then the 100 1-β% confidence interval on x- is
x-i-var x-i.t 1-β/2,m-n<xi*<x-i+var x-i.t 1-β/2,m-n,  i=1,2,…,n
where t 1-β/2,m-n is the 100 1-β/2 percentage point of the t-distribution with m-n degrees of freedom.
In the majority of problems, the residuals fi, for i=1,2,…,m, contain the difference between the values of a model function ϕ z,x calculated for m different values of the independent variable z, and the corresponding observed values at these points. The minimization process determines the parameters, or constants x, of the fitted function ϕ z,x. For any value, z-, of the independent variable z, an unbiased estimate of the variance of ϕ is
var ϕ=2 Sm-n∑i=1 n∑j=1 n∂ϕ∂xi z-∂ϕ∂xj z-H ij.
The 100 1-β% confidence interval on F at the point z- is
ϕ z-,x--var ϕ.t β/2,m-n<ϕ z-,x*<ϕ z-,x-+var ϕ.t β/2,m-n.
For further details on the analysis of least squares solutions see Bard (1974) and Wolberg (1967).

Recommendations on Choice and Use of Available Methods

The choice of method depends on several factors: the type of problem (unconstrained, etc.); the level of derivative information available (function values only, etc.); your experience (there are easy-to-use versions of some methods); whether or not storage is a problem; whether or not the method is to be used in a multithreaded environment; and whether computational time has a high priority. Not all choices are catered for in the current version of the Library.

Easy-to-use and Comprehensive Methods

Many methods appear in the Library in two forms: a comprehensive form and an easy-to-use form. The objective in the easy-to-use forms is to make the method simple to use by including in the calling sequence only those parameters absolutely essential to the definition of the problem, as opposed to parameters relevant to the solution method. If you are an experienced user the comprehensive methods have additional parameters which enable you to improve their efficiency by ‘tuning’ the method to a particular problem. If you are a casual or inexperienced user, this feature is of little value and may in some cases cause a failure because of a poor choice of some parameters.
In the easy-to-use methods, these extra parameters are determined either by fixing them at a known safe and reasonably efficient value, or by an auxiliary method which generates a ‘good’ value automatically.
For methods introduced since Mark 12 of the Library a different approach has been adopted towards the choice of easy-to-use and comprehensive methods. The optimization method has an easy-to-use parameter list, but additional parameters may be changed from their default values by calling an ‘option’ setting method before the call to the main optimization method. This approach has the advantages of allowing the options to be given in the form of keywords and requiring only those options that are to be different from their default values to be set.

Thread Safe Methods

Many of the methods in this chapter come in pairs, with each method in the pair having exactly the same functionality, except that one of them has additional parameters in order to make it safe for use in multithreaded applications. The method that is safe for use in multithreaded applicatons has an ‘A’ as the last character in the name, in place of the usual ‘F’.
An example of such a pair is e04ab (E04ABA not in this release).
All ‘F’ methods not scheduled for withdrawal from the Library and where there is no ‘A’ version of that method are thread safe provided that the implementation as a whole is considered thread safe (refer to the Users' Note for your implementation).

Reverse Communication Methods

Most of the methods in this chapter are called just once in order to compute the minimum of a given objective function subject to a set of constraints on the variables. The objective function and nonlinear constraints (if any) are specified by you and written as methods to a very rigid format described in the relevant method document.
For the majority of applications this is the simplest and most convenient usage. Sometimes however this approach can be restrictive:
(i) | when the required format of the method does not allow useful information to be passed conveniently to and from your calling program;
(ii) | when the minimization method is being called from another computer language, such as Visual Basic, which does not fully support procedure arguments in a way that is compatible with the Library.
A way around these problems is to utilize reverse communication methods. Instead of performing complete optimizations, these methods perform one step in the solution process before returning to the calling program with an appropriate flag (irevcm) set. The value of irevcm determines whether the minimization process has finished or whether fresh information is required. In the latter case you calculate this information (in the form of a vector or as a scalar, as appropriate) and re-enter the reverse communication method with the information contained in appropriate arguments. Thus you have the responsibility for providing the iterative loop in the minimization process, but as compensation, you have an extremely flexible and basic user-interface to the reverse communication method.
The only reverse communication methods in this chapter are e04uf, which solve dense NLP problems using a sequential quadratic programming method.

Service Methods

One of the most common errors in the use of optimization methods is that user-supplied delegates do not evaluate the relevant partial derivatives correctly. Because exact gradient information normally enhances efficiency in all areas of optimization, you are encouraged to provide analytical derivatives whenever possible. However, mistakes in the computation of derivatives can result in serious and obscure run-time errors. Consequently, service methods are provided to perform an elementary check on the gradients you supplied. These methods are inexpensive to use in terms of the number of calls they require to user-supplied delegates.
The appropriate checking methods are as follows:
Minimization method | Checking method(s)
e04kd | e04hc
e04lb | e04hc and e04hd
(E04GBF not in this release) | e04ya
e04gd | e04ya
e04he | e04ya and e04yb
It should be noted that methods e04uf, e04us, e04vh and e04wd each incorporate a check on the gradients being supplied. This involves verifying the gradients at the first point that satisfies the linear constraints and bounds. There is also an option to perform a more reliable (but more expensive) check on the individual gradient elements being supplied. Note that the checks are not infallible.
A second type of service method computes a set of finite differences to be used when approximating first derivatives. Such differences are required as input parameters by some methods that use only function evaluations.
(E04YCF not in this release) estimates selected elements of the variance-covariance matrix for the computed regression parameters following the use of a nonlinear least squares method.
e04xa estimates the gradient and Hessian of a function at a point, given a method to calculate function values only, or estimates the Hessian of a function at a point, given a method to calculate function and gradient values.

Function Evaluations at Infeasible Points

All the methods for constrained problems will ensure that any evaluations of the objective function occur at points which approximately satisfy any simple bounds or linear constraints. Satisfaction of such constraints is only approximate because methods which estimate derivatives by finite differences may require function evaluations at points which just violate such constraints even though the current iteration just satisfies them.
There is no attempt to ensure that the current iteration satisfies any nonlinear constraints. If you wish to prevent your objective function being evaluated outside some known region (where it may be undefined or not practically computable), you may try to confine the iteration within this region by imposing suitable simple bounds or linear constraints (but beware as this may create new local minima where these constraints are active).
Note also that some methods allow you to return the parameter (iflag or mode) with a negative value to force an immediate clean exit from the minimization method when the objective function (or nonlinear constraints where appropriate) cannot be evaluated.

Related Problems

Apart from the standard types of optimization problem, there are other related problems which can be solved by methods in this or other chapters of the Library.
h02bb solves dense integer LP problems, h02cb solves dense integer QP problems, h02ce solves sparse integer QP problems and (H03ABF not in this release) solves a special type of such problem known as a ‘transportation’ problem.
Several methods in (F04 not in this release) F08 class solve linear least squares problems, i.e., minimize ∑i=1 m ri x 2 where ri x=bi-∑j=1 n a ijxj.
(E02GAF not in this release) solves an overdetermined system of linear equations in the l 1 norm, i.e., minimizes ∑i=1 m ri x, with ri as above, and (E02GBF not in this release) solves the same problem subject to linear inequality constraints.
(E02GCF not in this release) solves an overdetermined system of linear equations in the l∞ norm, i.e., minimizes maxi ri x, with ri as above.
E05 class contains methods for global minimization.
[Methods for handling multi-objective optimization] describes how a multi-objective optimization problem might be addressed using methods from this chapter and from E05 class.

Choosing Between Variant Methods for Some Problems

As evidenced by the wide variety of methods available in E04 class, it is clear that no single algorithm can solve all optimization problems. It is important to try to match the problem to the most suitable method, and that is what the decision trees in [Decision Trees] help to do.
Sometimes in E04 class more than one method is available to solve precisely the same minimization problem. Thus, for example, the general nonlinear programming methods e04uc and e04wd are based on similar methods. Experience shows that although both methods can usually solve the same problem and get similar results, sometimes one method will be faster, sometimes one might find a different local minimum to the other, or, in difficult cases, one method may obtain a solution when the other one fails.
After using one of these methods, if the results obtained are unacceptable for some reason, it may be worthwhile trying the other method instead. In the absence of any other information, in the first instance you are recommended to try using e04uc, and if that proves unsatisfactory, try using e04wd. Although the algorithms used are very similar, the two methods each have slightly different optional arguments which may allow the course of the computation to be altered in different ways.
Other pairs of methods which solve the same kind of problem are e04nq (recommended first choice) or e04nk, for sparse quadratic or linear programming problems, and e04ug or e04vh, for sparse nonlinear programming. In these cases the argument lists are not so similar as e04uc or e04wd, but the same considerations apply.

Decision Trees

Tree 1: Selection chart for unconstrained problems

Only one variable? | _ yes | Are first derivatives available? | _ yes | e04bb
| |  | no | |
| |  | e04ab
no | |
Does the function have many discontinuities? | _ yes | e04cb
no | |
Is store size a problem? | _ yes | e04dg
no | |
Is the function a sum of squares? | _ yes | Are you an experienced user? | _ yes | Are first derivatives available? | _ yes | Are second derivatives available? | _ yes | e04he
| |  | | |  | | |  | no | |
| |  | | |  | | |  | Are there more than ten variables? | _ yes | (E04GBF not in this release)
| |  | | |  | | |  | no | |
| |  | | |  | | |  | e04gd
| |  | | |  | no | |
| |  | | |  | e04fc
| |  | no | |
| |  | Are first derivatives available? | _ yes | Are second derivatives available? | _ yes | e04hy
| |  | | |  | no | |
| |  | | |  | Are there more than ten variables? | _ yes | e04gy
| |  | | |  | no | |
| |  | | |  | e04gz
| |  | no | |
| |  | e04fy
no | |
Are you an experienced user? | _ yes | Are first derivatives available? | _ yes | Are second derivatives available? | _ yes | e04lb
| |  | | |  | no | |
| |  | | |  | Is computational cost critical? | _ yes | e04uc, e04uf, e04ug, e04vh or e04wd
| |  | | |  | no | |
| |  | | |  | e04kd
| |  | no | |
| |  | e04uc, e04uf, e04ug, e04vh or e04wd
no | |
Are first derivatives available? | _ yes | Are second derivatives available? | _ yes | e04ly
| |  | no | |
| |  | Is computational cost critical? | _ yes | e04ky
| |  | no | |
| |  | e04kz
no | |
e04jy

Tree 2: Selection chart for bound-constrained, linearly-constrained and nonlinearly-constrained problems

Are there any nonlinear constraints? | _ yes | Is the objective function a sum of squares? (A least squares problem) | _ yes | e04us
| |  | no | |
| |  | Are the constraints sparse? | _ yes | e04ug or e04vh
| |  | no | |
| |  | e04uc, e04uf or e04wd
no | |
Is the objective function linear? (An LP problem) | _ yes | See Tree 3
no | |
Is the objective function quadratic? (A QP or least squares problem) | _ yes | Is the problem a least squares problem? | _ yes | Are the constraints simple bounds? | _ yes | e04pc
| |  | | |  | no | |
| |  | | |  | e04nc and e04pc
| |  | no | |
| |  | See Tree 3
no | |
Is the objective function a sum of squares? (A least squares problem) | _ yes | e04us
no | |
Are the constraints simple bounds? | _ yes | Are you an experienced user? | _ yes | Are first derivatives available? | _ yes | Are second derivatives available? | _ yes | e04lb
| |  | | |  | | |  | no | |
| |  | | |  | | |  | e04kd, e04uc, e04uf, e04ug or e04vh
| |  | | |  | no | |
| |  | | |  | e04uc, e04uf, e04ug, e04vh or e04wd
| |  | no | |
| |  | Are first derivatives available? | _ yes | Are second derivatives available? | _ yes | e04ly
| |  | | |  | no | |
| |  | | |  | Is computational cost critical? | _ yes | e04ky
| |  | | |  | no | |
| |  | | |  | e04kz
| |  | no | |
| |  | e04jc or e04jy
no | |
e04uc, e04uf, e04ug or e04vh

Tree 3: Linear, Quadratic and Semi-definite Programming (LP, QP and SDP)

Does the problem include semidefinite constraints or bilinear matrix inequalities (an SDP problem)? | _ yes | (E04RAF not in this release) and associated suite
no | |
Is the linear constraint matrix sparse? | _ yes | e04nq, e04nk, e04vh and e04ug
no | |
Is the objective function linear (an LP problem)? | _ yes | e04mf
no | |
Is the QP problem convex? | _ yes | e04nc
no | |
e04nf

References

Bard Y (1974) Nonlinear Parameter Estimation Academic Press
Dantzig G B (1963) Linear Programming and Extensions Princeton University Press
Fletcher R (1987) Practical Methods of Optimization (2nd Edition) Wiley
Gill P E and Murray W (ed.) (1974) Numerical Methods for Constrained Optimization Academic Press
Gill P E, Murray W and Wright M H (1981) Practical Optimization Academic Press
Murray W (ed.) (1972) Numerical Methods for Unconstrained Optimization Academic Press
Wolberg J R (1967) Prediction Analysis Van Nostrand

Inheritance Hierarchy

System..::..Object
NagLibrary..::..E04

See Also

E04 Members


E04 Members

[image] [image]

NAG Library for .NET Release 2
E04 Members
E04 Class Methods See Also Send Feedback

The E04 type exposes the following members.

Methods

Name Description
e04ab
e04ab searches for a minimum, in a given finite interval, of a continuous function of a single variable, using function values only. The method (based on quadratic interpolation) is intended for functions which have a continuous first derivative (although it will usually work if the derivative has occasional discontinuities).
e04bb
e04bb searches for a minimum, in a given finite interval, of a continuous function of a single variable, using function and first derivative values. The method (based on cubic interpolation) is intended for functions which have a continuous first derivative (although it will usually work if the derivative has occasional discontinuities).
e04cb
e04cb minimizes a general function F x of n independent variables x=x 1,x 2,…,xn T by the Nelder and Mead simplex method (see Nelder and Mead (1965)). Derivatives of the function need not be supplied.
e04cbk
Auxiliary for use as a delegate parameter
e04dg
e04dg minimizes an unconstrained nonlinear function of several variables using a pre-conditioned, limited memory quasi-Newton conjugate gradient method. First derivatives (or an ‘acceptable’ finite difference approximation to them) are required. It is intended for use on large scale problems.
e04fc
e04fc is a comprehensive algorithm for finding an unconstrained minimum of a sum of squares of m nonlinear functions in n variables m≥n. No derivatives are required.
The method is intended for functions which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04fdz
Auxiliary for use as a delegate parameter
e04fy
e04fy is an easy-to-use algorithm for finding an unconstrained minimum of a sum of squares of m nonlinear functions in n variables m≥n. No derivatives are required.
It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04gd
e04gd is a comprehensive modified Gauss–Newton algorithm for finding an unconstrained minimum of a sum of squares of m nonlinear functions in n variables m≥n. First derivatives are required.
The method is intended for functions which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04gy
e04gy is an easy-to-use quasi-Newton algorithm for finding an unconstrained minimum of a sum of squares of m nonlinear functions in n variables m≥n. First derivatives are required.
It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04gz
e04gz is an easy-to-use modified Gauss–Newton algorithm for finding an unconstrained minimum of a sum of squares of m nonlinear functions in n variables m≥n. First derivatives are required.
It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04hc
e04hc checks that a method for evaluating an objective function and its first derivatives produces derivative values which are consistent with the function values calculated.
e04hd
e04hd checks that a method for calculating second derivatives of an objective function is consistent with a method for calculating the corresponding first derivatives.
e04he
e04he is a comprehensive modified Gauss–Newton algorithm for finding an unconstrained minimum of a sum of squares of m nonlinear functions in n variables m≥n. First and second derivatives are required.
The method is intended for functions which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04hy
e04hy is an easy-to-use modified Gauss–Newton algorithm for finding an unconstrained minimum of a sum of squares of m nonlinear functions in n variables m≥n. First and second derivatives are required.
It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04jc
e04jc is an easy-to-use algorithm that uses methods of quadratic approximation to find a minimum of an objective function F over x∈Rn, subject to fixed lower and upper bounds on the independent variables x 1,x 2,…,xn. Derivatives of F are not required.
The method is intended for functions that are continuous and that have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities). Efficiency is maintained for large n.
e04jcp
Auxiliary for use as a delegate parameter
e04jy
e04jy is an easy-to-use quasi-Newton algorithm for finding a minimum of a function F x 1,x 2,…,xn, subject to fixed upper and lower bounds of the independent variables x 1,x 2,…,xn, using function values only.
It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04kd
e04kd is a comprehensive modified Newton algorithm for finding:
  • – an unconstrained minimum of a function of several variables;
  • – a minimum of a function of several variables subject to fixed upper and/or lower bounds on the variables.
First derivatives are required. The method is intended for functions which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04ky
e04ky is an easy-to-use quasi-Newton algorithm for finding a minimum of a function F x 1,x 2,…,xn, subject to fixed upper and lower bounds on the independent variables x 1,x 2,…,xn, when first derivatives of F are available.
It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04kz
e04kz is an easy-to-use modified Newton algorithm for finding a minimum of a function F x 1,x 2,…,xn, subject to fixed upper and lower bounds on the independent variables x 1,x 2,…,xn, when first derivatives of F are available. It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04lb
e04lb is a comprehensive modified Newton algorithm for finding:
  • an unconstrained minimum of a function of several variables
  • a minimum of a function of several variables subject to fixed upper and/or lower bounds on the variables.
First and second derivatives are required. The method is intended for functions which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04ly
e04ly is an easy-to-use modified-Newton algorithm for finding a minimum of a function, F x 1,x 2,…,xn subject to fixed upper and lower bounds on the independent variables, x 1,x 2,…,xn when first and second derivatives of F are available. It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04mf
e04mf solves general linear programming problems. It is not intended for large sparse problems.
e04nc
e04nc solves linearly constrained linear least squares problems and convex quadratic programming problems. It is not intended for large sparse problems.
e04nf
e04nf solves general quadratic programming problems. It is not intended for large sparse problems.
e04nfu
Auxiliary for use as a delegate parameter
e04nk
e04nk solves sparse linear programming or convex quadratic programming problems.
e04nku
Auxiliary for use as a delegate parameter
e04nq
e04nq solves sparse linear programming or convex quadratic programming problems. The initialization method (E04NPF not in this release) must have been called before calling e04nq.
e04nsh
Auxiliary for use as a delegate parameter
e04pc
e04pc solves a linear least squares problem subject to fixed lower and upper bounds on the variables.
e04uc
e04uc is designed to minimize an arbitrary smooth function subject to constraints (which may include simple bounds on the variables, linear constraints and smooth nonlinear constraints) using a sequential quadratic programming (SQP) method. As many first derivatives as possible should be supplied by you; any unspecified derivatives are approximated by finite differences. It is not intended for large sparse problems.
e04uc may also be used for unconstrained, bound-constrained and linearly constrained optimization.
e04uc uses forward communication for evaluating the objective function, the nonlinear constraint functions, and any of their derivatives.
e04udm
Auxiliary for use as a delegate parameter
e04uf
e04uf is designed to minimize an arbitrary smooth function subject to constraints (which may include simple bounds on the variables, linear constraints and smooth nonlinear constraints) using a sequential quadratic programming (SQP) method. You should supply as many first derivatives as possible; any unspecified derivatives are approximated by finite differences. It is not intended for large sparse problems.
e04uf may also be used for unconstrained, bound-constrained and linearly constrained optimization.
e04uf uses reverse communication for evaluating the objective function, the nonlinear constraint functions and any of their derivatives.
e04ug
e04ug solves sparse nonlinear programming problems.
e04ugm
Auxiliary for use as a delegate parameter
e04ugn
Auxiliary for use as a delegate parameter
e04us
e04us is designed to minimize an arbitrary smooth sum of squares function subject to constraints (which may include simple bounds on the variables, linear constraints and smooth nonlinear constraints) using a sequential quadratic programming (SQP) method. As many first derivatives as possible should be supplied by you; any unspecified derivatives are approximated by finite differences. See the description of the optional parameter Derivative Level, in [Description of the Optional Parameters]. It is not intended for large sparse problems.
e04us may also be used for unconstrained, bound-constrained and linearly constrained optimization.
e04vh
e04vh solves sparse linear and nonlinear programming problems.
e04vj
e04vj may be used before e04vh to determine the sparsity pattern for the Jacobian.
e04wd
e04wd is designed to minimize an arbitrary smooth function subject to constraints (which may include simple bounds on the variables, linear constraints and smooth nonlinear constraints) using a sequential quadratic programming (SQP) method. As many first derivatives as possible should be supplied by you; any unspecified derivatives are approximated by finite differences. It is not intended for large sparse problems.
e04wd may also be used for unconstrained, bound-constrained and linearly constrained optimization.
e04wd uses forward communication for evaluating the objective function, the nonlinear constraint functions, and any of their derivatives.
The initialization method (E04WCF not in this release) must have been called before to calling e04wd.
e04wdp
Auxiliary for use as a delegate parameter
e04xa
e04xa computes an approximation to the gradient vector and/or the Hessian matrix for use in conjunction with, or following the use of an optimization method (such as e04uf).
e04ya
e04ya checks that a user-supplied method for evaluating a vector of functions and the matrix of their first derivatives produces derivative values which are consistent with the function values calculated.
e04yb
e04yb checks that a user-supplied method for evaluating the second derivative term of the Hessian matrix of a sum of squares is consistent with a user-supplied method for calculating the corresponding first derivatives.

See Also

E04 Class


E04 Delegates

[image]

NAG Library for .NET Release 2
E04 Delegates

E04 Delegate Types

  • E04.E04AB_FUNCT Delegate
  • E04.E04BB_FUNCT Delegate
  • E04.E04CB_FUNCT Delegate
  • E04.E04CB_MONIT Delegate
  • E04.E04DG_OBJFUN Delegate
  • E04.E04FC_LSQFUN Delegate
  • E04.E04FC_LSQMON Delegate
  • E04.E04FY_LSFUN1 Delegate
  • E04.E04GD_LSQFUN Delegate
  • E04.E04GD_LSQMON Delegate
  • E04.E04GY_LSFUN2 Delegate
  • E04.E04GZ_LSFUN2 Delegate
  • E04.E04HC_FUNCT Delegate
  • E04.E04HD_FUNCT Delegate
  • E04.E04HD_H Delegate
  • E04.E04HE_LSQFUN Delegate
  • E04.E04HE_LSQHES Delegate
  • E04.E04HE_LSQMON Delegate
  • E04.E04HY_LSFUN2 Delegate
  • E04.E04HY_LSHES2 Delegate
  • E04.E04JC_MONFUN Delegate
  • E04.E04JC_OBJFUN Delegate
  • E04.E04JY_FUNCT1 Delegate
  • E04.E04KD_FUNCT Delegate
  • E04.E04KD_MONIT Delegate
  • E04.E04KY_FUNCT2 Delegate
  • E04.E04KZ_FUNCT2 Delegate
  • E04.E04LB_FUNCT Delegate
  • E04.E04LB_H Delegate
  • E04.E04LB_MONIT Delegate
  • E04.E04LY_FUNCT2 Delegate
  • E04.E04LY_HESS2 Delegate
  • E04.E04NF_QPHESS Delegate
  • E04.E04NK_QPHX Delegate
  • E04.E04NQ_QPHX Delegate
  • E04.E04UC_CONFUN Delegate
  • E04.E04UC_OBJFUN Delegate
  • E04.E04UG_CONFUN Delegate
  • E04.E04UG_OBJFUN Delegate
  • E04.E04US_CONFUN Delegate
  • E04.E04US_OBJFUN Delegate
  • E04.E04VH_USRFUN Delegate
  • E04.E04VJ_USRFUN Delegate
  • E04.E04WD_CONFUN Delegate
  • E04.E04WD_OBJFUN Delegate
  • E04.E04XA_OBJFUN Delegate
  • E04.E04YA_LSQFUN Delegate
  • E04.E04YB_LSQFUN Delegate
  • E04.E04YB_LSQHES Delegate


E04.E04AB_FUNCT Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04AB_FUNCT Delegate
E04 Class See Also Send Feedback
You must supply this method to calculate the value of the function F x at any point x in a,b. It should be tested separately before being used in conjunction with e04ab.

Syntax

C#
public delegate void E04AB_FUNCT(
    double xc,
    out double fc
)
Visual Basic
Public Delegate Sub E04AB_FUNCT ( _
    xc As Double, _
    <OutAttribute> ByRef fc As Double _
)
Visual C++
public delegate void E04AB_FUNCT(
    double xc,
    [OutAttribute] double% fc
)
F#
type E04AB_FUNCT =
    delegate of
        xc : float *
        fc : float byref -> unit

Parameters

xc
Type: System..::..Double
On entry: the point x at which the value of F is required.
fc
Type: System..::..Double %
On exit: must be set to the value of the function F at the current point x.

See Also

NagLibrary Namespace
NAG Library Overview
e04ab


E04.E04BB_FUNCT Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04BB_FUNCT Delegate
E04 Class See Also Send Feedback
You must supply this method to calculate the values of F x and dFdx at any point x in a,b.
It should be tested separately before being used in conjunction with e04bb.

Syntax

C#
public delegate void E04BB_FUNCT(
    double xc,
    out double fc,
    out double gc
)
Visual Basic
Public Delegate Sub E04BB_FUNCT ( _
    xc As Double, _
    <OutAttribute> ByRef fc As Double, _
    <OutAttribute> ByRef gc As Double _
)
Visual C++
public delegate void E04BB_FUNCT(
    double xc,
    [OutAttribute] double% fc,
    [OutAttribute] double% gc
)
F#
type E04BB_FUNCT =
    delegate of
        xc : float *
        fc : float byref *
        gc : float byref -> unit

Parameters

xc
Type: System..::..Double
On entry: the point x at which the values of F and dFdx are required.
fc
Type: System..::..Double %
On exit: must be set to the value of the function F at the current point x.
gc
Type: System..::..Double %
On exit: must be set to the value of the first derivative dFdx at the current point x.

See Also

NagLibrary Namespace
NAG Library Overview
e04bb


E04.E04CB_FUNCT Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04CB_FUNCT Delegate
E04 Class See Also Send Feedback
funct must evaluate the function F at a specified point. It should be tested separately before being used in conjunction with e04cb.

Syntax

C#
public delegate void E04CB_FUNCT(
    int n,
    double[] xc,
    out double fc
)
Visual Basic
Public Delegate Sub E04CB_FUNCT ( _
    n As Integer, _
    xc As Double(), _
    <OutAttribute> ByRef fc As Double _
)
Visual C++
public delegate void E04CB_FUNCT(
    int n,
    array<double>^ xc,
    [OutAttribute] double% fc
)
F#
type E04CB_FUNCT =
    delegate of
        n : int *
        xc : float[] *
        fc : float byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the point at which the function value is required.
fc
Type: System..::..Double %
On exit: the value of the function F at the current point x.

See Also

NagLibrary Namespace
NAG Library Overview
e04cb


E04.E04CB_MONIT Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04CB_MONIT Delegate
E04 Class See Also Send Feedback
monit may be used to monitor the optimization process. It is invoked once every iteration.
If no monitoring is required, monit may be the dummy monitoring method E04CBK supplied by the NAG Library.

Syntax

C#
public delegate void E04CB_MONIT(
    double fmin,
    double fmax,
    double[,] sim,
    int n,
    int ncall,
    double serror,
    double vratio
)
Visual Basic
Public Delegate Sub E04CB_MONIT ( _
    fmin As Double, _
    fmax As Double, _
    sim As Double(,), _
    n As Integer, _
    ncall As Integer, _
    serror As Double, _
    vratio As Double _
)
Visual C++
public delegate void E04CB_MONIT(
    double fmin,
    double fmax,
    array<double,2>^ sim,
    int n,
    int ncall,
    double serror,
    double vratio
)
F#
type E04CB_MONIT =
    delegate of
        fmin : float *
        fmax : float *
        sim : float[,] *
        n : int *
        ncall : int *
        serror : float *
        vratio : float -> unit

Parameters

fmin
Type: System..::..Double
On entry: the smallest function value in the current simplex.
fmax
Type: System..::..Double
On entry: the largest function value in the current simplex.
sim
Type: array< System..::..Double ,2>[,](,)[,][,]
On entry: the n+1 position vectors of the current simplex.
n
Type: System..::..Int32
On entry: n, the number of variables.
ncall
Type: System..::..Int32
On entry: the number of times that funct has been called so far.
serror
Type: System..::..Double
On entry: the current value of the standard deviation in function values used in termination test (1).
vratio
Type: System..::..Double
On entry: the current value of the linearized volume ratio used in termination test (2).

See Also

NagLibrary Namespace
NAG Library Overview
e04cb


E04.E04DG_OBJFUN Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04DG_OBJFUN Delegate
E04 Class See Also Send Feedback
objfun must calculate the objective function F x and possibly its gradient as well for a specified n-element vector x.

Syntax

C#
public delegate void E04DG_OBJFUN(
    ref int mode,
    int n,
    double[] x,
    out double objf,
    double[] objgrd,
    int nstate
)
Visual Basic
Public Delegate Sub E04DG_OBJFUN ( _
    ByRef mode As Integer, _
    n As Integer, _
    x As Double(), _
    <OutAttribute> ByRef objf As Double, _
    objgrd As Double(), _
    nstate As Integer _
)
Visual C++
public delegate void E04DG_OBJFUN(
    int% mode,
    int n,
    array<double>^ x,
    [OutAttribute] double% objf,
    array<double>^ objgrd,
    int nstate
)
F#
type E04DG_OBJFUN =
    delegate of
        mode : int byref *
        n : int *
        x : float[] *
        objf : float byref *
        objgrd : float[] *
        nstate : int -> unit

Parameters

mode
Type: System..::..Int32 %
On entry: indicates which values must be assigned during each call of objfun. Only the following values need be assigned:
mode=0
objf.
mode=2
objf and objgrd.
On exit: may be set to a negative value if you wish to terminate the solution to the current problem, and in this case e04dg will terminate with ifail set to mode.
n
Type: System..::..Int32
On entry: n, the number of variables.
x
Type: array< System..::..Double >[]()[][]
On entry: x, the vector of variables at which the objective function and its gradient are to be evaluated.
objf
Type: System..::..Double %
On exit: the value of the objective function at x.
objgrd
Type: array< System..::..Double >[]()[][]
On exit: if mode=2, objgrd[i-1] must contain the value of ∂F∂xi evaluated at x, for i=1,2,…,n.
nstate
Type: System..::..Int32
On entry: will be 1 on the first call of objfun by e04dg, and 0 for all subsequent calls. Thus, you may wish to test, nstate within objfun in order to perform certain calculations once only. For example, you may read data or initialize global variables when nstate=1.

See Also

NagLibrary Namespace
NAG Library Overview
e04dg


E04.E04FC_LSQFUN Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04FC_LSQFUN Delegate
E04 Class See Also Send Feedback
lsqfun must calculate the vector of values fi x at any point x. (However, if you do not wish to calculate the residuals at a particular x, there is the option of setting a parameter to cause e04fc to terminate immediately.)

Syntax

C#
public delegate void E04FC_LSQFUN(
    ref int iflag,
    int m,
    int n,
    double[] xc,
    double[] fvec
)
Visual Basic
Public Delegate Sub E04FC_LSQFUN ( _
    ByRef iflag As Integer, _
    m As Integer, _
    n As Integer, _
    xc As Double(), _
    fvec As Double() _
)
Visual C++
public delegate void E04FC_LSQFUN(
    int% iflag,
    int m,
    int n,
    array<double>^ xc,
    array<double>^ fvec
)
F#
type E04FC_LSQFUN =
    delegate of
        iflag : int byref *
        m : int *
        n : int *
        xc : float[] *
        fvec : float[] -> unit

Parameters

iflag
Type: System..::..Int32 %
On entry: has a non-negative value.
On exit: if lsqfun resets iflag to some negative number, e04fc will terminate immediately, with ifail set to your setting of iflag.
m
Type: System..::..Int32
On entry: m, the numbers of residuals.
n
Type: System..::..Int32
On entry: n, the numbers of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the point x at which the values of the fi are required.
fvec
Type: array< System..::..Double >[]()[][]
On exit: unless iflag is reset to a negative number, fvec[i-1] must contain the value of fi at the point x, for i=1,2,…,m.

See Also

NagLibrary Namespace
NAG Library Overview
e04fc


E04.E04FC_LSQMON Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04FC_LSQMON Delegate
E04 Class See Also Send Feedback
If iprint≥0, you must supply lsqmon which is suitable for monitoring the minimization process. lsqmon must not change the values of any of its parameters.
If iprint<0, the dummy method E04FDZ can be used as lsqmon.

Syntax

C#
public delegate void E04FC_LSQMON(
    int m,
    int n,
    double[] xc,
    double[] fvec,
    double[,] fjac,
    double[] s,
    int igrade,
    int niter,
    int nf
)
Visual Basic
Public Delegate Sub E04FC_LSQMON ( _
    m As Integer, _
    n As Integer, _
    xc As Double(), _
    fvec As Double(), _
    fjac As Double(,), _
    s As Double(), _
    igrade As Integer, _
    niter As Integer, _
    nf As Integer _
)
Visual C++
public delegate void E04FC_LSQMON(
    int m,
    int n,
    array<double>^ xc,
    array<double>^ fvec,
    array<double,2>^ fjac,
    array<double>^ s,
    int igrade,
    int niter,
    int nf
)
F#
type E04FC_LSQMON =
    delegate of
        m : int *
        n : int *
        xc : float[] *
        fvec : float[] *
        fjac : float[,] *
        s : float[] *
        igrade : int *
        niter : int *
        nf : int -> unit

Parameters

m
Type: System..::..Int32
On entry: m, the numbers of residuals.
n
Type: System..::..Int32
On entry: n, the numbers of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the coordinates of the current point x.
fvec
Type: array< System..::..Double >[]()[][]
On entry: the values of the residuals fi at the current point x.
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
On entry: fjac[i-1,j-1] contains the value of ∂fi∂xj at the current point x, for i=1,2,…,m and j=1,2,…,n.
s
Type: array< System..::..Double >[]()[][]
On entry: the singular values of the current approximation to the Jacobian matrix. Thus s may be useful as information about the structure of your problem.
igrade
Type: System..::..Int32
On entry: e04fc estimates the dimension of the subspace for which the Jacobian matrix can be used as a valid approximation to the curvature (see Gill and Murray (1978)). This estimate is called the grade of the Jacobian matrix, and igrade gives its current value.
niter
Type: System..::..Int32
On entry: the number of iterations which have been performed in e04fc.
nf
Type: System..::..Int32
On entry: the number of times that lsqfun has been called so far. (However, for intermediate calls of lsqmon, nf is calculated on the assumption that the latest linear search has been successful. If this is not the case, then the n evaluations allowed for approximating the Jacobian at the new point will not in fact have been made. nf will be accurate at the final call of lsqmon.)

See Also

NagLibrary Namespace
NAG Library Overview
e04fc


E04.E04FY_LSFUN1 Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04FY_LSFUN1 Delegate
E04 Class See Also Send Feedback
You must supply this method to calculate the vector of values fi x at any point x. It should be tested separately before being used in conjunction with e04fy (see the E04 class).

Syntax

C#
public delegate void E04FY_LSFUN1(
    int m,
    int n,
    double[] xc,
    double[] fvec
)
Visual Basic
Public Delegate Sub E04FY_LSFUN1 ( _
    m As Integer, _
    n As Integer, _
    xc As Double(), _
    fvec As Double() _
)
Visual C++
public delegate void E04FY_LSFUN1(
    int m,
    int n,
    array<double>^ xc,
    array<double>^ fvec
)
F#
type E04FY_LSFUN1 =
    delegate of
        m : int *
        n : int *
        xc : float[] *
        fvec : float[] -> unit

Parameters

m
Type: System..::..Int32
On entry: m, the numbers of residuals.
n
Type: System..::..Int32
On entry: n, the numbers of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the point x at which the values of the fi are required.
fvec
Type: array< System..::..Double >[]()[][]
On exit: fvec[i-1] must contain the value of fi at the point x, for i=1,2,…,m.

See Also

NagLibrary Namespace
NAG Library Overview
e04fy


E04.E04GD_LSQFUN Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04GD_LSQFUN Delegate
E04 Class See Also Send Feedback
lsqfun must calculate the vector of values fi x and Jacobian matrix of first derivatives ∂fi∂xj at any point x. (However, if you do not wish to calculate the residuals or first derivatives at a particular x, there is the option of setting a parameter to cause e04gd to terminate immediately.)

Syntax

C#
public delegate void E04GD_LSQFUN(
    ref int iflag,
    int m,
    int n,
    double[] xc,
    double[] fvec,
    double[,] fjac
)
Visual Basic
Public Delegate Sub E04GD_LSQFUN ( _
    ByRef iflag As Integer, _
    m As Integer, _
    n As Integer, _
    xc As Double(), _
    fvec As Double(), _
    fjac As Double(,) _
)
Visual C++
public delegate void E04GD_LSQFUN(
    int% iflag,
    int m,
    int n,
    array<double>^ xc,
    array<double>^ fvec,
    array<double,2>^ fjac
)
F#
type E04GD_LSQFUN =
    delegate of
        iflag : int byref *
        m : int *
        n : int *
        xc : float[] *
        fvec : float[] *
        fjac : float[,] -> unit

Parameters

iflag
Type: System..::..Int32 %
On entry: to lsqfun, iflag will be set to 1 or 2.
iflag=1
Indicates that only the Jacobian matrix needs to be evaluated
iflag=2
Indicates that both the residuals and the Jacobian matrix must be calculated
On exit: if it is not possible to evaluate the fi x or their first derivatives at the point given in xc (or if it wished to stop the calculations for any other reason), you should reset iflag to some negative number and return control to e04gd. e04gd will then terminate immediately, with ifail set to your setting of iflag.
m
Type: System..::..Int32
On entry: m, the numbers of residuals.
n
Type: System..::..Int32
On entry: n, the numbers of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the point x at which the values of the fi and the ∂fi∂xj are required.
fvec
Type: array< System..::..Double >[]()[][]
On exit: unless iflag=1 on entry, or iflag is reset to a negative number, then fvec[i-1] must contain the value of fi at the point x, for i=1,2,…,m.
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
On exit: unless iflag is reset to a negative number, fjac[i-1,j-1] must contain the value of ∂fi∂xj at the point x, for i=1,2,…,m and j=1,2,…,n.

See Also

NagLibrary Namespace
NAG Library Overview
e04gd


E04.E04GD_LSQMON Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04GD_LSQMON Delegate
E04 Class See Also Send Feedback
If iprint≥0, you must supply lsqmon which is suitable for monitoring the minimization process. lsqmon must not change the values of any of its parameters.
If iprint<0, the dummy method E04FDZ can be used as lsqmon.

Syntax

C#
public delegate void E04GD_LSQMON(
    int m,
    int n,
    double[] xc,
    double[] fvec,
    double[,] fjac,
    double[] s,
    int igrade,
    int niter,
    int nf
)
Visual Basic
Public Delegate Sub E04GD_LSQMON ( _
    m As Integer, _
    n As Integer, _
    xc As Double(), _
    fvec As Double(), _
    fjac As Double(,), _
    s As Double(), _
    igrade As Integer, _
    niter As Integer, _
    nf As Integer _
)
Visual C++
public delegate void E04GD_LSQMON(
    int m,
    int n,
    array<double>^ xc,
    array<double>^ fvec,
    array<double,2>^ fjac,
    array<double>^ s,
    int igrade,
    int niter,
    int nf
)
F#
type E04GD_LSQMON =
    delegate of
        m : int *
        n : int *
        xc : float[] *
        fvec : float[] *
        fjac : float[,] *
        s : float[] *
        igrade : int *
        niter : int *
        nf : int -> unit

Parameters

m
Type: System..::..Int32
On entry: m, the numbers of residuals.
n
Type: System..::..Int32
On entry: n, the numbers of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the coordinates of the current point x.
fvec
Type: array< System..::..Double >[]()[][]
On entry: the values of the residuals fi at the current point x.
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
On entry: fjac[i-1,j-1] contains the value of ∂fi∂xj at the current point x, for i=1,2,…,m and j=1,2,…,n.
s
Type: array< System..::..Double >[]()[][]
On entry: the singular values of the current Jacobian matrix. Thus s may be useful as information about the structure of your problem. (If iprint>0, lsqmon is called at the initial point before the singular values have been calculated. So the elements of s are set to zero for the first call of lsqmon.)
igrade
Type: System..::..Int32
On entry: e04gd estimates the dimension of the subspace for which the Jacobian matrix can be used as a valid approximation to the curvature (see Gill and Murray (1978)). This estimate is called the grade of the Jacobian matrix, and igrade gives its current value.
niter
Type: System..::..Int32
On entry: the number of iterations which have been performed in e04gd.
nf
Type: System..::..Int32
On entry: the number of times that lsqfun has been called so far with iflag=2. (In addition to these calls monitored by nf, lsqfun is called not more than n times per iteration with iflag set to 1.)

See Also

NagLibrary Namespace
NAG Library Overview
e04gd


E04.E04GY_LSFUN2 Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04GY_LSFUN2 Delegate
E04 Class See Also Send Feedback
You must supply this method to calculate the vector of values fi x and the Jacobian matrix of first derivatives ∂fi∂xj at any point x. It should be tested separately before being used in conjunction with e04gy (see the E04 class).

Syntax

C#
public delegate void E04GY_LSFUN2(
    int m,
    int n,
    double[] xc,
    double[] fvec,
    double[,] fjac
)
Visual Basic
Public Delegate Sub E04GY_LSFUN2 ( _
    m As Integer, _
    n As Integer, _
    xc As Double(), _
    fvec As Double(), _
    fjac As Double(,) _
)
Visual C++
public delegate void E04GY_LSFUN2(
    int m,
    int n,
    array<double>^ xc,
    array<double>^ fvec,
    array<double,2>^ fjac
)
F#
type E04GY_LSFUN2 =
    delegate of
        m : int *
        n : int *
        xc : float[] *
        fvec : float[] *
        fjac : float[,] -> unit

Parameters

m
Type: System..::..Int32
On entry: m, the numbers of residuals.
n
Type: System..::..Int32
On entry: n, the numbers of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the point x at which the values of the fi and the ∂fi∂xj are required.
fvec
Type: array< System..::..Double >[]()[][]
On exit: fvec[i-1] must contain the value of fi at the point x, for i=1,2,…,m.
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
On exit: fjac[i-1,j-1] must contain the value of ∂fi∂xj at the point x, for i=1,2,…,m and j=1,2,…,n.

See Also

NagLibrary Namespace
NAG Library Overview
e04gy


E04.E04GZ_LSFUN2 Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04GZ_LSFUN2 Delegate
E04 Class See Also Send Feedback
You must supply this method to calculate the vector of values fi x and the Jacobian matrix of first derivatives ∂fi∂xj at any point x. It should be tested separately before being used in conjunction with e04gz.

Syntax

C#
public delegate void E04GZ_LSFUN2(
    int m,
    int n,
    double[] xc,
    double[] fvec,
    double[,] fjac
)
Visual Basic
Public Delegate Sub E04GZ_LSFUN2 ( _
    m As Integer, _
    n As Integer, _
    xc As Double(), _
    fvec As Double(), _
    fjac As Double(,) _
)
Visual C++
public delegate void E04GZ_LSFUN2(
    int m,
    int n,
    array<double>^ xc,
    array<double>^ fvec,
    array<double,2>^ fjac
)
F#
type E04GZ_LSFUN2 =
    delegate of
        m : int *
        n : int *
        xc : float[] *
        fvec : float[] *
        fjac : float[,] -> unit

Parameters

m
Type: System..::..Int32
On entry: m, the numbers of residuals.
n
Type: System..::..Int32
On entry: n, the numbers of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the point x at which the values of the fi and the ∂fi∂xj are required.
fvec
Type: array< System..::..Double >[]()[][]
On exit: fvec[i-1] must be set to the value of fi at the point x, for i=1,2,…,m.
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
On exit: fjac[i-1,j-1] must be set to the value of ∂fi∂xj at the point x, for i=1,2,…,m and j=1,2,…,n.

See Also

NagLibrary Namespace
NAG Library Overview
e04gz


E04.E04HC_FUNCT Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04HC_FUNCT Delegate
E04 Class See Also Send Feedback
funct must evaluate the function and its first derivatives at a given point. (The minimization methods mentioned in [Description] gives you the option of resetting parameters of funct to cause the minimization process to terminate immediately. e04hc will also terminate immediately, without finishing the checking process, if the parameter in question is reset.)

Syntax

C#
public delegate void E04HC_FUNCT(
    ref int iflag,
    int n,
    double[] xc,
    ref double fc,
    double[] gc
)
Visual Basic
Public Delegate Sub E04HC_FUNCT ( _
    ByRef iflag As Integer, _
    n As Integer, _
    xc As Double(), _
    ByRef fc As Double, _
    gc As Double() _
)
Visual C++
public delegate void E04HC_FUNCT(
    int% iflag,
    int n,
    array<double>^ xc,
    double% fc,
    array<double>^ gc
)
F#
type E04HC_FUNCT =
    delegate of
        iflag : int byref *
        n : int *
        xc : float[] *
        fc : float byref *
        gc : float[] -> unit

Parameters

iflag
Type: System..::..Int32 %
On entry: will be set to 2.
On exit: if you reset iflag to a negative number in funct and return control to e04hc, e04hc will terminate immediately with ifail set to your setting of iflag.
n
Type: System..::..Int32
On entry: the number n of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the point x at which F and its derivatives are required.
fc
Type: System..::..Double %
On exit: unless funct resets iflag, fc must be set to the value of the function F at the current point x.
gc
Type: array< System..::..Double >[]()[][]
On exit: unless funct resets iflag, gc[j-1] must be set to the value of the first derivative ∂F∂xj at the point x, for j=1,2,…,n.

See Also

NagLibrary Namespace
NAG Library Overview
e04hc


E04.E04HD_FUNCT Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04HD_FUNCT Delegate
E04 Class See Also Send Feedback
funct must evaluate the function and its first derivatives at a given point. (e04lb gives you the option of resetting parameters of funct to cause the minimization process to terminate immediately. e04hd will also terminate immediately, without finishing the checking process, if the parameter in question is reset.)

Syntax

C#
public delegate void E04HD_FUNCT(
    ref int iflag,
    int n,
    double[] xc,
    ref double fc,
    double[] gc
)
Visual Basic
Public Delegate Sub E04HD_FUNCT ( _
    ByRef iflag As Integer, _
    n As Integer, _
    xc As Double(), _
    ByRef fc As Double, _
    gc As Double() _
)
Visual C++
public delegate void E04HD_FUNCT(
    int% iflag,
    int n,
    array<double>^ xc,
    double% fc,
    array<double>^ gc
)
F#
type E04HD_FUNCT =
    delegate of
        iflag : int byref *
        n : int *
        xc : float[] *
        fc : float byref *
        gc : float[] -> unit

Parameters

iflag
Type: System..::..Int32 %
On entry: to funct, iflag will be set to 2.
On exit: if you set iflag to some negative number in funct and return control to e04hd, e04hd will terminate immediately with ifail set to your setting of iflag.
n
Type: System..::..Int32
On entry: the number n of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the point x at which the function and first derivatives are required.
fc
Type: System..::..Double %
On exit: unless funct resets iflag, fc must be set to the value of the objective function F at the current point x.
gc
Type: array< System..::..Double >[]()[][]
On exit: unless funct resets iflag, gc[j-1] must be set to the value of the first derivative ∂F∂xj at the point x, for j=1,2,…,n.

See Also

NagLibrary Namespace
NAG Library Overview
e04hd


E04.E04HD_H Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04HD_H Delegate
E04 Class See Also Send Feedback
h must evaluate the second derivatives of the function at a given point. (As with funct, a parameter can be set to cause immediate termination.)

Syntax

C#
public delegate void E04HD_H(
    ref int iflag,
    int n,
    double[] xc,
    double[] fhesl,
    double[] fhesd
)
Visual Basic
Public Delegate Sub E04HD_H ( _
    ByRef iflag As Integer, _
    n As Integer, _
    xc As Double(), _
    fhesl As Double(), _
    fhesd As Double() _
)
Visual C++
public delegate void E04HD_H(
    int% iflag,
    int n,
    array<double>^ xc,
    array<double>^ fhesl,
    array<double>^ fhesd
)
F#
type E04HD_H =
    delegate of
        iflag : int byref *
        n : int *
        xc : float[] *
        fhesl : float[] *
        fhesd : float[] -> unit

Parameters

iflag
Type: System..::..Int32 %
On entry: is set to a non-negative number.
On exit: if h resets iflag to a negative number, e04hd will terminate immediately with ifail set to your setting of iflag.
n
Type: System..::..Int32
On entry: the number n of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the point x at which the second derivatives of F x are required.
fhesl
Type: array< System..::..Double >[]()[][]
On exit: unless iflag is reset, h must place the strict lower triangle of the second derivative matrix of F (evaluated at the point x) in fhesl, stored by rows, i.e., fhesl[i-1i-2/2+j-1] must be set to the value of ∂2 F∂xi∂xj at the point x, for i=2,3,…,n and j=1,2,…,i-1. (The upper triangle is not required because the matrix is symmetric.)
fhesd
Type: array< System..::..Double >[]()[][]
On entry: contains the value of ∂F∂xj at the point x, for j=1,2,…,n. Methods written to take advantage of a similar feature of e04lb can be tested as they stand by e04hd.
On exit: unless iflag is reset, h must place the diagonal elements of the second derivative matrix of F (evaluated at the point x) in fhesd, i.e., fhesd[j-1] must be set to the value of ∂2 F∂xj 2 at the point x, for j=1,2,…,n.

See Also

NagLibrary Namespace
NAG Library Overview
e04hd


E04.E04HE_LSQFUN Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04HE_LSQFUN Delegate
E04 Class See Also Send Feedback
lsqfun must calculate the vector of values fi x and Jacobian matrix of first derivatives ∂fi∂xj at any point x. (However, if you do not wish to calculate the residuals or first derivatives at a particular x, there is the option of setting a parameter to cause e04he to terminate immediately.)

Syntax

C#
public delegate void E04HE_LSQFUN(
    ref int iflag,
    int m,
    int n,
    double[] xc,
    double[] fvec,
    double[,] fjac
)
Visual Basic
Public Delegate Sub E04HE_LSQFUN ( _
    ByRef iflag As Integer, _
    m As Integer, _
    n As Integer, _
    xc As Double(), _
    fvec As Double(), _
    fjac As Double(,) _
)
Visual C++
public delegate void E04HE_LSQFUN(
    int% iflag,
    int m,
    int n,
    array<double>^ xc,
    array<double>^ fvec,
    array<double,2>^ fjac
)
F#
type E04HE_LSQFUN =
    delegate of
        iflag : int byref *
        m : int *
        n : int *
        xc : float[] *
        fvec : float[] *
        fjac : float[,] -> unit

Parameters

iflag
Type: System..::..Int32 %
On entry: to lsqfun, iflag will be set to 2.
On exit: if it is not possible to evaluate the fi x or their first derivatives at the point given in xc (or if it wished to stop the calculations for any other reason), you should reset iflag to some negative number and return control to e04he. e04he will then terminate immediately, with ifail set to your setting of iflag.
m
Type: System..::..Int32
On entry: m, the numbers of residuals.
n
Type: System..::..Int32
On entry: n, the numbers of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the point x at which the values of the fi and the ∂fi∂xj are required.
fvec
Type: array< System..::..Double >[]()[][]
On exit: unless iflag is reset to a negative number, fvec[i-1] must contain the value of fi at the point x, for i=1,2,…,m.
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
On exit: unless iflag is reset to a negative number, fjac[i-1,j-1] must contain the value of ∂fi∂xj at the point x, for i=1,2,…,m and j=1,2,…,n.

See Also

NagLibrary Namespace
NAG Library Overview
e04he


E04.E04HE_LSQHES Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04HE_LSQHES Delegate
E04 Class See Also Send Feedback
lsqhes must calculate the elements of the symmetric matrix
B x=∑i=1 m fi x Gi x,
at any point x, where Gi x is the Hessian matrix of fi x. (As with lsqfun, there is the option of causing e04he to terminate immediately.)

Syntax

C#
public delegate void E04HE_LSQHES(
    ref int iflag,
    int m,
    int n,
    double[] fvec,
    double[] xc,
    double[] b
)
Visual Basic
Public Delegate Sub E04HE_LSQHES ( _
    ByRef iflag As Integer, _
    m As Integer, _
    n As Integer, _
    fvec As Double(), _
    xc As Double(), _
    b As Double() _
)
Visual C++
public delegate void E04HE_LSQHES(
    int% iflag,
    int m,
    int n,
    array<double>^ fvec,
    array<double>^ xc,
    array<double>^ b
)
F#
type E04HE_LSQHES =
    delegate of
        iflag : int byref *
        m : int *
        n : int *
        fvec : float[] *
        xc : float[] *
        b : float[] -> unit

Parameters

iflag
Type: System..::..Int32 %
On entry: is set to a non-negative number.
On exit: if lsqhes resets iflag to some negative number, e04he will terminate immediately, with ifail set to your setting of iflag.
m
Type: System..::..Int32
On entry: m, the numbers of residuals.
n
Type: System..::..Int32
On entry: n, the numbers of variables.
fvec
Type: array< System..::..Double >[]()[][]
On entry: the value of the residual fi at the point x, for i=1,2,…,m, so that the values of the fi can be used in the calculation of the elements of b.
xc
Type: array< System..::..Double >[]()[][]
On entry: the point x at which the elements of b are to be evaluated.
b
Type: array< System..::..Double >[]()[][]
On exit: unless iflag is reset to a negative number, b must contain the lower triangle of the matrix b[x-1], evaluated at the point x, stored by rows. (The upper triangle is not required because the matrix is symmetric.) More precisely, b[j j-1/2+k-1] must contain ∑i=1 m fi∂2 fi∂xj∂xk evaluated at the point x, for j=1,2,…,n and k=1,2,…,j.

See Also

NagLibrary Namespace
NAG Library Overview
e04he


E04.E04HE_LSQMON Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04HE_LSQMON Delegate
E04 Class See Also Send Feedback
If iprint≥0, you must supply lsqmon which is suitable for monitoring the minimization process. lsqmon must not change the values of any of its parameters.
If iprint<0, the dummy method E04FDZ can be used as lsqmon.

Syntax

C#
public delegate void E04HE_LSQMON(
    int m,
    int n,
    double[] xc,
    double[] fvec,
    double[,] fjac,
    double[] s,
    int igrade,
    int niter,
    int nf
)
Visual Basic
Public Delegate Sub E04HE_LSQMON ( _
    m As Integer, _
    n As Integer, _
    xc As Double(), _
    fvec As Double(), _
    fjac As Double(,), _
    s As Double(), _
    igrade As Integer, _
    niter As Integer, _
    nf As Integer _
)
Visual C++
public delegate void E04HE_LSQMON(
    int m,
    int n,
    array<double>^ xc,
    array<double>^ fvec,
    array<double,2>^ fjac,
    array<double>^ s,
    int igrade,
    int niter,
    int nf
)
F#
type E04HE_LSQMON =
    delegate of
        m : int *
        n : int *
        xc : float[] *
        fvec : float[] *
        fjac : float[,] *
        s : float[] *
        igrade : int *
        niter : int *
        nf : int -> unit

Parameters

m
Type: System..::..Int32
On entry: m, the numbers of residuals.
n
Type: System..::..Int32
On entry: n, the numbers of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the coordinates of the current point x.
fvec
Type: array< System..::..Double >[]()[][]
On entry: the values of the residuals fi at the current point x.
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
On entry: fjac[i-1,j-1] contains the value of ∂fi∂xj at the current point x, for i=1,2,…,m and j=1,2,…,n.
s
Type: array< System..::..Double >[]()[][]
On entry: the singular values of the current Jacobian matrix. Thus s may be useful as information about the structure of your problem. (If iprint>0, lsqmon is called at the initial point before the singular values have been calculated, so the elements of s are set to zero for the first call of lsqmon.)
igrade
Type: System..::..Int32
On entry: e04he estimates the dimension of the subspace for which the Jacobian matrix can be used as a valid approximation to the curvature (see Gill and Murray (1978)). This estimate is called the grade of the Jacobian matrix, and igrade gives its current value.
niter
Type: System..::..Int32
On entry: the number of iterations which have been performed in e04he.
nf
Type: System..::..Int32
On entry: the number of times that lsqfun has been called so far. Thus nf gives the number of evaluations of the residuals and the Jacobian matrix.

See Also

NagLibrary Namespace
NAG Library Overview
e04he


E04.E04HY_LSFUN2 Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04HY_LSFUN2 Delegate
E04 Class See Also Send Feedback
You must supply this method to calculate the vector of values fi x and the Jacobian matrix of first derivatives ∂fi∂xj at any point x. It should be tested separately before being used in conjunction with e04hy (see the E04 class).

Syntax

C#
public delegate void E04HY_LSFUN2(
    int m,
    int n,
    double[] xc,
    double[] fvec,
    double[,] fjac
)
Visual Basic
Public Delegate Sub E04HY_LSFUN2 ( _
    m As Integer, _
    n As Integer, _
    xc As Double(), _
    fvec As Double(), _
    fjac As Double(,) _
)
Visual C++
public delegate void E04HY_LSFUN2(
    int m,
    int n,
    array<double>^ xc,
    array<double>^ fvec,
    array<double,2>^ fjac
)
F#
type E04HY_LSFUN2 =
    delegate of
        m : int *
        n : int *
        xc : float[] *
        fvec : float[] *
        fjac : float[,] -> unit

Parameters

m
Type: System..::..Int32
On entry: m, the numbers of residuals.
n
Type: System..::..Int32
On entry: n, the numbers of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the point x at which the values of the fi and the ∂fi∂xj are required.
fvec
Type: array< System..::..Double >[]()[][]
On exit: fvec[i-1] must be set to the value of fi at the point x, for i=1,2,…,m.
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
On exit: fjac[i-1,j-1] must be set to the value of ∂fi∂xj at the point x, for i=1,2,…,m and j=1,2,…,n.

See Also

NagLibrary Namespace
NAG Library Overview
e04hy


E04.E04HY_LSHES2 Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04HY_LSHES2 Delegate
E04 Class See Also Send Feedback
You must supply this method to calculate the elements of the symmetric matrix
B x=∑i=1 m fi x Gi x,
at any point x, where Gi x is the Hessian matrix of fi x. It should be tested separately before being used in conjunction with e04hy (see the E04 class).

Syntax

C#
public delegate void E04HY_LSHES2(
    int m,
    int n,
    double[] fvec,
    double[] xc,
    double[] b
)
Visual Basic
Public Delegate Sub E04HY_LSHES2 ( _
    m As Integer, _
    n As Integer, _
    fvec As Double(), _
    xc As Double(), _
    b As Double() _
)
Visual C++
public delegate void E04HY_LSHES2(
    int m,
    int n,
    array<double>^ fvec,
    array<double>^ xc,
    array<double>^ b
)
F#
type E04HY_LSHES2 =
    delegate of
        m : int *
        n : int *
        fvec : float[] *
        xc : float[] *
        b : float[] -> unit

Parameters

m
Type: System..::..Int32
On entry: m, the number of residuals.
n
Type: System..::..Int32
On entry: n, the number of residuals.
fvec
Type: array< System..::..Double >[]()[][]
On entry: the value of the residual fi at the point x, for i=1,2,…,m, so that the values of the fi can be used in the calculation of the elements of b.
xc
Type: array< System..::..Double >[]()[][]
On entry: the point x at which the elements of b are to be evaluated.
b
Type: array< System..::..Double >[]()[][]
On exit: must contain the lower triangle of the matrix B x, evaluated at the point x, stored by rows. (The upper triangle is not required because the matrix is symmetric.) More precisely, b[j j-1/2+k-1] must contain ∑i=1 m fi∂2 fi∂xj∂xk evaluated at the point x, for j=1,2,…,n and k=1,2,…,j.

See Also

NagLibrary Namespace
NAG Library Overview
e04hy


E04.E04JC_MONFUN Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04JC_MONFUN Delegate
E04 Class See Also Send Feedback
monfun may be used to monitor the optimization process. It is invoked every time a new trust-region radius is chosen.
If no monitoring is required, monfun may be the dummy monitoring method E04JCP supplied by the NAG Library.

Syntax

C#
public delegate void E04JC_MONFUN(
    int n,
    int nf,
    double[] x,
    double f,
    double rho,
    out int inform
)
Visual Basic
Public Delegate Sub E04JC_MONFUN ( _
    n As Integer, _
    nf As Integer, _
    x As Double(), _
    f As Double, _
    rho As Double, _
    <OutAttribute> ByRef inform As Integer _
)
Visual C++
public delegate void E04JC_MONFUN(
    int n,
    int nf,
    array<double>^ x,
    double f,
    double rho,
    [OutAttribute] int% inform
)
F#
type E04JC_MONFUN =
    delegate of
        n : int *
        nf : int *
        x : float[] *
        f : float *
        rho : float *
        inform : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of independent variables.
nf
Type: System..::..Int32
On entry: the cumulative number of calls made to objfun.
x
Type: array< System..::..Double >[]()[][]
On entry: the current best point.
f
Type: System..::..Double
On entry: the value of objfun at x.
rho
Type: System..::..Double
On entry: a lower bound on the current trust-region radius.
inform
Type: System..::..Int32 %
On exit: must be set to a value describing the action to be taken by the solver on return from monfun. Specifically, if the value is negative the solution of the current problem will terminate immediately; otherwise, computations will continue.

See Also

NagLibrary Namespace
NAG Library Overview
e04jc


E04.E04JC_OBJFUN Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04JC_OBJFUN Delegate
E04 Class See Also Send Feedback
objfun must evaluate the objective function F at a specified vector x.

Syntax

C#
public delegate void E04JC_OBJFUN(
    int n,
    double[] x,
    out double f,
    out int inform
)
Visual Basic
Public Delegate Sub E04JC_OBJFUN ( _
    n As Integer, _
    x As Double(), _
    <OutAttribute> ByRef f As Double, _
    <OutAttribute> ByRef inform As Integer _
)
Visual C++
public delegate void E04JC_OBJFUN(
    int n,
    array<double>^ x,
    [OutAttribute] double% f,
    [OutAttribute] int% inform
)
F#
type E04JC_OBJFUN =
    delegate of
        n : int *
        x : float[] *
        f : float byref *
        inform : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of independent variables.
x
Type: array< System..::..Double >[]()[][]
On entry: x, the vector at which the objective function is to be evaluated.
f
Type: System..::..Double %
On exit: must be set to the value of the objective function at x, unless you have specified termination of the current problem using inform.
inform
Type: System..::..Int32 %
On exit: must be set to a value describing the action to be taken by the solver on return from objfun. Specifically, if the value is negative the solution of the current problem will terminate immediately; otherwise, computations will continue.

See Also

NagLibrary Namespace
NAG Library Overview
e04jc


E04.E04JY_FUNCT1 Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04JY_FUNCT1 Delegate
E04 Class See Also Send Feedback
You must supply funct1 to calculate the value of the function F x at any point x. It should be tested separately before being used with e04jy (see the E04 class).

Syntax

C#
public delegate void E04JY_FUNCT1(
    int n,
    double[] xc,
    out double fc
)
Visual Basic
Public Delegate Sub E04JY_FUNCT1 ( _
    n As Integer, _
    xc As Double(), _
    <OutAttribute> ByRef fc As Double _
)
Visual C++
public delegate void E04JY_FUNCT1(
    int n,
    array<double>^ xc,
    [OutAttribute] double% fc
)
F#
type E04JY_FUNCT1 =
    delegate of
        n : int *
        xc : float[] *
        fc : float byref -> unit

Parameters

n
Type: System..::..Int32
On entry: the number n of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the point x at which the function value is required.
fc
Type: System..::..Double %
On exit: the value of the function F at the current point x.

See Also

NagLibrary Namespace
NAG Library Overview
e04jy


E04.E04KD_FUNCT Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04KD_FUNCT Delegate
E04 Class See Also Send Feedback
funct must evaluate the function F x and its first derivatives ∂F∂xj at a specified point. (However, if you do not wish to calculate F or its first derivatives at a particular x, there is the option of setting a parameter to cause e04kd to terminate immediately.)

Syntax

C#
public delegate void E04KD_FUNCT(
    ref int iflag,
    int n,
    double[] xc,
    ref double fc,
    double[] gc
)
Visual Basic
Public Delegate Sub E04KD_FUNCT ( _
    ByRef iflag As Integer, _
    n As Integer, _
    xc As Double(), _
    ByRef fc As Double, _
    gc As Double() _
)
Visual C++
public delegate void E04KD_FUNCT(
    int% iflag,
    int n,
    array<double>^ xc,
    double% fc,
    array<double>^ gc
)
F#
type E04KD_FUNCT =
    delegate of
        iflag : int byref *
        n : int *
        xc : float[] *
        fc : float byref *
        gc : float[] -> unit

Parameters

iflag
Type: System..::..Int32 %
On entry: will have been set to 1 or 2. The value 1 indicates that only the first derivatives of F need be supplied, and the value 2 indicates that both F itself and its first derivatives must be calculated.
On exit: if it is not possible to evaluate F or its first derivatives at the point given in xc (or if it is wished to stop the calculations for any other reason) you should reset iflag to a negative number and return control to e04kd. e04kd will then terminate immediately, with ifail set to your setting of iflag.
n
Type: System..::..Int32
On entry: the number n of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the point x at which the ∂F∂xj, or F and the ∂F∂xj, are required.
fc
Type: System..::..Double %
On exit: unless iflag=1 on entry or iflag is reset, funct must set fc to the value of the objective function F at the current point x.
gc
Type: array< System..::..Double >[]()[][]
On exit: unless funct resets iflag, it must set gc[j-1] to the value of the first derivative ∂F∂xj at the point x, for j=1,2,…,n.

See Also

NagLibrary Namespace
NAG Library Overview
e04kd


E04.E04KD_MONIT Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04KD_MONIT Delegate
E04 Class See Also Send Feedback
If iprint≥0, you must supply monit which is suitable for monitoring the minimization process. monit must not change the values of any of its parameters.
If iprint<0, a monit with the correct parameter list must still be supplied, although it will not be called.

Syntax

C#
public delegate void E04KD_MONIT(
    int n,
    double[] xc,
    double fc,
    double[] gc,
    int[] istate,
    double gpjnrm,
    double cond,
    bool posdef,
    int niter,
    int nf
)
Visual Basic
Public Delegate Sub E04KD_MONIT ( _
    n As Integer, _
    xc As Double(), _
    fc As Double, _
    gc As Double(), _
    istate As Integer(), _
    gpjnrm As Double, _
    cond As Double, _
    posdef As Boolean, _
    niter As Integer, _
    nf As Integer _
)
Visual C++
public delegate void E04KD_MONIT(
    int n,
    array<double>^ xc,
    double fc,
    array<double>^ gc,
    array<int>^ istate,
    double gpjnrm,
    double cond,
    bool posdef,
    int niter,
    int nf
)
F#
type E04KD_MONIT =
    delegate of
        n : int *
        xc : float[] *
        fc : float *
        gc : float[] *
        istate : int[] *
        gpjnrm : float *
        cond : float *
        posdef : bool *
        niter : int *
        nf : int -> unit

Parameters

n
Type: System..::..Int32
On entry: the number n of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the coordinates of the current point x.
fc
Type: System..::..Double
On entry: the value of F x at the current point x.
gc
Type: array< System..::..Double >[]()[][]
On entry: the value of ∂F∂xj at the current point x, for j=1,2,…,n.
istate
Type: array< System..::..Int32 >[]()[][]
On entry: information about which variables are currently fixed on their bounds and which are free.
If istate[j-1] is negative, xj is currently:
– fixed on its upper bound if istate[j-1]=-1
– fixed on its lower bound if istate[j-1]=-2
– effectively a constant (i.e., lj=uj) if istate[j-1]=-3
If istate[j-1] is positive, its value gives the position of xj in the sequence of free variables.
gpjnrm
Type: System..::..Double
On entry: the Euclidean norm of the current projected gradient vector gz.
cond
Type: System..::..Double
On entry: the ratio of the largest to the smallest elements of the diagonal factor D of the approximated projected Hessian matrix. This quantity is usually a good estimate of the condition number of the projected Hessian matrix. (If no variables are currently free, cond is set to zero.)
posdef
Type: System..::..Boolean
On entry: specifies true or false according to whether or not the approximation to the second derivative matrix for the current subspace, H, is positive definite.
niter
Type: System..::..Int32
On entry: the number of iterations (as outlined in []) which have been performed by e04kd so far.
nf
Type: System..::..Int32
On entry: the number of evaluations of F x so far, i.e., the number of calls of funct with iflag set to 2. Each such call of funct also calculates the first derivatives of F. (In addition to these calls monitored by nf, funct is called with iflag set to 1 not more than n times per iteration.)

See Also

NagLibrary Namespace
NAG Library Overview
e04kd


E04.E04KY_FUNCT2 Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04KY_FUNCT2 Delegate
E04 Class See Also Send Feedback
You must supply funct2 to calculate the values of the function F x and its first derivative ∂F∂xj at any point x. It should be tested separately before being used in conjunction with e04ky (see the E04 class).

Syntax

C#
public delegate void E04KY_FUNCT2(
    int n,
    double[] xc,
    out double fc,
    double[] gc
)
Visual Basic
Public Delegate Sub E04KY_FUNCT2 ( _
    n As Integer, _
    xc As Double(), _
    <OutAttribute> ByRef fc As Double, _
    gc As Double() _
)
Visual C++
public delegate void E04KY_FUNCT2(
    int n,
    array<double>^ xc,
    [OutAttribute] double% fc,
    array<double>^ gc
)
F#
type E04KY_FUNCT2 =
    delegate of
        n : int *
        xc : float[] *
        fc : float byref *
        gc : float[] -> unit

Parameters

n
Type: System..::..Int32
On entry: the number n of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the point x at which the function and derivatives are required.
fc
Type: System..::..Double %
On exit: the value of the function F at the current point x.
gc
Type: array< System..::..Double >[]()[][]
On exit: gc[j-1] must be set to the value of the first derivative ∂F∂xj at the point x, for j=1,2,…,n.

See Also

NagLibrary Namespace
NAG Library Overview
e04ky


E04.E04KZ_FUNCT2 Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04KZ_FUNCT2 Delegate
E04 Class See Also Send Feedback
You must supply this method to calculate the values of the function F x and its first derivatives ∂F∂xj at any point x. It should be tested separately before being used in conjunction with e04kz (see E04 class).

Syntax

C#
public delegate void E04KZ_FUNCT2(
    int n,
    double[] xc,
    out double fc,
    double[] gc
)
Visual Basic
Public Delegate Sub E04KZ_FUNCT2 ( _
    n As Integer, _
    xc As Double(), _
    <OutAttribute> ByRef fc As Double, _
    gc As Double() _
)
Visual C++
public delegate void E04KZ_FUNCT2(
    int n,
    array<double>^ xc,
    [OutAttribute] double% fc,
    array<double>^ gc
)
F#
type E04KZ_FUNCT2 =
    delegate of
        n : int *
        xc : float[] *
        fc : float byref *
        gc : float[] -> unit

Parameters

n
Type: System..::..Int32
On entry: the number n of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the point x at which the function and derivatives are required.
fc
Type: System..::..Double %
On exit: the value of the function F at the current point x,
gc
Type: array< System..::..Double >[]()[][]
On exit: gc[j-1] must be set to the value of the first derivative ∂F∂xj at the point x, for j=1,2,…,n.

See Also

NagLibrary Namespace
NAG Library Overview
e04kz


E04.E04LB_FUNCT Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04LB_FUNCT Delegate
E04 Class See Also Send Feedback
funct must evaluate the function F x and its first derivatives ∂F∂xj at any point x. (However, if you do not wish to calculate F x or its first derivatives at a particular x, there is the option of setting a parameter to cause e04lb to terminate immediately.)

Syntax

C#
public delegate void E04LB_FUNCT(
    ref int iflag,
    int n,
    double[] xc,
    ref double fc,
    double[] gc
)
Visual Basic
Public Delegate Sub E04LB_FUNCT ( _
    ByRef iflag As Integer, _
    n As Integer, _
    xc As Double(), _
    ByRef fc As Double, _
    gc As Double() _
)
Visual C++
public delegate void E04LB_FUNCT(
    int% iflag,
    int n,
    array<double>^ xc,
    double% fc,
    array<double>^ gc
)
F#
type E04LB_FUNCT =
    delegate of
        iflag : int byref *
        n : int *
        xc : float[] *
        fc : float byref *
        gc : float[] -> unit

Parameters

iflag
Type: System..::..Int32 %
On entry: will have been set to 2.
On exit: if it is not possible to evaluate F x or its first derivatives at the point x given in xc (or if it is wished to stop the calculation for any other reason) you should reset iflag to some negative number and return control to e04lb. e04lb will then terminate immediately with ifail set to your setting of iflag.
n
Type: System..::..Int32
On entry: the number n of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the point x at which F and the ∂F∂xj are required.
fc
Type: System..::..Double %
On exit: unless iflag is reset, funct must set fc to the value of the objective function F at the current point x.
gc
Type: array< System..::..Double >[]()[][]
On exit: unless iflag is reset, funct must set gc[j-1] to the value of the first derivative ∂F∂xj at the point x, for j=1,2,…,n.

See Also

NagLibrary Namespace
NAG Library Overview
e04lb


E04.E04LB_H Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04LB_H Delegate
E04 Class See Also Send Feedback
h must calculate the second derivatives of F at any point x. (As with funct, there is the option of causing e04lb to terminate immediately.)

Syntax

C#
public delegate void E04LB_H(
    ref int iflag,
    int n,
    double[] xc,
    double[] fhesl,
    double[] fhesd
)
Visual Basic
Public Delegate Sub E04LB_H ( _
    ByRef iflag As Integer, _
    n As Integer, _
    xc As Double(), _
    fhesl As Double(), _
    fhesd As Double() _
)
Visual C++
public delegate void E04LB_H(
    int% iflag,
    int n,
    array<double>^ xc,
    array<double>^ fhesl,
    array<double>^ fhesd
)
F#
type E04LB_H =
    delegate of
        iflag : int byref *
        n : int *
        xc : float[] *
        fhesl : float[] *
        fhesd : float[] -> unit

Parameters

iflag
Type: System..::..Int32 %
On entry: is set to a non-negative number.
On exit: if h resets iflag to some negative number, e04lb will terminate immediately with ifail set to your setting of iflag.
n
Type: System..::..Int32
On entry: the number n of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the point x at which the second derivatives of F are required.
fhesl
Type: array< System..::..Double >[]()[][]
On exit: unless iflag is reset, h must place the strict lower triangle of the second derivative matrix of F (evaluated at the point x) in fhesl, stored by rows, i.e., set fhesl[i-1i-2/2+j-1]=∂2 F∂xi∂xj xc, for i=2,3,…,n and j=1,2,…,i-1. (The upper triangle is not required because the matrix is symmetric.)
fhesd
Type: array< System..::..Double >[]()[][]
On entry: the value of ∂F∂xj at the point x, for j=1,2,…,n.
These values may be useful in the evaluation of the second derivatives.
On exit: unless iflag is reset, h must place the diagonal elements of the second derivative matrix of F (evaluated at the point x) in fhesd, i.e., set fhesd[j-1]=∂2 F∂xj 2 xc, j=1,2,…,n.

See Also

NagLibrary Namespace
NAG Library Overview
e04lb


E04.E04LB_MONIT Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04LB_MONIT Delegate
E04 Class See Also Send Feedback
If iprint≥0, you must supply monit which is suitable for monitoring the minimization process. monit must not change the values of any of its parameters.
If iprint<0, a monit with the correct parameter list should still be supplied, although it will not be called.

Syntax

C#
public delegate void E04LB_MONIT(
    int n,
    double[] xc,
    double fc,
    double[] gc,
    int[] istate,
    double gpjnrm,
    double cond,
    bool posdef,
    int niter,
    int nf
)
Visual Basic
Public Delegate Sub E04LB_MONIT ( _
    n As Integer, _
    xc As Double(), _
    fc As Double, _
    gc As Double(), _
    istate As Integer(), _
    gpjnrm As Double, _
    cond As Double, _
    posdef As Boolean, _
    niter As Integer, _
    nf As Integer _
)
Visual C++
public delegate void E04LB_MONIT(
    int n,
    array<double>^ xc,
    double fc,
    array<double>^ gc,
    array<int>^ istate,
    double gpjnrm,
    double cond,
    bool posdef,
    int niter,
    int nf
)
F#
type E04LB_MONIT =
    delegate of
        n : int *
        xc : float[] *
        fc : float *
        gc : float[] *
        istate : int[] *
        gpjnrm : float *
        cond : float *
        posdef : bool *
        niter : int *
        nf : int -> unit

Parameters

n
Type: System..::..Int32
On entry: the number n of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the coordinates of the current point x.
fc
Type: System..::..Double
On entry: the value of F x at the current point x.
gc
Type: array< System..::..Double >[]()[][]
On entry: the value of ∂F∂xj at the current point x, for j=1,2,…,n.
istate
Type: array< System..::..Int32 >[]()[][]
On entry: information about which variables are currently fixed on their bounds and which are free.
If istate[j-1] is negative, xj is currently:
– fixed on its upper bound if istate[j-1]=-1;
– fixed on its lower bound if istate[j-1]=-2;
– effectively a constant (i.e., lj=uj) if istate[j-1]=-3.
If istate is positive, its value gives the position of xj in the sequence of free variables.
gpjnrm
Type: System..::..Double
On entry: the Euclidean norm of the projected gradient vector gz.
cond
Type: System..::..Double
On entry: the ratio of the largest to the smallest elements of the diagonal factor D of the projected Hessian matrix (see specification of h). This quantity is usually a good estimate of the condition number of the projected Hessian matrix. (If no variables are currently free, cond is set to zero.)
posdef
Type: System..::..Boolean
On entry: is set true or false according to whether the second derivative matrix for the current subspace, H, is positive definite or not.
niter
Type: System..::..Int32
On entry: the number of iterations (as outlined in []) which have been performed by e04lb so far.
nf
Type: System..::..Int32
On entry: the number of times that funct has been called so far. Thus nf is the number of function and gradient evaluations made so far.

See Also

NagLibrary Namespace
NAG Library Overview
e04lb


E04.E04LY_FUNCT2 Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04LY_FUNCT2 Delegate
E04 Class See Also Send Feedback
You must supply this method to calculate the values of the function F x and its first derivatives ∂F∂xj at any point x. It should be tested separately before being used in conjunction with e04ly (see the E04 class).

Syntax

C#
public delegate void E04LY_FUNCT2(
    int n,
    double[] xc,
    ref double fc,
    double[] gc
)
Visual Basic
Public Delegate Sub E04LY_FUNCT2 ( _
    n As Integer, _
    xc As Double(), _
    ByRef fc As Double, _
    gc As Double() _
)
Visual C++
public delegate void E04LY_FUNCT2(
    int n,
    array<double>^ xc,
    double% fc,
    array<double>^ gc
)
F#
type E04LY_FUNCT2 =
    delegate of
        n : int *
        xc : float[] *
        fc : float byref *
        gc : float[] -> unit

Parameters

n
Type: System..::..Int32
On entry: the number n of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the point x at which the function and its derivatives are required.
fc
Type: System..::..Double %
On exit: the value of the function F at the current point x.
gc
Type: array< System..::..Double >[]()[][]
On exit: gc[j-1] must be set to the value of the first derivative ∂F∂xj at the point x, for j=1,2,…,n.

See Also

NagLibrary Namespace
NAG Library Overview
e04ly


E04.E04LY_HESS2 Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04LY_HESS2 Delegate
E04 Class See Also Send Feedback
You must supply this method to evaluate the elements H ij=∂2 F∂xi∂xj of the matrix of second derivatives of F x at any point x. It should be tested separately before being used in conjunction with e04ly (see the E04 class).

Syntax

C#
public delegate void E04LY_HESS2(
    int n,
    double[] xc,
    double[] heslc,
    double[] hesdc
)
Visual Basic
Public Delegate Sub E04LY_HESS2 ( _
    n As Integer, _
    xc As Double(), _
    heslc As Double(), _
    hesdc As Double() _
)
Visual C++
public delegate void E04LY_HESS2(
    int n,
    array<double>^ xc,
    array<double>^ heslc,
    array<double>^ hesdc
)
F#
type E04LY_HESS2 =
    delegate of
        n : int *
        xc : float[] *
        heslc : float[] *
        hesdc : float[] -> unit

Parameters

n
Type: System..::..Int32
On entry: the number n of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the point x at which the derivatives are required.
heslc
Type: array< System..::..Double >[]()[][]
On exit: hess2 must place the strict lower triangle of the second derivative matrix H in heslc, stored by rows, i.e., set heslc[i-1i-2/2+j-1]=∂2 F∂xi∂xj, for i=2,3,…,n and j=1,2,…,i-1. (The upper triangle is not required because the matrix is symmetric.)
hesdc
Type: array< System..::..Double >[]()[][]
On exit: must contain the diagonal elements of the second derivative matrix, i.e., set hesdc[j-1]=∂2 F∂xj 2, for j=1,2,…,n.

See Also

NagLibrary Namespace
NAG Library Overview
e04ly


E04.E04NF_QPHESS Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04NF_QPHESS Delegate
E04 Class See Also Send Feedback
In general, you need not provide a version of qphess, because a ‘default’ method with name E04NFU/E54NFU is included in the Library. However, the algorithm of e04nf requires only the product of H or HT H and a vector x; and in some cases you may obtain increased efficiency by providing a version of qphess that avoids the need to define the elements of the matrices H or HT H explicitly.
qphess is not referenced if the problem is of type FP or LP, in which case qphess may be the method E04NFU/E54NFU.

Syntax

C#
public delegate void E04NF_QPHESS(
    int n,
    int jthcol,
    double[,] h,
    double[] x,
    double[] hx,
    E04..::..e04nfOptions options
)
Visual Basic
Public Delegate Sub E04NF_QPHESS ( _
    n As Integer, _
    jthcol As Integer, _
    h As Double(,), _
    x As Double(), _
    hx As Double(), _
    options As E04..::..e04nfOptions _
)
Visual C++
public delegate void E04NF_QPHESS(
    int n,
    int jthcol,
    array<double,2>^ h,
    array<double>^ x,
    array<double>^ hx,
    E04..::..e04nfOptions^ options
)
F#
type E04NF_QPHESS =
    delegate of
        n : int *
        jthcol : int *
        h : float[,] *
        x : float[] *
        hx : float[] *
        options : E04..::..e04nfOptions -> unit

Parameters

n
Type: System..::..Int32
On entry: this is the same parameter as supplied to this method. See the description for the top level parameter n.
jthcol
Type: System..::..Int32
On entry: specifies whether or not the vector x is a column of the identity matrix.
jthcol=j>0
The vector x is the jth column of the identity matrix, and hence Hx or HT Hx is the jth column of H or HT H, respectively. This may in some cases require very little computation and qphess may be coded to take advantage of this. However special code is not necessary because x is always stored explicitly in the array x.
jthcol=0
x has no special form.
h
Type: array< System..::..Double ,2>[,](,)[,][,]
On entry: this is the same parameter as supplied to this method. See the description for the top level parameter h.
x
Type: array< System..::..Double >[]()[][]
On entry: the vector x.
hx
Type: array< System..::..Double >[]()[][]
On exit: the product Hx if the problem is of type QP1 or QP2 (the default), or the product HT Hx if the problem is of type QP3 or QP4.
options
Type: NagLibrary..::..E04..::..e04nfOptions

See Also

NagLibrary Namespace
NAG Library Overview
e04nf


E04.E04NK_QPHX Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04NK_QPHX Delegate
E04 Class See Also Send Feedback
For QP problems, you must supply a version of qphx to compute the matrix product Hx. If H has zero rows and columns, it is most efficient to order the variables x=yz T so that
Hx=H 1000yz=H 1 y0,
where the nonlinear variables y appear first as shown. For FP and LP problems, qphx will never be called by e04nk and hence qphx may be the dummy method E04NKU/E54NKU.

Syntax

C#
public delegate void E04NK_QPHX(
    int nstate,
    int ncolh,
    double[] x,
    double[] hx
)
Visual Basic
Public Delegate Sub E04NK_QPHX ( _
    nstate As Integer, _
    ncolh As Integer, _
    x As Double(), _
    hx As Double() _
)
Visual C++
public delegate void E04NK_QPHX(
    int nstate,
    int ncolh,
    array<double>^ x,
    array<double>^ hx
)
F#
type E04NK_QPHX =
    delegate of
        nstate : int *
        ncolh : int *
        x : float[] *
        hx : float[] -> unit

Parameters

nstate
Type: System..::..Int32
On entry: if nstate=1, e04nk is calling qphx for the first time. This parameter setting allows you to save computation time if certain data must be read or calculated only once.
If nstate≥2, e04nk is calling qphx for the last time. This parameter setting allows you to perform some additional computation on the final solution. In general, the last call to qphx is made with nstate=2+ifail (see []).
Otherwise, nstate=0.
ncolh
Type: System..::..Int32
On entry: this is the same parameter ncolh as supplied to e04nk.
x
Type: array< System..::..Double >[]()[][]
On entry: the first ncolh elements of the vector x.
hx
Type: array< System..::..Double >[]()[][]
On exit: the product Hx.

See Also

NagLibrary Namespace
NAG Library Overview
e04nk


E04.E04NQ_QPHX Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04NQ_QPHX Delegate
E04 Class See Also Send Feedback
For QP problems, you must supply a version of qphx to compute the matrix product Hx for a given vector x. If H has rows and columns of zeros, it is most efficient to order x so that the nonlinear variables appear first. For example, if x=y,z T and only y enters the objective quadratically then
Hx=H 1000yz=H 1 y0. (2)
In this case, ncolh should be the dimension of y, and qphx should compute H 1 y. For FP and LP problems, qphx will never be called by e04nq and hence qphx may be the dummy method E04NSH.

Syntax

C#
public delegate void E04NQ_QPHX(
    int ncolh,
    double[] x,
    double[] hx,
    int nstate
)
Visual Basic
Public Delegate Sub E04NQ_QPHX ( _
    ncolh As Integer, _
    x As Double(), _
    hx As Double(), _
    nstate As Integer _
)
Visual C++
public delegate void E04NQ_QPHX(
    int ncolh,
    array<double>^ x,
    array<double>^ hx,
    int nstate
)
F#
type E04NQ_QPHX =
    delegate of
        ncolh : int *
        x : float[] *
        hx : float[] *
        nstate : int -> unit

Parameters

ncolh
Type: System..::..Int32
On entry: this is the same parameter ncolh as supplied to e04nq.
x
Type: array< System..::..Double >[]()[][]
On entry: the first ncolh elements of the vector x.
hx
Type: array< System..::..Double >[]()[][]
On exit: the product Hx. If ncolh is less than the input parameter n, Hx is really the product H 1 y in (2).
nstate
Type: System..::..Int32
On entry: allows you to save computation time if certain data must be read or calculated only once. To preserve this data for a subsequent calculation place it in one of cuser, ruser or iuser .
nstate=1
e04nq is calling qphx for the first time.
nstate=0
There is nothing special about the current call of qphx.
nstate≥2
e04nq is calling qphx for the last time. This parameter setting allows you to perform some additional computation on the final solution.
nstate=2
The current x is optimal.
nstate=3
The problem appears to be infeasible.
nstate=4
The problem appears to be unbounded.
nstate=5
The iterations limit was reached.

See Also

NagLibrary Namespace
NAG Library Overview
e04nq


E04.E04UC_CONFUN Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04UC_CONFUN Delegate
E04 Class See Also Send Feedback
confun must calculate the vector c x of nonlinear constraint functions and (optionally) its Jacobian (=∂c∂x) for a specified n-element vector x. If there are no nonlinear constraints (i.e., ncnln=0), confun will never be called by e04uc and confun may be the dummy method E04UDM. (E04UDM is included in the NAG Library.) If there are nonlinear constraints, the first call to confun will occur before the first call to objfun.

Syntax

C#
public delegate void E04UC_CONFUN(
    ref int mode,
    int ncnln,
    int n,
    int[] needc,
    double[] x,
    double[] c,
    double[,] cjac,
    int nstate
)
Visual Basic
Public Delegate Sub E04UC_CONFUN ( _
    ByRef mode As Integer, _
    ncnln As Integer, _
    n As Integer, _
    needc As Integer(), _
    x As Double(), _
    c As Double(), _
    cjac As Double(,), _
    nstate As Integer _
)
Visual C++
public delegate void E04UC_CONFUN(
    int% mode,
    int ncnln,
    int n,
    array<int>^ needc,
    array<double>^ x,
    array<double>^ c,
    array<double,2>^ cjac,
    int nstate
)
F#
type E04UC_CONFUN =
    delegate of
        mode : int byref *
        ncnln : int *
        n : int *
        needc : int[] *
        x : float[] *
        c : float[] *
        cjac : float[,] *
        nstate : int -> unit

Parameters

mode
Type: System..::..Int32 %
On entry: indicates which values must be assigned during each call of confun. Only the following values need be assigned, for each value of i such that needc[i-1]>0:
mode=0
c[i-1].
mode=1
All available elements in the ith row of cjac.
mode=2
c[i-1] and all available elements in the ith row of cjac.
On exit: may be set to a negative value if you wish to terminate the solution to the current problem. In this case e04uc will terminate with ifail set to mode.
ncnln
Type: System..::..Int32
On entry: nN, the number of nonlinear constraints.
n
Type: System..::..Int32
On entry: n, the number of variables.
needc
Type: array< System..::..Int32 >[]()[][]
On entry: the indices of the elements of c and/or cjac that must be evaluated by confun. If needc[i-1]>0, the ith element of c and/or the available elements of the ith row of cjac (see parameter mode) must be evaluated at x.
x
Type: array< System..::..Double >[]()[][]
On entry: x, the vector of variables at which the constraint functions and/or the available elements of the constraint Jacobian are to be evaluated.
c
Type: array< System..::..Double >[]()[][]
On exit: if needc[i-1]>0 and mode=0 or 2, c[i-1] must contain the value of the ith constraint at x. The remaining elements of c, corresponding to the non-positive elements of needc, are ignored.
cjac
Type: array< System..::..Double ,2>[,](,)[,][,]
On entry: unless Derivative Level=2 or 3, the elements of cjac are set to special values which enable e04uc to detect whether they are changed by confun.
On exit: if needc[i-1]>0 and mode=1 or 2, the ith row of cjac must contain the available elements of the vector ∇ci given by
∇ci=∂ci∂x 1,∂ci∂x 2,…,∂ci∂xn T,
where ∂ci∂xj is the partial derivative of the ith constraint with respect to the jth variable, evaluated at the point x. See also the parameter nstate. The remaining rows of cjac, corresponding to non-positive elements of needc, are ignored.
If all elements of the constraint Jacobian are known (i.e., Derivative Level=2 or 3), any constant elements may be assigned to cjac one time only at the start of the optimization. An element of cjac that is not subsequently assigned in confun will retain its initial value throughout. Constant elements may be loaded into cjac either before the call to e04uc or during the first call to confun (signalled by the value nstate=1). The ability to preload constants is useful when many Jacobian elements are identically zero, in which case cjac may be initialized to zero and nonzero elements may be reset by confun.
Note that constant nonzero elements do affect the values of the constraints. Thus, if cjac[i-1,j-1] is set to a constant value, it need not be reset in subsequent calls to confun, but the value cjac[i-1,j-1]×x[j-1] must nonetheless be added to c[i-1]. For example, if cjac[0,0]=2 and cjac[0,1]=-5 then the term 2×x[0]-5×x[1] must be included in the definition of c[0].
It must be emphasized that, if Derivative Level=0 or 1, unassigned elements of cjac are not treated as constant; they are estimated by finite differences, at nontrivial expense. If you do not supply a value for the optional parameter Difference Interval, an interval for each element of x is computed automatically at the start of the optimization. The automatic procedure can usually identify constant elements of cjac, which are then computed once only by finite differences.
nstate
Type: System..::..Int32
On entry: if nstate=1 then e04uc is calling confun for the first time. This parameter setting allows you to save computation time if certain data must be read or calculated only once.

See Also

NagLibrary Namespace
NAG Library Overview
e04uc


E04.E04UC_OBJFUN Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04UC_OBJFUN Delegate
E04 Class See Also Send Feedback
objfun must calculate the objective function F x and (optionally) its gradient g x=∂F∂x for a specified n-vector x.

Syntax

C#
public delegate void E04UC_OBJFUN(
    ref int mode,
    int n,
    double[] x,
    ref double objf,
    double[] objgrd,
    int nstate
)
Visual Basic
Public Delegate Sub E04UC_OBJFUN ( _
    ByRef mode As Integer, _
    n As Integer, _
    x As Double(), _
    ByRef objf As Double, _
    objgrd As Double(), _
    nstate As Integer _
)
Visual C++
public delegate void E04UC_OBJFUN(
    int% mode,
    int n,
    array<double>^ x,
    double% objf,
    array<double>^ objgrd,
    int nstate
)
F#
type E04UC_OBJFUN =
    delegate of
        mode : int byref *
        n : int *
        x : float[] *
        objf : float byref *
        objgrd : float[] *
        nstate : int -> unit

Parameters

mode
Type: System..::..Int32 %
On entry: indicates which values must be assigned during each call of objfun. Only the following values need be assigned:
mode=0
objf.
mode=1
All available elements of objgrd.
mode=2
objf and all available elements of objgrd.
On exit: may be set to a negative value if you wish to terminate the solution to the current problem. In this case e04uc will terminate with ifail set to mode.
n
Type: System..::..Int32
On entry: n, the number of variables.
x
Type: array< System..::..Double >[]()[][]
On entry: x, the vector of variables at which the objective function and/or all available elements of its gradient are to be evaluated.
objf
Type: System..::..Double %
On exit: if mode=0 or 2, objf must be set to the value of the objective function at x.
objgrd
Type: array< System..::..Double >[]()[][]
On entry: the elements of objgrd are set to special values which enable e04uc to detect whether they are changed by objfun.
On exit: if mode=1 or 2, objgrd must return the available elements of the gradient evaluated at x.
nstate
Type: System..::..Int32
On entry: if nstate=1 then e04uc is calling objfun for the first time. This parameter setting allows you to save computation time if certain data must be read or calculated only once.

See Also

NagLibrary Namespace
NAG Library Overview
e04uc


E04.E04UG_CONFUN Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04UG_CONFUN Delegate
E04 Class See Also Send Feedback
confun must calculate the vector F x of nonlinear constraint functions and (optionally) its Jacobian =∂F∂x for a specified n 1′′ (≤n) element vector x. If there are no nonlinear constraints (i.e., ncnln=0), confun will never be called by e04ug and confun may be the dummy method E04UGM. (E04UGM is included in the NAG Library.) If there are nonlinear constraints, the first call to confun will occur before the first call to objfun.

Syntax

C#
public delegate void E04UG_CONFUN(
    ref int mode,
    int ncnln,
    int njnln,
    int nnzjac,
    double[] x,
    double[] f,
    double[] fjac,
    int nstate
)
Visual Basic
Public Delegate Sub E04UG_CONFUN ( _
    ByRef mode As Integer, _
    ncnln As Integer, _
    njnln As Integer, _
    nnzjac As Integer, _
    x As Double(), _
    f As Double(), _
    fjac As Double(), _
    nstate As Integer _
)
Visual C++
public delegate void E04UG_CONFUN(
    int% mode,
    int ncnln,
    int njnln,
    int nnzjac,
    array<double>^ x,
    array<double>^ f,
    array<double>^ fjac,
    int nstate
)
F#
type E04UG_CONFUN =
    delegate of
        mode : int byref *
        ncnln : int *
        njnln : int *
        nnzjac : int *
        x : float[] *
        f : float[] *
        fjac : float[] *
        nstate : int -> unit

Parameters

mode
Type: System..::..Int32 %
On entry: indicates which values must be assigned during each call of confun. Only the following values need be assigned:
mode=0
f.
mode=1
All available elements of fjac.
mode=2
f and all available elements of fjac.
On exit: you may set to a negative value as follows:
mode≤-2
The solution to the current problem is terminated and in this case e04ug will terminate with ifail set to mode.
mode=-1
The nonlinear constraint functions cannot be calculated at the current x. e04ug will then terminate with ifail=-1 unless this occurs during the linesearch; in this case, the linesearch will shorten the step and try again.
ncnln
Type: System..::..Int32
On entry: nN, the number of nonlinear constraints. These must be the first ncnln constraints in the problem.
njnln
Type: System..::..Int32
On entry: n 1′′, the number of nonlinear variables. These must be the first njnln variables in the problem.
nnzjac
Type: System..::..Int32
On entry: the number of nonzero elements in the constraint Jacobian. Note that nnzjac will usually be less than ncnln×njnln.
x
Type: array< System..::..Double >[]()[][]
On entry: x, the vector of nonlinear Jacobian variables at which the nonlinear constraint functions and/or the available elements of the constraint Jacobian are to be evaluated.
f
Type: array< System..::..Double >[]()[][]
On exit: if mode=0 or 2, f[i-1] must contain the value of the ith nonlinear constraint function at x.
fjac
Type: array< System..::..Double >[]()[][]
On entry: the elements of fjac are set to special values which enable e04ug to detect whether they are changed by confun.
On exit: if mode=1 or 2, fjac must return the available elements of the constraint Jacobian evaluated at x. These elements must be stored in exactly the same positions as implied by the definitions of the arrays a, ha and ka. If optional parameter Derivative Level=2 or 3, the value of any constant Jacobian element not defined by confun will be obtained directly from a. Note that the method does not perform any internal checks for consistency (except indirectly via the optional parameter Verify Level), so great care is essential.
nstate
Type: System..::..Int32
On entry: if nstate=1, then e04ug is calling confun for the first time. This parameter setting allows you to save computation time if certain data must be read or calculated only once.
If nstate≥2, then e04ug is calling confun for the last time. This parameter setting allows you to perform some additional computation on the final solution. In general, the last call to confun is made with nstate=2+ifail (see []).
Otherwise, nstate=0.

See Also

NagLibrary Namespace
NAG Library Overview
e04ug


E04.E04UG_OBJFUN Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04UG_OBJFUN Delegate
E04 Class See Also Send Feedback
objfun must calculate the nonlinear part of the objective function f x and (optionally) its gradient =∂f∂x for a specified n 1′ (≤n) element vector x. If there are no nonlinear objective variables (i.e., nonln=0), objfun will never be called by e04ug and objfun may be the dummy method E04UGN. (E04UGN is included in the NAG Library.)

Syntax

C#
public delegate void E04UG_OBJFUN(
    ref int mode,
    int nonln,
    double[] x,
    ref double objf,
    double[] objgrd,
    int nstate
)
Visual Basic
Public Delegate Sub E04UG_OBJFUN ( _
    ByRef mode As Integer, _
    nonln As Integer, _
    x As Double(), _
    ByRef objf As Double, _
    objgrd As Double(), _
    nstate As Integer _
)
Visual C++
public delegate void E04UG_OBJFUN(
    int% mode,
    int nonln,
    array<double>^ x,
    double% objf,
    array<double>^ objgrd,
    int nstate
)
F#
type E04UG_OBJFUN =
    delegate of
        mode : int byref *
        nonln : int *
        x : float[] *
        objf : float byref *
        objgrd : float[] *
        nstate : int -> unit

Parameters

mode
Type: System..::..Int32 %
On entry: indicates which values must be assigned during each call of objfun. Only the following values need be assigned:
mode=0
objf.
mode=1
All available elements of objgrd.
mode=2
objf and all available elements of objgrd.
On exit: you may set to a negative value as follows:
mode≤-2
The solution to the current problem is terminated and in this case e04ug will terminate with ifail set to mode.
mode=-1
The nonlinear part of the objective function cannot be calculated at the current x. e04ug will then terminate with ifail=-1 unless this occurs during the linesearch; in this case, the linesearch will shorten the step and try again.
nonln
Type: System..::..Int32
On entry: n 1′, the number of nonlinear objective variables. These must be the first nonln variables in the problem.
x
Type: array< System..::..Double >[]()[][]
On entry: x, the vector of nonlinear variables at which the nonlinear part of the objective function and/or all available elements of its gradient are to be evaluated.
objf
Type: System..::..Double %
On exit: if mode=0 or 2, objf must be set to the value of the objective function at x.
objgrd
Type: array< System..::..Double >[]()[][]
On entry: the elements of objgrd are set to special values which enable e04ug to detect whether they are changed by objfun.
On exit: if mode=1 or 2, objgrd must return the available elements of the gradient evaluated at x.
nstate
Type: System..::..Int32
On entry: if nstate=1, e04ug is calling objfun for the first time. This parameter setting allows you to save computation time if certain data must be read or calculated only once.
If nstate≥2, e04ug is calling objfun for the last time. This parameter setting allows you to perform some additional computation on the final solution. In general, the last call to objfun is made with nstate=2+ifail (see []).
Otherwise, nstate=0.

See Also

NagLibrary Namespace
NAG Library Overview
e04ug


E04.E04US_CONFUN Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04US_CONFUN Delegate
E04 Class See Also Send Feedback
confun must calculate the vector c x of nonlinear constraint functions and (optionally) its Jacobian (=∂c∂x) for a specified n-element vector x. If there are no nonlinear constraints (i.e., ncnln=0), confun will never be called by e04us and confun may be the dummy method E04UDM. (E04UDM is included in the NAG Library.) If there are nonlinear constraints, the first call to confun will occur before the first call to objfun.

Syntax

C#
public delegate void E04US_CONFUN(
    ref int mode,
    int ncnln,
    int n,
    int[] needc,
    double[] x,
    double[] c,
    double[,] cjac,
    int nstate
)
Visual Basic
Public Delegate Sub E04US_CONFUN ( _
    ByRef mode As Integer, _
    ncnln As Integer, _
    n As Integer, _
    needc As Integer(), _
    x As Double(), _
    c As Double(), _
    cjac As Double(,), _
    nstate As Integer _
)
Visual C++
public delegate void E04US_CONFUN(
    int% mode,
    int ncnln,
    int n,
    array<int>^ needc,
    array<double>^ x,
    array<double>^ c,
    array<double,2>^ cjac,
    int nstate
)
F#
type E04US_CONFUN =
    delegate of
        mode : int byref *
        ncnln : int *
        n : int *
        needc : int[] *
        x : float[] *
        c : float[] *
        cjac : float[,] *
        nstate : int -> unit

Parameters

mode
Type: System..::..Int32 %
On entry: indicates which values must be assigned during each call of confun. Only the following values need be assigned, for each value of i such that needc[i-1]>0:
mode=0
c[i-1].
mode=1
All available elements in the ith row of cjac.
mode=2
c[i-1] and all available elements in the ith row of cjac.
On exit: may be set to a negative value if you wish to terminate the solution to the current problem, and in this case e04us will terminate with ifail set to mode.
ncnln
Type: System..::..Int32
On entry: nN, the number of nonlinear constraints.
n
Type: System..::..Int32
On entry: n, the number of variables.
needc
Type: array< System..::..Int32 >[]()[][]
On entry: the indices of the elements of c and/or cjac that must be evaluated by confun. If needc[i-1]>0, then the ith element of c and/or the available elements of the ith row of cjac (see parameter mode) must be evaluated at x.
x
Type: array< System..::..Double >[]()[][]
On entry: x, the vector of variables at which the constraint functions and/or all available elements of the constraint Jacobian are to be evaluated.
c
Type: array< System..::..Double >[]()[][]
On exit: if needc[i-1]>0 and mode=0 or 2, c[i-1] must contain the value of the ith constraint at x. The remaining elements of c, corresponding to the non-positive elements of needc, are ignored.
cjac
Type: array< System..::..Double ,2>[,](,)[,][,]
On entry: is set to a special value.
On exit: if needc[i-1]>0 and mode=1 or 2, the ith row of cjac must contain the available elements of the vector ∇ci given by
∇ci=∂ci∂x 1,∂ci∂x 2,…,∂ci∂xn T,
where ∂ci∂xj is the partial derivative of the ith constraint with respect to the jth variable, evaluated at the point x. See also the parameter nstate. The remaining rows of cjac, corresponding to non-positive elements of needc, are ignored.
If all elements of the constraint Jacobian are known (i.e., Derivative Level=2 or 3), any constant elements may be assigned to cjac one time only at the start of the optimization. An element of cjac that is not subsequently assigned in confun will retain its initial value throughout. Constant elements may be loaded into cjac either before the call to e04us or during the first call to confun (signalled by the value nstate=1). The ability to preload constants is useful when many Jacobian elements are identically zero, in which case cjac may be initialized to zero and nonzero elements may be reset by confun.
Note that constant nonzero elements do affect the values of the constraints. Thus, if cjac[i-1,j-1] is set to a constant value, it need not be reset in subsequent calls to confun, but the value cjac[i-1,j-1]×x[j-1] must nonetheless be added to c[i-1]. For example, if cjac[0,0]=2 and cjac[0,1]=-5, then the term 2×x[0]-5×x[1] must be included in the definition of c[0].
It must be emphasized that, if Derivative Level=0 or 1, unassigned elements of cjac are not treated as constant; they are estimated by finite differences, at nontrivial expense. If you do not supply a value for the optional parameter Difference Interval, an interval for each element of x is computed automatically at the start of the optimization. The automatic procedure can usually identify constant elements of cjac, which are then computed once only by finite differences.
nstate
Type: System..::..Int32
On entry: if nstate=1 then e04us is calling confun for the first time. This parameter setting allows you to save computation time if certain data must be read or calculated only once.

See Also

NagLibrary Namespace
NAG Library Overview
e04us


E04.E04US_OBJFUN Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04US_OBJFUN Delegate
E04 Class See Also Send Feedback
objfun must calculate either the ith element of the vector f x=f 1 x,f 2 x,…,fm x T or all m elements of f x and (optionally) its Jacobian (=∂f∂x) for a specified n-element vector x.

Syntax

C#
public delegate void E04US_OBJFUN(
    ref int mode,
    int m,
    int n,
    int needfi,
    double[] x,
    double[] f,
    double[,] fjac,
    int nstate
)
Visual Basic
Public Delegate Sub E04US_OBJFUN ( _
    ByRef mode As Integer, _
    m As Integer, _
    n As Integer, _
    needfi As Integer, _
    x As Double(), _
    f As Double(), _
    fjac As Double(,), _
    nstate As Integer _
)
Visual C++
public delegate void E04US_OBJFUN(
    int% mode,
    int m,
    int n,
    int needfi,
    array<double>^ x,
    array<double>^ f,
    array<double,2>^ fjac,
    int nstate
)
F#
type E04US_OBJFUN =
    delegate of
        mode : int byref *
        m : int *
        n : int *
        needfi : int *
        x : float[] *
        f : float[] *
        fjac : float[,] *
        nstate : int -> unit

Parameters

mode
Type: System..::..Int32 %
On entry: indicates which values must be assigned during each call of objfun. Only the following values need be assigned:
mode=0 and needfi=i, where i>0
f[i-1].
mode=0 and needfi<0
f.
mode=1 and needfi<0
All available elements of fjac.
mode=2 and needfi<0
f and all available elements of fjac.
On exit: may be set to a negative value if you wish to terminate the solution to the current problem, and in this case e04us will terminate with ifail set to mode.
m
Type: System..::..Int32
On entry: m, the number of subfunctions.
n
Type: System..::..Int32
On entry: n, the number of variables.
needfi
Type: System..::..Int32
On entry: if needfi=i>0, only the ith element of f x needs to be evaluated at x; the remaining elements need not be set. This can result in significant computational savings when m≫n.
x
Type: array< System..::..Double >[]()[][]
On entry: x, the vector of variables at which f x and/or all available elements of its Jacobian are to be evaluated.
f
Type: array< System..::..Double >[]()[][]
On exit: if mode=0 and needfi=i>0, f[i-1] must contain the value of fi at x.
If mode=0 or 2 and needfi<0, f[i-1] must contain the value of fi at x, for i=1,2,…,m.
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
On entry: is set to a special value.
On exit: if mode=1 or 2 and needfi<0, the ith row of fjac must contain the available elements of the vector ∇fi given by
∇fi=∂fi∂x 1,∂fi∂x 2,…,∂fi∂xn T,
evaluated at the point x. See also the parameter nstate.
nstate
Type: System..::..Int32
On entry: if nstate=1 then e04us is calling objfun for the first time. This parameter setting allows you to save computation time if certain data must be read or calculated only once.

See Also

NagLibrary Namespace
NAG Library Overview
e04us


E04.E04VH_USRFUN Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04VH_USRFUN Delegate
E04 Class See Also Send Feedback
usrfun must define the nonlinear portion f x of the problem functions F x=f x+Ax, along with its gradient elements G ij x=∂fi x∂xj. (A dummy method is needed even if f≡0 and all functions are linear.)
In general, usrfun should return all function and gradient values on every entry except perhaps the last. This provides maximum reliability and corresponds to the default option setting, Derivative Option=1.
The elements of G x are stored in the array g 1:usrfun_leng in the order specified by the input arrays igfun and jgvar.
In practice it is often convenient not to code gradients. e04vh is able to estimate them by finite differences, using a call to usrfun for each variable xj for which some ∂fi x∂xj needs to be estimated. However, this reduces the reliability of the optimization algorithm, and it can be very expensive if there are many such variables xj.
As a compromise, e04vh allows you to code as many gradients as you like. This option is implemented as follows. Just before usrfun is called, each element of the derivative array g is initialized to a specific value. On exit, any element retaining that value must be estimated by finite differences.
Some rules of thumb follow:
(i) | for maximum reliability, compute all gradients;
(ii) | if the gradients are expensive to compute, specify optional parameter Nonderivative Linesearch and use the value of the input parameter needg to avoid computing them on certain entries. (There is no need to compute gradients if needg=0 on entry to usrfun.);
(iii) | if not all gradients are known, you must specify Derivative Option=0. You should still compute as many gradients as you can. (It often happens that some of them are constant or zero.);
(iv) | again, if the known gradients are expensive, don't compute them if needg=0 on entry to usrfun;
(v) | use the input parameter status to test for special actions on the first or last entries;
(vi) | while usrfun is being developed, use the optional parameter Verify Level to check the computation of gradients that are supposedly known;
(vii) | usrfun is not called until the linear constraints and bounds on x are satisfied. This helps confine x to regions where the functions fi x are likely to be defined. However, be aware of the optional parameter Minor Feasibility Tolerance if the functions have singularities on the constraint boundaries;
(viii) | set status=-1 if some of the functions are undefined. The linesearch will shorten the step and try again;
(ix) | set status≤-2 if you want e04vh to stop.

Syntax

C#
public delegate void E04VH_USRFUN(
    ref int status,
    int n,
    double[] x,
    int needf,
    int nf,
    double[] f,
    int needg,
    double[] g
)
Visual Basic
Public Delegate Sub E04VH_USRFUN ( _
    ByRef status As Integer, _
    n As Integer, _
    x As Double(), _
    needf As Integer, _
    nf As Integer, _
    f As Double(), _
    needg As Integer, _
    g As Double() _
)
Visual C++
public delegate void E04VH_USRFUN(
    int% status,
    int n,
    array<double>^ x,
    int needf,
    int nf,
    array<double>^ f,
    int needg,
    array<double>^ g
)
F#
type E04VH_USRFUN =
    delegate of
        status : int byref *
        n : int *
        x : float[] *
        needf : int *
        nf : int *
        f : float[] *
        needg : int *
        g : float[] -> unit

Parameters

status
Type: System..::..Int32 %
On entry: indicates the first and last calls to usrfun.
status=0
There is nothing special about the current call to usrfun.
status=1
e04vh is calling your method for the first time. You may wish to do something special such as read data from a file.
status≥2
e04vh is calling your method for the last time. This parameter setting allows you to perform some additional computation on the final solution.
status=2
The current x is optimal.
status=3
The problem appears to be infeasible.
status=4
The problem appears to be unbounded.
status=5
An iterations limit was reached.
If the functions are expensive to evaluate, it may be desirable to do nothing on the last call. The first executable statement could be
On exit: may be used to indicate that you are unable to evaluate f or its gradients at the current x. (For example, the problem functions may not be defined there.)
During the linesearch, f x is evaluated at points x=xk+α pk for various step lengths α, where f xk has already been evaluated satisfactorily. For any such x, if you set status=-1, e04vh will reduce α and evaluate f again (closer to xk, where f xk is more likely to be defined).
If for some reason you wish to terminate the current problem, set status≤-2.
n
Type: System..::..Int32
On entry: n, the number of variables, as defined in the call to e04vh.
x
Type: array< System..::..Double >[]()[][]
On entry: the variables x at which the problem functions are to be calculated. The array x must not be altered.
needf
Type: System..::..Int32
On entry: indicates whether f must be assigned during this call of usrfun.
needf=0
f is not required and is ignored.
needf>0
The components of f x corresponding to the nonlinear part of F x must be calculated and assigned to f.
If Fi x is linear and completely defined by the ith row of A, Ai′, then the associated value fi x is ignored and need not be assigned. However, if Fi x has a nonlinear portion fi x that happens to be zero at x, then it is still necessary to set fi x=0. If the linear part Ai′ of a nonlinear Fi x is provided using the arrays iafun, javar and a, then it must not be computed again as part of fi x.
To simplify the code, you may ignore the value of needf and compute f x on every entry to usrfun.
needf may also be ignored with Derivative Linesearch and Derivative Option=1. In this case, needf is always 1, and f must always be assigned.
nf
Type: System..::..Int32
On entry: is the length of the full vector F x=f x+Ax as defined in the call to e04vh.
f
Type: array< System..::..Double >[]()[][]
On entry: concerns the calculation of f x.
On exit: f contains the computed functions f x (except perhaps if needf=0).
needg
Type: System..::..Int32
On entry: indicates whether g must be assigned during this call of usrfun.
needg=0
g is not required and is ignored.
needg>0
The partial derivatives of f x must be calculated and assigned to g. The value of g[k-1] should be ∂fi x∂xj, where i=igfun[k-1], j=jgvar[k-1] and k=1,2,…,leng.
g
Type: array< System..::..Double >[]()[][]
On entry: concerns the calculations of the derivatives of the function f x.
On exit: contains the computed derivatives G x (unless needg=0).
These derivative elements must be stored in g in exactly the same positions as implied by the definitions of arrays igfun and jgvar. There is no internal check for consistency (except indirectly via the optional parameter Verify Level), so great care is essential.

See Also

NagLibrary Namespace
NAG Library Overview
e04vh


E04.E04VJ_USRFUN Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04VJ_USRFUN Delegate
E04 Class See Also Send Feedback
usrfun must define the problem functions F x. This method is passed to e04vj as the external parameter usrfun.

Syntax

C#
public delegate void E04VJ_USRFUN(
    ref int status,
    int n,
    double[] x,
    int needf,
    int nf,
    double[] f,
    int needg,
    double[] g
)
Visual Basic
Public Delegate Sub E04VJ_USRFUN ( _
    ByRef status As Integer, _
    n As Integer, _
    x As Double(), _
    needf As Integer, _
    nf As Integer, _
    f As Double(), _
    needg As Integer, _
    g As Double() _
)
Visual C++
public delegate void E04VJ_USRFUN(
    int% status,
    int n,
    array<double>^ x,
    int needf,
    int nf,
    array<double>^ f,
    int needg,
    array<double>^ g
)
F#
type E04VJ_USRFUN =
    delegate of
        status : int byref *
        n : int *
        x : float[] *
        needf : int *
        nf : int *
        f : float[] *
        needg : int *
        g : float[] -> unit

Parameters

status
Type: System..::..Int32 %
On entry: indicates the first call to usrfun.
status=0
There is nothing special about the current call to usrfun.
status=1
e04vj is calling your method for the first time. Some data may need to be input or computed and saved.
On exit: may be used to indicate that you are unable to evaluate F at the current x. (For example, the problem functions may not be defined there).
e04vj evaluates F x at random perturbation of the initial point x, say xp. If the functions cannot be evaluated at xp, you can set status=-1, e04vj will use another random perturbation.
If for some reason you wish to terminate the current problem, set status≤-2.
n
Type: System..::..Int32
On entry: n, the number of variables, as defined in the call to e04vj.
x
Type: array< System..::..Double >[]()[][]
On entry: the variables x at which the problem functions are to be calculated. The array x must not be altered.
needf
Type: System..::..Int32
On entry: indicates if f must be assigned during the call to usrfun (see f).
nf
Type: System..::..Int32
On entry: nf, the number of problem functions.
f
Type: array< System..::..Double >[]()[][]
On entry: this will be set by e04vj.
On exit: the computed F x according to the setting of needf.
If needf=0, f is not required and is ignored.
If needf>0, the components of F x must be calculated and assigned to f. e04vj will always call usrfun with needf>0.
To simplify the code, you may ignore the value of needf and compute F x on every entry to usrfun.
needg
Type: System..::..Int32
On entry: e04vj will call usrfun with needg=0 to indicate that g is not required.
g
Type: array< System..::..Double >[]()[][]
On entry: concerns the calculations of the derivatives of the function f x.
On exit: e04vj will always call usrfun with needg=0: g is not required to be set on exit but must be declared correctly.

See Also

NagLibrary Namespace
NAG Library Overview
e04vj


E04.E04WD_CONFUN Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04WD_CONFUN Delegate
E04 Class See Also Send Feedback
confun must calculate the vector c x of nonlinear constraint functions and (optionally) its Jacobian, ∂c∂x, for a specified n-vector x. If there are no nonlinear constraints (i.e., ncnln=0), e04wd will never call confun, so it may be the dummy method E04WDP. (E04WDP is included in the NAG Library). If there are nonlinear constraints, the first call to confun will occur before the first call to objfun.
If all constraint gradients (Jacobian elements) are known (i.e., Derivative Level=2 or 3), any constant elements may be assigned to cjac once only at the start of the optimization. An element of cjac that is not subsequently assigned in confun will retain its initial value throughout. Constant elements may be loaded in cjac during the first call to confun (signalled by the value of nstate=1). The ability to preload constants is useful when many Jacobian elements are identically zero, in which case cjac may be initialized to zero and nonzero elements may be reset by confun.
It must be emphasized that, if Derivative Level<2, unassigned elements of cjac are not treated as constant; they are estimated by finite differences, at nontrivial expense.

Syntax

C#
public delegate void E04WD_CONFUN(
    ref int mode,
    int ncnln,
    int n,
    int[] needc,
    double[] x,
    double[] ccon,
    double[,] cjac,
    int nstate
)
Visual Basic
Public Delegate Sub E04WD_CONFUN ( _
    ByRef mode As Integer, _
    ncnln As Integer, _
    n As Integer, _
    needc As Integer(), _
    x As Double(), _
    ccon As Double(), _
    cjac As Double(,), _
    nstate As Integer _
)
Visual C++
public delegate void E04WD_CONFUN(
    int% mode,
    int ncnln,
    int n,
    array<int>^ needc,
    array<double>^ x,
    array<double>^ ccon,
    array<double,2>^ cjac,
    int nstate
)
F#
type E04WD_CONFUN =
    delegate of
        mode : int byref *
        ncnln : int *
        n : int *
        needc : int[] *
        x : float[] *
        ccon : float[] *
        cjac : float[,] *
        nstate : int -> unit

Parameters

mode
Type: System..::..Int32 %
On entry: is set by e04wd to indicate which values must be assigned during each call of confun. Only the following values need be assigned, for each value of i such that needc[i-1]>0:
mode=0
The components of ccon corresponding to positive values in needc must be set. Other components and the array cjac are ignored.
mode=1
The known components of the rows of cjac corresponding to positive values in needc must be set. Other rows of cjac and the array ccon will be ignored.
mode=2
Only the elements of ccon corresponding to positive values of needc need to be set (and similarly for the known components of the rows of cjac).
On exit: may be used to indicate that you are unable or unwilling to evaluate the constraint functions at the current x.
During the linesearch, the constraint functions are evaluated at points of the form x=xk+α pk after they have already been evaluated satisfactorily at xk. At any such α, if you set mode=-1, e04wd will evaluate the functions at some point closer to xk (where they are more likely to be defined).
If for some reason you wish to terminate the current problem, set mode<-1.
ncnln
Type: System..::..Int32
On entry: nN, the number of nonlinear constraints.
n
Type: System..::..Int32
On entry: n, the number of variables.
needc
Type: array< System..::..Int32 >[]()[][]
On entry: the indices of the elements of ccon and/or cjac that must be evaluated by confun. If needc[i-1]>0, the ith element of ccon and/or the available elements of the ith row of cjac (see parameter mode) must be evaluated at x.
x
Type: array< System..::..Double >[]()[][]
On entry: x, the vector of variables at which the constraint functions and/or the available elements of the constraint Jacobian are to be evaluated.
ccon
Type: array< System..::..Double >[]()[][]
On exit: if needc[i-1]>0 and mode=0 or 2, ccon[i-1] must contain the value of the ith constraint at x. The remaining elements of ccon, corresponding to the non-positive elements of needc, are ignored.
cjac
Type: array< System..::..Double ,2>[,](,)[,][,]
On entry: the elements of cjac are set to special values that enable e04wd to detect whether they are reset by confun.
On exit: if needc[i-1]>0 and mode=1 or 2, the ith row of cjac must contain the available elements of the vector ∇ci given by
∇ci=∂ci∂x 1,∂ci∂x 2,…,∂ci∂xn T,
where ∂ci∂xj is the partial derivative of the ith constraint with respect to the jth variable, evaluated at the point x. See also the parameter nstate. The remaining rows of cjac, corresponding to non-positive elements of needc, are ignored.
If all elements of the constraint Jacobian are known (i.e., Derivative Level=2 or 3), any constant elements may be assigned to cjac one time only at the start of the optimization. An element of cjac that is not subsequently assigned in confun will retain its initial value throughout. Constant elements may be loaded into cjac during the first call to confun (signalled by the value nstate=1). The ability to preload constants is useful when many Jacobian elements are identically zero, in which case cjac may be initialized to zero and nonzero elements may be reset by confun.
Note that constant nonzero elements do affect the values of the constraints. Thus, if cjac[i-1,j-1] is set to a constant value, it need not be reset in subsequent calls to confun, but the value cjac[i-1,j-1]×x[j-1] must nonetheless be added to ccon[i-1]. For example, if cjac[0,0]=2 and cjac[0,1]=-5 then the term 2×x[0]-5×x[1] must be included in the definition of ccon[0].
It must be emphasized that, if Derivative Level=0 or 1, unassigned elements of cjac are not treated as constant; they are estimated by finite differences, at nontrivial expense. If you do not supply a value for the optional parameter Difference Interval, an interval for each element of x is computed automatically at the start of the optimization. The automatic procedure can usually identify constant elements of cjac, which are then computed once only by finite differences.
nstate
Type: System..::..Int32
On entry: if nstate=1 then e04wd is calling confun for the first time. This parameter setting allows you to save computation time if certain data must be read or calculated only once.

See Also

NagLibrary Namespace
NAG Library Overview
e04wd


E04.E04WD_OBJFUN Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04WD_OBJFUN Delegate
E04 Class See Also Send Feedback
objfun must calculate the objective function F x and (optionally) its gradient g x=∂F∂x for a specified n-vector x.

Syntax

C#
public delegate void E04WD_OBJFUN(
    ref int mode,
    int n,
    double[] x,
    ref double objf,
    double[] grad,
    int nstate
)
Visual Basic
Public Delegate Sub E04WD_OBJFUN ( _
    ByRef mode As Integer, _
    n As Integer, _
    x As Double(), _
    ByRef objf As Double, _
    grad As Double(), _
    nstate As Integer _
)
Visual C++
public delegate void E04WD_OBJFUN(
    int% mode,
    int n,
    array<double>^ x,
    double% objf,
    array<double>^ grad,
    int nstate
)
F#
type E04WD_OBJFUN =
    delegate of
        mode : int byref *
        n : int *
        x : float[] *
        objf : float byref *
        grad : float[] *
        nstate : int -> unit

Parameters

mode
Type: System..::..Int32 %
On entry: is set by e04wd to indicate which values must be assigned during each call of objfun. Only the following values need be assigned:
mode=0
objf.
mode=1
All available elements of grad.
mode=2
objf and all available elements of grad.
On exit: may be used to indicate that you are unable or unwilling to evaluate the objective function at the current x.
During the linesearch, the function is evaluated at points of the form x=xk+α pk after they have already been evaluated satisfactorily at xk. For any such x, if you set mode=-1, e04wd will reduce α and evaluate the functions again (closer to xk, where they are more likely to be defined).
If for some reason you wish to terminate the current problem, set mode<-1.
n
Type: System..::..Int32
On entry: n, the number of variables.
x
Type: array< System..::..Double >[]()[][]
On entry: x, the vector of variables at which the objective function and/or all available elements of its gradient are to be evaluated.
objf
Type: System..::..Double %
On exit: if mode=0 or 2, objf must be set to the value of the objective function at x.
grad
Type: array< System..::..Double >[]()[][]
On entry: the elements of grad are set to special values.
On exit: if mode=1 or 2, grad must return the available elements of the gradient evaluated at x, i.e., grad[i-1] contains the partial derivative ∂F∂xi.
nstate
Type: System..::..Int32
On entry: if nstate=1 then e04wd is calling objfun for the first time. This parameter setting allows you to save computation time if certain data must be read or calculated only once.

See Also

NagLibrary Namespace
NAG Library Overview
e04wd


E04.E04XA_OBJFUN Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04XA_OBJFUN Delegate
E04 Class See Also Send Feedback
If mode=0 or 2, objfun must calculate the objective function; otherwise if mode=1, objfun must calculate the objective function and the gradients.

Syntax

C#
public delegate void E04XA_OBJFUN(
    ref int mode,
    int n,
    double[] x,
    ref double objf,
    double[] objgrd,
    int nstate
)
Visual Basic
Public Delegate Sub E04XA_OBJFUN ( _
    ByRef mode As Integer, _
    n As Integer, _
    x As Double(), _
    ByRef objf As Double, _
    objgrd As Double(), _
    nstate As Integer _
)
Visual C++
public delegate void E04XA_OBJFUN(
    int% mode,
    int n,
    array<double>^ x,
    double% objf,
    array<double>^ objgrd,
    int nstate
)
F#
type E04XA_OBJFUN =
    delegate of
        mode : int byref *
        n : int *
        x : float[] *
        objf : float byref *
        objgrd : float[] *
        nstate : int -> unit

Parameters

mode
Type: System..::..Int32 %
mode indicates which parameter values within objfun need to be set.
On entry: to objfun, mode is always set to the value that you set it to before the call to e04xa.
On exit: its value must not be altered unless you wish to indicate a failure within objfun, in which case it should be set to a negative value. If mode is negative on exit from objfun, the execution of e04xa is terminated with ifail set to mode.
n
Type: System..::..Int32
On entry: the number n of variables as input to e04xa.
x
Type: array< System..::..Double >[]()[][]
On entry: the point x at which the objective function (and gradients if mode=1) is to be evaluated.
objf
Type: System..::..Double %
On exit: must be set to the value of the objective function.
objgrd
Type: array< System..::..Double >[]()[][]
On exit: if mode=1, objgrd[j-1] must contain the value of the first derivative with respect to x.
If mode≠1, objgrd need not be set.
nstate
Type: System..::..Int32
On entry: will be set to 1 on the first call of objfun by e04xa, and is 0 for all subsequent calls. Thus, if you wish, nstate may be tested within objfun in order to perform certain calculations once only. For example you may read data.

See Also

NagLibrary Namespace
NAG Library Overview
e04xa


E04.E04YA_LSQFUN Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04YA_LSQFUN Delegate
E04 Class See Also Send Feedback
lsqfun must calculate the vector of values fi x and their first derivatives ∂fi∂xj at any point x. (The minimization methods mentioned in [Description] give you the option of resetting a parameter to terminate immediately. e04ya will also terminate immediately, without finishing the checking process, if the parameter in question is reset.)

Syntax

C#
public delegate void E04YA_LSQFUN(
    ref int iflag,
    int m,
    int n,
    double[] xc,
    double[] fvec,
    double[,] fjac
)
Visual Basic
Public Delegate Sub E04YA_LSQFUN ( _
    ByRef iflag As Integer, _
    m As Integer, _
    n As Integer, _
    xc As Double(), _
    fvec As Double(), _
    fjac As Double(,) _
)
Visual C++
public delegate void E04YA_LSQFUN(
    int% iflag,
    int m,
    int n,
    array<double>^ xc,
    array<double>^ fvec,
    array<double,2>^ fjac
)
F#
type E04YA_LSQFUN =
    delegate of
        iflag : int byref *
        m : int *
        n : int *
        xc : float[] *
        fvec : float[] *
        fjac : float[,] -> unit

Parameters

iflag
Type: System..::..Int32 %
On entry: to lsqfun, iflag will be set to 2.
On exit: if you reset iflag to some negative number in lsqfun and return control to e04ya, the method will terminate immediately with ifail set to your setting of iflag.
m
Type: System..::..Int32
On entry: the numbers m of residuals.
n
Type: System..::..Int32
On entry: the numbers n of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: x, the point at which the values of the fi and the ∂fi∂xj are required.
fvec
Type: array< System..::..Double >[]()[][]
On exit: unless iflag is reset to a negative number, fvec[i-1] must contain the value of fi at the point x, for i=1,2,…,m.
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
On exit: unless iflag is reset to a negative number, fjac[i-1,j-1] must contain the value of ∂fi∂xj at the point x, for i=1,2,…,m and j=1,2,…,n.

See Also

NagLibrary Namespace
NAG Library Overview
e04ya


E04.E04YB_LSQFUN Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04YB_LSQFUN Delegate
E04 Class See Also Send Feedback
lsqfun must calculate the vector of values fi x and their first derivatives ∂fi∂xj at any point x. (e04he gives you the option of resetting parameters of lsqfun to cause the minimization process to terminate immediately. e04yb will also terminate immediately, without finishing the checking process, if the parameter in question is reset.)

Syntax

C#
public delegate void E04YB_LSQFUN(
    ref int iflag,
    int m,
    int n,
    double[] xc,
    double[] fvec,
    double[,] fjac
)
Visual Basic
Public Delegate Sub E04YB_LSQFUN ( _
    ByRef iflag As Integer, _
    m As Integer, _
    n As Integer, _
    xc As Double(), _
    fvec As Double(), _
    fjac As Double(,) _
)
Visual C++
public delegate void E04YB_LSQFUN(
    int% iflag,
    int m,
    int n,
    array<double>^ xc,
    array<double>^ fvec,
    array<double,2>^ fjac
)
F#
type E04YB_LSQFUN =
    delegate of
        iflag : int byref *
        m : int *
        n : int *
        xc : float[] *
        fvec : float[] *
        fjac : float[,] -> unit

Parameters

iflag
Type: System..::..Int32 %
On entry: to lsqfun, iflag will be set to 2.
On exit: if you reset iflag to some negative number in lsqfun and return control to e04yb, the method will terminate immediately with ifail set to your setting of iflag.
m
Type: System..::..Int32
On entry: the numbers m of residuals.
n
Type: System..::..Int32
On entry: the numbers n of variables.
xc
Type: array< System..::..Double >[]()[][]
On entry: the point x at which the values of the fi and the ∂fi∂xj are required.
fvec
Type: array< System..::..Double >[]()[][]
On exit: unless iflag is reset to a negative number, fvec[i-1] must contain the value of fi at the point x, for i=1,2,…,m.
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
On exit: unless iflag is reset to a negative number, fjac[i-1,j-1] must contain the value of ∂fi∂xj at the point x, for i=1,2,…,m and j=1,2,…,n.

See Also

NagLibrary Namespace
NAG Library Overview
e04yb


E04.E04YB_LSQHES Delegate

[image]

NAG Library for .NET Release 2
E04..::..E04YB_LSQHES Delegate
E04 Class See Also Send Feedback
lsqhes must calculate the elements of the symmetric matrix
B x=∑i=1 m fi x Gi x,
at any point x, where Gi x is the Hessian matrix of fi x. (As with lsqfun, a parameter can be set to cause immediate termination.)

Syntax

C#
public delegate void E04YB_LSQHES(
    ref int iflag,
    int m,
    int n,
    double[] fvec,
    double[] xc,
    double[] b
)
Visual Basic
Public Delegate Sub E04YB_LSQHES ( _
    ByRef iflag As Integer, _
    m As Integer, _
    n As Integer, _
    fvec As Double(), _
    xc As Double(), _
    b As Double() _
)
Visual C++
public delegate void E04YB_LSQHES(
    int% iflag,
    int m,
    int n,
    array<double>^ fvec,
    array<double>^ xc,
    array<double>^ b
)
F#
type E04YB_LSQHES =
    delegate of
        iflag : int byref *
        m : int *
        n : int *
        fvec : float[] *
        xc : float[] *
        b : float[] -> unit

Parameters

iflag
Type: System..::..Int32 %
On entry: is set to a non-negative number.
On exit: if lsqhes resets iflag to some negative number, e04yb will terminate immediately, with ifail set to your setting of iflag.
m
Type: System..::..Int32
On entry: the numbers m of residuals.
n
Type: System..::..Int32
On entry: the numbers n of variables.
fvec
Type: array< System..::..Double >[]()[][]
On entry: the value of the residual fi at the point x, for i=1,2,…,m, so that the values of the fi can be used in the calculation of the elements of b.
xc
Type: array< System..::..Double >[]()[][]
On entry: the point x at which the elements of b are to be evaluated.
b
Type: array< System..::..Double >[]()[][]
On exit: unless iflag is reset to a negative number b must contain the lower triangle of the matrix B x, evaluated at the point in xc, stored by rows. (The upper triangle is not needed because the matrix is symmetric.) More precisely, b[j j-1/2+k-1] must contain ∑i=1 m fi∂2 fi∂xj∂xk evaluated at the point x, for j=1,2,…,n and k=1,2,…,j.

See Also

NagLibrary Namespace
NAG Library Overview
e04yb


E04 Classes

[image]

NAG Library for .NET Release 2
E04 Classes

E04 Classes

  • E04.e04dgOptions Class
  • E04.e04mfOptions Class
  • E04.e04ncOptions Class
  • E04.e04nfOptions Class
  • E04.e04nkOptions Class
  • E04.e04nqOptions Class
  • E04.e04ucOptions Class
  • E04.e04ufOptions Class
  • E04.e04ugOptions Class
  • E04.e04usOptions Class
  • E04.e04vhOptions Class
  • E04.e04wdOptions Class


E04.e04dgOptions Class

[image]

NAG Library for .NET Release 2
E04..::..e04dgOptions Class
E04 Class Members See Also Send Feedback
Options Class for e04dg

Syntax

C#
public class e04dgOptions
Visual Basic
Public Class e04dgOptions
Visual C++
public ref class e04dgOptions
F#
type e04dgOptions =  class end

Description of the Optional Parameters

For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
  • the keywords, where the minimum abbreviation of each keyword is underlined (if no characters of an optional qualifier are underlined, the qualifier may be omitted);
  • a parameter value, where the letters a, i​ and ​r denote options that take character, integer and real values respectively;
  • the default value, where the symbol ε is a generic notation for machine precision (see x02aj), and εr denotes the relative precision of the objective function Function Precision.
Keywords and character values are case and white space insensitive.
Defaults
This special keyword may be used to reset all optional parameters to their default values.
Estimated Optimal Function Value
This value of r specifies the user-supplied guess of the optimum objective function value Fest. This value is used to calculate an initial step length α 0 (see [Algorithmic Details]). If the value of r is not specified (the default), then this has the effect of setting α 0 to unity. It should be noted that for badly scaled functions a unit step along the steepest descent direction will often compute the objective function at very large values of x.
Function Precision
The parameter defines εr, which is intended to be a measure of the accuracy with which the problem function F x can be computed. If r<ε or r≥1, the default value is used.
The value of εr should reflect the relative precision of 1+F x; i.e., εr acts as a relative precision when F is large, and as an absolute precision when F is small. For example, if F x is typically of order 1000 and the first six significant digits are known to be correct, an appropriate value for εr would be 10-6. In contrast, if F x is typically of order 10-4 and the first six significant digits are known to be correct, an appropriate value for εr would be 10-10. The choice of εr can be quite complicated for badly scaled problems; see Chapter 8 of Gill et al. (1981) for a discussion of scaling techniques. The default value is appropriate for most simple functions that are computed with full accuracy. However when the accuracy of the computed function values is known to be significantly worse than full precision, the value of εr should be large enough so that no attempt will be made to distinguish between function values that differ by less than the error inherent in the calculation.
Iteration Limit
Iters
Itns
The value of i specifies the maximum number of iterations allowed before termination. If i<0, the default value is used.
Problems whose Hessian matrices at the solution contain sets of clustered eigenvalues are likely to be minimized in significantly fewer than n iterations. Problems without this property may require anything between n and 5 n iterations, with approximately 2 n iterations being a common figure for moderately difficult problems.
Linesearch Tolerance
The value r controls the accuracy with which the step α taken during each iteration approximates a minimum of the function along the search direction (the smaller the value of r, the more accurate the linesearch). The default value r=0.9 requests an inaccurate search, and is appropriate for most problems. A more accurate search may be appropriate when it is desirable to reduce the number of iterations – for example, if the objective function is cheap to evaluate. If r<0 or r≥1, the default value is used.
List
Nolist
Normally each optional parameter specification is printed as it is supplied. Optional parameter Nolist may be used to suppress the printing and optional parameter List may be used to restore printing.
Maximum Step Length
If r>0, the maximum allowable step length for the linesearch is taken as min 1 x02am,r pk. If r≤0, the default value is used.
Optimality Tolerance
The parameter r specifies the accuracy to which you wish the final iterate to approximate a solution of the problem. Broadly speaking, r indicates the number of correct figures desired in the objective function at the solution. For example, if r is 10-6 and termination occurs with ifail=0 (see [Parameters]), then the final point satisfies the termination criteria, where τF represents Optimality Tolerance. If r<εr or r≥1, the default value is used.
Print Level
The value i controls the amount of printout produced by e04dg, as indicated below. A detailed description of the printout is given in [Description of Printed Output] (summary output at each iteration and the final solution).
i | Output
0 0 | No output.
0 1 | The final solution only.
0 5 | One line of summary output (<80 characters; see [Description of Printed Output]) for each iteration (no printout of the final solution).
10 | The final solution and one line of summary output for each iteration.
Start Objective Check at Variable
Stop Objective Check at Variable
These keywords take effect only if Verify Level>0. They may be used to control the verification of gradient elements computed by objfun. For example, if the first 30 elements of the objective gradient appeared to be correct in an earlier run, so that only element 31 remains questionable, it is reasonable to specify Start Objective Check at Variable=31. If the first 30 variables appear linearly in the objective, so that the corresponding gradient elements are constant, the above choice would also be appropriate.
If i 1≤0 or i 1>max 1,min n,i 2, the default value is used. If i 2≤0 or i 2>n, the default value is used.
Verify Level
Verify
Verify Gradients
Verify Objective Gradients
These keywords refer to finite difference checks on the gradient elements computed by objfun. Gradients are verified at the user-supplied initial estimate of the solution. The possible choices for i are as follows:
i | Meaning
-1 | No checks are performed.
-0 | Only a ‘cheap’ test will be performed, requiring one call to objfun.
-1 | In addition to the ‘cheap’ test, individual gradient elements will also be checked using a reliable (but more expensive) test.
For example, the objective gradient will be verified if Verify, Verify=YES, Verify Gradients, Verify Objective Gradients or Verify Level=1 is specified.

Inheritance Hierarchy

System..::..Object
NagLibrary..::..E04..::..e04dgOptions

See Also

E04..::..e04dgOptions Members
NagLibrary Namespace
NAG Library Overview
e04dg


E04.e04dgOptions Members

[image] [image]

NAG Library for .NET Release 2
E04..::..e04dgOptions Members
E04..::..e04dgOptions Class Constructors Methods Properties See Also Send Feedback

An optimization problem involves minimizing a function (called the objective function) of several variables, possibly subject to restrictions on the values of the variables defined by a set of constraint functions. Most methods in the Library are concerned with function minimization only, since the problem of maximizing a given objective function F(x) is equivalent to minimizing -F x. Some methods allow you to specify whether you are solving a minimization or maximization problem, carrying out the required transformation of the objective function in the latter case.
In general methods in this chapter find a local minimum of a function f, that is a point x* s.t. for all x near x* f x≥f x*.
The E05 class contains methods to find the global minimum of a function f. At a global minimum x* f x≥f x* for all x.
The (H not in this release) contains methods typically regarded as belonging to the field of operations research.
This introduction is only a brief guide to the subject of optimization designed for the casual user. Anyone with a difficult or protracted problem to solve will find it beneficial to consult a more detailed text, such as Gill et al. (1981) or Fletcher (1987).
If you are unfamiliar with the mathematics of the subject you may find some sections difficult at first reading; if so, you should concentrate on [Types of Optimization Problems], [Geometric Representation and Terminology], [Scaling], [Analysis of Computed Results] and [Recommendations on Choice and Use of Available Methods] .

The E04..::..e04dgOptions type exposes the following members.

Constructors

Name | Description
E04..::..e04dgOptions | Constructor

Methods

Name | Description
Set | Overloaded.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e04dg.
Warning | Set the method used for logging any warning or error messages from e04dg.

See Also

E04..::..e04dgOptions Class


E04.e04dgOptions Constructor

[image]

NAG Library for .NET Release 2
E04..::..e04dgOptions Constructor
E04..::..e04dgOptions Class See Also Send Feedback
Constructor

Syntax

C#
public e04dgOptions()
Visual Basic
Public Sub New
Visual C++
public:
e04dgOptions()
F#
new : unit -> e04dgOptions

See Also

E04..::..e04dgOptions Class
E04..::..e04dgOptions Members


E04.e04dgOptions Methods

[image] [image]

NAG Library for .NET Release 2
E04..::..e04dgOptions Methods
E04..::..e04dgOptions Class See Also Send Feedback

Methods

Name | Description
Set | Overloaded.

See Also

E04..::..e04dgOptions Class


Set Method

[image] [image]

NAG Library for .NET Release 2
E04..::..e04dgOptions..::Set Method
E04..::..e04dgOptions Class See Also Send Feedback

Overload List

Name | Description
Set(String) | Set an Option for e04dg
Set(DataReader) | Set Options for from a DataReader Stream.

See Also

E04..::..e04dgOptions Class
E04..::..e04dgOptions Members


Set Method (String)

[image]

NAG Library for .NET Release 2
E04..::..e04dgOptions..::Set Method (String)
E04..::..e04dgOptions Class See Also Send Feedback
Set an Option for e04dg

Syntax

C#
public void Set(
    string str
)
Visual Basic
Public Sub Set ( _
    str As String _
)
Visual C++
public:
void Set(
    String^ str
)
F#
member Set :
        str : string -> unit

Parameters

str
Type: System..::..String
A string of the form option = value, or for boolean options, simply option.

See Also

E04..::..e04dgOptions Class
E04..::..e04dgOptions Members
Set Overload


Set Method (DataReader)

[image]

NAG Library for .NET Release 2
E04..::..e04dgOptions..::Set Method (DataReader)
E04..::..e04dgOptions Class See Also Send Feedback
Set Options for from a DataReader Stream.

Syntax

C#
public void Set(
    DataReader sr
)
Visual Basic
Public Sub Set ( _
    sr As DataReader _
)
Visual C++
public:
void Set(
    DataReader^ sr
)
F#
member Set :
        sr : DataReader -> unit

Parameters

sr
Type: NagLibrary..::..DataReader
A DataReader Stream, containing an option setting on each line.

See Also

E04..::..e04dgOptions Class
E04..::..e04dgOptions Members
Set Overload


E04.e04dgOptions Properties

[image] [image]

NAG Library for .NET Release 2
E04..::..e04dgOptions Properties
E04..::..e04dgOptions Class See Also Send Feedback

The E04..::..e04dgOptions type exposes the following members.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e04dg.
Warning | Set the method used for logging any warning or error messages from e04dg.

See Also

E04..::..e04dgOptions Class


Message Property

[image]

NAG Library for .NET Release 2
E04..::..e04dgOptions..::Message Property
E04..::..e04dgOptions Class See Also Send Feedback
Set the method used for logging any monitoring messages from e04dg.

Syntax

C#
public PrintManager..::..MessageLogger Message { get; set; }
Visual Basic
Public Property Message As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Message {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Message : PrintManager..::..MessageLogger with get, set

See Also

E04..::..e04dgOptions Class
E04..::..e04dgOptions Members


Warning Property

[image]

NAG Library for .NET Release 2
E04..::..e04dgOptions..::Warning Property
E04..::..e04dgOptions Class See Also Send Feedback
Set the method used for logging any warning or error messages from e04dg.

Syntax

C#
public PrintManager..::..MessageLogger Warning { get; set; }
Visual Basic
Public Property Warning As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Warning {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Warning : PrintManager..::..MessageLogger with get, set

See Also

E04..::..e04dgOptions Class
E04..::..e04dgOptions Members


E04.e04mfOptions Class

[image]

NAG Library for .NET Release 2
E04..::..e04mfOptions Class
E04 Class Members See Also Send Feedback
Options Class for e04mf

Syntax

C#
public class e04mfOptions
Visual Basic
Public Class e04mfOptions
Visual C++
public ref class e04mfOptions
F#
type e04mfOptions =  class end

Description of the Optional Parameters

For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
  • the keywords, where the minimum abbreviation of each keyword is underlined (if no characters of an optional qualifier are underlined, the qualifier may be omitted);
  • a parameter value, where the letters a, i​ and ​r denote options that take character, integer and real values respectively;
  • the default value, where the symbol ε is a generic notation for machine precision (see x02aj).
Keywords and character values are case and white space insensitive.
Check Frequency
Every ith iteration, a numerical test is made to see if the current solution x satisfies the constraints in the working set. If the largest residual of the constraints in the working set is judged to be too large, the current working set is refactorized and the variables are recomputed to satisfy the constraints more accurately. If i≤0, the default value is used.
Cold Start
Warm Start
This option specifies how the initial working set is chosen. With a Cold Start, e04mf chooses the initial working set based on the values of the variables and constraints at the initial point. Broadly speaking, the initial working set will include equality constraints and bounds or inequality constraints that violate or ‘nearly’ satisfy their bounds (to within Crash Tolerance).
With a Warm Start, you must provide a valid definition of every element of the array istate. e04mf will override your specification of istate if necessary, so that a poor choice of the working set will not cause a fatal error. For instance, any elements of istate which are set to -2, -1​ or ​4 will be reset to zero, as will any elements which are set to 3 when the corresponding elements of bl and bu are not equal. A warm start will be advantageous if a good estimate of the initial working set is available – for example, when e04mf is called repeatedly to solve related problems.
Crash Tolerance
This value is used in conjunction with the optional parameter Cold Start (the default value) when e04mf selects an initial working set. If 0≤r≤1, the initial working set will include (if possible) bounds or general inequality constraints that lie within r of their bounds. In particular, a constraint of the form ajT x≥l will be included in the initial working set if ajT x-l≤r 1+l. If r<0 or r>1, the default value is used.
Defaults
This special keyword may be used to reset all optional parameters to their default values.
Expand Frequency
This option is part of an anti-cycling procedure designed to guarantee progress even on highly degenerate problems.
The strategy is to force a positive step at every iteration, at the expense of violating the constraints by a small amount. Suppose that the value of the optional parameter Feasibility Tolerance is δ. Over a period of i iterations, the feasibility tolerance actually used by e04mf (i.e., the working feasibility tolerance) increases from 0.5 δ to δ (in steps of 0.5 δ/i).
At certain stages the following ‘resetting procedure’ is used to remove constraint infeasibilities. First, all variables whose upper or lower bounds are in the working set are moved exactly onto their bounds. A count is kept of the number of nontrivial adjustments made. If the count is positive, iterative refinement is used to give variables that satisfy the working set to (essentially) machine precision. Finally, the working feasibility tolerance is reinitialized to 0.5 δ.
If a problem requires more than i iterations, the resetting procedure is invoked and a new cycle of i iterations is started with i incremented by 10. (The decision to resume the feasibility phase or optimality phase is based on comparing any constraint infeasibilities with δ.)
The resetting procedure is also invoked when e04mf reaches an apparently optimal, infeasible or unbounded solution, unless this situation has already occurred twice. If any nontrivial adjustments are made, iterations are continued.
If i≤0, the default value is used. If i≥9999999, no anti-cycling procedure is invoked.
Feasibility Tolerance
If r≥ε, r defines the maximum acceptable absolute violation in each constraint at a ‘feasible’ point. For example, if the variables and the coefficients in the general constraints are of order unity, and the latter are correct to about 6 decimal digits, it would be appropriate to specify r as 10-6. If 0≤r<ε, the default value is used.
e04mf attempts to find a feasible solution before optimizing the objective function. If the sum of infeasibilities cannot be reduced to zero, the optional parameter Minimum Sum of Infeasibilities can be used to find the minimum value of the sum. Let Sinf be the corresponding sum of infeasibilities. If Sinf is quite small, it may be appropriate to raise r by a factor of 10 or 100. Otherwise, some error in the data should be suspected.
Note that a ‘feasible solution’ is a solution that satisfies the current constraints to within the tolerance r.
Infinite Bound Size
If r>0, r defines the ‘infinite’ bound bigbnd in the definition of the problem constraints. Any upper bound greater than or equal to bigbnd will be regarded as +∞ (and similarly any lower bound less than or equal to -bigbnd will be regarded as -∞). If r<0, the default value is used.
Infinite Step Size
If r>0, r specifies the magnitude of the change in variables that will be considered a step to an unbounded solution. (Note that an unbounded solution can occur only when the problem is of type LP.) If the change in x during an iteration would exceed the value of r, the objective function is considered to be unbounded below in the feasible region. If r≤0, the default value is used.
Iteration Limit
Iters
Itns
The value of i specifies the maximum number of iterations allowed before termination. With i=0 and Print Level>0, the workspace needed will be computed and printed, but no iterations will be performed. If i<0, the default value is used.
List
Nolist
Normally each optional parameter specification is printed as it is supplied. Optional parameter Nolist may be used to suppress the printing and optional parameter List may be used to restore printing.
Minimum Sum of Infeasibilities
If no feasible point exists for the constraints, this option is used to control whether or not e04mf will calculate a point that minimizes the constraint violations. If Minimum Sum of Infeasibilities=NO, e04mf will terminate as soon as it is evident that no feasible point exists for the constraints. The final point will generally not be the point at which the sum of infeasibilities is minimized. If Minimum Sum of Infeasibilities=YES, e04mf will continue until the sum of infeasibilities is minimized.
Monitoring File
If i≥0 and Print Level≥5, monitoring information produced by e04mf at every iteration is sent to a file with logical unit number i. If i<0 and/or Print Level<5, no monitoring information is produced.
Optimality Tolerance
If r≥ε, r defines the tolerance used to determine if the bounds and general constraints have the right ‘sign’ for the solution to be judged to be optimal.
If 0≤r<ε, the default value is used.
Print Level
The value of i controls the amount of printout produced by e04mf, as indicated below. A detailed description of the printed output is given in [Description of the Printed Output] (summary output at each iteration and the final solution) and [Description of Monitoring Information] (monitoring information at each iteration).
The following printout is sent to the current advisory message unit (as defined by (X04ABF not in this release)):
i | Output
≥0 0 | No output.
≥0 1 | The final solution only.
≥0 5 | One line of summary output (<80 characters; see [Description of the Printed Output]) for each iteration (no printout of the final solution).
≥10 | The final solution and one line of summary output for each iteration.
The following printout is sent to the logical unit number defined by the optional parameter Monitoring File:
i | Output
<0 5 | No output.
≥0 5 | One long line of output (>80 characters; see [Description of Monitoring Information]) for each iteration (no printout of the final solution).
≥20 | At each iteration, the Lagrange multipliers, the variables x, the constraint values Ax and the constraint status (see istate).
≥30 | At each iteration, the diagonal elements of the upper triangular matrix T associated with the TQ factorization (3) (see [Definition of Search Direction]) of the working set.
If Print Level≥5 and the unit number defined by the optional parameter Monitoring File is the same as that defined by (X04ABF not in this release), then the summary output is suppressed.
Problem Type
This option specifies the type of objective function to be minimized during the optimality phase. The following is the optional keyword and the dimensions of the array that must be specified in order to define the objective function:
LP cvec[n-1] required.
For problems of type FP, the objective function is omitted and cvec is not referenced. The following keywords are also acceptable. The minimum abbreviation of each keyword is underlined.
a | Option
Linear | LP
Feasible | FP

Inheritance Hierarchy

System..::..Object
NagLibrary..::..E04..::..e04mfOptions

See Also

E04..::..e04mfOptions Members
NagLibrary Namespace
NAG Library Overview
e04mf


E04.e04mfOptions Members

[image] [image]

NAG Library for .NET Release 2
E04..::..e04mfOptions Members
E04..::..e04mfOptions Class Constructors Methods Properties See Also Send Feedback

An optimization problem involves minimizing a function (called the objective function) of several variables, possibly subject to restrictions on the values of the variables defined by a set of constraint functions. Most methods in the Library are concerned with function minimization only, since the problem of maximizing a given objective function F(x) is equivalent to minimizing -F x. Some methods allow you to specify whether you are solving a minimization or maximization problem, carrying out the required transformation of the objective function in the latter case.
In general methods in this chapter find a local minimum of a function f, that is a point x* s.t. for all x near x* f x≥f x*.
The E05 class contains methods to find the global minimum of a function f. At a global minimum x* f x≥f x* for all x.
The (H not in this release) contains methods typically regarded as belonging to the field of operations research.
This introduction is only a brief guide to the subject of optimization designed for the casual user. Anyone with a difficult or protracted problem to solve will find it beneficial to consult a more detailed text, such as Gill et al. (1981) or Fletcher (1987).
If you are unfamiliar with the mathematics of the subject you may find some sections difficult at first reading; if so, you should concentrate on [Types of Optimization Problems], [Geometric Representation and Terminology], [Scaling], [Analysis of Computed Results] and [Recommendations on Choice and Use of Available Methods] .

The E04..::..e04mfOptions type exposes the following members.

Constructors

Name | Description
E04..::..e04mfOptions | Constructor

Methods

Name | Description
Set | Overloaded.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e04mf.
Warning | Set the method used for logging any warning or error messages from e04mf.

See Also

E04..::..e04mfOptions Class


E04.e04mfOptions Constructor

[image]

NAG Library for .NET Release 2
E04..::..e04mfOptions Constructor
E04..::..e04mfOptions Class See Also Send Feedback
Constructor

Syntax

C#
public e04mfOptions()
Visual Basic
Public Sub New
Visual C++
public:
e04mfOptions()
F#
new : unit -> e04mfOptions

See Also

E04..::..e04mfOptions Class
E04..::..e04mfOptions Members


E04.e04mfOptions Methods

[image] [image]

NAG Library for .NET Release 2
E04..::..e04mfOptions Methods
E04..::..e04mfOptions Class See Also Send Feedback

Methods

Name | Description
Set | Overloaded.

See Also

E04..::..e04mfOptions Class


Set Method

[image] [image]

NAG Library for .NET Release 2
E04..::..e04mfOptions..::Set Method
E04..::..e04mfOptions Class See Also Send Feedback

Overload List

Name | Description
Set(String) | Set an Option for e04mf
Set(DataReader) | Set Options for from a DataReader Stream.

See Also

E04..::..e04mfOptions Class
E04..::..e04mfOptions Members


Set Method (String)

[image]

NAG Library for .NET Release 2
E04..::..e04mfOptions..::Set Method (String)
E04..::..e04mfOptions Class See Also Send Feedback
Set an Option for e04mf

Syntax

C#
public void Set(
    string str
)
Visual Basic
Public Sub Set ( _
    str As String _
)
Visual C++
public:
void Set(
    String^ str
)
F#
member Set :
        str : string -> unit

Parameters

str
Type: System..::..String
A string of the form option = value, or for boolean options, simply option.

See Also

E04..::..e04mfOptions Class
E04..::..e04mfOptions Members
Set Overload


Set Method (DataReader)

[image]

NAG Library for .NET Release 2
E04..::..e04mfOptions..::Set Method (DataReader)
E04..::..e04mfOptions Class See Also Send Feedback
Set Options for from a DataReader Stream.

Syntax

C#
public void Set(
    DataReader sr
)
Visual Basic
Public Sub Set ( _
    sr As DataReader _
)
Visual C++
public:
void Set(
    DataReader^ sr
)
F#
member Set :
        sr : DataReader -> unit

Parameters

sr
Type: NagLibrary..::..DataReader
A DataReader Stream, containing an option setting on each line.

See Also

E04..::..e04mfOptions Class
E04..::..e04mfOptions Members
Set Overload


E04.e04mfOptions Properties

[image] [image]

NAG Library for .NET Release 2
E04..::..e04mfOptions Properties
E04..::..e04mfOptions Class See Also Send Feedback

The E04..::..e04mfOptions type exposes the following members.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e04mf.
Warning | Set the method used for logging any warning or error messages from e04mf.

See Also

E04..::..e04mfOptions Class


Message Property

[image]

NAG Library for .NET Release 2
E04..::..e04mfOptions..::Message Property
E04..::..e04mfOptions Class See Also Send Feedback
Set the method used for logging any monitoring messages from e04mf.

Syntax

C#
public PrintManager..::..MessageLogger Message { get; set; }
Visual Basic
Public Property Message As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Message {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Message : PrintManager..::..MessageLogger with get, set

See Also

E04..::..e04mfOptions Class
E04..::..e04mfOptions Members


Warning Property

[image]

NAG Library for .NET Release 2
E04..::..e04mfOptions..::Warning Property
E04..::..e04mfOptions Class See Also Send Feedback
Set the method used for logging any warning or error messages from e04mf.

Syntax

C#
public PrintManager..::..MessageLogger Warning { get; set; }
Visual Basic
Public Property Warning As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Warning {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Warning : PrintManager..::..MessageLogger with get, set

See Also

E04..::..e04mfOptions Class
E04..::..e04mfOptions Members


E04.e04ncOptions Class

[image]

NAG Library for .NET Release 2
E04..::..e04ncOptions Class
E04 Class Members See Also Send Feedback
Options Class for e04nc

Syntax

C#
public class e04ncOptions
Visual Basic
Public Class e04ncOptions
Visual C++
public ref class e04ncOptions
F#
type e04ncOptions =  class end

Description of the Optional Parameters

For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
  • the keywords, where the minimum abbreviation of each keyword is underlined (if no characters of an optional qualifier are underlined, the qualifier may be omitted);
  • a parameter value, where the letters a, i​ and ​r denote options that take character, integer and real values respectively;
  • the default value, where the symbol ε is a generic notation for machine precision (see x02aj).
Keywords and character values are case and white space insensitive.
Cold Start
Warm Start
This option specifies how the initial working set is chosen. With a Cold Start, e04nc chooses the initial working set based on the values of the variables and constraints at the initial point. Broadly speaking, the initial working set will include equality constraints and bounds or inequality constraints that violate or ‘nearly’ satisfy their bounds (to within Crash Tolerance).
With a Warm Start, you must provide a valid definition of every element of the array istate. e04nc will override your specification of istate if necessary, so that a poor choice of the working set will not cause a fatal error. For instance, any elements of istate which are set to -2, -1​ or ​4 will be reset to zero, as will any elements which are set to 3 when the corresponding elements of bl and bu are not equal. A warm start will be advantageous if a good estimate of the initial working set is available – for example, when e04nc is called repeatedly to solve related problems.
Crash Tolerance
This value is used in conjunction with the optional parameter Cold Start (the default value) when e04nc selects an initial working set. If 0≤r≤1, the initial working set will include (if possible) bounds or general inequality constraints that lie within r of their bounds. In particular, a constraint of the form cjT x≥l will be included in the initial working set if cjT x-l≤r 1+l. If r<0 or r>1, the default value is used.
Defaults
This special keyword may be used to reset all optional parameters to their default values.
Feasibility Phase Iteration Limit
Optimality Phase Iteration Limit
The scalars i 1 and i 2 specify the maximum number of iterations allowed in the feasibility and optimality phases. Optional parameter Optimality Phase Iteration Limit is equivalent to optional parameter Iteration Limit. Setting i 2=0 and Print Level>0 means that the workspace needed will be computed and printed, but no iterations will be performed. If i 1<0 or i 2<0, the default value is used.
Feasibility Tolerance
If r>ε, r defines the maximum acceptable absolute violation in each constraint at a ‘feasible’ point. For example, if the variables and the coefficients in the general constaints are of order unity, and the latter are correct to about 6 decimal digits, it would be appropriate to specify r as 10-6. If 0≤r<ε, the default value is used.
Note that a ‘feasible solution’ is a solution that satisfies the current constraints to within the tolerance r.
Hessian
This option controls the contents of the upper triangular matrix R (see the description of a in [Parameters]). e04nc works exclusively with the transformed and reordered matrix HQ (8), and hence extra computation is required to form the Hessian itself. If Hessian=NO, a contains the Cholesky factor of the matrix HQ with columns ordered as indicated by kx (see [Parameters]). If Hessian=YES, a contains the Cholesky factor of the matrix H, with columns ordered as indicated by kx.
Infinite Bound Size
If r>0, r defines the ‘infinite’ bound bigbnd in the definition of the problem constraints. Any upper bound greater than or equal to bigbnd will be regarded as +∞ (and similarly any lower bound less than or equal to -bigbnd will be regarded as -∞). If r<0, the default value is used.
Infinite Step Size
If r>0, r specifies the magnitude of the change in variables that will be considered a step to an unbounded solution. (Note that an unbounded solution can occur only when the Hessian is singular and the objective contains an explicit linear term.) If the change in x during an iteration would exceed the value of r, the objective function is considered to be unbounded below in the feasible region. If r≤0, the default value is used.
Iteration Limit
Iters
Itns
See optional parameter Feasibility Phase Iteration Limit.
List
Nolist
Normally each optional parameter specification is printed as it is supplied. Optional parameter Nolist may be used to suppress the printing and optional parameter List may be used to restore printing.
Monitoring File
If i≥0 and Print Level≥5, monitoring information produced by e04nc at every iteration is sent to a file with logical unit number i. If i<0 and/or Print Level<5, no monitoring information is produced.
Print Level
The value of i controls the amount of printout produced by e04nc, as indicated below. A detailed description of the printed output is given in [Description of the Printed Output] (summary output at each iteration and the final solution) and [Description of Monitoring Information] (monitoring information at each iteration).
The following printout is sent to the current advisory message unit (as defined by (X04ABF not in this release)):
i | Output
≥0 0 | No output.
≥0 1 | The final solution only.
≥0 5 | One line of summary output (<80 characters; see [Description of the Printed Output]) for each iteration (no printout of the final solution).
≥10 | The final solution and one line of summary output for each iteration.
The following printout is sent to the logical unit number defined by the optional parameter Monitoring File:
i | Output
<5 | No output.
≥5 | One long line of output (>80 characters; see [Description of Monitoring Information]) for each iteration (no printout of the final solution).
≥20 | At each iteration, the Lagrange multipliers, the variables x, the constraint values Cx and the constraint status.
≥30 | At each iteration, the diagonal elements of the matrix T associated with the TQ factorization (4) (see [Definition of Search Direction]) of the working set, and the diagonal elements of the upper triangular matrix R.
If Print Level≥5 and the unit number defined by the optional parameter Monitoring File is the same as that defined by (X04ABF not in this release), then the summary output is suppressed.
Problem Type
This option specifies the type of objective function to be minimized during the optimality phase. The following are the nine optional keywords and the dimensions of the arrays that must be specified in order to define the objective function:
LP | a and b not referenced, cvec[n-1];
QP1 | a[lda-1,n-1] symmetric, b and cvec not referenced;
QP2 | a[lda-1,n-1] symmetric, b not referenced, cvec[n-1];
QP3 | a[lda-1,n-1] upper trapezoidal, kx[n-1], b and cvec not referenced;
QP4 | a[lda-1,n-1] upper trapezoidal, kx[n-1], b not referenced, cvec[n-1];
LS1 | a[lda-1,n-1], b[m-1], cvec not referenced;
LS2 | a[lda-1,n-1], b[m-1], cvec[n-1];
LS3 | a[lda-1,n-1] upper trapezoidal, kx[n-1], b[m-1], cvec not referenced;
LS4 | a[lda-1,n-1] upper trapezoidal, kx[n-1], b[m-1], cvec[n-1].
For problems of type FP, the objective function is omitted and a, b and cvec are not referenced.
The following keywords are also acceptable. The minimum abbreviation of each keyword is underlined.
a | Option
Least | LS1
Quadratic | QP2
Linear | LP
In addition, the keywords LS and LSQ are equivalent to the default option LS1, and the keyword QP is equivalent to the option QP2.
If A=0, i.e., the objective function is purely linear, the efficiency of e04nc may be increased by specifying a as LP.
Rank Tolerance
Note that this option does not apply to problems of type FP or LP.
The default value of r depends on the problem type. If A occurs as a least squares matrix, as it does in problem types QP1, LS1 and LS3, then the default value of r is 100 ε. In all other cases, A is treated as the ‘square root’ of the Hessian matrix H and r has the default value 10 ε.
This parameter enables you to control the estimate of the triangular factor R 1 (see [Main Iteration]). If ρi denotes the function ρi=max R 11,R 22,…,R ii, the rank of R is defined to be smallest index i such that R i+1,i+1≤r ρ i+1. If r≤0, the default value is used.

Inheritance Hierarchy

System..::..Object
NagLibrary..::..E04..::..e04ncOptions

See Also

E04..::..e04ncOptions Members
NagLibrary Namespace
NAG Library Overview
e04nc


E04.e04ncOptions Members

[image] [image]

NAG Library for .NET Release 2
E04..::..e04ncOptions Members
E04..::..e04ncOptions Class Constructors Methods Properties See Also Send Feedback

An optimization problem involves minimizing a function (called the objective function) of several variables, possibly subject to restrictions on the values of the variables defined by a set of constraint functions. Most methods in the Library are concerned with function minimization only, since the problem of maximizing a given objective function F(x) is equivalent to minimizing -F x. Some methods allow you to specify whether you are solving a minimization or maximization problem, carrying out the required transformation of the objective function in the latter case.
In general methods in this chapter find a local minimum of a function f, that is a point x* s.t. for all x near x* f x≥f x*.
The E05 class contains methods to find the global minimum of a function f. At a global minimum x* f x≥f x* for all x.
The (H not in this release) contains methods typically regarded as belonging to the field of operations research.
This introduction is only a brief guide to the subject of optimization designed for the casual user. Anyone with a difficult or protracted problem to solve will find it beneficial to consult a more detailed text, such as Gill et al. (1981) or Fletcher (1987).
If you are unfamiliar with the mathematics of the subject you may find some sections difficult at first reading; if so, you should concentrate on [Types of Optimization Problems], [Geometric Representation and Terminology], [Scaling], [Analysis of Computed Results] and [Recommendations on Choice and Use of Available Methods] .

The E04..::..e04ncOptions type exposes the following members.

Constructors

Name | Description
E04..::..e04ncOptions | Constructor

Methods

Name | Description
Set | Overloaded.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e04nc.
Warning | Set the method used for logging any warning or error messages from e04nc.

See Also

E04..::..e04ncOptions Class


E04.e04ncOptions Constructor

[image]

NAG Library for .NET Release 2
E04..::..e04ncOptions Constructor
E04..::..e04ncOptions Class See Also Send Feedback
Constructor

Syntax

C#
public e04ncOptions()
Visual Basic
Public Sub New
Visual C++
public:
e04ncOptions()
F#
new : unit -> e04ncOptions

See Also

E04..::..e04ncOptions Class
E04..::..e04ncOptions Members


E04.e04ncOptions Methods

[image] [image]

NAG Library for .NET Release 2
E04..::..e04ncOptions Methods
E04..::..e04ncOptions Class See Also Send Feedback

Methods

Name | Description
Set | Overloaded.

See Also

E04..::..e04ncOptions Class


Set Method

[image] [image]

NAG Library for .NET Release 2
E04..::..e04ncOptions..::Set Method
E04..::..e04ncOptions Class See Also Send Feedback

Overload List

Name | Description
Set(String) | Set an Option for e04nc
Set(DataReader) | Set Options for from a DataReader Stream.

See Also

E04..::..e04ncOptions Class
E04..::..e04ncOptions Members


Set Method (String)

[image]

NAG Library for .NET Release 2
E04..::..e04ncOptions..::Set Method (String)
E04..::..e04ncOptions Class See Also Send Feedback
Set an Option for e04nc

Syntax

C#
public void Set(
    string str
)
Visual Basic
Public Sub Set ( _
    str As String _
)
Visual C++
public:
void Set(
    String^ str
)
F#
member Set :
        str : string -> unit

Parameters

str
Type: System..::..String
A string of the form option = value, or for boolean options, simply option.

See Also

E04..::..e04ncOptions Class
E04..::..e04ncOptions Members
Set Overload


Set Method (DataReader)

[image]

NAG Library for .NET Release 2
E04..::..e04ncOptions..::Set Method (DataReader)
E04..::..e04ncOptions Class See Also Send Feedback
Set Options for from a DataReader Stream.

Syntax

C#
public void Set(
    DataReader sr
)
Visual Basic
Public Sub Set ( _
    sr As DataReader _
)
Visual C++
public:
void Set(
    DataReader^ sr
)
F#
member Set :
        sr : DataReader -> unit

Parameters

sr
Type: NagLibrary..::..DataReader
A DataReader Stream, containing an option setting on each line.

See Also

E04..::..e04ncOptions Class
E04..::..e04ncOptions Members
Set Overload


E04.e04ncOptions Properties

[image] [image]

NAG Library for .NET Release 2
E04..::..e04ncOptions Properties
E04..::..e04ncOptions Class See Also Send Feedback

The E04..::..e04ncOptions type exposes the following members.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e04nc.
Warning | Set the method used for logging any warning or error messages from e04nc.

See Also

E04..::..e04ncOptions Class


Message Property

[image]

NAG Library for .NET Release 2
E04..::..e04ncOptions..::Message Property
E04..::..e04ncOptions Class See Also Send Feedback
Set the method used for logging any monitoring messages from e04nc.

Syntax

C#
public PrintManager..::..MessageLogger Message { get; set; }
Visual Basic
Public Property Message As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Message {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Message : PrintManager..::..MessageLogger with get, set

See Also

E04..::..e04ncOptions Class
E04..::..e04ncOptions Members


Warning Property

[image]

NAG Library for .NET Release 2
E04..::..e04ncOptions..::Warning Property
E04..::..e04ncOptions Class See Also Send Feedback
Set the method used for logging any warning or error messages from e04nc.

Syntax

C#
public PrintManager..::..MessageLogger Warning { get; set; }
Visual Basic
Public Property Warning As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Warning {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Warning : PrintManager..::..MessageLogger with get, set

See Also

E04..::..e04ncOptions Class
E04..::..e04ncOptions Members


E04.e04nfOptions Class

[image]

NAG Library for .NET Release 2
E04..::..e04nfOptions Class
E04 Class Members See Also Send Feedback
Options Class for e04nf

Syntax

C#
public class e04nfOptions
Visual Basic
Public Class e04nfOptions
Visual C++
public ref class e04nfOptions
F#
type e04nfOptions =  class end

Description of the Optional Parameters

For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
  • the keywords, where the minimum abbreviation of each keyword is underlined (if no characters of an optional qualifier are underlined, the qualifier may be omitted);
  • a parameter value, where the letters a, i​ and ​r denote options that take character, integer and real values respectively;
  • the default value, where the symbol ε is a generic notation for machine precision (see x02aj).
Keywords and character values are case and white space insensitive.
Check Frequency
Every ith iteration, a numerical test is made to see if the current solution x satisfies the constraints in the working set. If the largest residual of the constraints in the working set is judged to be too large, the current working set is refactorized and the variables are recomputed to satisfy the constraints more accurately. If i≤0, the default value is used.
Cold Start
Warm Start
This option specifies how the initial working set is chosen. With a Cold Start, e04nf chooses the initial working set based on the values of the variables and constraints at the initial point. Broadly speaking, the initial working set will include equality constraints and bounds or inequality constraints that violate or ‘nearly’ satisfy their bounds (to within Crash Tolerance).
With a Warm Start, you must provide a valid definition of every element of the array istate. e04nf will override your specification of istate if necessary, so that a poor choice of the working set will not cause a fatal error. For instance, any elements of istate which are set to -2, -1​ or ​4 will be reset to zero, as will any elements which are set to 3 when the corresponding elements of bl and bu are not equal. A warm start will be advantageous if a good estimate of the initial working set is available – for example, when e04nf is called repeatedly to solve related problems.
Crash Tolerance
This value is used in conjunction with the optional parameter Cold Start (the default value) when e04nf selects an initial working set. If 0≤r≤1, the initial working set will include (if possible) bounds or general inequality constraints that lie within r of their bounds. In particular, a constraint of the form ajT x≥l will be included in the initial working set if ajT x-l≤r 1+l. If r<0 or r>1, the default value is used.
Defaults
This special keyword may be used to reset all optional parameters to their default values.
Expand Frequency
This option is part of an anti-cycling procedure designed to guarantee progress even on highly degenerate problems.
The strategy is to force a positive step at every iteration, at the expense of violating the constraints by a small amount. Suppose that the value of the optional parameter Feasibility Tolerance is δ. Over a period of i iterations, the feasibility tolerance actually used by e04nf (i.e., the working feasibility tolerance) increases from 0.5 δ to δ (in steps of 0.5 δ/i).
At certain stages the following ‘resetting procedure’ is used to remove constraint infeasibilities. First, all variables whose upper or lower bounds are in the working set are moved exactly onto their bounds. A count is kept of the number of nontrivial adjustments made. If the count is positive, iterative refinement is used to give variables that satisfy the working set to (essentially) machine precision. Finally, the working feasibility tolerance is reinitialized to 0.5 δ.
If a problem requires more than i iterations, the resetting procedure is invoked and a new cycle of i iterations is started with i incremented by 10. (The decision to resume the feasibility phase or optimality phase is based on comparing any constraint infeasibilities with δ.)
The resetting procedure is also invoked when e04nf reaches an apparently optimal, infeasible or unbounded solution, unless this situation has already occurred twice. If any nontrivial adjustments are made, iterations are continued.
If i≤0, the default value is used. If i≥9999999, no anti-cycling procedure is invoked.
Feasibility Phase Iteration Limit
Optimality Phase Iteration Limit
For problems of type FP, the scalar i 1 specifies the maximum number of iterations allowed before temination. Setting i 1=0 and Print Level>0 means that the workspace needed will be computed and printed, but no iterations will be performed.
For problems of type LP, the maximum number of iterations allowed before temination is taken as max i 1,i 2. Setting i 1=0, i 2=0 and Print Level>0 means that the workspace needed will be computed and printed, but no iterations will be performed.
For problems of type QP, the scalars i 1 and i 2 specify the maximum number of iterations allowed in the feasibility and optimality phases. Optimality Phase Iteration Limit is equivalent to Iteration Limit. Setting i 1=0 and Print Level>0 means that the workspace needed will be computed and printed, but no iterations will be performed.
If i 1<0 or i 2<0, the default value is used.
Feasibility Tolerance
If r≥ε, r defines the maximum acceptable absolute violation in each constraint at a ‘feasible’ point. For example, if the variables and the coefficients in the general constraints are of order unity, and the latter are correct to about 6 decimal digits, it would be appropriate to specify r as 10-6. If 0≤r<ε, the default value is used.
e04nf attempts to find a feasible solution before optimizing the objective function. If the sum of infeasibilities cannot be reduced to zero, the optional parameter Minimum Sum of Infeasibilities can be used to find the minimum value of the sum. Let Sinf be the corresponding sum of infeasibilities. If Sinf is quite small, it may be appropriate to raise r by a factor of 10 or 100. Otherwise, some error in the data should be suspected.
Note that a ‘feasible solution’ is a solution that satisfies the current constraints to within the tolerance r.
Hessian Rows
Note that this option does not apply to problems of type FP or LP.
This specifies m, the number of rows of the Hessian matrix H. The default value of m is n, the number of variables of the problem.
If the problem is of type QP then m will usually be n, the number of variables. However, a value of m less than n is appropriate for QP3 or QP4 if H is an upper trapezoidal matrix with m rows. Similarly, m may be used to define the dimension of a leading block of nonzeros in the Hessian matrices of QP1 or QP2. In this case the last n-m rows and columns of H are assumed to be zero. In the QP case m should not be greater than n; if it is, the last m-n rows of H are ignored.
If i<0 or i>n, the default value is used.
Infinite Bound Size
If r>0, r defines the ‘infinite’ bound bigbnd in the definition of the problem constraints. Any upper bound greater than or equal to bigbnd will be regarded as +∞ (and similarly any lower bound less than or equal to -bigbnd will be regarded as -∞). If r<0, the default value is used.
Infinite Step Size
If r>0, r specifies the magnitude of the change in variables that will be considered a step to an unbounded solution. (Note that an unbounded solution can occur only when the Hessian is not positive definite.) If the change in x during an iteration would exceed the value of r then the objective function is considered to be unbounded below in the feasible region. If r≤0, the default value is used.
Iteration Limit
Iters
Itns
See optional parameter Feasibility Phase Iteration Limit.
List
Nolist
Normally each optional parameter specification is printed as it is supplied. Optional parameter Nolist may be used to suppress the printing and optional parameter List may be used to restore printing.
Maximum Degrees of Freedom
Note that this option does not apply to problems of type FP or LP.
This places a limit on the storage allocated for the triangular factor R of the reduced Hessian HR. Ideally, i should be set slightly larger than the value of nR expected at the solution. It need not be larger than mn+1, where mn is the number of variables that appear nonlinearly in the quadratic objective function. For many problems it can be much smaller than mn.
For quadratic problems, a minimizer may lie on any number of constraints, so that nR may vary between 1 and n. The default value of i is therefore the number of variables n. If Hessian Rows m is specified, the default value of i is the same number, m.
Minimum Sum of Infeasibilities
If no feasible point exists for the constraints then this option is used to control whether or not e04nf will calculate a point that minimizes the constraint violations. If Minimum Sum of Infeasibilities=NO, e04nf will terminate as soon as it is evident that no feasible point exists for the constraints. The final point will generally not be the point at which the sum of infeasibilities is minimized. If Minimum Sum of Infeasibilities=YES, e04nf will continue until the sum of infeasibilities is minimized.
Monitoring File
If i≥0 and Print Level≥5, monitoring information produced by e04nf at every iteration is sent to a file with logical unit number i.
If i<0 and/or Print Level<5, no monitoring information is produced.
Optimality Tolerance
If r≥ε, r defines the tolerance used to determine if the bounds and general constraints have the right ‘sign’ for the solution to be judged to be optimal.
If 0≤r<ε, the default value is used.
Print Level
The value of i controls the amount of printout produced by e04nf, as indicated below. A detailed description of the printed output is given in [Description of the Printed Output] (summary output at each iteration and the final solution) and [Description of Monitoring Information] (monitoring information at each iteration). If i<0, the default value is used.
The following printout is sent to the current advisory message unit (as defined by (X04ABF not in this release)):
i | Output
≥0 0 | No output.
≥0 1 | The final solution only.
≥0 5 | One line of summary output (<80 characters; see [Description of the Printed Output]) for each iteration (no printout of the final solution).
≥10 | The final solution and one line of summary output for each iteration.
The following printout is sent to the logical unit number defined by the optional parameter Monitoring File:
i | Output
<5 | No output.
≥5 | One long line of output (>80 characters; see [Description of Monitoring Information]) for each iteration (no printout of the final solution).
≥20 | At each iteration: the Lagrange multipliers, the variables x, the constraint values Ax and the constraint status (see istate).
≥30 | At each iteration: the diagonal elements of the upper triangular matrix T associated with the TQ factorization (3) (see [Definition of Search Direction]) of the working set and the diagonal elements of the upper triangular matrix R.
If Print Level≥5 and the unit number defined by the Monitoring File is the same as that defined by (X04ABF not in this release) then the summary output is suppressed.
Problem Type
This option specifies the type of objective function to be minimized during the optimality phase. The following are the five optional keywords and the dimensions of the arrays that must be specified in order to define the objective function:
LP | h not referenced, cvec[n-1] required;
QP1 | h[ldh-1,!!!!!!!!!*-1] symmetric, cvec not referenced;
QP2 | h[ldh-1,!!!!!!!!!*-1] symmetric, cvec[n-1] required;
QP3 | h[ldh-1,!!!!!!!!!*-1] upper trapezoidal, cvec not referenced;
QP4 | h[ldh-1,!!!!!!!!!*-1] upper trapezoidal, cvec[n-1] required.
For problems of type FP the objective function is omitted and neither h nor cvec are referenced.
The following keywords are also acceptable. The minimum abbreviation of each keyword is underlined.
a | Option
Quadratic | QP2
Linear | LP
Feasible | FP
In addition, the keyword QP is equivalent to the default option QP2.
If H=0 (i.e., the objective function is purely linear), the efficiency of e04nf may be increased by specifying a as LP.
Rank Tolerance
Note that this option does not apply to problems of type FP or LP.
This optional parameter enables you to control the condition number of the triangular factor R (see [Algorithmic Details]). If ρi denotes the function ρi=max R 11,R 22,…,R ii, the dimension of R is defined to be smallest index i such that R i+1,i+1≤r ρ i+1. If r≤0, the default value is used.

Inheritance Hierarchy

System..::..Object
NagLibrary..::..E04..::..e04nfOptions

See Also

E04..::..e04nfOptions Members
NagLibrary Namespace
NAG Library Overview
e04nf


E04.e04nfOptions Members

[image] [image]

NAG Library for .NET Release 2
E04..::..e04nfOptions Members
E04..::..e04nfOptions Class Constructors Methods Properties See Also Send Feedback

An optimization problem involves minimizing a function (called the objective function) of several variables, possibly subject to restrictions on the values of the variables defined by a set of constraint functions. Most methods in the Library are concerned with function minimization only, since the problem of maximizing a given objective function F(x) is equivalent to minimizing -F x. Some methods allow you to specify whether you are solving a minimization or maximization problem, carrying out the required transformation of the objective function in the latter case.
In general methods in this chapter find a local minimum of a function f, that is a point x* s.t. for all x near x* f x≥f x*.
The E05 class contains methods to find the global minimum of a function f. At a global minimum x* f x≥f x* for all x.
The (H not in this release) contains methods typically regarded as belonging to the field of operations research.
This introduction is only a brief guide to the subject of optimization designed for the casual user. Anyone with a difficult or protracted problem to solve will find it beneficial to consult a more detailed text, such as Gill et al. (1981) or Fletcher (1987).
If you are unfamiliar with the mathematics of the subject you may find some sections difficult at first reading; if so, you should concentrate on [Types of Optimization Problems], [Geometric Representation and Terminology], [Scaling], [Analysis of Computed Results] and [Recommendations on Choice and Use of Available Methods] .

The E04..::..e04nfOptions type exposes the following members.

Constructors

Name | Description
E04..::..e04nfOptions | Constructor

Methods

Name | Description
Set | Overloaded.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e04nf.
Warning | Set the method used for logging any warning or error messages from e04nf.

See Also

E04..::..e04nfOptions Class


E04.e04nfOptions Constructor

[image]

NAG Library for .NET Release 2
E04..::..e04nfOptions Constructor
E04..::..e04nfOptions Class See Also Send Feedback
Constructor

Syntax

C#
public e04nfOptions()
Visual Basic
Public Sub New
Visual C++
public:
e04nfOptions()
F#
new : unit -> e04nfOptions

See Also

E04..::..e04nfOptions Class
E04..::..e04nfOptions Members


E04.e04nfOptions Methods

[image] [image]

NAG Library for .NET Release 2
E04..::..e04nfOptions Methods
E04..::..e04nfOptions Class See Also Send Feedback

Methods

Name | Description
Set | Overloaded.

See Also

E04..::..e04nfOptions Class


Set Method

[image] [image]

NAG Library for .NET Release 2
E04..::..e04nfOptions..::Set Method
E04..::..e04nfOptions Class See Also Send Feedback

Overload List

Name | Description
Set(String) | Set an Option for e04nf
Set(DataReader) | Set Options for from a DataReader Stream.

See Also

E04..::..e04nfOptions Class
E04..::..e04nfOptions Members


Set Method (String)

[image]

NAG Library for .NET Release 2
E04..::..e04nfOptions..::Set Method (String)
E04..::..e04nfOptions Class See Also Send Feedback
Set an Option for e04nf

Syntax

C#
public void Set(
    string str
)
Visual Basic
Public Sub Set ( _
    str As String _
)
Visual C++
public:
void Set(
    String^ str
)
F#
member Set :
        str : string -> unit

Parameters

str
Type: System..::..String
A string of the form option = value, or for boolean options, simply option.

See Also

E04..::..e04nfOptions Class
E04..::..e04nfOptions Members
Set Overload


Set Method (DataReader)

[image]

NAG Library for .NET Release 2
E04..::..e04nfOptions..::Set Method (DataReader)
E04..::..e04nfOptions Class See Also Send Feedback
Set Options for from a DataReader Stream.

Syntax

C#
public void Set(
    DataReader sr
)
Visual Basic
Public Sub Set ( _
    sr As DataReader _
)
Visual C++
public:
void Set(
    DataReader^ sr
)
F#
member Set :
        sr : DataReader -> unit

Parameters

sr
Type: NagLibrary..::..DataReader
A DataReader Stream, containing an option setting on each line.

See Also

E04..::..e04nfOptions Class
E04..::..e04nfOptions Members
Set Overload


E04.e04nfOptions Properties

[image] [image]

NAG Library for .NET Release 2
E04..::..e04nfOptions Properties
E04..::..e04nfOptions Class See Also Send Feedback

The E04..::..e04nfOptions type exposes the following members.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e04nf.
Warning | Set the method used for logging any warning or error messages from e04nf.

See Also

E04..::..e04nfOptions Class


Message Property

[image]

NAG Library for .NET Release 2
E04..::..e04nfOptions..::Message Property
E04..::..e04nfOptions Class See Also Send Feedback
Set the method used for logging any monitoring messages from e04nf.

Syntax

C#
public PrintManager..::..MessageLogger Message { get; set; }
Visual Basic
Public Property Message As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Message {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Message : PrintManager..::..MessageLogger with get, set

See Also

E04..::..e04nfOptions Class
E04..::..e04nfOptions Members


Warning Property

[image]

NAG Library for .NET Release 2
E04..::..e04nfOptions..::Warning Property
E04..::..e04nfOptions Class See Also Send Feedback
Set the method used for logging any warning or error messages from e04nf.

Syntax

C#
public PrintManager..::..MessageLogger Warning { get; set; }
Visual Basic
Public Property Warning As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Warning {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Warning : PrintManager..::..MessageLogger with get, set

See Also

E04..::..e04nfOptions Class
E04..::..e04nfOptions Members


E04.e04nkOptions Class

[image]

NAG Library for .NET Release 2
E04..::..e04nkOptions Class
E04 Class Members See Also Send Feedback
Options Class for e04nk

Syntax

C#
public class e04nkOptions
Visual Basic
Public Class e04nkOptions
Visual C++
public ref class e04nkOptions
F#
type e04nkOptions =  class end

Description of the Optional Parameters

For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
  • the keywords, where the minimum abbreviation of each keyword is underlined (if no characters of an optional qualifier are underlined, the qualifier may be omitted);
  • a parameter value, where the letters a, i​ and ​r denote options that take character, integer and real values respectively;
  • the default value is used whenever the condition i≥100000000 is satisfied and where the symbol ε is a generic notation for machine precision (see x02aj);
Keywords and character values are case and white space insensitive.
Check Frequency
Every ith iteration after the most recent basis factorization, a numerical test is made to see if the current solution x,s satisfies the linear constraints Ax-s=0. If the largest element of the residual vector r=Ax-s is judged to be too large, the current basis is refactorized and the basic variables recomputed to satisfy the constraints more accurately. If i<0, the default value is used. If i=0, the value i=99999999 is used and effectively no checks are made.
Crash Option
Note that this option does not apply when start="W" (see [Parameters]).
If start="C", an internal Crash procedure is used to select an initial basis from various rows and columns of the constraint matrix A-I. The value of i determines which rows and columns are initially eligible for the basis, and how many times the Crash procedure is called. If i=0, the all-slack basis B=-I is chosen. If i=1, the Crash procedure is called once (looking for a triangular basis in all rows and columns of the linear constraint matrix A). If i=2, the Crash procedure is called twice (looking at any equality constraints first followed by any inequality constraints). If i<0 or i>2, the default value is used.
If i=1​ or ​2, certain slacks on inequality rows are selected for the basis first. (If i=2, numerical values are used to exclude slacks that are close to a bound.) The Crash procedure then makes several passes through the columns of A, searching for a basis matrix that is essentially triangular. A column is assigned to ‘pivot’ on a particular row if the column contains a suitably large element in a row that has not yet been assigned. (The pivot elements ultimately form the diagonals of the triangular basis.) For remaining unassigned rows, slack variables are inserted to complete the basis.
Crash Tolerance
This value allows the Crash procedure to ignore certain ‘small’ nonzero elements in the constraint matrix A while searching for a triangular basis. For each column of A, if amax is the largest element in the column, other nonzeros in that column are ignored if they are less than (or equal to) amax×r.
When r>0, the basis obtained by the Crash procedure may not be strictly triangular, but it is likely to be nonsingular and almost triangular. The intention is to obtain a starting basis with more column variables and fewer (arbitrary) slacks. A feasible solution may be reached earlier for some problems. If r<0 or r≥1, the default value is used.
Defaults
This special keyword may be used to reset all optional parameters to their default values.
Expand Frequency
This option is part of an anti-cycling procedure (see [Miscellaneous]) designed to allow progress even on highly degenerate problems.
For LP problems, the strategy is to force a positive step at every iteration, at the expense of violating the constraints by a small amount. Suppose that the value of the optional parameter Feasibility Tolerance is δ. Over a period of i iterations, the feasibility tolerance actually used by e04nk (i.e., the working feasibility tolerance) increases from 0.5 δ to δ (in steps of 0.5 δ/i).
For QP problems, the same procedure is used for iterations in which there is only one superbasic variable. (Cycling can only occur when the current solution is at a vertex of the feasible region.) Thus, zero steps are allowed if there is more than one superbasic variable, but otherwise positive steps are enforced.
Increasing the value of i helps reduce the number of slightly infeasible nonbasic basic variables (most of which are eliminated during the resetting procedure). However, it also diminishes the freedom to choose a large pivot element (see optional parameter Pivot Tolerance).
If i<0, the default value is used. If i=0, the value i=99999999 is used and effectively no anti-cycling procedure is invoked.
Factorization Frequency
If i>0, at most i basis changes will occur between factorizations of the basis matrix. For LP problems, the basis factors are usually updated at every iteration. For QP problems, fewer basis updates will occur as the solution is approached. The number of iterations between basis factorizations will therefore increase. During these iterations a test is made regularly according to the value of optional parameter Check Frequency to ensure that the linear constraints Ax-s=0 are satisfied. If necessary, the basis will be refactorized before the limit of i updates is reached. If i≤0, the default value is used.
Feasibility Tolerance
If r≥ε, r defines the maximum acceptable absolute violation in each constraint at a ‘feasible’ point (including slack variables). For example, if the variables and the coefficients in the linear constraints are of order unity, and the latter are correct to about five decimal digits, it would be appropriate to specify r as 10-5. If r<ε, the default value is used.
e04nk attempts to find a feasible solution before optimizing the objective function. If the sum of infeasibilities cannot be reduced to zero, the problem is assumed to be infeasible. Let Sinf be the corresponding sum of infeasibilities. If Sinf is quite small, it may be appropriate to raise r by a factor of 10 or 100. Otherwise, some error in the data should be suspected. Note that the method does not attempt to find the minimum value of Sinf.
If the constraints and variables have been scaled (see Scale Option), then feasibility is defined in terms of the scaled problem (since it is more likely to be meaningful).
Infinite Bound Size
If r>0, r defines the ‘infinite’ bound bigbnd in the definition of the problem constraints. Any upper bound greater than or equal to bigbnd will be regarded as +∞ (and similarly any lower bound less than or equal to -bigbnd will be regarded as -∞). If r≤0, the default value is used.
Infinite Step Size
If r>0, r specifies the magnitude of the change in variables that will be considered a step to an unbounded solution. (Note that an unbounded solution can occur only when the Hessian is not positive definite.) If the change in x during an iteration would exceed the value of r, the objective function is considered to be unbounded below in the feasible region. If r≤0, the default value is used.
Iteration Limit
Iters
Itns
The value of i specifies the maximum number of iterations allowed before termination. Setting i=0 and Print Level>0 means that the workspace needed to start solving the problem will be computed and printed, but no iterations will be performed. If i<0, the default value is used.
List
Nolist
Normally each optional parameter specification is printed as it is supplied. Optional parameter Nolist may be used to suppress the printing and optional parameter List may be used to restore printing.
LU Factor Tolerance
LU Update Tolerance
The values of r 1 and r 2 affect the stability and sparsity of the basis factorization B=LU, during refactorization and updates respectively. The lower triangular matrix L is a product of matrices of the form
10μ1
where the multipliers μ will satisfy μ≤ri. The default values of r 1 and r 2 usually strike a good compromise between stability and sparsity. For large and relatively dense problems, setting r 1 and r 2 to 25 (say) may give a marked improvement in sparsity without impairing stability to a serious degree.
Note that for band matrices it may be necessary to set r 1 in the range 1≤r 1<2 in order to achieve stability. If r 1<1 or r 2<1, the default value is used.
LU Singularity Tolerance
If r>0, r defines the singularity tolerance used to guard against ill-conditioned basis matrices. Whenever the basis is refactorized, the diagonal elements of U are tested as follows. If u jj≤r or u jj<r×maxi u ij, the jth column of the basis is replaced by the corresponding slack variable. If r≤0, the default value is used.
Minimize
Maximize
This option specifies the required direction of the optimization. It applies to both linear and nonlinear terms (if any) in the objective function. Note that if two problems are the same except that one minimizes f x and the other maximizes -f x, their solutions will be the same but the signs of the dual variables πi and the reduced gradients dj (see [Main Iteration]) will be reversed.
Monitoring File
If i≥0 and Print Level>0 (see Print Level), monitoring information produced by e04nk is sent to a file with logical unit number i. If i<0 and/or Print Level=0, the default value is used and hence no monitoring information is produced.
Optimality Tolerance
If r≥ε, r is used to judge the size of the reduced gradients dj=gj-πT aj. By definition, the reduced gradients for basic variables are always zero. Optimality is declared if the reduced gradients for any nonbasic variables at their lower or upper bounds satisfy -r×max 1,π≤dj≤r×max 1,π, and if dj≤r×max 1,π for any superbasic variables. If r<ε, the default value is used.
Partial Price
Note that this option does not apply to QP problems.
This option is recommended for large FP or LP problems that have significantly more variables than constraints (i.e., n≫m). It reduces the work required for each pricing operation (i.e., when a nonbasic variable is selected to enter the basis). If i=1, all columns of the constraint matrix A-I are searched. If i>1, A and -I are partitioned to give i roughly equal segments Aj,Kj, for j=1,2,…,p (modulo p). If the previous pricing search was successful on A j-1,K j-1, the next search begins on the segments Aj,Kj. If a reduced gradient is found that is larger than some dynamic tolerance, the variable with the largest such reduced gradient (of appropriate sign) is selected to enter the basis. If nothing is found, the search continues on the next segments A j+1,K j+1, and so on. If i≤0, the default value is used.
Pivot Tolerance
If r>0, r is used to prevent columns entering the basis if they would cause the basis to become almost singular. If r≤0, the default value is used.
Print Level
The value of i controls the amount of printout produced by e04nk, as indicated below. A detailed description of the printed output is given in [Description of the Printed Output] (summary output at each iteration and the final solution) and [Description of Monitoring Information] (monitoring information at each iteration). Note that the summary output will not exceed 80 characters per line and that the monitoring information will not exceed 120 characters per line. If i<0, the default value is used.
The following printout is sent to the current advisory message unit (as defined by (X04ABF not in this release)):
i | Output
≥0 0 | No output.
≥0 1 | The final solution only.
≥0 5 | One line of summary output for each iteration (no printout of the final solution).
≥10 | The final solution and one line of summary output for each iteration.
The following printout is sent to the logical unit number defined by the optional parameter Monitoring File:
i | Output
≥0 0 | No output.
≥0 1 | The final solution only.
≥0 5 | One long line of output for each iteration (no printout of the final solution).
≥10 | The final solution and one long line of output for each iteration.
≥20 | The final solution, one long line of output for each iteration, matrix statistics (initial status of rows and columns, number of elements, density, biggest and smallest elements, etc.), details of the scale factors resulting from the scaling procedure (if Scale Option=1 or 2 (see the description of the optional parameter Scale Option), basis factorization statistics and details of the initial basis resulting from the Crash procedure (if start="C"; see [Parameters]).
If Print Level>0 and the unit number defined by optional parameter Monitoring File is the same as that defined by (X04ABF not in this release), then the summary output is suppressed.
Rank Tolerance
Scale Option
This option enables you to scale the variables and constraints using an iterative procedure due to Fourer (1982), which attempts to compute row scales ri and column scales cj such that the scaled matrix coefficients a-ij=a ij×cj/ri are as close as possible to unity. This may improve the overall efficiency on some problems. (The lower and upper bounds on the variables and slacks for the scaled problem are redefined as l-j=lj/cj and u-j=uj/cj respectively, where cj≡r j-n if j>n.)
If i=0, no scaling is performed. If i=1, all rows and columns of the constraint matrix A are scaled. If i=2, an additional scaling is performed that may be helpful when the solution x is large; it takes into account columns of A-I that are fixed or have positive lower bounds or negative upper bounds. If i<0 or i>2, the default value is used.
Scale Tolerance
Note that this option does not apply when Scale Option=0.
If 0<r<1, r is used to control the number of scaling passes to be made through the constraint matrix A. At least 3 (and at most 10) passes will be made. More precisely, let ap denote the largest column ratio (i.e., 'biggest'​ element'smallest'​ element in some sense) after the pth scaling pass through A. The scaling procedure is terminated if ap≥a p-1×r for some p≥3. Thus, increasing the value of r from 0.9 to 0.99 (say) will probably increase the number of passes through A.
If r≤0 or r≥1, the default value is used.
Superbasics Limit
Note that this option does not apply to FP or LP problems.
The value of i specifies ‘how nonlinear’ you expect the QP problem to be. If i≤0, the default value is used.

Inheritance Hierarchy

System..::..Object
NagLibrary..::..E04..::..e04nkOptions

See Also

E04..::..e04nkOptions Members
NagLibrary Namespace
NAG Library Overview
e04nk


E04.e04nkOptions Members

[image] [image]

NAG Library for .NET Release 2
E04..::..e04nkOptions Members
E04..::..e04nkOptions Class Constructors Methods Properties See Also Send Feedback

An optimization problem involves minimizing a function (called the objective function) of several variables, possibly subject to restrictions on the values of the variables defined by a set of constraint functions. Most methods in the Library are concerned with function minimization only, since the problem of maximizing a given objective function F(x) is equivalent to minimizing -F x. Some methods allow you to specify whether you are solving a minimization or maximization problem, carrying out the required transformation of the objective function in the latter case.
In general methods in this chapter find a local minimum of a function f, that is a point x* s.t. for all x near x* f x≥f x*.
The E05 class contains methods to find the global minimum of a function f. At a global minimum x* f x≥f x* for all x.
The (H not in this release) contains methods typically regarded as belonging to the field of operations research.
This introduction is only a brief guide to the subject of optimization designed for the casual user. Anyone with a difficult or protracted problem to solve will find it beneficial to consult a more detailed text, such as Gill et al. (1981) or Fletcher (1987).
If you are unfamiliar with the mathematics of the subject you may find some sections difficult at first reading; if so, you should concentrate on [Types of Optimization Problems], [Geometric Representation and Terminology], [Scaling], [Analysis of Computed Results] and [Recommendations on Choice and Use of Available Methods] .

The E04..::..e04nkOptions type exposes the following members.

Constructors

Name | Description
E04..::..e04nkOptions | Constructor

Methods

Name | Description
Set | Overloaded.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e04nk.
Warning | Set the method used for logging any warning or error messages from e04nk.

See Also

E04..::..e04nkOptions Class


E04.e04nkOptions Constructor

[image]

NAG Library for .NET Release 2
E04..::..e04nkOptions Constructor
E04..::..e04nkOptions Class See Also Send Feedback
Constructor

Syntax

C#
public e04nkOptions()
Visual Basic
Public Sub New
Visual C++
public:
e04nkOptions()
F#
new : unit -> e04nkOptions

See Also

E04..::..e04nkOptions Class
E04..::..e04nkOptions Members


E04.e04nkOptions Methods

[image] [image]

NAG Library for .NET Release 2
E04..::..e04nkOptions Methods
E04..::..e04nkOptions Class See Also Send Feedback

Methods

Name | Description
Set | Overloaded.

See Also

E04..::..e04nkOptions Class


Set Method

[image] [image]

NAG Library for .NET Release 2
E04..::..e04nkOptions..::Set Method
E04..::..e04nkOptions Class See Also Send Feedback

Overload List

Name | Description
Set(String) | Set an Option for e04nk
Set(DataReader) | Set Options for from a DataReader Stream.

See Also

E04..::..e04nkOptions Class
E04..::..e04nkOptions Members


Set Method (String)

[image]

NAG Library for .NET Release 2
E04..::..e04nkOptions..::Set Method (String)
E04..::..e04nkOptions Class See Also Send Feedback
Set an Option for e04nk

Syntax

C#
public void Set(
    string str
)
Visual Basic
Public Sub Set ( _
    str As String _
)
Visual C++
public:
void Set(
    String^ str
)
F#
member Set :
        str : string -> unit

Parameters

str
Type: System..::..String
A string of the form option = value, or for boolean options, simply option.

See Also

E04..::..e04nkOptions Class
E04..::..e04nkOptions Members
Set Overload


Set Method (DataReader)

[image]

NAG Library for .NET Release 2
E04..::..e04nkOptions..::Set Method (DataReader)
E04..::..e04nkOptions Class See Also Send Feedback
Set Options for from a DataReader Stream.

Syntax

C#
public void Set(
    DataReader sr
)
Visual Basic
Public Sub Set ( _
    sr As DataReader _
)
Visual C++
public:
void Set(
    DataReader^ sr
)
F#
member Set :
        sr : DataReader -> unit

Parameters

sr
Type: NagLibrary..::..DataReader
A DataReader Stream, containing an option setting on each line.

See Also

E04..::..e04nkOptions Class
E04..::..e04nkOptions Members
Set Overload


E04.e04nkOptions Properties

[image] [image]

NAG Library for .NET Release 2
E04..::..e04nkOptions Properties
E04..::..e04nkOptions Class See Also Send Feedback

The E04..::..e04nkOptions type exposes the following members.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e04nk.
Warning | Set the method used for logging any warning or error messages from e04nk.

See Also

E04..::..e04nkOptions Class


Message Property

[image]

NAG Library for .NET Release 2
E04..::..e04nkOptions..::Message Property
E04..::..e04nkOptions Class See Also Send Feedback
Set the method used for logging any monitoring messages from e04nk.

Syntax

C#
public PrintManager..::..MessageLogger Message { get; set; }
Visual Basic
Public Property Message As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Message {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Message : PrintManager..::..MessageLogger with get, set

See Also

E04..::..e04nkOptions Class
E04..::..e04nkOptions Members


Warning Property

[image]

NAG Library for .NET Release 2
E04..::..e04nkOptions..::Warning Property
E04..::..e04nkOptions Class See Also Send Feedback
Set the method used for logging any warning or error messages from e04nk.

Syntax

C#
public PrintManager..::..MessageLogger Warning { get; set; }
Visual Basic
Public Property Warning As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Warning {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Warning : PrintManager..::..MessageLogger with get, set

See Also

E04..::..e04nkOptions Class
E04..::..e04nkOptions Members


E04.e04nqOptions Class

[image]

NAG Library for .NET Release 2
E04..::..e04nqOptions Class
E04 Class Members See Also Send Feedback
Options Class for e04nq

Syntax

C#
public class e04nqOptions
Visual Basic
Public Class e04nqOptions
Visual C++
public ref class e04nqOptions
F#
type e04nqOptions =  class end

Description of the Optional Parameters

For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
  • the keywords;
  • a parameter value, where the letters a, i​ and ​r denote options that take character, integer and real values respectively;
  • the default value is used whenever the condition i≥100000000 is satisfied and where the symbol ε is a generic notation for machine precision (see x02aj);
  • The variable bigbnd holds the value of Infinite Bound Size.
Keywords and character values are case and white space insensitive.
Check Frequency
Every ith iteration after the most recent basis factorization, a numerical test is made to see if the current solution x,s satisfies the linear constraints Ax-s=0. If the largest element of the residual vector r=Ax-s is judged to be too large, the current basis is refactorized and the basic variables recomputed to satisfy the constraints more accurately. If i≤0, the value i=99999999 is used and effectively no checks are made.
Check Frequency=1 is useful for debugging purposes, but otherwise this option should not be needed.
Crash Option
Crash Tolerance
Note that these options do not apply when start="W" (see [Parameters]).
If start="C", an internal Crash procedure is used to select an initial basis from various rows and columns of the constraint matrix A-I. The value of i determines which rows and columns of A are initially eligible for the basis, and how many times the Crash procedure is called. Columns of -I are used to pad the basis where necessary.
i | Meaning
0 | The initial basis contains only slack variables: B=I.
1 | The Crash procedure is called once, looking for a triangular basis in all rows and columns of the matrix A.
2 | The Crash procedure is called once, looking for a triangular basis in rows.
3 | The Crash procedure is called twice, treating linear equalities and linear inequalities separately.
If i≥1, certain slacks on inequality rows are selected for the basis first. (If i≥2, numerical values are used to exclude slacks that are close to a bound.) The Crash procedure then makes several passes through the columns of A, searching for a basis matrix that is essentially triangular. A column is assigned to ‘pivot’ on a particular row if the column contains a suitably large element in a row that has not yet been assigned. (The pivot elements ultimately form the diagonals of the triangular basis.) For remaining unassigned rows, slack variables are inserted to complete the basis.
The Crash Tolerance allows the Crash procedure to ignore certain ‘small’ nonzero elements in each column of A. If amax is the largest element in column j, other nonzeros a ij in the column are ignored if a ij≤amax×r. (To be meaningful, r should be in the range 0≤r<1.)
When r>0.0, the basis obtained by the Crash procedure may not be strictly triangular, but it is likely to be nonsingular and almost triangular. The intention is to obtain a starting basis containing more columns of A and fewer (arbitrary) slacks. A feasible solution may be reached sooner on some problems.
For example, suppose the first m columns of A form the matrix shown under LU Factor Tolerance; i.e., a tridiagonal matrix with entries -1, 4, -1. To help the Crash procedure choose all m columns for the initial basis, we would specify a Crash Tolerance of r for some value of r>0.5.
Defaults
This special keyword may be used to reset all optional parameters to their default values.
Dump File
Load File
Optional parameters Dump File and Load File are similar to optional parameters Punch File and Insert File, but they record solution information in a manner that is more direct and more easily modified. A full description of information recorded in optional parameters Dump File and Load File is given in Gill et al. (2005a).
If i 1>0, the last solution obtained will be output to the file with unit number i.
If i 2>0, the Load File containing basis information will be read. The file will usually have been output previously as a Dump File. The file will not be accessed if optional parameters Old Basis File or Insert File are specified.
Elastic Mode
This parameter determines if (and when) elastic mode is to be started. Three elastic modes are available as follows:
i | Meaning
0 | Elastic mode is never invoked. e04nq will terminate as soon as infeasibility is detected. There may be other points with significantly smaller sums of infeasibilities.
1 | Elastic mode is invoked only if the constraints are found to be infeasible (the default). If the constraints are infeasible, continue in elastic mode with the composite objective determined by the values of the optional parameters Elastic Objective and Elastic Weight.
2 | The iterations start and remain in elastic mode. This option allows you to minimize the composite objective function directly without first performing Phase 1 iterations. The success of this option will depend critically on your choice of Elastic Weight. If Elastic Weight is sufficiently large and the constraints are feasible, the minimizer of the composite objective and the solution of the original problem are identical. However, if the Elastic Weight is not sufficiently large, the minimizer of the composite function may be infeasible, even if a feasible point exists.
Elastic Objective
This determines the form of the composite objective f x+γ∑j vj+wj in Phase 2 (γ). Three types of composite objectives are available.
i | Meaning
0 | Include only the true objective f x in the composite objective. This option sets γ=0 in the composite objective and allows e04nq to ignore the elastic bounds and find a solution that minimizes f x subject to the non-elastic constraints. This option is useful if there are some ‘soft’ constraints that you would like to ignore if the constraints are infeasible.
1 | Use a composite objective defined with γ determined by the value of Elastic Weight. This value is intended to be used in conjunction with Elastic Mode=2.
2 | Include only the elastic variables in the composite objective. The elastics are weighted by γ=1. This choice minimizes the violations of the elastic variables at the expense of possibly increasing the true objective. This option can be used to find a point that minimizes the sum of the violations of a subset of constraints specified by the input array helast.
Elastic Weight
This defines the value of γ in the composite objective in Phase 2 (γ).
At each iteration of elastic mode, the composite objective is defined to be
minimize​ ​σ​ ​f x+γ​ (sum of infeasibilities);
where σ=1 for Minimize, σ=-1 for Maximize, and f x is the quadratic objective.
Note that the effect of γ is not disabled once a feasible point is obtained.
Expand Frequency
This option is part of an anti-cycling procedure (see [Miscellaneous]) designed to allow progress even on highly degenerate problems.
The strategy is to force a positive step at every iteration, at the expense of violating the constraints by a small amount. Suppose that the value of the optional parameter Feasibility Tolerance is δ. Over a period of i iterations, the feasibility tolerance actually used by e04nq (i.e., the working feasibility tolerance) increases from 0.5 δ to δ (in steps of 0.5 δ/i).
Increasing the value of i helps reduce the number of slightly infeasible nonbasic variables (most of which are eliminated during the resetting procedure). However, it also diminishes the freedom to choose a large pivot element (see the description of the optional parameter Pivot Tolerance).
If i≤0, the value i=99999999 is used and effectively no anti-cycling procedure is invoked.
Factorization Frequency
If i>0, at most i basis changes will occur between factorizations of the basis matrix.
For LP problems, the basis factors are usually updated at every iteration. Higher values of i may be more efficient on problems that are extremely sparse and well scaled.
For QP problems, fewer basis updates will occur as the solution is approached. The number of iterations between basis factorizations will therefore increase. During these iterations a test is made regularly according to the value of optional parameter Check Frequency to ensure that the linear constraints Ax-s=0 are satisfied. Occasionally, the basis will be refactorized before the limit of i updates is reached. If i≤0, the default value is used.
Feasibility Tolerance
A feasible problem is one in which all variables satisfy their upper and lower bounds to within the absolute tolerance r. (This includes slack variables. Hence, the general constraints are also satisfied to within r.)
e04nq attempts to find a feasible solution before optimizing the objective function. If the sum of infeasibilities cannot be reduced to zero, the problem is assumed to be infeasible. Let sInf be the corresponding sum of infeasibilities. If sInf is quite small, it may be appropriate to raise r by a factor of 10 or 100. Otherwise, some error in the data should be suspected.
Note that if sInf is not small and you have not asked e04nq to minimize the violations of the elastic variables (i.e., you have not specified Elastic Objective=2), there may be other points that have a significantly smaller sum of infeasibilities. e04nq will not attempt to find the solution that minimizes the sum unless Elastic Objective=2.
If the constraints and variables have been scaled (see the description of the optional parameter Scale Option), then feasibility is defined in terms of the scaled problem (since it is more likely to be meaningful).
Infinite Bound Size
If r≥0, r defines the ‘infinite’ bound infbnd in the definition of the problem constraints. Any upper bound greater than or equal to infbnd will be regarded as +∞ (and similarly any lower bound less than or equal to -infbnd will be regarded as -∞). If r<0, the default value is used.
Iterations Limit
The value of i specifies the maximum number of iterations allowed before termination. Setting i=0 and Print Level>0 means that: the workspace needed to start solving the problem will be computed and printed; and feasibility and optimality will be checked. No iterations will be performed. If i<0, the default value is used.
LU Density Tolerance
LU Singularity Tolerance
The density tolerance r 1 is used during LU factorization of the basis matrix. Columns of L and rows of U are formed one at a time, and the remaining rows and columns of the basis are altered appropriately. At any stage, if the density of the remaining matrix exceeds r 1, the Markowitz strategy for choosing pivots is terminated. The remaining matrix is factored by a dense LU procedure. Raising the density tolerance towards 1.0 may give slightly sparser LU factors, with a slight increase in factorization time.
If r 2>0, r 2 defines the singularity tolerance used to guard against ill-conditioned basis matrices. After B is refactorized, the diagonal elements of U are tested as follows. If u jj≤r 2 or u jj<r 2 maxi u ij, the jth column of the basis is replaced by the corresponding slack variable. If r 2≤0, the default value is used.
LU Factor Tolerance
LU Update Tolerance
The values of r 1 and r 2 affect the stability and sparsity of the basis factorization B=LU, during refactorization and updates respectively. The lower triangular matrix L is a product of matrices of the form
10μ1
where the multipliers μ will satisfy μ≤ri. The default values of r 1 and r 2 usually strike a good compromise between stability and sparsity. They must satisfy r 1, r 2≥1.0.
For large and relatively dense problems, r 1=10.0​ or ​5.0 (say) may give a useful improvement in stability without impairing sparsity to a serious degree.
For certain very regular structures (e.g., band matrices) it may be necessary to reduce r 1​ and/or ​r 2 in order to achieve stability. For example, if the columns of A include a sub-matrix of the form
4-1-14-1-14-1………-14-1-14,
one should set both r 1 and r 2 to values in the range 1.0≤ri<4.0.
LU Partial Pivoting
LU Complete Pivoting
LU Rook Pivoting
The LU factorization implements a Markowitz-type search for pivots that locally minimize the fill-in subject to a threshold pivoting stability criterion. The default option is to use threshold partial pivoting. The options LU Complete Pivoting and LU Rook Pivoting are more expensive but more stable and better at revealing rank, as long as the LU Factor Tolerance is not too large (say <2.0).
Minimize
Maximize
Feasible Point
This option specifies the required direction of the optimization. It applies to both linear and nonlinear terms (if any) in the objective function. Note that if two problems are the same except that one minimizes f x and the other maximizes -f x, their solutions will be the same but the signs of the dual variables πi and the reduced gradients dj (see [Main Iteration]) will be reversed.
The option Feasible Point means ‘ignore the objective function, while finding a feasible point for the linear constraints’. It can be used to check that the constraints are feasible without altering the call to e04nq.
New Basis File
Backup Basis File
Save Frequency
Optional parameters New Basis File and Backup Basis File are sometimes referred to as basis maps. They contain the most compact representation of the state of each variable. They are intended for restarting the solution of a problem at a point that was reached by an earlier run. For nontrivial problems, it is advisable to save basis maps at the end of a run, in order to restart the run if necessary.
If i 1>0, a basis map will be saved on file i 1 every i 3th iteration, where i 3 is the Save Frequency. The first record of the file will contain the word PROCEEDING if the run is still in progress. A basis map will also be saved at the end of a run, with some other word indicating the final solution status.
Use of i 2>0 is intended as a safeguard against losing the results of a long run. Suppose that a New Basis File is being saved every 100 (Save Frequency) iterations, and that e04nq is about to save such a basis at iteration 2000. It is conceivable that the run may be interrupted during the next few milliseconds (in the middle of the save). In this case the Basis file will be corrupted and the run will have been essentially wasted.
To eliminate this risk, both a New Basis File and a Backup Basis File may be specified. The following would be suitable for the above example:

Backup Basis File 11
New Basis File 12
The current basis will then be saved every 100 iterations, first on File 12 and then immediately on File 11. If the run is interrupted at iteration 2000 during the save on File 12, there will still be a usable basis on File 11 (corresponding to iteration 1900).
Note that a new basis will be saved in New Basis File at the end of a run if it terminates normally, but it will not be saved in Backup Basis File. In the above example, if an optimum solution is found at iteration 2050 (or if the iteration limit is 2050), the final basis on File 12 will correspond to iteration 2050, but the last basis saved on File 11 will be the one for iteration 2000.
A full description of information recorded in New Basis File and Backup Basis File is given in Gill et al. (2005a).
Nolist
List
Normally each optional parameter specification is printed to unit Print File as it is supplied. Optional parameter Nolist may be used to suppress the printing and optional parameter List may be used to restore printing.
Old Basis File
If i>0, the basis maps information will be obtained from this file. The file will usually have been output previously as a New Basis File or Backup Basis File. A full description of information recorded in New Basis File and Backup Basis File is given in Gill et al. (2005a).
The file will not be acceptable if the number of rows or columns in the problem has been altered.
Optimality Tolerance
This is used to judge the size of the reduced gradients dj=gj-ajT π, where gj is the jth component of the gradient, aj is the associated column of the constraint matrix A-I, and π is the set of dual variables.
By construction, the reduced gradients for basic variables are always zero. The problem will be declared optimal if the reduced gradients for nonbasic variables at their lower or upper bounds satisfy
dj/π≥-r or dj/π≤r
respectively, and if dj/π≤r for superbasic variables.
In the above tests, π is a measure of the size of the dual variables. It is included to make the tests independent of a scale factor on the objective function. The quantity π actually used is defined by
π=max σ/m,1, where ​σ=∑i=1 m πi,
so that only large scale factors are allowed for.
If the objective is scaled down to be very small, the optimality test reduces to comparing dj against 0.01 r.
Partial Price
This option is recommended for large FP or LP problems that have significantly more variables than constraints (i.e., n≫m). It reduces the work required for each pricing operation (i.e., when a nonbasic variable is selected to enter the basis). If i=1, all columns of the constraint matrix A-I are searched. If i>1, A and I are partitioned to give i roughly equal segments Aj,Ij, for j=1,2,…,i (modulo i). If the previous pricing search was successful on A j-1,I j-1, the next search begins on the segments Aj and Ij. If a reduced gradient is found that is larger than some dynamic tolerance, the variable with the largest such reduced gradient (of appropriate sign) is selected to enter the basis. If nothing is found, the search continues on the next segments A j+1,I j+1, and so on. If i≤0, the default value is used.
Pivot Tolerance
Broadly speaking, the pivot tolerance is used to prevent columns entering the basis if they would cause the basis to become almost singular.
When x changes to x+αp for some search direction p, a ‘ratio test’ determines which component of x reaches an upper or lower bound first. The corresponding element of p is called the pivot element. Elements of p are ignored (and therefore cannot be pivot elements) if they are smaller than the pivot tolerance r.
It is common for two or more variables to reach a bound at essentially the same time. In such cases, the optional parameter Feasibility Tolerance (say t) provides some freedom to maximize the pivot element and thereby improve numerical stability. Excessively small values of t should therefore not be specified. To a lesser extent, the optional parameter Expand Frequency (say f) also provides some freedom to maximize the pivot element. Excessively large values of f should therefore not be specified.
Print File
If i>0, the following information is output to i during the solution of each problem:
– | a listing of the optional parameters;
– | some statistics about the problem;
– | the amount of storage available for the LU factorization of the basis matrix;
– | notes about the initial basis resulting from a Crash procedure or a Basis file;
– | the iteration log;
– | basis factorization statistics;
– | the exit ifail condition and some statistics about the solution obtained;
– | the printed solution, if requested.
The last four items are described in [Further Comments] and [Description of Monitoring Information]. Further brief output may be directed to the Summary File.
Print Frequency
If i>0, one line of the iteration log will be printed every ith iteration. A value such as i=10 is suggested for those interested only in the final solution. If i≤0, the value of i=99999999 is used and effectively no checks are made.
Print Level
This controls the amount of printing produced by e04nq as follows.
i | Meaning
0 | No output except error messages. If you want to suppress all output, set Print File=0.
=1 | The set of selected options, problem statistics, summary of the scaling procedure, information about the initial basis resulting from a Crash or a Basis file, a single line of output at each iteration (controlled by the optional parameter Print Frequency), and the exit condition with a summary of the final solution.
≥10 | Basis factorization statistics.
Punch File
Insert File
These files provide compatibility with commercial mathematical programming systems. The Punch File from a previous run may be used as an Insert File for a later run on the same problem. A full description of information recorded in Insert File and Punch File is given in Gill et al. (2005a).
If i 1>0, the final solution obtained will be output to file i 1. For linear programs, this format is compatible with various commercial systems.
If i 2>0, the Insert File containing basis information will be read. The file will usually have been output previously as a Punch File. The file will not be accessed if Old Basis File is specified.
QPSolver Cholesky
QPSolver CG
QPSolver QN
Specifies the active-set algorithm used to solve the quadratic program in Phase 2 (γ). QPSolver Cholesky holds the full Cholesky factor R of the reduced Hessian ZT HZ. As the QP iterations proceed, the dimension of R changes with the number of superbasic variables. If the number of superbasic variables needs to increase beyond the value of Reduced Hessian Dimension, the reduced Hessian cannot be stored and the solver switches to QPSolver CG. The Cholesky solver is reactivated if the number of superbasics stabilizes at a value less than Reduced Hessian Dimension.
QPSolver QN solves the QP using a quasi-Newton method. In this case, R is the factor of a quasi-Newton approximate Hessian.
QPSolver CG uses an active-set method similar to QPSolver QN, but uses the conjugate-gradient method to solve all systems involving the reduced Hessian.
The Cholesky QP solver is the most robust, but may require a significant amount of computation if there are many superbasics.
The quasi-Newton QP solver does not require computation of the exact R at the start of Phase 2 (γ). It may be appropriate when the number of superbasics is large but relatively few iterations are needed to reach a solution (e.g., if e04nq is called with a Warm Start).
The conjugate-gradient QP solver is appropriate for problems with many degrees of freedom (say, more than 2000 superbasics).
Reduced Hessian Dimension
This specifies that an i by i triangular matrix R (to define the reduced Hessian according to RT R=ZT HZ). is to be available for use by the Cholesky QP solver.
Scale Option
Scale Tolerance
Scale Print
Three scale options are available as follows:
i | Meaning
0 | No scaling. This is recommended if it is known that x and the constraint matrix never have very large elements (say, larger than 100).
1 | The constraints and variables are scaled by an iterative procedure that attempts to make the matrix coefficients as close as possible to 1.0 (see Fourer (1982)). This will sometimes improve the performance of the solution procedures.
2 | The constraints and variables are scaled by the iterative procedure. Also, a certain additional scaling is performed that may be helpful if the right-hand side b or the solution x is large. This takes into account columns of A-I that are fixed or have positive lower bounds or negative upper bounds.
Optional parameter Scale Tolerance affects how many passes might be needed through the constraint matrix. On each pass, the scaling procedure computes the ratio of the largest and smallest nonzero coefficients in each column:
ρj=maxj a ij/mini a ij a ij≠0.
If maxj ρj is less than r times its previous value, another scaling pass is performed to adjust the row and column scales. Raising r from 0.9 to 0.99 (say) usually increases the number of scaling passes through A. At most 10 passes are made. The value of r should lie in the range 0<r<1.
Scale Print causes the row scales r i and column scales c j to be printed to Print File, if System Information Yes has been specified. The scaled matrix coefficients are a-ij=a ij c j/r i, and the scaled bounds on the variables and slacks are l-j=lj/c j, u-j=uj/c j, where c j=r j-n if j>n.
Solution Yes
Solution No
This option determines if the final obtained solution is to be output to the Print File. Note that the Solution File option operates independently.
Solution File
If i>0, the final solution will be output to file i (whether optimal or not).
To see more significant digits in the printed solution, it will sometimes be useful to make i refer to the system Print File.
Summary File
Summary Frequency
If i 1>0, the Summary File is output to file i 1, including a line of the iteration log every i 2th iteration. In an interactive environment, it is useful to direct this output to the terminal, to allow a run to be monitored online. (If something looks wrong, the run can be manually terminated.) Further details are given in [Description of Monitoring Information]. If i 2≤0, the value of i 2=99999999 is used and effectively no checks are made.
Superbasics Limit
This places a limit on the storage allocated for superbasic variables. Ideally, i should be set slightly larger than the ‘number of degrees of freedom’ expected at an optimal solution.
For linear programs, an optimum is normally a basic solution with no degrees of freedom. (The number of variables lying strictly between their bounds is no more than m, the number of general constraints.) The default value of i is therefore 1.
For quadratic problems, the number of degrees of freedom is often called the ‘number of independent variables’. Normally, i need not be greater than nH+1, where nH is the number of leading nonzero columns of H. For many problems, i may be considerably smaller than nH. This will save storage if nH is very large.
Suppress Parameters
Normally e04nq prints the options file as it is being read, and then prints a complete list of the available keywords and their final values. The optional parameter Suppress Parameters tells e04nq not to print the full list.
System Information No
System Information Yes
This option prints additional information on the progress of major and minor iterations, and Crash statistics. See [Description of Monitoring Information].
Timing Level
If i>0, some timing information will be output to the Print file, if Print File>0.
Unbounded Step Size
If r>0, r specifies the magnitude of the change in variables that will be considered a step to an unbounded solution. (Note that an unbounded solution can occur only when the Hessian is not positive definite.) If the change in x during an iteration would exceed the value of r, the objective function is considered to be unbounded below in the feasible region. If r≤0, the default value is used. See Infinite Bound Size for the definition of infbnd.

Inheritance Hierarchy

System..::..Object
NagLibrary..::..E04..::..e04nqOptions

See Also

E04..::..e04nqOptions Members
NagLibrary Namespace
NAG Library Overview
e04nq


E04.e04nqOptions Members

[image] [image]

NAG Library for .NET Release 2
E04..::..e04nqOptions Members
E04..::..e04nqOptions Class Constructors Methods Properties See Also Send Feedback

An optimization problem involves minimizing a function (called the objective function) of several variables, possibly subject to restrictions on the values of the variables defined by a set of constraint functions. Most methods in the Library are concerned with function minimization only, since the problem of maximizing a given objective function F(x) is equivalent to minimizing -F x. Some methods allow you to specify whether you are solving a minimization or maximization problem, carrying out the required transformation of the objective function in the latter case.
In general methods in this chapter find a local minimum of a function f, that is a point x* s.t. for all x near x* f x≥f x*.
The E05 class contains methods to find the global minimum of a function f. At a global minimum x* f x≥f x* for all x.
The (H not in this release) contains methods typically regarded as belonging to the field of operations research.
This introduction is only a brief guide to the subject of optimization designed for the casual user. Anyone with a difficult or protracted problem to solve will find it beneficial to consult a more detailed text, such as Gill et al. (1981) or Fletcher (1987).
If you are unfamiliar with the mathematics of the subject you may find some sections difficult at first reading; if so, you should concentrate on [Types of Optimization Problems], [Geometric Representation and Terminology], [Scaling], [Analysis of Computed Results] and [Recommendations on Choice and Use of Available Methods] .

The E04..::..e04nqOptions type exposes the following members.

Constructors

Name | Description
E04..::..e04nqOptions | Constructor

Methods

Name | Description
Set | Overloaded.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e04nq.
Warning | Set the method used for logging any warning or error messages from e04nq.

See Also

E04..::..e04nqOptions Class


E04.e04nqOptions Constructor

[image]

NAG Library for .NET Release 2
E04..::..e04nqOptions Constructor
E04..::..e04nqOptions Class See Also Send Feedback
Constructor

Syntax

C#
public e04nqOptions()
Visual Basic
Public Sub New
Visual C++
public:
e04nqOptions()
F#
new : unit -> e04nqOptions

See Also

E04..::..e04nqOptions Class
E04..::..e04nqOptions Members


E04.e04nqOptions Methods

[image] [image]

NAG Library for .NET Release 2
E04..::..e04nqOptions Methods
E04..::..e04nqOptions Class See Also Send Feedback

Methods

Name | Description
Set | Overloaded.

See Also

E04..::..e04nqOptions Class


Set Method

[image] [image]

NAG Library for .NET Release 2
E04..::..e04nqOptions..::Set Method
E04..::..e04nqOptions Class See Also Send Feedback

Overload List

Name | Description
Set(String) | Set an Option for e04nq
Set(DataReader) | Set Options for from a DataReader Stream.
Set(String, Double) | Set an Option for e04nq
Set(String, Int32) | Set an Option for e04nq

See Also

E04..::..e04nqOptions Class
E04..::..e04nqOptions Members


Set Method (String)

[image]

NAG Library for .NET Release 2
E04..::..e04nqOptions..::Set Method (String)
E04..::..e04nqOptions Class See Also Send Feedback
Set an Option for e04nq

Syntax

C#
public void Set(
    string dnstring
)
Visual Basic
Public Sub Set ( _
    dnstring As String _
)
Visual C++
public:
void Set(
    String^ dnstring
)
F#
member Set :
        dnstring : string -> unit

Parameters

dnstring
Type: System..::..String
A string of the form option = value, or for boolean options, simply option.

See Also

E04..::..e04nqOptions Class
E04..::..e04nqOptions Members
Set Overload


Set Method (DataReader)

[image]

NAG Library for .NET Release 2
E04..::..e04nqOptions..::Set Method (DataReader)
E04..::..e04nqOptions Class See Also Send Feedback
Set Options for from a DataReader Stream.

Syntax

C#
public void Set(
    DataReader sr
)
Visual Basic
Public Sub Set ( _
    sr As DataReader _
)
Visual C++
public:
void Set(
    DataReader^ sr
)
F#
member Set :
        sr : DataReader -> unit

Parameters

sr
Type: NagLibrary..::..DataReader
A DataReader Stream, containing an option setting on each line.

See Also

E04..::..e04nqOptions Class
E04..::..e04nqOptions Members
Set Overload


Set Method (String, Double)

[image]

NAG Library for .NET Release 2
E04..::..e04nqOptions..::Set Method (String, Double)
E04..::..e04nqOptions Class See Also Send Feedback
Set an Option for e04nq

Syntax

C#
public void Set(
    string dnstring,
    double rvalue
)
Visual Basic
Public Sub Set ( _
    dnstring As String, _
    rvalue As Double _
)
Visual C++
public:
void Set(
    String^ dnstring,
    double rvalue
)
F#
member Set :
        dnstring : string *
        rvalue : float -> unit

Parameters

dnstring
Type: System..::..String
The name of an option.
rvalue
Type: System..::..Double
The option value.

See Also

E04..::..e04nqOptions Class
E04..::..e04nqOptions Members
Set Overload


Set Method (String, Int32)

[image]

NAG Library for .NET Release 2
E04..::..e04nqOptions..::Set Method (String, Int32)
E04..::..e04nqOptions Class See Also Send Feedback
Set an Option for e04nq

Syntax

C#
public void Set(
    string dnstring,
    int ivalue
)
Visual Basic
Public Sub Set ( _
    dnstring As String, _
    ivalue As Integer _
)
Visual C++
public:
void Set(
    String^ dnstring,
    int ivalue
)
F#
member Set :
        dnstring : string *
        ivalue : int -> unit

Parameters

dnstring
Type: System..::..String
The name of an option.
ivalue
Type: System..::..Int32
The option value.

See Also

E04..::..e04nqOptions Class
E04..::..e04nqOptions Members
Set Overload


E04.e04nqOptions Properties

[image] [image]

NAG Library for .NET Release 2
E04..::..e04nqOptions Properties
E04..::..e04nqOptions Class See Also Send Feedback

The E04..::..e04nqOptions type exposes the following members.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e04nq.
Warning | Set the method used for logging any warning or error messages from e04nq.

See Also

E04..::..e04nqOptions Class


Message Property

[image]

NAG Library for .NET Release 2
E04..::..e04nqOptions..::Message Property
E04..::..e04nqOptions Class See Also Send Feedback
Set the method used for logging any monitoring messages from e04nq.

Syntax

C#
public PrintManager..::..MessageLogger Message { get; set; }
Visual Basic
Public Property Message As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Message {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Message : PrintManager..::..MessageLogger with get, set

See Also

E04..::..e04nqOptions Class
E04..::..e04nqOptions Members


Warning Property

[image]

NAG Library for .NET Release 2
E04..::..e04nqOptions..::Warning Property
E04..::..e04nqOptions Class See Also Send Feedback
Set the method used for logging any warning or error messages from e04nq.

Syntax

C#
public PrintManager..::..MessageLogger Warning { get; set; }
Visual Basic
Public Property Warning As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Warning {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Warning : PrintManager..::..MessageLogger with get, set

See Also

E04..::..e04nqOptions Class
E04..::..e04nqOptions Members


E04.e04ucOptions Class

[image]

NAG Library for .NET Release 2
E04..::..e04ucOptions Class
E04 Class Members See Also Send Feedback
Options Class for e04uc

Syntax

C#
public class e04ucOptions
Visual Basic
Public Class e04ucOptions
Visual C++
public ref class e04ucOptions
F#
type e04ucOptions =  class end

Description of the Optional Parameters

For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
  • the keywords, where the minimum abbreviation of each keyword is underlined (if no characters of an optional qualifier are underlined, the qualifier may be omitted);
  • a parameter value, where the letters a, i​ and ​r denote options that take character, integer and real values respectively;
  • the default value, where the symbol ε is a generic notation for machine precision (see x02aj), and εr denotes the relative precision of the objective function Function Precision, and bigbnd signifies the value of Infinite Bound Size.
Keywords and character values are case and white space insensitive.
Central Difference Interval
If the algorithm switches to central differences because the forward-difference approximation is not sufficiently accurate, the value of r is used as the difference interval for every element of x. The switch to central differences is indicated by C at the end of each line of intermediate printout produced by the major iterations (see [Description of the Printed Output]). The use of finite differences is discussed further under the optional parameter Difference Interval.
If you supply a value for this optional parameter, a small value between 0.0 and 1.0 is appropriate.
Cold Start
Warm Start
This option controls the specification of the initial working set in both the procedure for finding a feasible point for the linear constraints and bounds and in the first QP subproblem thereafter. With a Cold Start, the first working set is chosen by e04uc based on the values of the variables and constraints at the initial point. Broadly speaking, the initial working set will include equality constraints and bounds or inequality constraints that violate or ‘nearly’ satisfy their bounds (to within Crash Tolerance).
With a Warm Start, you must set the istate array and define clamda and r as discussed in [Parameters]. istate values associated with bounds and linear constraints determine the initial working set of the procedure to find a feasible point with respect to the bounds and linear constraints. istate values associated with nonlinear constraints determine the initial working set of the first QP subproblem after such a feasible point has been found. e04uc will override your specification of istate if necessary, so that a poor choice of the working set will not cause a fatal error. For instance, any elements of istate which are set to -2, -1​ or ​4 will be reset to zero, as will any elements which are set to 3 when the corresponding elements of bl and bu are not equal. A warm start will be advantageous if a good estimate of the initial working set is available – for example, when e04uc is called repeatedly to solve related problems.
Crash Tolerance
This value is used in conjunction with the optional parameter Cold Start (the default value) when e04uc selects an initial working set. If 0≤r≤1, the initial working set will include (if possible) bounds or general inequality constraints that lie within r of their bounds. In particular, a constraint of the form ajT x≥l will be included in the initial working set if ajT x-l≤r 1+l. If r<0 or r>1, the default value is used.
Defaults
This special keyword may be used to reset all optional parameters to their default values.
Derivative Level
This parameter indicates which derivatives are provided in user-supplied delegates objfun and confun. The possible choices for i are the following.
i | Meaning
3 | All elements of the objective gradient and the constraint Jacobian are provided.
2 | All elements of the constraint Jacobian are provided, but some elements of the objective gradient are not specified.
1 | All elements of the objective gradient are provided, but some elements of the constraint Jacobian are not specified.
0 | Some elements of both the objective gradient and the constraint Jacobian are not specified.
The value i=3 should be used whenever possible, since e04uc is more reliable (and will usually be more efficient) when all derivatives are exact.
If i=0​ or ​2, e04uc will estimate the unspecified elements of the objective gradient, using finite differences. The computation of finite difference approximations usually increases the total run-time, since a call to objfun is required for each unspecified element. Furthermore, less accuracy can be attained in the solution (see Chapter 8 of Gill et al. (1981), for a discussion of limiting accuracy).
If i=0​ or ​1, e04uc will approximate unspecified elements of the constraint Jacobian. One call to confun is needed for each variable for which partial derivatives are not available. For example, if the Jacobian has the form
*****??***?*****
where ‘*’ indicates an element provided by you and ‘?’ indicates an unspecified element, e04uc will call confun twice: once to estimate the missing element in column 2, and again to estimate the two missing elements in column 3. (Since columns 1 and 4 are known, they require no calls to confun.)
At times, central differences are used rather than forward differences, in which case twice as many calls to objfun and confun are needed. (The switch to central differences is not under your control.)
If i<0 or i>3, the default value is used.
Difference Interval
This option defines an interval used to estimate derivatives by finite differences in the following circumstances:
(a) | For verifying the objective and/or constraint gradients (see the description of the optional parameter Verify).
(b) | For estimating unspecified elements of the objective gradient or the constraint Jacobian.
In general, a derivative with respect to the jth variable is approximated using the interval δj, where δj=r 1+x^j, with x^ the first point feasible with respect to the bounds and linear constraints. If the functions are well scaled, the resulting derivative approximation should be accurate to O r. See Gill et al. (1981) for a discussion of the accuracy in finite difference approximations.
If a difference interval is not specified by you, a finite difference interval will be computed automatically for each variable by a procedure that requires up to six calls of confun and objfun for each element. This option is recommended if the function is badly scaled or you wish to have e04uc determine constant elements in the objective and constraint gradients (see the descriptions of confun and objfun in [Parameters]).
If you supply a value for this optional parameter, a small value between 0.0 and 1.0 is appropriate.
Feasibility Tolerance
The scalar r defines the maximum acceptable absolute violations in linear and nonlinear constraints at a ‘feasible’ point; i.e., a constraint is considered satisfied if its violation does not exceed r. If r<ε or r≥1, the default value is used. Using this keyword sets both optional parameters Linear Feasibility Tolerance and Nonlinear Feasibility Tolerance to r, if ε≤r<1. (Additional details are given under the descriptions of these optional parameters.)
Function Precision
This parameter defines εr, which is intended to be a measure of the accuracy with which the problem functions F x and c x can be computed. If r<ε or r≥1, the default value is used.
The value of εr should reflect the relative precision of 1+F x; i.e., εr acts as a relative precision when F is large and as an absolute precision when F is small. For example, if F x is typically of order 1000 and the first six significant digits are known to be correct, an appropriate value for εr would be 10-6. In contrast, if F x is typically of order 10-4 and the first six significant digits are known to be correct, an appropriate value for εr would be 10-10. The choice of εr can be quite complicated for badly scaled problems; see Chapter 8 of Gill et al. (1981) for a discussion of scaling techniques. The default value is appropriate for most simple functions that are computed with full accuracy. However, when the accuracy of the computed function values is known to be significantly worse than full precision, the value of εr should be large enough so that e04uc will not attempt to distinguish between function values that differ by less than the error inherent in the calculation.
Hessian
This option controls the contents of the upper triangular matrix R (see [Parameters]). e04uc works exclusively with the transformed and reordered Hessian HQ (6), and hence extra computation is required to form the Hessian itself. If Hessian=NO, r contains the Cholesky factor of the transformed and reordered Hessian. If Hessian=YES, the Cholesky factor of the approximate Hessian itself is formed and stored in r. You should select Hessian=YES if a Warm Start will be used for the next call to e04uc.
Infinite Bound Size
If r>0, r defines the ‘infinite’ bound bigbnd in the definition of the problem constraints. Any upper bound greater than or equal to bigbnd will be regarded as +∞ (and similarly any lower bound less than or equal to -bigbnd will be regarded as -∞). If r<0, the default value is used.
Infinite Step Size
If r>0, r specifies the magnitude of the change in variables that is treated as a step to an unbounded solution. If the change in x during an iteration would exceed the value of r, the objective function is considered to be unbounded below in the feasible region. If r≤0, the default value is used.
Line Search Tolerance
The value r (0≤r<1) controls the accuracy with which the step α taken during each iteration approximates a minimum of the merit function along the search direction (the smaller the value of r, the more accurate the linesearch). The default value r=0.9 requests an inaccurate search and is appropriate for most problems, particularly those with any nonlinear constraints.
If there are no nonlinear constraints, a more accurate search may be appropriate when it is desirable to reduce the number of major iterations – for example, if the objective function is cheap to evaluate, or if a substantial number of derivatives are unspecified. If r<0 or r≥1, the default value is used.
Linear Feasibility Tolerance
Nonlinear Feasibility Tolerance
The default value of r 2 is ε 0.33 if Derivative Level=0 or 1, and ε otherwise.
The scalars r 1 and r 2 define the maximum acceptable absolute violations in linear and nonlinear constraints at a ‘feasible’ point; i.e., a linear constraint is considered satisfied if its violation does not exceed r 1, and similarly for a nonlinear constraint and r 2. If rm<ε or rm≥1, the default value is used, for m=1,2.
On entry to e04uc, an iterative procedure is executed in order to find a point that satisfies the linear constraints and bounds on the variables to within the tolerance r 1. All subsequent iterates will satisfy the linear constraints to within the same tolerance (unless r 1 is comparable to the finite difference interval).
For nonlinear constraints, the feasibility tolerance r 2 defines the largest constraint violation that is acceptable at an optimal point. Since nonlinear constraints are generally not satisfied until the final iterate, the value of optional parameter Nonlinear Feasibility Tolerance acts as a partial termination criterion for the iterative sequence generated by e04uc (see the discussion of optional parameter Optimality Tolerance).
These tolerances should reflect the precision of the corresponding constraints. For example, if the variables and the coefficients in the linear constraints are of order unity, and the latter are correct to about 6 decimal digits, it would be appropriate to specify r 1 as 10-6.
List
Nolist
For e04uc, normally each optional parameter specification is printed as it is supplied. Optional parameter Nolist may be used to suppress the printing and optional parameter List may be used to turn on printing.
Major Iteration Limit
Iteration Limit
Iters
Itns
The value of i specifies the maximum number of major iterations allowed before termination. Setting i=0 and Major Print Level>0 means that the workspace needed will be computed and printed, but no iterations will be performed. If i<0, the default value is used.
Major Print Level
Print Level
The value of i controls the amount of printout produced by the major iterations of e04uc, as indicated below. A detailed description of the printed output is given in [Description of the Printed Output] (summary output at each major iteration and the final solution) and [Description of Monitoring Information] (monitoring information at each major iteration). (See also the description of the optional parameter Minor Print Level.)
The following printout is sent to the current advisory message unit (as defined by (X04ABF not in this release)):
i | Output
≥0 0 | No output.
For the other values described below, the parameters used by E04UCF/ E04UCA are displayed in addition to intermediate and final output.
i | Output
≥0 1 | The final solution only.
≥0 5 | One line of summary output (<80 characters; see [Description of the Printed Output]) for each major iteration (no printout of the final solution).
≥10 | The final solution and one line of summary output for each major iteration.
The following printout is sent to the logical unit number defined by the optional parameter Monitoring File:
i | Output
<5 | No output.
≥5 | One long line of output (>80 characters; see [Description of Monitoring Information]) for each major iteration (no printout of the final solution).
≥20 | At each major iteration, the objective function, the Euclidean norm of the nonlinear constraint violations, the values of the nonlinear constraints (the vector c), the values of the linear constraints (the vector AL x), and the current values of the variables (the vector x).
≥30 | At each major iteration, the diagonal elements of the matrix T associated with the TQ factorization (5) (see [Overview]) of the QP working set, and the diagonal elements of R, the triangular factor of the transformed and reordered Hessian (6) (see [Overview]).
If Major Print Level≥5 and the unit number defined by the optional parameter Monitoring File is the same as that defined by (X04ABF not in this release), then the summary output for each major iteration is suppressed.
Minor Iteration Limit
The value of i specifies the maximum number of iterations for finding a feasible point with respect to the bounds and linear constraints (if any). The value of i also specifies the maximum number of minor iterations for the optimality phase of each QP subproblem. If i≤0, the default value is used.
Minor Print Level
The value of i controls the amount of printout produced by the minor iterations of e04uc (i.e., the iterations of the quadratic programming algorithm), as indicated below. A detailed description of the printed output is given in [Description of the Printed Output] (summary output at each minor iteration and the final QP solution) and [Description of Monitoring Information] in e04nc (monitoring information at each minor iteration). (See also the description of the optional parameter Major Print Level.) The following printout is sent to the current advisory message unit (as defined by (X04ABF not in this release)):
i | Output
≥0 0 | No output.
≥0 1 | The final QP solution only.
≥0 5 | One line of summary output (<80 characters; see [Description of the Printed Output] in e04nc) for each minor iteration (no printout of the final QP solution).
≥10 | The final QP solution and one line of summary output for each minor iteration.
The following printout is sent to the logical unit number defined by the optional parameter Monitoring File:
i | Output
<5 | No output.
≥5 | One long line of output (>80 characters; see [Description of the Printed Output] in e04nc) for each minor iteration (no printout of the final QP solution).
≥20 | At each minor iteration, the current estimates of the QP multipliers, the current estimate of the QP search direction, the QP constraint values, and the status of each QP constraint.
≥30 | At each minor iteration, the diagonal elements of the matrix T associated with the TQ factorization (5) (see [Overview]) of the QP working set, and the diagonal elements of the Cholesky factor R of the transformed Hessian (6) (see [Overview]).
If Minor Print Level≥5 and the unit number defined by the optional parameter Monitoring File is the same as that defined by (X04ABF not in this release), then the summary output for each minor iteration is suppressed.
Monitoring File
If i≥0 and Major Print Level≥5 or i≥0 and Minor Print Level≥5, monitoring information produced by e04uc at every iteration is sent to a file with logical unit number i. If i<0 and/or Major Print Level<5 and Minor Print Level<5, no monitoring information is produced.
Optimality Tolerance
The parameter r (εr≤r<1) specifies the accuracy to which you wish the final iterate to approximate a solution of the problem. Broadly speaking, r indicates the number of correct figures desired in the objective function at the solution. For example, if r is 10-6 and e04uc terminates successfully, the final value of F should have approximately six correct figures. If r<εr or r≥1, the default value is used.
e04uc will terminate successfully if the iterative sequence of x values is judged to have converged and the final point satisfies the first-order Kuhn–Tucker conditions (see [Overview]). The sequence of iterates is considered to have converged at x if
α p≤r 1+x, (16)
where p is the search direction and α the step length from (3). An iterate is considered to satisfy the first-order conditions for a minimum if
ZT gFR≤r 1+max 1+F x,gFR (17)
and
resj≤ftol  for all  j, (18)
where ZT gFR is the projected gradient (see [Overview]), gFR is the gradient of F x with respect to the free variables, resj is the violation of the jth active nonlinear constraint, and ftol is the Nonlinear Feasibility Tolerance.
Start Objective Check At Variable
Stop Objective Check At Variable
Start Constraint Check At Variable
Stop Constraint Check At Variable
These keywords take effect only if Verify Level>0. They may be used to control the verification of gradient elements computed by objfun and/or Jacobian elements computed by confun. For example, if the first 30 elements of the objective gradient appeared to be correct in an earlier run, so that only element 31 remains questionable, it is reasonable to specify Start Objective Check At Variable=31. If the first 30 variables appear linearly in the objective, so that the corresponding gradient elements are constant, the above choice would also be appropriate.
If i 2 m-1≤0 or i 2 m-1>min n,i 2 m, the default value is used, for m=1,2. If i 2 m≤0 or i 2 m>n, the default value is used, for m=1,2.
Step Limit
If r>0,r specifies the maximum change in variables at the first step of the linesearch. In some cases, such as F x=a e bx or F x=a xb, even a moderate change in the elements of x can lead to floating-point overflow. The parameter r is therefore used to encourage evaluation of the problem functions at meaningful points. Given any major iterate x, the first point x~ at which F and c are evaluated during the linesearch is restricted so that
x~-x 2≤r 1+x 2.
The linesearch may go on and evaluate F and c at points further from x if this will result in a lower value of the merit function (indicated by L at the end of each line of output produced by the major iterations; see [Description of the Printed Output]). If L is printed for most of the iterations, r should be set to a larger value.
Wherever possible, upper and lower bounds on x should be used to prevent evaluation of nonlinear functions at wild values. The default value Step Limit=2.0 should not affect progress on well-behaved functions, but values such as 0.1​ or ​0.01 may be helpful when rapidly varying functions are present. If a small value of Step Limit is selected, a good starting point may be required. An important application is to the class of nonlinear least squares problems. If r≤0, the default value is used.
Verify Level
Verify
Verify Constraint Gradients
Verify Gradients
Verify Objective Gradients
These keywords refer to finite difference checks on the gradient elements computed by objfun and confun. The possible choices for i are as follows:
i | Meaning
-1 | No checks are performed.
-0 | Only a ‘cheap’ test will be performed.
≥1 | Individual gradient elements will also be checked using a reliable (but more expensive) test.
It is possible to specify Verify Level=0 to 3 in several ways. For example, the nonlinear objective gradient (if any) will be verified if either Verify Objective Gradients or Verify Level=1 is specified. The constraint gradients will be verified if Verify=YES or Verify Level=2 or Verify is specified. Similarly, the objective and the constraint gradients will be verified if Verify=YES or Verify Level=3 or Verify is specified.
If 0≤i≤3, gradients will be verified at the first point that satisfies the linear constraints and bounds.
If i=0, only a ‘cheap’ test will be performed, requiring one call to objfun and (if appropriate) one call to confun.
If 1≤i≤3, a more reliable (but more expensive) check will be made on individual gradient elements, within the ranges specified by the Start Constraint Check At Variable and Stop Constraint Check At Variable keywords. A result of the form OK or BAD? is printed by e04uc to indicate whether or not each element appears to be correct.
If 10≤i≤13, the action is the same as for i-10, except that it will take place at the user-specified initial value of x.
If i<-1 or 4≤i≤9 or i>13, the default value is used.
We suggest that Verify Level=3 be used whenever a new function method is being developed.

Inheritance Hierarchy

System..::..Object
NagLibrary..::..E04..::..e04ucOptions

See Also

E04..::..e04ucOptions Members
NagLibrary Namespace
NAG Library Overview
e04uc


E04.e04ucOptions Members

[image] [image]

NAG Library for .NET Release 2
E04..::..e04ucOptions Members
E04..::..e04ucOptions Class Constructors Methods Properties See Also Send Feedback

An optimization problem involves minimizing a function (called the objective function) of several variables, possibly subject to restrictions on the values of the variables defined by a set of constraint functions. Most methods in the Library are concerned with function minimization only, since the problem of maximizing a given objective function F(x) is equivalent to minimizing -F x. Some methods allow you to specify whether you are solving a minimization or maximization problem, carrying out the required transformation of the objective function in the latter case.
In general methods in this chapter find a local minimum of a function f, that is a point x* s.t. for all x near x* f x≥f x*.
The E05 class contains methods to find the global minimum of a function f. At a global minimum x* f x≥f x* for all x.
The (H not in this release) contains methods typically regarded as belonging to the field of operations research.
This introduction is only a brief guide to the subject of optimization designed for the casual user. Anyone with a difficult or protracted problem to solve will find it beneficial to consult a more detailed text, such as Gill et al. (1981) or Fletcher (1987).
If you are unfamiliar with the mathematics of the subject you may find some sections difficult at first reading; if so, you should concentrate on [Types of Optimization Problems], [Geometric Representation and Terminology], [Scaling], [Analysis of Computed Results] and [Recommendations on Choice and Use of Available Methods] .

The E04..::..e04ucOptions type exposes the following members.

Constructors

Name | Description
E04..::..e04ucOptions | Constructor

Methods

Name | Description
Set | Overloaded.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e04uc.
Warning | Set the method used for logging any warning or error messages from e04uc.

See Also

E04..::..e04ucOptions Class


E04.e04ucOptions Constructor

[image]

NAG Library for .NET Release 2
E04..::..e04ucOptions Constructor
E04..::..e04ucOptions Class See Also Send Feedback
Constructor

Syntax

C#
public e04ucOptions()
Visual Basic
Public Sub New
Visual C++
public:
e04ucOptions()
F#
new : unit -> e04ucOptions

See Also

E04..::..e04ucOptions Class
E04..::..e04ucOptions Members


E04.e04ucOptions Methods

[image] [image]

NAG Library for .NET Release 2
E04..::..e04ucOptions Methods
E04..::..e04ucOptions Class See Also Send Feedback

Methods

Name | Description
Set | Overloaded.

See Also

E04..::..e04ucOptions Class


Set Method

[image] [image]

NAG Library for .NET Release 2
E04..::..e04ucOptions..::Set Method
E04..::..e04ucOptions Class See Also Send Feedback

Overload List

Name | Description
Set(String) | Set an Option for e04uc
Set(DataReader) | Set Options for from a DataReader Stream.

See Also

E04..::..e04ucOptions Class
E04..::..e04ucOptions Members


Set Method (String)

[image]

NAG Library for .NET Release 2
E04..::..e04ucOptions..::Set Method (String)
E04..::..e04ucOptions Class See Also Send Feedback
Set an Option for e04uc

Syntax

C#
public void Set(
    string str
)
Visual Basic
Public Sub Set ( _
    str As String _
)
Visual C++
public:
void Set(
    String^ str
)
F#
member Set :
        str : string -> unit

Parameters

str
Type: System..::..String
A string of the form option = value, or for boolean options, simply option.

See Also

E04..::..e04ucOptions Class
E04..::..e04ucOptions Members
Set Overload


Set Method (DataReader)

[image]

NAG Library for .NET Release 2
E04..::..e04ucOptions..::Set Method (DataReader)
E04..::..e04ucOptions Class See Also Send Feedback
Set Options for from a DataReader Stream.

Syntax

C#
public void Set(
    DataReader sr
)
Visual Basic
Public Sub Set ( _
    sr As DataReader _
)
Visual C++
public:
void Set(
    DataReader^ sr
)
F#
member Set :
        sr : DataReader -> unit

Parameters

sr
Type: NagLibrary..::..DataReader
A DataReader Stream, containing an option setting on each line.

See Also

E04..::..e04ucOptions Class
E04..::..e04ucOptions Members
Set Overload


E04.e04ucOptions Properties

[image] [image]

NAG Library for .NET Release 2
E04..::..e04ucOptions Properties
E04..::..e04ucOptions Class See Also Send Feedback

The E04..::..e04ucOptions type exposes the following members.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e04uc.
Warning | Set the method used for logging any warning or error messages from e04uc.

See Also

E04..::..e04ucOptions Class


Message Property

[image]

NAG Library for .NET Release 2
E04..::..e04ucOptions..::Message Property
E04..::..e04ucOptions Class See Also Send Feedback
Set the method used for logging any monitoring messages from e04uc.

Syntax

C#
public PrintManager..::..MessageLogger Message { get; set; }
Visual Basic
Public Property Message As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Message {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Message : PrintManager..::..MessageLogger with get, set

See Also

E04..::..e04ucOptions Class
E04..::..e04ucOptions Members


Warning Property

[image]

NAG Library for .NET Release 2
E04..::..e04ucOptions..::Warning Property
E04..::..e04ucOptions Class See Also Send Feedback
Set the method used for logging any warning or error messages from e04uc.

Syntax

C#
public PrintManager..::..MessageLogger Warning { get; set; }
Visual Basic
Public Property Warning As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Warning {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Warning : PrintManager..::..MessageLogger with get, set

See Also

E04..::..e04ucOptions Class
E04..::..e04ucOptions Members


E04.e04ufOptions Class

[image]

NAG Library for .NET Release 2
E04..::..e04ufOptions Class
E04 Class Members See Also Send Feedback
Options Class for e04uf

Syntax

C#
public class e04ufOptions
Visual Basic
Public Class e04ufOptions
Visual C++
public ref class e04ufOptions
F#
type e04ufOptions =  class end

Description of the Optional Parameters

For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
  • the keywords, where the minimum abbreviation of each keyword is underlined (if no characters of an optional qualifier are underlined, the qualifier may be omitted);
  • a parameter value, where the letters a, i​ and ​r denote options that take character, integer and real values respectively;
  • the default value, where the symbol ε is a generic notation for machine precision (see x02aj), and εr denotes the relative precision of the objective function Function Precision.
Keywords and character values are case and white space insensitive.
Central Difference Interval
If the algorithm switches to central differences because the forward-difference approximation is not sufficiently accurate, the value of r is used as the difference interval for every element of x. The switch to central differences is indicated by C at the end of each line of intermediate printout produced by the major iterations (see [Description of the Printed Output]). The use of finite differences is discussed further under the optional parameter Difference Interval.
If you supply a value for this optional parameter, a small value between 0.0 and 1.0 is appropriate.
Cold Start
Warm Start
This option controls the specification of the initial working set in both the procedure for finding a feasible point for the linear constraints and bounds and in the first QP subproblem thereafter. With a Cold Start, the first working set is chosen by e04uf based on the values of the variables and constraints at the initial point. Broadly speaking, the initial working set will include equality constraints and bounds or inequality constraints that violate or ‘nearly’ satisfy their bounds (to within Crash Tolerance).
With a Warm Start, you must set the istate array and define clamda and r as discussed in [Parameters]. istate values associated with bounds and linear constraints determine the initial working set of the procedure to find a feasible point with respect to the bounds and linear constraints. istate values associated with nonlinear constraints determine the initial working set of the first QP subproblem after such a feasible point has been found. e04uf will override your specification of istate if necessary, so that a poor choice of the working set will not cause a fatal error. For instance, any elements of istate which are set to -2, -1​ or ​4 will be reset to zero, as will any elements which are set to 3 when the corresponding elements of bl and bu are not equal. A warm start will be advantageous if a good estimate of the initial working set is available – for example, when e04uf is called repeatedly to solve related problems.
Crash Tolerance
This value is used in conjunction with the optional parameter Cold Start (the default value) when e04uf selects an initial working set. If 0≤r≤1, the initial working set will include (if possible) bounds or general inequality constraints that lie within r of their bounds. In particular, a constraint of the form ajT x≥l will be included in the initial working set if ajT x-l≤r 1+l. If r<0 or r>1, the default value is used.
Defaults
This special keyword may be used to reset all optional parameters to their default values.
Derivative Level
This parameter indicates which derivatives are provided during intermediate exits. The possible choices for i are the following.
i | Meaning
3 | All elements of the objective gradient and the constraint Jacobian are provided.
2 | All elements of the constraint Jacobian are provided, but some elements of the objective gradient are not specified.
1 | All elements of the objective gradient are provided, but some elements of the constraint Jacobian are not specified.
0 | Some elements of both the objective gradient and the constraint Jacobian are not specified.
The value i=3 should be used whenever possible, since e04uf is more reliable (and will usually be more efficient) when all derivatives are exact.
If i=0​ or ​2, e04uf will estimate the unspecified elements of the objective gradient, using finite differences. The computation of finite difference approximations usually increases the total run-time, since an intermediate exit to the calling program is required for each unspecified element. Furthermore, less accuracy can be attained in the solution (see Chapter 8 of Gill et al. (1981), for a discussion of limiting accuracy).
If i=0​ or ​1, e04uf will approximate unspecified elements of the constraint Jacobian. One intermediate exit is needed for each variable for which partial derivatives are not available. For example, if the Jacobian has the form
*****??***?*****
where ‘*’ indicates an element provided and ‘?’ indicates an unspecified element, e04uf will make an intermediate exit to the calling program twice: once to estimate the missing element in column 2, and again to estimate the two missing elements in column 3. (Since columns 1 and 4 are known, they require no intermediate exits for information.)
At times, central differences are used rather than forward differences, in which case twice as many intermediate exits are needed. (The switch to central differences is not under your control.)
If i<0 or i>3, the default value is used.
Difference Interval
This option defines an interval used to estimate derivatives by finite differences in the following circumstances:
(a) | For verifying the objective and/or constraint gradients (see the description of the optional parameter Verify).
(b) | For estimating unspecified elements of the objective gradient or the constraint Jacobian.
In general, a derivative with respect to the jth variable is approximated using the interval δj, where δj=r 1+x^j, with x^ the first point feasible with respect to the bounds and linear constraints. If the functions are well scaled then the resulting derivative approximation should be accurate to O r. See Gill et al. (1981) for a discussion of the accuracy in finite difference approximations.
If a difference interval is not specified then a finite difference interval will be computed automatically for each variable by a procedure that requires up to six intermediate exits for each element. This option is recommended if the function is badly scaled or you wish to have e04uf determine constant elements in the objective and constraint gradients.
If you supply a value for this optional parameter, a small value between 0.0 and 1.0 is appropriate.
Feasibility Tolerance
The scalar r defines the maximum acceptable absolute violations in linear and nonlinear constraints at a ‘feasible’ point; i.e., a constraint is considered satisfied if its violation does not exceed r. If r<ε or r≥1, the default value is used. Using this keyword sets both optional parameters Linear Feasibility Tolerance and Nonlinear Feasibility Tolerance to r, if ε≤r<1. (Additional details are given under the descriptions of these optional parameters.)
Function Precision
This parameter defines εr, which is intended to be a measure of the accuracy with which the problem functions F x and c x can be computed. If r<ε or r≥1, the default value is used.
The value of εr should reflect the relative precision of 1+F x; i.e., εr acts as a relative precision when F is large and as an absolute precision when F is small. For example, if F x is typically of order 1000 and the first six significant digits are known to be correct, an appropriate value for εr would be 10-6. In contrast, if F x is typically of order 10-4 and the first six significant digits are known to be correct, an appropriate value for εr would be 10-10. The choice of εr can be quite complicated for badly scaled problems; see Chapter 8 of Gill et al. (1981) for a discussion of scaling techniques. The default value is appropriate for most simple functions that are computed with full accuracy. However, when the accuracy of the computed function values is known to be significantly worse than full precision, the value of εr should be large enough so that e04uf will not attempt to distinguish between function values that differ by less than the error inherent in the calculation.
Hessian
This option controls the contents of the upper triangular matrix R (see [Parameters]). e04uf works exclusively with the transformed and reordered Hessian HQ (6), and hence extra computation is required to form the Hessian itself. If Hessian=NO, r contains the Cholesky factor of the transformed and reordered Hessian. If Hessian=YES, the Cholesky factor of the approximate Hessian itself is formed and stored in r. You should select Hessian=YES if a Warm Start will be used for the next call to e04uf.
Infinite Bound Size
If r>0, r defines the ‘infinite’ bound bigbnd in the definition of the problem constraints. Any upper bound greater than or equal to bigbnd will be regarded as +∞ (and similarly any lower bound less than or equal to -bigbnd will be regarded as -∞). If r<0, the default value is used.
Infinite Step Size
If r>0, r specifies the magnitude of the change in variables that is treated as a step to an unbounded solution. If the change in x during an iteration would exceed the value of r, the objective function is considered to be unbounded below in the feasible region. If r≤0, the default value is used.
Line Search Tolerance
The value r (0≤r<1) controls the accuracy with which the step α taken during each iteration approximates a minimum of the merit function along the search direction (the smaller the value of r, the more accurate the linesearch). The default value r=0.9 requests an inaccurate search and is appropriate for most problems, particularly those with any nonlinear constraints.
If there are no nonlinear constraints, a more accurate search may be appropriate when it is desirable to reduce the number of major iterations – for example, if the objective function is cheap to evaluate, or if a substantial number of derivatives are unspecified. If r<0 or r≥1, the default value is used.
Linear Feasibility Tolerance
Nonlinear Feasibility Tolerance
The default value of r 2 is ε 0.33 if Derivative Level=0 or 1, and ε otherwise.
The scalars r 1 and r 2 define the maximum acceptable absolute violations in linear and nonlinear constraints at a ‘feasible’ point; i.e., a linear constraint is considered satisfied if its violation does not exceed r 1. Similarly a nonlinear constraint is considered satisfied if its violation does not exceed r 2. If rm<ε or rm≥1, the default value is used, for m=1,2.
On entry to e04uf, an iterative procedure is executed in order to find a point that satisfies the linear constraints and bounds on the variables to within the tolerance r 1. All subsequent iterates will satisfy the linear constraints to within the same tolerance (unless r 1 is comparable to the finite difference interval).
For nonlinear constraints, the feasibility tolerance r 2 defines the largest constraint violation that is acceptable at an optimal point. Since nonlinear constraints are generally not satisfied until the final iterate, the value of optional parameter Nonlinear Feasibility Tolerance acts as a partial termination criterion for the iterative sequence generated by e04uf (see the discussion of optional parameter Optimality Tolerance).
These tolerances should reflect the precision of the corresponding constraints. For example, if the variables and the coefficients in the linear constraints are of order unity, and the latter are correct to about 6 decimal digits, it would be appropriate to specify r 1 as 10-6.
List
Nolist
Optional parameter List may be used to turn on printing of each optional parameter specification as it is supplied. Nolist may then be used to suppress this printing again.
Major Iteration Limit
Iteration Limit
Iters
Itns
The value of i specifies the maximum number of major iterations allowed before termination. Setting i=0 and Major Print Level>0 means that the workspace needed will be computed and printed, but no iterations will be performed. If i<0, the default value is used.
Major Print Level
Print Level
The value of i controls the amount of printout produced by the major iterations of e04uf, as indicated below. A detailed description of the printed output is given in [Description of the Printed Output] (summary output at each major iteration and the final solution) and [Description of Monitoring Information] (monitoring information at each major iteration). (See also the description of the optional parameter Minor Print Level.)
The following printout is sent to the current advisory message unit (as defined by (X04ABF not in this release)):
i | Output
≥0 0 | No output.
≥0 1 | The final solution only.
≥0 5 | One line of summary output (<80 characters; see [Description of the Printed Output]) for each major iteration (no printout of the final solution).
≥10 | The final solution and one line of summary output for each major iteration.
The following printout is sent to the logical unit number by the optional parameter Monitoring File:
i | Output
<5 | No output.
≥5 | One long line of output (>80 characters; see [Description of Monitoring Information]) for each major iteration (no printout of the final solution).
≥20 | At each major iteration, the objective function, the Euclidean norm of the nonlinear constraint violations, the values of the nonlinear constraints (the vector c), the values of the linear constraints (the vector AL x) and the current values of the variables (the vector x).
≥30 | At each major iteration, the diagonal elements of the matrix T associated with the TQ factorization (5) (see [Overview]) of the QP working set and the diagonal elements of R, the triangular factor of the transformed and reordered Hessian (6) (see [Overview]).
If Major Print Level≥5 and the unit number defined by the optional parameter Monitoring File is the same as that defined by (X04ABF not in this release), then the summary output for each major iteration is suppressed.
Minor Iteration Limit
The value of i specifies the maximum number of iterations for finding a feasible point with respect to the bounds and linear constraints (if any). The value of i also specifies the maximum number of minor iterations for the optimality phase of each QP subproblem. If i≤0, the default value is used.
Minor Print Level
The value of i controls the amount of printout produced by the minor iterations of e04uf (i.e., the iterations of the quadratic programming algorithm), as indicated below. A detailed description of the printed output is given in [Description of the Printed Output] in e04nc (summary output at each minor iteration and the final QP solution) and [Description of Monitoring Information] in e04nc) (monitoring information at each minor iteration). (See also the description of the optional parameter Major Print Level.)
The following printout is sent to the current advisory message unit (as defined by (X04ABF not in this release)):
i | Output
≥0 0 | No output.
≥0 1 | The final QP solution only.
≥0 5 | One line of summary output (<80 characters; see [Description of the Printed Output] in e04nc) for each minor iteration (no printout of the final QP solution).
≥10 | The final QP solution and one line of summary output for each minor iteration.
The following printout is sent to the logical unit number defined by the optional parameter Monitoring File:
i | Output
<5 | No output.
≥5 | One long line of output (>80 characters; see [Description of the Printed Output] in e04nc) for each minor iteration (no printout of the final QP solution).
≥20 | At each minor iteration, the current estimates of the QP multipliers, the current estimate of the QP search direction, the QP constraint values and the status of each QP constraint.
≥30 | At each minor iteration, the diagonal elements of the matrix T associated with the TQ factorization (5) (see [Overview]) of the QP working set and the diagonal elements of the Cholesky factor R of the transformed Hessian (6) (see [Overview]).
If Minor Print Level≥5 and the unit number defined by the optional parameter Monitoring File is the same as that defined by (X04ABF not in this release) then the summary output for each minor iteration is suppressed.
Monitoring File
If i≥0 and Major Print Level≥5 or i≥0 and Minor Print Level≥5, monitoring information produced by e04uf at every iteration is sent to a file with logical unit number i. If i<0 and/or Major Print Level<5 and Minor Print Level<5, no monitoring information is produced.
Optimality Tolerance
The parameter r (εr≤r<1) specifies the accuracy to which you wish the final iterate to approximate a solution of the problem. Broadly speaking, r indicates the number of correct figures desired in the objective function at the solution. For example, if r is 10-6 and e04uf terminates successfully, the final value of F should have approximately six correct figures. If r<εr or r≥1, the default value is used.
e04uf will terminate successfully if the iterative sequence of x values is judged to have converged and the final point satisfies the first-order Kuhn–Tucker conditions (see [Overview]). The sequence of iterates is considered to have converged at x if
α p≤r 1+x, (16)
where p is the search direction and α the step length from (3). An iterate is considered to satisfy the first-order conditions for a minimum if
ZT gFR≤r 1+max 1+F x,gFR (17)
and
resj≤ftol  for all  j, (18)
where ZT gFR is the projected gradient (see [Overview]), gFR is the gradient of F x with respect to the free variables, resj is the violation of the jth active nonlinear constraint, and ftol is the Nonlinear Feasibility Tolerance.
Start Objective Check At Variable
Stop Objective Check At Variable
Start Constraint Check At Variable
Stop Constraint Check At Variable
These keywords take effect only if Verify Level>0. They may be used to control the verification of gradient elements and/or Jacobian elements computed by the calling program during intermediate exits. For example, if the first 30 elements of the objective gradient appeared to be correct in an earlier run, so that only element 31 remains questionable, it is reasonable to specify Start Objective Check At Variable=31. If the first 30 variables appear linearly in the objective, so that the corresponding gradient elements are constant, the above choice would also be appropriate.
If i 2 m-1≤0 or i 2 m-1>min n,i 2 m, the default value is used, for m=1,2. If i 2 m≤0 or i 2 m>n, the default value is used, for m=1,2.
Step Limit
If r>0,r specifies the maximum change in variables at the first step of the linesearch. In some cases, such as F x=a e bx or F x=a xb, even a moderate change in the elements of x can lead to floating-point overflow. The parameter r is therefore used to encourage evaluation of the problem functions at meaningful points. Given any major iterate x, the first point x~ at which F and c are evaluated during the linesearch is restricted so that
x~-x 2≤r 1+x 2.
The linesearch may go on and evaluate F and c at points further from x if this will result in a lower value of the merit function (indicated by L at the end of each line of output produced by the major iterations; see [Description of the Printed Output]). If L is printed for most of the iterations, r should be set to a larger value.
Wherever possible, upper and lower bounds on x should be used to prevent evaluation of nonlinear functions at wild values. The default value Step Limit=2.0 should not affect progress on well-behaved functions, but values such as 0.1​ or ​0.01 may be helpful when rapidly varying functions are present. If a small value of Step Limit is selected then a good starting point may be required. An important application is to the class of nonlinear least squares problems. If r≤0, the default value is used.
Verify Level
Verify
Verify Constraint Gradients
Verify Gradients
Verify Objective Gradients
These keywords refer to finite difference checks on the gradient elements computed by the calling program during intermediate exits. (Unspecified gradient elements are not checked.) The possible choices for i are as follows:
i | Meaning
-1 | No checks are performed.
-0 | Only a ‘cheap’ test will be performed.
≥1 | In addition to the ‘cheap’ test, individual gradient elements will also be checked using a reliable (but more expensive) test.
It is possible to specify Verify Level=0 to 3 in several ways. For example, the objective gradient will be verified if Verify, Verify=YES, Verify Gradients, Verify Objective Gradients or Verify Level=1 is specified. The constraint gradients will be verified if Verify=YES or Verify Level=2 or Verify is specified. Similarly, the objective and the constraint gradients will be verified if Verify=YES or Verify Level=3 or Verify is specified.
If 0≤i≤3, gradients will be verified at the first point that satisfies the linear constraints and bounds.
If i=0, only a ‘cheap’ test will be performed, requiring one intermediate exit for the objective function gradients and (if appropriate) one intermediate exit for the partial derivatives of the constraints.
If 1≤i≤3, a more reliable (but more expensive) check will be made on individual gradient elements, within the ranges specified by the Start Objective Check At Variable and Stop Objective Check At Variable keywords. A result of the form OK or BAD? is printed by e04uf to indicate whether or not each element appears to be correct.
If 10≤i≤13, the action is the same as for i<10, except that it will take place at the user-specified initial value of x.
If i<-1 or 4≤i≤9 or i>13, the default value is used.
We suggest that Verify Level=3 be used whenever a new calling program is being developed.

Inheritance Hierarchy

System..::..Object
NagLibrary..::..E04..::..e04ufOptions

See Also

E04..::..e04ufOptions Members
NagLibrary Namespace
NAG Library Overview
e04uf


E04.e04ufOptions Members

[image] [image]

NAG Library for .NET Release 2
E04..::..e04ufOptions Members
E04..::..e04ufOptions Class Constructors Methods Properties See Also Send Feedback

An optimization problem involves minimizing a function (called the objective function) of several variables, possibly subject to restrictions on the values of the variables defined by a set of constraint functions. Most methods in the Library are concerned with function minimization only, since the problem of maximizing a given objective function F(x) is equivalent to minimizing -F x. Some methods allow you to specify whether you are solving a minimization or maximization problem, carrying out the required transformation of the objective function in the latter case.
In general methods in this chapter find a local minimum of a function f, that is a point x* s.t. for all x near x* f x≥f x*.
The E05 class contains methods to find the global minimum of a function f. At a global minimum x* f x≥f x* for all x.
The (H not in this release) contains methods typically regarded as belonging to the field of operations research.
This introduction is only a brief guide to the subject of optimization designed for the casual user. Anyone with a difficult or protracted problem to solve will find it beneficial to consult a more detailed text, such as Gill et al. (1981) or Fletcher (1987).
If you are unfamiliar with the mathematics of the subject you may find some sections difficult at first reading; if so, you should concentrate on [Types of Optimization Problems], [Geometric Representation and Terminology], [Scaling], [Analysis of Computed Results] and [Recommendations on Choice and Use of Available Methods] .

The E04..::..e04ufOptions type exposes the following members.

Constructors

Name | Description
E04..::..e04ufOptions | Constructor

Methods

Name | Description
Set | Overloaded.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e04uf.
Warning | Set the method used for logging any warning or error messages from e04uf.

See Also

E04..::..e04ufOptions Class


E04.e04ufOptions Constructor

[image]

NAG Library for .NET Release 2
E04..::..e04ufOptions Constructor
E04..::..e04ufOptions Class See Also Send Feedback
Constructor

Syntax

C#
public e04ufOptions()
Visual Basic
Public Sub New
Visual C++
public:
e04ufOptions()
F#
new : unit -> e04ufOptions

See Also

E04..::..e04ufOptions Class
E04..::..e04ufOptions Members


E04.e04ufOptions Methods

[image] [image]

NAG Library for .NET Release 2
E04..::..e04ufOptions Methods
E04..::..e04ufOptions Class See Also Send Feedback

Methods

Name | Description
Set | Overloaded.

See Also

E04..::..e04ufOptions Class


Set Method

[image] [image]

NAG Library for .NET Release 2
E04..::..e04ufOptions..::Set Method
E04..::..e04ufOptions Class See Also Send Feedback

Overload List

Name | Description
Set(String) | Set an Option for e04uf
Set(DataReader) | Set Options for from a DataReader Stream.

See Also

E04..::..e04ufOptions Class
E04..::..e04ufOptions Members


Set Method (String)

[image]

NAG Library for .NET Release 2
E04..::..e04ufOptions..::Set Method (String)
E04..::..e04ufOptions Class See Also Send Feedback
Set an Option for e04uf

Syntax

C#
public void Set(
    string str
)
Visual Basic
Public Sub Set ( _
    str As String _
)
Visual C++
public:
void Set(
    String^ str
)
F#
member Set :
        str : string -> unit

Parameters

str
Type: System..::..String
A string of the form option = value, or for boolean options, simply option.

See Also

E04..::..e04ufOptions Class
E04..::..e04ufOptions Members
Set Overload


Set Method (DataReader)

[image]

NAG Library for .NET Release 2
E04..::..e04ufOptions..::Set Method (DataReader)
E04..::..e04ufOptions Class See Also Send Feedback
Set Options for from a DataReader Stream.

Syntax

C#
public void Set(
    DataReader sr
)
Visual Basic
Public Sub Set ( _
    sr As DataReader _
)
Visual C++
public:
void Set(
    DataReader^ sr
)
F#
member Set :
        sr : DataReader -> unit

Parameters

sr
Type: NagLibrary..::..DataReader
A DataReader Stream, containing an option setting on each line.

See Also

E04..::..e04ufOptions Class
E04..::..e04ufOptions Members
Set Overload


E04.e04ufOptions Properties

[image] [image]

NAG Library for .NET Release 2
E04..::..e04ufOptions Properties
E04..::..e04ufOptions Class See Also Send Feedback

The E04..::..e04ufOptions type exposes the following members.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e04uf.
Warning | Set the method used for logging any warning or error messages from e04uf.

See Also

E04..::..e04ufOptions Class


Message Property

[image]

NAG Library for .NET Release 2
E04..::..e04ufOptions..::Message Property
E04..::..e04ufOptions Class See Also Send Feedback
Set the method used for logging any monitoring messages from e04uf.

Syntax

C#
public PrintManager..::..MessageLogger Message { get; set; }
Visual Basic
Public Property Message As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Message {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Message : PrintManager..::..MessageLogger with get, set

See Also

E04..::..e04ufOptions Class
E04..::..e04ufOptions Members


Warning Property

[image]

NAG Library for .NET Release 2
E04..::..e04ufOptions..::Warning Property
E04..::..e04ufOptions Class See Also Send Feedback
Set the method used for logging any warning or error messages from e04uf.

Syntax

C#
public PrintManager..::..MessageLogger Warning { get; set; }
Visual Basic
Public Property Warning As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Warning {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Warning : PrintManager..::..MessageLogger with get, set

See Also

E04..::..e04ufOptions Class
E04..::..e04ufOptions Members


E04.e04ugOptions Class

[image]

NAG Library for .NET Release 2
E04..::..e04ugOptions Class
E04 Class Members See Also Send Feedback
Options Class for e04ug

Syntax

C#
public class e04ugOptions
Visual Basic
Public Class e04ugOptions
Visual C++
public ref class e04ugOptions
F#
type e04ugOptions =  class end

Description of the Optional Parameters

For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
  • the keywords, where the minimum abbreviation of each keyword is underlined (if no characters of an optional qualifier are underlined, the qualifier may be omitted);
  • a parameter value, where the letters a, i​ and ​r denote options that take character, integer and real values respectively;
  • the default value is used whenever the condition i≥100000000 is satisfied and where the symbol ε is a generic notation for machine precision (see x02aj).
Keywords and character values are case and white space insensitive.
Central Difference Interval
Note that this option does not apply when Derivative Level=3.
The value of r is used near an optimal solution in order to obtain more accurate (but more expensive) estimates of gradients. This requires twice as many function evaluations as compared to using forward differences (see optional parameter Forward Difference Interval). The interval used for the jth variable is hj=r 1+xj. The resulting gradient estimates should be accurate to O r 2, unless the functions are badly scaled. The switch to central differences is indicated by c at the end of each line of intermediate printout produced by the major iterations (see [Major Iteration Printout]). See Gill et al. (1981) for a discussion of the accuracy in finite difference approximations.
If r≤0, the default value is used.
Check Frequency
Every ith minor iteration after the most recent basis factorization, a numerical test is made to see if the current solution x,s satisfies the general linear constraints (including any linearized nonlinear constraints). The constraints are of the form Ax-s=b, where s is the set of slack variables. If the largest element of the residual vector r=b-Ax+s is judged to be too large, the current basis is refactorized and the basic variables recomputed to satisfy the general constraints more accurately.
If i<0, the default value is used. If i=0, the value i=99999999 is used and effectively no checks are made.
Crash Option
The default value of i is 0 if there are any nonlinear constraints and 3 otherwise. Note that this option does not apply when start="W" (see [Parameters]).
If start="C", an internal Crash procedure is used to select an initial basis from various rows and columns of the constraint matrix A-I. The value of i determines which rows and columns of A are initially eligible for the basis and how many times the Crash procedure is called. Columns of -I are used to pad the basis where necessary. The possible choices for i are the following.
i | Meaning
0 | The initial basis contains only slack variables: B=I.
1 | The Crash procedure is called once (looking for a triangular basis in all rows and columns of A).
2 | The Crash procedure is called twice (if there are any nonlinear constraints). The first call looks for a triangular basis in linear rows and the iteration proceeds with simplex iterations until the linear constraints are satisfied. The Jacobian is then evaluated for the first major iteration and the Crash procedure is called again to find a triangular basis in the nonlinear rows (whilst retaining the current basis for linear rows).
3 | The Crash procedure is called up to three times (if there are any nonlinear constraints). The first two calls treat linear equality constraints and linear inequality constraints separately. The Jacobian is then evaluated for the first major iteration and the Crash procedure is called again to find a triangular basis in the nonlinear rows (whilst retaining the current basis for linear rows).
If i<0 or i>3, the default value is used.
If i≥1, certain slacks on inequality rows are selected for the basis first. (If i≥2, numerical values are used to exclude slacks that are close to a bound.) The Crash procedure then makes several passes through the columns of A, searching for a basis matrix that is essentially triangular. A column is assigned to ‘pivot’ on a particular row if the column contains a suitably large element in a row that has not yet been assigned. (The pivot elements ultimately form the diagonals of the triangular basis.) For remaining unassigned rows, slack variables are inserted to complete the basis.
Crash Tolerance
The value r (0≤r<1) allows the Crash procedure to ignore certain ‘small’ nonzero elements in the columns of A while searching for a triangular basis. If amax is the largest element in the jth column, other nonzeros a ij in the column are ignored if a ij≤amax×r.
When r>0, the basis obtained by the Crash procedure may not be strictly triangular, but it is likely to be nonsingular and almost triangular. The intention is to obtain a starting basis containing more columns of A and fewer (arbitrary) slacks. A feasible solution may be reached earlier on some problems.
If r<0 or r≥1, the default value is used.
Defaults
This special keyword may be used to reset all optional parameters to their default values.
Derivative Level
This parameter indicates which nonlinear function gradients are provided in user-supplied delegates objfun and confun. The possible choices for i are the following.
i | Meaning
3 | All elements of the objective gradient and the constraint Jacobian are provided.
2 | All elements of the constraint Jacobian are provided, but some (or all) elements of the objective gradient are not specified.
1 | All elements of the objective gradient are provided, but some (or all) elements of the constraint Jacobian are not specified.
0 | Some (or all) elements of both the objective gradient and the constraint Jacobian are not specified.
The default value i=3 should be used whenever possible. It is the most reliable and will usually be the most efficient.
If i=0​ or ​2, e04ug will estimate the unspecified elements of the objective gradient, using finite differences. This may simplify the coding of objfun. However, the computation of finite difference approximations usually increases the total run-time substantially (since a call to objfun is required for each unspecified element) and there is less assurance that an acceptable solution will be found.
If i=0​ or ​1, e04ug will approximate unspecified elements of the constraint Jacobian. For each column of the Jacobian, one call to confun is needed to estimate all unspecified elements in that column (if any). For example, if the sparsity pattern of the Jacobian has the form
*****??***?*****
where ‘*’ indicates an element provided and ‘?’ indicates an unspecified element, e04ug will call confun twice: once to estimate the missing element in column 2 and again to estimate the two missing elements in column 3. (Since columns 1 and 4 are known, they require no calls to confun.)
At times, central differences are used rather than forward differences, in which case twice as many calls to objfun and confun are needed. (The switch to central differences is not under your control.)
If i<0 or i>3, the default value is used.
Derivative Linesearch
Nonderivative Linesearch
At each major iteration, a linesearch is used to improve the value of the Lagrangian merit function (6). The default linesearch uses safeguarded cubic interpolation and requires both function and gradient values in order to compute estimates of the step αk. If some analytic derivatives are not provided or optional parameter Nonderivative Linesearch is specified, a linesearch based upon safeguarded quadratic interpolation (which does not require the evaluation or approximation of any gradients) is used instead.
A nonderivative linesearch can be slightly less robust on difficult problems and it is recommended that the default be used if the functions and their derivatives can be computed at approximately the same cost. If the gradients are very expensive to compute relative to the functions however, a nonderivative linesearch may result in a significant decrease in the total run-time.
If optional parameter Nonderivative Linesearch is selected, e04ug signals the evaluation of the linesearch by calling objfun and confun with mode=0. Once the linesearch is complete, the nonlinear functions are re-evaluated with mode=2. If the potential savings offered by a nonderivative linesearch are to be fully realised, it is essential that objfun and confun be coded so that no derivatives are computed when mode=0.
Elastic Weight
The default value of r is 100.0 if there are any nonlinear constraints and 1.0 otherwise.
This option defines the initial weight γ associated with problem (8).
At any given major iteration k, elastic mode is entered if the QP subproblem is infeasible or the QP dual variables (Lagrange multipliers) are larger in magnitude than r×1+g xk 2, where g is the objective gradient. In either case, the QP subproblem is resolved in elastic mode with γ=r×1+g xk 2.
Thereafter, γ is increased (subject to a maximum allowable value) at any point that is optimal for problem (8), but not feasible for problem (1). After the pth increase, γ=r×10 p×1+g x k 1 2, where x k 1 is the iterate at which γ was first needed.
If r<0, the default value is used.
Expand Frequency
This option is part of the EXPAND anti-cycling procedure due to Gill et al. (1989), which is designed to make progress even on highly degenerate problems.
For linear models, the strategy is to force a positive step at every iteration, at the expense of violating the constraints by a small amount. Suppose that the value of optional parameter Minor Feasibility Tolerance is δ. Over a period of i iterations, the feasibility tolerance actually used by e04ug (i.e., the working feasibility tolerance) increases from 0.5 δ to δ (in steps of 0.5 δ/i).
For nonlinear models, the same procedure is used for iterations in which there is only one superbasic variable. (Cycling can only occur when the current solution is at a vertex of the feasible region.) Thus, zero steps are allowed if there is more than one superbasic variable, but otherwise positive steps are enforced.
Increasing the value of i helps reduce the number of slightly infeasible nonbasic basic variables (most of which are eliminated during the resetting procedure). However, it also diminishes the freedom to choose a large pivot element (see optional parameter Pivot Tolerance).
If i<0, the default value is used. If i=0, the value i=99999999 is used and effectively no anti-cycling procedure is invoked.
Factorization Frequency
The default value of i is 50 if there are any nonlinear constraints and 100 otherwise.
If i>0, at most i basis changes will occur between factorizations of the basis matrix.
For linear problems, the basis factors are usually updated at every iteration. The default value i=100 is reasonable for typical problems, particularly those that are extremely sparse and well-scaled.
When the objective function is nonlinear, fewer basis updates will occur as the solution is approached. The number of iterations between basis factorizations will therefore increase. During these iterations a test is made regularly according to the value of optional parameter Check Frequency to ensure that the general constraints are satisfied. If necessary, the basis will be refactorized before the limit of i updates is reached.
If i≤0, the default value is used.
Infeasible Exit
Feasible Exit
Note that this option is ignored if the value of optional parameter Major Iteration Limit is exceeded, or the linear constraints are infeasible.
If termination is about to occur at a point that does not satisfy the nonlinear constraints and optional parameter Feasible Exit is selected, this option requests that additional iterations be performed in order to find a feasible point (if any) for the nonlinear constraints. This involves solving a feasible point problem in which the objective function is omitted.
Otherwise, this option requests no additional iterations be performed.
Minimize
Maximize
Feasible Point
If optional parameter Feasible Point is selected, this option attempts to find a feasible point (if any) for the nonlinear constraints by omitting the objective function. It can also be used to check whether the nonlinear constraints are feasible.
Otherwise, this option specifies the required direction of the optimization. It applies to both linear and nonlinear terms (if any) in the objective function. Note that if two problems are the same except that one minimizes f x and the other maximizes -f x, their solutions will be the same but the signs of the dual variables πi and the reduced gradients dj will be reversed.
Forward Difference Interval
This option defines an interval used to estimate derivatives by forward differences in the following circumstances:
(a) | For verifying the objective and/or constraint gradients (see the description of the optional parameter Verify Level).
(b) | For estimating unspecified elements of the objective gradient and/or the constraint Jacobian.
A derivative with respect to xj is estimated by perturbing that element of x to the value xj+r 1+xj and then evaluating f x and/or F x (as appropriate) at the perturbed point. The resulting gradient estimates should be accurate to O r, unless the functions are badly scaled. Judicious alteration of r may sometimes lead to greater accuracy. See Gill et al. (1981) for a discussion of the accuracy in finite difference approximations.
If r≤0, the default value is used.
Function Precision
This parameter defines the relative function precision εr, which is intended to be a measure of the relative accuracy with which the nonlinear functions can be computed. For example, if f x (or Fi x) is computed as 1000.56789 for some relevant x and the first 6 significant digits are known to be correct then the appropriate value for εr would be 10-6.
Ideally the functions f x or Fi x should have magnitude of order 1. If all functions are substantially less than 1 in magnitude, εr should be the absolute precision. For example, if f x (or Fi x) is computed as 1.23456789×10-4 for some relevant x and the first 6 significant digits are known to be correct then the appropriate value for εr would be 10-10.
The choice of εr can be quite complicated for badly scaled problems; see Chapter 8 of Gill et al. (1981) for a discussion of scaling techniques. The default value is appropriate for most simple functions that are computed with full accuracy.
In some cases the function values will be the result of extensive computation, possibly involving an iterative procedure that can provide few digits of precision at reasonable cost. Specifying an appropriate value of r may therefore lead to savings, by allowing the linesearch procedure to terminate when the difference between function values along the search direction becomes as small as the absolute error in the values.
If r<ε or r≥1, the default value is used.
Hessian Frequency
This option forces the approximate Hessian formed from i BFGS updates to be reset to the identity matrix upon completion of a major iteration. It is intended to be used in conjunction with optional parameter Hessian Full Memory.
If i≤0, the default value is used and effectively no resets occur.
Hessian Full Memory
Hessian Limited Memory
These options specify the method for storing and updating the quasi-Newton approximation to the Hessian of the Lagrangian function.
If Hessian Full Memory is specified, the approximate Hessian is treated as a dense matrix and BFGS quasi-Newton updates are applied explicitly. This is most efficient when the total number of nonlinear variables is not too large (say, n-<75). In this case, the storage requirement is fixed and you can expect 1-step Q-superlinear convergence to the solution.
Hessian Limited Memory should only be specified when n- is very large. In this case a limited memory procedure is used to update a diagonal Hessian approximation Hr a limited number of times. (Updates are accumulated as a list of vector pairs. They are discarded at regular intervals after Hr has been reset to their diagonal.)
Note that if Hessian Frequency=20 is used in conjunction with Hessian Full Memory, the effect will be similar to using Hessian Limited Memory in conjunction with Hessian Updates=20, except that the latter will retain the current diagonal during resets.
Hessian Updates
The default value of i is 20 when Hessian Limited Memory is in effect and 99999999 when Hessian Full Memory is in effect, in which case no updates are performed.
If Hessian Limited Memory is in effect, this option defines the maximum number of pairs of Hessian update vectors that are to be used to define the quasi-Newton approximate Hessian. Once the limit of i updates is reached, all but the diagonal elements of the accumulated updates are discarded and the process starts again. Broadly speaking, the more updates that are stored, the better the quality of the approximate Hessian. On the other hand, the more vectors that are stored, the greater the cost of each QP iteration.
The default value of i is likely to give a robust algorithm without significant expense, but faster convergence may be obtained with far fewer updates (e.g., i=5).
If i<0, the default value is used.
Infinite Bound Size
If r>0, r defines the ‘infinite’ bound bigbnd in the definition of the problem constraints. Any upper bound greater than or equal to bigbnd will be regarded as +∞ (and similarly any lower bound less than or equal to -bigbnd will be regarded as -∞).
If r≤0, the default value is used.
Iteration Limit
The value of i specifies the maximum number of minor iterations allowed (i.e., iterations of the simplex method or the QP algorithm), summed over all major iterations. (See also the description of the optional parameters Major Iteration Limit and Minor Iteration Limit.)
If i<0, the default value is used.
Linesearch Tolerance
This option controls the accuracy with which a step length will be located along the direction of search at each iteration. At the start of each linesearch a target directional derivative for the Lagrangian merit function is identified. The value of r therefore determines the accuracy to which this target value is approximated.
The default value r=0.9 requests an inaccurate search and is appropriate for most problems, particularly those with any nonlinear constraints.
If the nonlinear functions are cheap to evaluate, a more accurate search may be appropriate; try r=0.1,0.01​ or ​0.001. The number of major iterations required to solve the problem might decrease.
If the nonlinear functions are expensive to evaluate, a less accurate search may be appropriate. If Derivative Level=3, try r=0.99. (The number of major iterations required to solve the problem might increase, but the total number of function evaluations may decrease enough to compensate.)
If Derivative Level<3, a moderately accurate search may be appropriate; try r=0.5. Each search will (typically) require only 1-5 function values, but many function calls will then be needed to estimate the missing gradients for the next iteration.
If r<0 or r≥1, the default value is used.
List
Nolist
Normally each optional parameter specification is printed as it is supplied. Optional parameter Nolist may be used to suppress the printing and optional parameter List may be used to restore printing.
LU Density Tolerance
LU Singularity Tolerance
If r 1>0, r 1 defines the density tolerance used during the LU factorization of the basis matrix. Columns of L and rows of U are formed one at a time and the remaining rows and columns of the basis are altered appropriately. At any stage, if the density of the remaining matrix exceeds r 1, the Markowitz strategy for choosing pivots is terminated. The remaining matrix is then factorized using a dense LU procedure. Increasing the value of r 1 towards unity may give slightly sparser LU factors, with a slight increase in factorization time. If r 1≤0, the default value is used.
If r 2>0, r 2 defines the singularity tolerance used to guard against ill-conditioned basis matrices. Whenever the basis is refactorized, the diagonal elements of U are tested as follows. If u jj≤r 2 or u jj<r 2×maxi u ij, the jth column of the basis is replaced by the corresponding slack variable. This is most likely to occur when start="W" (see [Parameters]), or at the start of a major iteration. If r 2≤0, the default value is used.
In some cases, the Jacobian matrix may converge to values that make the basis exactly singular (e.g., a whole row of the Jacobian matrix could be zero at an optimal solution). Before exact singularity occurs, the basis could become very ill-conditioned and the optimization could progress very slowly (if at all). Setting r 2=0.00001 (say) may therefore help cause a judicious change of basis in such situations.
LU Factor Tolerance
LU Update Tolerance
The default value of r 1 is 5.0 if there are any nonlinear constraints and 100.0 otherwise. The default value of r 2 is 5.0 if there are any nonlinear constraints and 10.0 otherwise.
If r 1≥1 and r 2≥1, the values of r 1 and r 2 affect the stability and sparsity of the basis factorization B=LU, during refactorization and updating, respectively. The lower triangular matrix L is a product of matrices of the form
10μ1,
where the multipliers μ satisfy μ≤ri. Smaller values of ri favour stability, while larger values favour sparsity. The default values of r 1 and r 2 usually strike a good compromise. For large and relatively dense problems, setting r 1=10.0​ or ​5.0 (say) may give a marked improvement in sparsity without impairing stability to a serious degree. Note that for problems involving band matrices, it may be necessary to reduce r 1 and/or r 2 in order to achieve stability.
If r 1<1 or r 2<1, the appropriate default value is used.
Major Feasibility Tolerance
This option specifies how accurately the nonlinear constraints should be satisfied. The default value is appropriate when the linear and nonlinear constraints contain data to approximately that accuracy. A larger value may be appropriate if some of the problem functions are known to be of low accuracy.
Let rowerr be defined as the maximum nonlinear constraint violation normalized by the size of the solution. It is required to satisfy
rowerr=maxi violi x,s≤r,
where violi is the violation of the ith nonlinear constraint.
If r≤ε, the default value is used.
Major Iteration Limit
The value of i specifies the maximum number of major iterations allowed before termination. It is intended to guard against an excessive number of linearizations of the nonlinear constraints. Setting i=0 and Major Print Level>0 means that the objective and constraint gradients will be checked if Verify Level>0 and the workspace needed to start solving the problem will be computed and printed, but no iterations will be performed.
If i<0, the default value is used.
Major Optimality Tolerance
Optimality Tolerance
This option specifies the final accuracy of the dual variables. If e04ug terminates with ifail=0, a primal and dual solution (x,s,π) will have been computed such that
maxgap=maxj gapj π≤r,
where gapj is an estimate of the complementarity gap for the jth variable and π is a measure of the size of the QP dual variables (or Lagrange multipliers) given by
π=max σ m,1,   where  σ=∑i=1 m πi.
It is included to make the tests independent of a scale factor on the objective function. Specifically, gapj is computed from the final QP solution using the reduced gradients dj=gj-πT aj, where gj is the jth element of the objective gradient and aj is the associated column of the constraint matrix A-I:
gapj=-dj min xj-lj,1if ​dj≥0;-dj min uj-xj,1if ​dj<0.
If r≤0, the default value is used.
Major Print Level
Print Level
The value of i controls the amount of printout produced by the major iterations of e04ug, as indicated below. A detailed description of the printed output is given in [Major Iteration Printout] (summary output at each major iteration and the final solution) and [Description of Monitoring Information] (monitoring information at each major iteration). (See also the description of Minor Print Level.)
The following printout is sent to the current advisory message unit (as defined by (X04ABF not in this release)):
i | Output
≥0 0 | No output.
≥0 1 | The final solution only.
≥0 5 | One line of summary output (<80 characters; see [Major Iteration Printout]) for each major iteration (no printout of the final solution).
≥10 | The final solution and one line of summary output for each major iteration.
The following printout is sent to the logical unit number defined by the optional parameter Monitoring File:
i | Output
≥0 0 | No output.
≥0 1 | The final solution only.
≥0 5 | One long line of output (<120 characters; see [Description of Monitoring Information]) for each major iteration (no printout of the final solution).
≥10 | The final solution and one long line of output for each major iteration.
≥20 | The final solution, one long line of output for each major iteration, matrix statistics (initial status of rows and columns, number of elements, density, biggest and smallest elements, etc.), details of the scale factors resulting from the scaling procedure (if Scale Option=1 or 2), basis factorization statistics and details of the initial basis resulting from the Crash procedure (if start="C"; see [Parameters]).
If Major Print Level≥5 and the unit number defined by the optional parameter Monitoring File is the same as that defined by (X04ABF not in this release) then the summary output for each major iteration is suppressed.
Major Step Limit
If r>0,r limits the change in x during a linesearch. It applies to all nonlinear problems once a ‘feasible solution’ or ‘feasible subproblem’ has been found.
A linesearch determines a step α in the interval 0<α≤β, where β=1 if there are any nonlinear constraints, or the step to the nearest upper or lower bound on x if all the constraints are linear. Normally, the first step attempted is α 1=min 1,β.
In some cases, such as f x=a e bx or f x=a xb, even a moderate change in the elements of x can lead to floating-point overflow. The parameter r is therefore used to define a step limit β- given by
β-=r 1+x 2p 2,
where p is the search direction and the first evaluation of f x is made at the (potentially) smaller step length α 1=min 1,β-,β.
Wherever possible, upper and lower bounds on x should be used to prevent evaluation of nonlinear functions at meaningless points. The default value r=2.0 should not affect progress on well-behaved functions, but values such as r=0.1​ or ​0.01 may be helpful when rapidly varying functions are present. If a small value of r is selected, a ‘good’ starting point may be required. An important application is to the class of nonlinear least squares problems.
If r≤0, the default value is used.
Minor Feasibility Tolerance
Feasibility Tolerance
This option attempts to ensure that all variables eventually satisfy their upper and lower bounds to within the tolerance r. Since this includes slack variables, general linear constraints should also be satisfied to within r. Note that feasibility with respect to nonlinear constraints is judged by the value of optional parameter Major Feasibility Tolerance and not by r.
If the bounds and linear constraints cannot be satisfied to within r, the problem is declared infeasible. Let Sinf be the corresponding sum of infeasibilities. If Sinf is quite small, it may be appropriate to raise r by a factor of 10 or 100. Otherwise, some error in the data should be suspected.
If Scale Option≥1, feasibility is defined in terms of the scaled problem (since it is more likely to be meaningful).
Nonlinear functions will only be evaluated at points that satisfy the bounds and linear constraints. If there are regions where a function is undefined, every effort should be made to eliminate these regions from the problem. For example, if f x 1,x 2=x 1+log x 2, it is essential to place lower bounds on both x 1 and x 2. If the value r=10-6 is used, the bounds x 1≥10-5 and x 2≥10-4 might be appropriate. (The log singularity is more serious; in general, you should attempt to keep x as far away from singularities as possible.)
In reality, r is used as a feasibility tolerance for satisfying the bounds on x and s in each QP subproblem. If the sum of infeasibilities cannot be reduced to zero, the QP subproblem is declared infeasible and the method is then in elastic mode thereafter (with only the linearized nonlinear constraints defined to be elastic). (See also the description of Elastic Weight.)
If r≤ε, the default value is used.
Minor Iteration Limit
The value of i specifies the maximum number of iterations allowed between successive linearizations of the nonlinear constraints. A value in the range 10≤i≤50 prevents excessive effort being expended on early major iterations, but allows later QP subproblems to be solved to completion. Note that an extra m minor iterations are allowed if the first QP subproblem to be solved starts with the all-slack basis B=I. (See the description of the optional parameter Crash Option.)
In general, it is unsafe to specify values as small as i=1​ or ​2 (because even when an optimal solution has been reached, a few minor iterations may be needed for the corresponding QP subproblem to be recognized as optimal).
If i≤0, the default value is used.
Minor Optimality Tolerance
This option is used to judge optimality for each QP subproblem. Let the QP reduced gradients be dj=gj-πT aj, where gj is the jth element of the QP gradient, aj is the associated column of the QP constraint matrix and π is the set of QP dual variables.
By construction, the reduced gradients for basic variables are always zero. The QP subproblem will be declared optimal if the reduced gradients for nonbasic variables at their upper or lower bounds satisfy
dj π≥-r  or  dj π≤r
respectively, and if dj π≤r for superbasic variables.
Note that π is a measure of the size of the dual variables. It is included to make the tests independent of a scale factor on the objective function. (The value of π actually used is defined in the description for optional parameter Major Optimality Tolerance.)
If the objective is scaled down to be very small, the optimality test reduces to comparing dj against r.
If r≤0, the default value is used.
Minor Print Level
The value of i controls the amount of printout produced by the minor iterations of e04ug (i.e., the iterations of the quadratic programming algorithm), as indicated below. A detailed description of the printed output is given in [Minor Iteration Printout] (summary output at each minor iteration) and [Description of Monitoring Information] (monitoring information at each minor iteration). (See also the description of the optional parameter Major Print Level.)
The following printout is sent to the current advisory message unit (as defined by (X04ABF not in this release)):
i | Output
≥0 | No output.
≥1 | One line of summary output (<80 characters; see [Minor Iteration Printout]) for each minor iteration.
The following printout is sent to the logical unit number defined by the optional parameter Monitoring File:
i | Output
≥0 | No output.
≥1 | One long line of output (<120 characters; see [Description of Monitoring Information]) for each minor iteration.
If Minor Print Level≥1 and the unit number defined by the optional parameter Monitoring File is the same as that defined by (X04ABF not in this release) then the summary output for each minor iteration is suppressed.
Monitoring File
If i≥0 and Major Print Level≥5 or i≥0 and Minor Print Level≥1 then monitoring information is produced by e04ug at every iteration is sent to a file with logical unit number i. If i<0 and/or Major Print Level<5 and Minor Print Level<1 then no monitoring information is produced.
Partial Price
The default value of i is 1 if there are any nonlinear constraints and 10 otherwise.
This option is recommended for large problems that have significantly more variables than constraints (i.e., n≫m). It reduces the work required for each ‘pricing’ operation (i.e., when a nonbasic variable is selected to become superbasic). The possible choices for i are the following.
i | Meaning
≥1 | All columns of the constraint matrix A-I are searched.
≥2 | Both A and I are partitioned to give i roughly equal segments Aj,Ij, for j=1,2,…,p (modulo p). If the previous pricing search was successful on Aj,Ij, the next search begins on the segments A j+1,I j+1. If a reduced gradient is found that is larger than some dynamic tolerance, the variable with the largest such reduced gradient (of appropriate sign) is selected to enter the basis. If nothing is found, the search continues on the next segments A j+2,I j+2 and so on.
If i≤0, the default value is used.
Pivot Tolerance
If r>0, r is used during the solution of QP subproblems to prevent columns entering the basis if they would cause the basis to become almost singular.
When x changes to x+αp for some specified search direction p, a ‘ratio test’ is used to determine which element of x reaches an upper or lower bound first. The corresponding element of p is called the pivot element. Elements of p are ignored (and therefore cannot be pivot elements) if they are smaller than r.
It is common in practice for two (or more) variables to reach a bound at essentially the same time. In such cases, the Minor Feasibility Tolerance provides some freedom to maximize the pivot element and thereby improve numerical stability. Excessively small values of Minor Feasibility Tolerance should therefore not be specified. To a lesser extent, the Expand Frequency also provides some freedom to maximize the pivot element. Excessively large values of Expand Frequency should therefore not be specified.
If r≤0, the default value is used.
Scale Option
The default value of i is 1 if there are any nonlinear constraints and 2 otherwise.
This option enables you to scale the variables and constraints using an iterative procedure due to Fourer (1982), which attempts to compute row scales ri and column scales cj such that the scaled matrix coefficients a-ij=a ij×cj/ri are as close as possible to unity. (The lower and upper bounds on the variables and slacks for the scaled problem are redefined as l-j=lj/cj and u-j=uj/cj respectively, where cj≡r j-n if j>n.) The possible choices for i are the following.
i | Meaning
0 | No scaling is performed. This is recommended if it is known that the elements of x and the constraint matrix A (along with its Jacobian) never become large (say, >1000).
1 | All linear constraints and variables are scaled. This may improve the overall efficiency of the method on some problems.
2 | All constraints and variables are scaled. Also, an additional scaling is performed that takes into account columns of A-I that are fixed or have positive lower bounds or negative upper bounds.
If there are any nonlinear constraints present, the scale factors depend on the Jacobian at the first point that satisfies the linear constraints and the upper and lower bounds. The setting i=2 should therefore be used only if a ‘good’ starting point is available and the problem is not highly nonlinear.
If i<0 or i>2, the default value is used.
Scale Tolerance
Note that this option does not apply when Scale Option=0.
The value r (0<r<1) is used to control the number of scaling passes to be made through the constraint matrix A. At least 3 (and at most 10) passes will be made. More precisely, let ap denote the largest column ratio (i.e., 'biggest'​ element'smallest'​ element in some sense) after the pth scaling pass through A. The scaling procedure is terminated if ap≥a p-1×r for some p≥3. Thus, increasing the value of r from 0.9 to 0.99 (say) will probably increase the number of passes through A.
If r≤0 or r≥1, the default value is used.
Start Objective Check At Column
Stop Objective Check At Column
Start Constraint Check At Column
Stop Constraint Check At Column
These keywords take effect only if Verify Level>0. They may be used to control the verification of gradient elements computed by objfun and/or Jacobian elements computed by confun. For example, if the first 30 elements of the objective gradient appeared to be correct in an earlier run, so that only element 31 remains questionable then it is reasonable to specify Start Objective Check At Column=31. Similarly for columns of the Jacobian. If the first 30 variables occur nonlinearly in the constraints but the remaining variables are nonlinear only in the objective, then objfun must set the first 30 elements of the array objgrd to zero, but these hardly need to be verified. Again it is reasonable to specify Start Objective Check At Column=31.
If i 2≤0 or i 2>n 1′, the default value is used.
If i 1≤0 or i 1>min n 1′,i 2, the default value is used.
If i 4≤0 or i 4>n 1′′, the default value is used.
If i 3≤0 or i 3>min n 1′′,i 4, the default value is used.
Superbasics Limit
Note that this option does not apply to linear problems.
It places a limit on the storage allocated for superbasic variables. Ideally, the value of i should be set slightly larger than the ‘number of degrees of freedom’ expected at the solution.
For nonlinear problems, the number of degrees of freedom is often called the ‘number of independent variables’. Normally, the value of i need not be greater than n-+1, but for many problems it may be considerably smaller. (This will save storage if n- is very large.)
If i≤0, the default value is used.
Unbounded Objective
Unbounded Step Size
These options are intended to detect unboundedness in nonlinear problems. During the linesearch, the objective function f is evaluated at points of the form x+αp, where x and p are fixed and α varies. If f exceeds r 1 or α exceeds r 2, the iterations are terminated and the method returns with ifail=3.
If singularities are present, unboundedness in f x may manifest itself by a floating-point overflow during the evaluation of f x+αp, before the test against r 1 can be made.
Unboundedness in x is best avoided by placing finite upper and lower bounds on the variables.
If r 1≤0 or r 2≤0, the appropriate default value is used.
Verify Level
This option refers to finite difference checks on the gradient elements computed by objfun and confun. Gradients are verified at the first point that satisfies the linear constraints and the upper and lower bounds. Unspecified gradient elements are not checked and hence they result in no overhead. The possible choices for i are the following.
i | Meaning
-1 | No checks are performed.
-0 | Only a ‘cheap’ test will be performed, requiring three calls to objfun and two calls to confun. Note that no checks are carried out if every column of the constraint gradients (Jacobian) contains a missing element.
-1 | Individual objective gradient elements will be checked using a reliable (but more expensive) test. If Major Print Level>0, a key of the form OK or BAD? indicates whether or not each element appears to be correct.
-2 | Individual columns of the constraint gradients (Jacobian) will be checked using a reliable (but more expensive) test. If Major Print Level>0, a key of the form OK or BAD? indicates whether or not each element appears to be correct.
-3 | Check both constraint and objective gradients (in that order) as described above for i=2 and i=1 respectively.
The value i=3 should be used whenever a new function method is being developed. The Start Objective Check At Column and Stop Objective Check At Column keywords may be used to limit the number of nonlinear variables to be checked.
If i<-1 or i>3, the default value is used.
Violation Limit
This option defines an absolute limit on the magnitude of the maximum constraint violation after the linesearch. Upon completion of the linesearch, the new iterate x k+1 satisfies the condition
vi x k+1≤r×max 1,vi x 0,
where x 0 is the point at which the nonlinear constraints are first evaluated and vi x is the ith nonlinear constraint violation vi x=max 0,li-Fi x,Fi x-ui.
The effect of the violation limit is to restrict the iterates to lie in an expanded feasible region whose size depends on the magnitude of r. This makes it possible to keep the iterates within a region where the objective function is expected to be well-defined and bounded below (or above in the case of maximization). If the objective function is bounded below (or above in the case of maximization) for all values of the variables, then r may be any large positive value.
If r≤0, the default value is used.

Inheritance Hierarchy

System..::..Object
NagLibrary..::..E04..::..e04ugOptions

See Also

E04..::..e04ugOptions Members
NagLibrary Namespace
NAG Library Overview
e04ug


E04.e04ugOptions Members

[image] [image]

NAG Library for .NET Release 2
E04..::..e04ugOptions Members
E04..::..e04ugOptions Class Constructors Methods Properties See Also Send Feedback

An optimization problem involves minimizing a function (called the objective function) of several variables, possibly subject to restrictions on the values of the variables defined by a set of constraint functions. Most methods in the Library are concerned with function minimization only, since the problem of maximizing a given objective function F(x) is equivalent to minimizing -F x. Some methods allow you to specify whether you are solving a minimization or maximization problem, carrying out the required transformation of the objective function in the latter case.
In general methods in this chapter find a local minimum of a function f, that is a point x* s.t. for all x near x* f x≥f x*.
The E05 class contains methods to find the global minimum of a function f. At a global minimum x* f x≥f x* for all x.
The (H not in this release) contains methods typically regarded as belonging to the field of operations research.
This introduction is only a brief guide to the subject of optimization designed for the casual user. Anyone with a difficult or protracted problem to solve will find it beneficial to consult a more detailed text, such as Gill et al. (1981) or Fletcher (1987).
If you are unfamiliar with the mathematics of the subject you may find some sections difficult at first reading; if so, you should concentrate on [Types of Optimization Problems], [Geometric Representation and Terminology], [Scaling], [Analysis of Computed Results] and [Recommendations on Choice and Use of Available Methods] .

The E04..::..e04ugOptions type exposes the following members.

Constructors

Name | Description
E04..::..e04ugOptions | Constructor

Methods

Name | Description
Set | Overloaded.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e04ug.
Warning | Set the method used for logging any warning or error messages from e04ug.

See Also

E04..::..e04ugOptions Class


E04.e04ugOptions Constructor

[image]

NAG Library for .NET Release 2
E04..::..e04ugOptions Constructor
E04..::..e04ugOptions Class See Also Send Feedback
Constructor

Syntax

C#
public e04ugOptions()
Visual Basic
Public Sub New
Visual C++
public:
e04ugOptions()
F#
new : unit -> e04ugOptions

See Also

E04..::..e04ugOptions Class
E04..::..e04ugOptions Members


E04.e04ugOptions Methods

[image] [image]

NAG Library for .NET Release 2
E04..::..e04ugOptions Methods
E04..::..e04ugOptions Class See Also Send Feedback

Methods

Name | Description
Set | Overloaded.

See Also

E04..::..e04ugOptions Class


Set Method

[image] [image]

NAG Library for .NET Release 2
E04..::..e04ugOptions..::Set Method
E04..::..e04ugOptions Class See Also Send Feedback

Overload List

Name | Description
Set(String) | Set an Option for e04ug
Set(DataReader) | Set Options for from a DataReader Stream.

See Also

E04..::..e04ugOptions Class
E04..::..e04ugOptions Members


Set Method (String)

[image]

NAG Library for .NET Release 2
E04..::..e04ugOptions..::Set Method (String)
E04..::..e04ugOptions Class See Also Send Feedback
Set an Option for e04ug

Syntax

C#
public void Set(
    string str
)
Visual Basic
Public Sub Set ( _
    str As String _
)
Visual C++
public:
void Set(
    String^ str
)
F#
member Set :
        str : string -> unit

Parameters

str
Type: System..::..String
A string of the form option = value, or for boolean options, simply option.

See Also

E04..::..e04ugOptions Class
E04..::..e04ugOptions Members
Set Overload


Set Method (DataReader)

[image]

NAG Library for .NET Release 2
E04..::..e04ugOptions..::Set Method (DataReader)
E04..::..e04ugOptions Class See Also Send Feedback
Set Options for from a DataReader Stream.

Syntax

C#
public void Set(
    DataReader sr
)
Visual Basic
Public Sub Set ( _
    sr As DataReader _
)
Visual C++
public:
void Set(
    DataReader^ sr
)
F#
member Set :
        sr : DataReader -> unit

Parameters

sr
Type: NagLibrary..::..DataReader
A DataReader Stream, containing an option setting on each line.

See Also

E04..::..e04ugOptions Class
E04..::..e04ugOptions Members
Set Overload


E04.e04ugOptions Properties

[image] [image]

NAG Library for .NET Release 2
E04..::..e04ugOptions Properties
E04..::..e04ugOptions Class See Also Send Feedback

The E04..::..e04ugOptions type exposes the following members.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e04ug.
Warning | Set the method used for logging any warning or error messages from e04ug.

See Also

E04..::..e04ugOptions Class


Message Property

[image]

NAG Library for .NET Release 2
E04..::..e04ugOptions..::Message Property
E04..::..e04ugOptions Class See Also Send Feedback
Set the method used for logging any monitoring messages from e04ug.

Syntax

C#
public PrintManager..::..MessageLogger Message { get; set; }
Visual Basic
Public Property Message As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Message {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Message : PrintManager..::..MessageLogger with get, set

See Also

E04..::..e04ugOptions Class
E04..::..e04ugOptions Members


Warning Property

[image]

NAG Library for .NET Release 2
E04..::..e04ugOptions..::Warning Property
E04..::..e04ugOptions Class See Also Send Feedback
Set the method used for logging any warning or error messages from e04ug.

Syntax

C#
public PrintManager..::..MessageLogger Warning { get; set; }
Visual Basic
Public Property Warning As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Warning {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Warning : PrintManager..::..MessageLogger with get, set

See Also

E04..::..e04ugOptions Class
E04..::..e04ugOptions Members


E04.e04usOptions Class

[image]

NAG Library for .NET Release 2
E04..::..e04usOptions Class
E04 Class Members See Also Send Feedback
Options Class for e04us

Syntax

C#
public class e04usOptions
Visual Basic
Public Class e04usOptions
Visual C++
public ref class e04usOptions
F#
type e04usOptions =  class end

Description of the Optional Parameters

For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
  • the keywords, where the minimum abbreviation of each keyword is underlined (if no characters of an optional qualifier are underlined, the qualifier may be omitted);
  • a parameter value, where the letters a, i​ and ​r denote options that take character, integer and real values respectively;
  • the default value, where the symbol ε is a generic notation for machine precision (see x02aj), and εr denotes the relative precision of the objective function Function Precision.
Keywords and character values are case and white space insensitive.
Further details of other quantities not explicitly defined in this section may be found by consulting the document for e04uf.
Central Difference Interval
If the algorithm switches to central differences because the forward-difference approximation is not sufficiently accurate, the value of r is used as the difference interval for every element of x. The switch to central differences is indicated by C at the end of each line of intermediate printout produced by the major iterations (see [Description of the Printed Output]). The use of finite differences is discussed further under the optional parameter Difference Interval.
If you supply a value for this optional parameter, a small value between 0.0 and 1.0 is appropriate.
Cold Start
Warm Start
This option controls the specification of the initial working set in both the procedure for finding a feasible point for the linear constraints and bounds, and in the first QP subproblem thereafter. With a Cold Start, the first working set is chosen by e04us based on the values of the variables and constraints at the initial point. Broadly speaking, the initial working set will include equality constraints and bounds or inequality constraints that violate or ‘nearly’ satisfy their bounds (to within Crash Tolerance).
With a Warm Start, you must set the istate array and define clamda and r as discussed in [Parameters]. istate values associated with bounds and linear constraints determine the initial working set of the procedure to find a feasible point with respect to the bounds and linear constraints. istate values associated with nonlinear constraints determine the initial working set of the first QP subproblem after such a feasible point has been found. e04us will override your specification of istate if necessary, so that a poor choice of the working set will not cause a fatal error. For instance, any elements of istate which are set to -2, -1​ or ​4 will be reset to zero, as will any elements which are set to 3 when the corresponding elements of bl and bu are not equal. A Warm Start will be advantageous if a good estimate of the initial working set is available – for example, when e04us is called repeatedly to solve related problems.
Crash Tolerance
This value is used in conjunction with the optional parameter Cold Start (the default value) when e04us selects an initial working set. If 0≤r≤1, the initial working set will include (if possible) bounds or general inequality constraints that lie within r of their bounds. In particular, a constraint of the form ajT x≥l will be included in the initial working set if ajT x-l≤r 1+l. If r<0 or r>1, the default value is used.
Defaults
This special keyword may be used to reset all optional parameters to their default values.
Derivative Level
This parameter indicates which derivatives are provided in user-supplied delegates objfun and confun. The possible choices for i are the following.
i | Meaning
3 | All elements of the objective Jacobian and the constraint Jacobian are provided by you.
2 | All elements of the constraint Jacobian are provided, but some elements of the objective Jacobian are not specified by you.
1 | All elements of the objective Jacobian are provided, but some elements of the constraint Jacobian are not specified by you.
0 | Some elements of both the objective Jacobian and the constraint Jacobian are not specified by you.
The value i=3 should be used whenever possible, since e04us is more reliable (and will usually be more efficient) when all derivatives are exact.
If i=0​ or ​2, e04us will approximate unspecified elements of the objective Jacobian, using finite differences. The computation of finite difference approximations usually increases the total run-time, since a call to objfun is required for each unspecified element. Furthermore, less accuracy can be attained in the solution (see Chapter 8 of Gill et al. (1981), for a discussion of limiting accuracy).
If i=0​ or ​1, e04us will approximate unspecified elements of the constraint Jacobian. One call to confun is needed for each variable for which partial derivatives are not available. For example, if the constraint Jacobian has the form
*****??***?*****
where ‘*’ indicates an element provided by you and ‘?’ indicates an unspecified element, e04us will call confun twice: once to estimate the missing element in column 2, and again to estimate the two missing elements in column 3. (Since columns 1 and 4 are known, they require no calls to confun.)
At times, central differences are used rather than forward differences, in which case twice as many calls to objfun and confun are needed. (The switch to central differences is not under your control.)
If i<0 or i>3, the default value is used.
Difference Interval
This option defines an interval used to estimate derivatives by finite differences in the following circumstances:
(a) | For verifying the objective and/or constraint gradients (see the description of the optional parameter Verify).
(b) | For estimating unspecified elements of the objective and/or constraint Jacobian matrix.
In general, a derivative with respect to the jth variable is approximated using the interval δj, where δj=r 1+x^j, with x^ the first point feasible with respect to the bounds and linear constraints. If the functions are well scaled, the resulting derivative approximation should be accurate to O r. See Gill et al. (1981) for a discussion of the accuracy in finite difference approximations.
If a difference interval is not specified, a finite difference interval will be computed automatically for each variable by a procedure that requires up to six calls of confun and objfun for each element. This option is recommended if the function is badly scaled or you wish to have e04us determine constant elements in the objective and constraint gradients (see the descriptions of confun and objfun in [Parameters]).
If you supply a value for this optional parameter, a small value between 0.0 and 1.0 is appropriate.
Feasibility Tolerance
The scalar r defines the maximum acceptable absolute violations in linear and nonlinear constraints at a ‘feasible’ point; i.e., a constraint is considered satisfied if its violation does not exceed r. If r<ε or r≥1, the default value is used. Using this keyword sets both optional parameters Linear Feasibility Tolerance and Nonlinear Feasibility Tolerance to r, if ε≤r<1. (Additional details are given under the descriptions of these optional parameters.)
Function Precision
This parameter defines εr, which is intended to be a measure of the accuracy with which the problem functions F x and c x can be computed. If r<ε or r≥1, the default value is used.
The value of εr should reflect the relative precision of 1+F x; i.e., εr acts as a relative precision when F is large and as an absolute precision when F is small. For example, if F x is typically of order 1000 and the first six significant digits are known to be correct, an appropriate value for εr would be 10-6. In contrast, if F x is typically of order 10-4 and the first six significant digits are known to be correct, an appropriate value for εr would be 10-10. The choice of εr can be quite complicated for badly scaled problems; see Chapter 8 of Gill et al. (1981) for a discussion of scaling techniques. The default value is appropriate for most simple functions that are computed with full accuracy. However, when the accuracy of the computed function values is known to be significantly worse than full precision, the value of εr should be large enough so that e04us will not attempt to distinguish between function values that differ by less than the error inherent in the calculation.
Hessian
This option controls the contents of the upper triangular matrix R (see [Parameters]). e04us works exclusively with the transformed and reordered Hessian HQ, and hence extra computation is required to form the Hessian itself. If Hessian=NO, r contains the Cholesky factor of the transformed and reordered Hessian. If Hessian=YES, the Cholesky factor of the approximate Hessian itself is formed and stored in r. You should select Hessian=YES if a Warm Start will be used for the next call to e04us.
Infinite Bound Size
If r>0, r defines the ‘infinite’ bound bigbnd in the definition of the problem constraints. Any upper bound greater than or equal to bigbnd will be regarded as +∞ (and similarly any lower bound less than or equal to -bigbnd will be regarded as -∞). If r<0, the default value is used.
Infinite Step Size
If r>0, r specifies the magnitude of the change in variables that is treated as a step to an unbounded solution. If the change in x during an iteration would exceed the value of r, the objective function is considered to be unbounded below in the feasible region. If r≤0, the default value is used.
JTJ Initial Hessian
Unit Initial Hessian
This option controls the initial value of the upper triangular matrix R. If J denotes the objective Jacobian matrix ∇f x, then JT J is often a good approximation to the objective Hessian matrix ∇2 F x (see also optional parameter Reset Frequency).
Line Search Tolerance
The value r (0≤r<1) controls the accuracy with which the step α taken during each iteration approximates a minimum of the merit function along the search direction (the smaller the value of r, the more accurate the linesearch). The default value r=0.9 requests an inaccurate search and is appropriate for most problems, particularly those with any nonlinear constraints.
If there are no nonlinear constraints, a more accurate search may be appropriate when it is desirable to reduce the number of major iterations – for example, if the objective function is cheap to evaluate, or if a substantial number of derivatives are unspecified. If r<0 or r≥1, the default value is used.
Linear Feasibility Tolerance
Nonlinear Feasibility Tolerance
The default value of r 2 is ε 0.33 if Derivative Level=0 or 1, and ε otherwise.
The scalars r 1 and r 2 define the maximum acceptable absolute violations in linear and nonlinear constraints at a ‘feasible’ point; i.e., a linear constraint is considered satisfied if its violation does not exceed r 1, and similarly for a nonlinear constraint and r 2. If rm<ε or rm≥1, the default value is used, for m=1,2.
On entry to e04us, an iterative procedure is executed in order to find a point that satisfies the linear constraints and bounds on the variables to within the tolerance r 1. All subsequent iterates will satisfy the linear constraints to within the same tolerance (unless r 1 is comparable to the finite difference interval).
For nonlinear constraints, the feasibility tolerance r 2 defines the largest constraint violation that is acceptable at an optimal point. Since nonlinear constraints are generally not satisfied until the final iterate, the value of optional parameter Nonlinear Feasibility Tolerance acts as a partial termination criterion for the iterative sequence generated by e04us (see also optional parameter Optimality Tolerance).
These tolerances should reflect the precision of the corresponding constraints. For example, if the variables and the coefficients in the linear constraints are of order unity, and the latter are correct to about 6 decimal digits, it would be appropriate to specify r 1 as 10-6.
List
Nolist
Normally each optional parameter specification is printed as it is supplied. Optional parameter Nolist may be used to suppress the printing and optional parameter List may be used to restore printing.
Major Iteration Limit
Iteration Limit
Iters
Itns
The value of i specifies the maximum number of major iterations allowed before termination. Setting i=0 and Major Print Level>0 means that the workspace needed will be computed and printed, but no iterations will be performed. If i<0, the default value is used.
Major Print Level
Print Level
The value of i controls the amount of printout produced by the major iterations of e04us, as indicated below. A detailed description of the printed output is given in [Description of the Printed Output] (summary output at each major iteration and the final solution) and [Description of Monitoring Information] (monitoring information at each major iteration). (See also the description of the optional parameter Minor Print Level.)
The following printout is sent to the current advisory message unit (as defined by (X04ABF not in this release)):
i | Output
≥0 0 | No output.
≥0 1 | The final solution only.
≥0 5 | One line of summary output (<80 characters; see [Description of the Printed Output]) for each major iteration (no printout of the final solution).
≥10 | The final solution and one line of summary output for each major iteration.
The following printout is sent to the logical unit number defined by the optional parameter Monitoring File:
i | Output
<5 | No output.
≥5 | One long line of output (>80 characters; see [Description of Monitoring Information]) for each major iteration (no printout of the final solution).
≥20 | At each major iteration, the objective function, the Euclidean norm of the nonlinear constraint violations, the values of the nonlinear constraints (the vector c), the values of the linear constraints (the vector AL x), and the current values of the variables (the vector x).
≥30 | At each major iteration, the diagonal elements of the matrix T associated with the TQ factorization (see (5) in e04uf) of the QP working set, and the diagonal elements of R, the triangular factor of the transformed and reordered Hessian (see (6) in e04uf).
If Major Print Level≥5 and the unit number defined by the optional parameter Monitoring File is the same as that defined by (X04ABF not in this release), then the summary output for each major iteration is suppressed.
Minor Iteration Limit
The value of i specifies the maximum number of iterations for finding a feasible point with respect to the bounds and linear constraints (if any). The value of i also specifies the maximum number of minor iterations for the optimality phase of each QP subproblem. If i≤0, the default value is used.
Minor Print Level
The value of i controls the amount of printout produced by the minor iterations of e04us (i.e., the iterations of the quadratic programming algorithm), as indicated below. A detailed description of the printed output is given in [Description of the Printed Output] (summary output at each minor iteration and the final QP solution) and [Description of Monitoring Information] (monitoring information at each minor iteration). (See also the description of the optional parameter Major Print Level.)
The following printout is sent to the current advisory message unit (as defined by (X04ABF not in this release)):
i | Output
≥0 0 | No output.
≥0 1 | The final QP solution only.
≥0 5 | One line of summary output (<80 characters; see [Description of the Printed Output]) for each minor iteration (no printout of the final QP solution).
≥10 | The final QP solution and one line of summary output for each minor iteration.
The following printout is sent to the logical unit number defined by the optional parameter Monitoring File:
i | Output
<5 | No output.
≥5 | One long line of output (>80 characters; see [Description of Monitoring Information]) for each minor iteration (no printout of the final QP solution).
≥20 | At each minor iteration, the current estimates of the QP multipliers, the current estimate of the QP search direction, the QP constraint values, and the status of each QP constraint.
≥30 | At each minor iteration, the diagonal elements of the matrix T associated with the TQ factorization (see (5) in e04uf) of the QP working set, and the diagonal elements of the Cholesky factor R of the transformed Hessian (see (6) in e04uf).
If Minor Print Level≥5 and the unit number defined by the optional parameter Monitoring File is the same as that defined by (X04ABF not in this release), then the summary output for each minor iteration is suppressed.
Monitoring File
If i≥0 and Major Print Level≥5 or i≥0 and Minor Print Level≥5, monitoring information produced by e04us at every iteration is sent to a file with logical unit number i. If i<0 and/or Major Print Level<5 and Minor Print Level<5, no monitoring information is produced.
Optimality Tolerance
The parameter r (εR≤r<1) specifies the accuracy to which you wish the final iterate to approximate a solution of the problem. Broadly speaking, r indicates the number of correct figures desired in the objective function at the solution. For example, if r is 10-6 and e04us terminates successfully, the final value of F should have approximately six correct figures. If r<εR or r≥1, the default value is used.
e04us will terminate successfully if the iterative sequence of x values is judged to have converged and the final point satisfies the first-order Kuhn–Tucker conditions (see [] in e04uf). The sequence of iterates is considered to have converged at x if
α p≤r 1+x, (2)
where p is the search direction and α the step length. An iterate is considered to satisfy the first-order conditions for a minimum if
ZT gFR≤r 1+max 1+F x,gFR (3)
and
resj≤ftol  for all  j, (4)
where ZT gFR is the projected gradient, gFR is the gradient of F x with respect to the free variables, resj is the violation of the jth active nonlinear constraint, and ftol is the Nonlinear Feasibility Tolerance.
Reset Frequency
If i>0, this parameter allows you to reset the approximate Hessian matrix to JT J every i iterations, where J is the objective Jacobian matrix ∇f x (see also the description of the optional parameter JTJ Initial Hessian).
At any point where there are no nonlinear constraints active and the values of f are small in magnitude compared to the norm of J, JT J will be a good approximation to the objective Hessian ∇2 F x. Under these circumstances, frequent resetting can significantly improve the convergence rate of e04us.
Resetting is suppressed at any iteration during which there are nonlinear constraints active.
If i≤0, the default value is used.
Start Objective Check At Variable
Stop Objective Check At Variable
Start Constraint Check At Variable
Stop Constraint Check At Variable
These keywords take effect only if Verify Level>0. They may be used to control the verification of Jacobian elements computed by user-supplied delegates objfun and confun. For example, if the first 30 columns of the objective Jacobian appeared to be correct in an earlier run, so that only column 31 remains questionable, it is reasonable to specify Start Objective Check At Variable=31. If the first 30 variables appear linearly in the subfunctions, so that the corresponding Jacobian elements are constant, the above choice would also be appropriate.
If i 2 m-1≤0 or i 2 m-1>min n,i 2 m, the default value is used, for m=1,2. If i 2 m≤0 or i 2 m>n, the default value is used, for m=1,2.
Step Limit
If r>0,r specifies the maximum change in variables at the first step of the linesearch. In some cases, such as F x=a e bx or F x=a xb, even a moderate change in the elements of x can lead to floating-point overflow. The parameter r is therefore used to encourage evaluation of the problem functions at meaningful points. Given any major iterate x, the first point x~ at which F and c are evaluated during the linesearch is restricted so that
x~-x 2≤r 1+x 2.
The linesearch may go on and evaluate F and c at points further from x if this will result in a lower value of the merit function (indicated by L at the end of each line of output produced by the major iterations; see [Description of the Printed Output]). If L is printed for most of the iterations, r should be set to a larger value.
Wherever possible, upper and lower bounds on x should be used to prevent evaluation of nonlinear functions at wild values. The default value Step Limit=2.0 should not affect progress on well-behaved functions, but values such as 0.1​ or ​0.01 may be helpful when rapidly varying functions are present. If a small value of Step Limit is selected, a good starting point may be required. An important application is to the class of nonlinear least squares problems. If r≤0, the default value is used.
Verify Level
Verify
Verify Constraint Gradients
Verify Gradients
Verify Objective Gradients
These keywords refer to finite difference checks on the gradient elements computed by objfun and confun. (Unspecified gradient elements are not checked.) The possible choices for i are the following:
i | Meaning
-1 | No checks are performed.
-0 | Only a ‘cheap’ test will be performed, requiring one call to objfun.
-1 | Individual gradient elements will also be checked using a reliable (but more expensive) test.
For example, the nonlinear objective gradient (if any) will be verified if either Verify Objective Gradients or Verify Level=1 is specified. Similarly, the objective and the constraint gradients will be verified if Verify=YES or Verify Level=3 or Verify is specified.
If i=-1, no checking will be performed.
If 0≤i≤3, gradients will be verified at the first point that satisfies the linear constraints and bounds. If i=0, only a ‘cheap’ test will be performed, requiring one call to objfun and (if appropriate) one call to confun. If 1≤i≤3, a more reliable (but more expensive) check will be made on individual gradient elements, within the ranges specified by the Start Objective Check At Variable and Stop Objective Check At Variable keywords. A result of the form OK or BAD? is printed by e04us to indicate whether or not each element appears to be correct.
If 10≤i≤13, the action is the same as for i-10, except that it will take place at the user-specified initial value of x.
If i<-1 or 4≤i≤9 or i>13, the default value is used.
We suggest that Verify Level=3 be used whenever a new function method is being developed.

Inheritance Hierarchy

System..::..Object
NagLibrary..::..E04..::..e04usOptions

See Also

E04..::..e04usOptions Members
NagLibrary Namespace
NAG Library Overview
e04us


E04.e04usOptions Members

[image] [image]

NAG Library for .NET Release 2
E04..::..e04usOptions Members
E04..::..e04usOptions Class Constructors Methods Properties See Also Send Feedback

An optimization problem involves minimizing a function (called the objective function) of several variables, possibly subject to restrictions on the values of the variables defined by a set of constraint functions. Most methods in the Library are concerned with function minimization only, since the problem of maximizing a given objective function F(x) is equivalent to minimizing -F x. Some methods allow you to specify whether you are solving a minimization or maximization problem, carrying out the required transformation of the objective function in the latter case.
In general methods in this chapter find a local minimum of a function f, that is a point x* s.t. for all x near x* f x≥f x*.
The E05 class contains methods to find the global minimum of a function f. At a global minimum x* f x≥f x* for all x.
The (H not in this release) contains methods typically regarded as belonging to the field of operations research.
This introduction is only a brief guide to the subject of optimization designed for the casual user. Anyone with a difficult or protracted problem to solve will find it beneficial to consult a more detailed text, such as Gill et al. (1981) or Fletcher (1987).
If you are unfamiliar with the mathematics of the subject you may find some sections difficult at first reading; if so, you should concentrate on [Types of Optimization Problems], [Geometric Representation and Terminology], [Scaling], [Analysis of Computed Results] and [Recommendations on Choice and Use of Available Methods] .

The E04..::..e04usOptions type exposes the following members.

Constructors

Name | Description
E04..::..e04usOptions | Constructor

Methods

Name | Description
Set | Overloaded.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e04us.
Warning | Set the method used for logging any warning or error messages from e04us.

See Also

E04..::..e04usOptions Class


E04.e04usOptions Constructor

[image]

NAG Library for .NET Release 2
E04..::..e04usOptions Constructor
E04..::..e04usOptions Class See Also Send Feedback
Constructor

Syntax

C#
public e04usOptions()
Visual Basic
Public Sub New
Visual C++
public:
e04usOptions()
F#
new : unit -> e04usOptions

See Also

E04..::..e04usOptions Class
E04..::..e04usOptions Members


E04.e04usOptions Methods

[image] [image]

NAG Library for .NET Release 2
E04..::..e04usOptions Methods
E04..::..e04usOptions Class See Also Send Feedback

Methods

Name | Description
Set | Overloaded.

See Also

E04..::..e04usOptions Class


Set Method

[image] [image]

NAG Library for .NET Release 2
E04..::..e04usOptions..::Set Method
E04..::..e04usOptions Class See Also Send Feedback

Overload List

Name | Description
Set(String) | Set an Option for e04us
Set(DataReader) | Set Options for from a DataReader Stream.

See Also

E04..::..e04usOptions Class
E04..::..e04usOptions Members


Set Method (String)

[image]

NAG Library for .NET Release 2
E04..::..e04usOptions..::Set Method (String)
E04..::..e04usOptions Class See Also Send Feedback
Set an Option for e04us

Syntax

C#
public void Set(
    string str
)
Visual Basic
Public Sub Set ( _
    str As String _
)
Visual C++
public:
void Set(
    String^ str
)
F#
member Set :
        str : string -> unit

Parameters

str
Type: System..::..String
A string of the form option = value, or for boolean options, simply option.

See Also

E04..::..e04usOptions Class
E04..::..e04usOptions Members
Set Overload


Set Method (DataReader)

[image]

NAG Library for .NET Release 2
E04..::..e04usOptions..::Set Method (DataReader)
E04..::..e04usOptions Class See Also Send Feedback
Set Options for from a DataReader Stream.

Syntax

C#
public void Set(
    DataReader sr
)
Visual Basic
Public Sub Set ( _
    sr As DataReader _
)
Visual C++
public:
void Set(
    DataReader^ sr
)
F#
member Set :
        sr : DataReader -> unit

Parameters

sr
Type: NagLibrary..::..DataReader
A DataReader Stream, containing an option setting on each line.

See Also

E04..::..e04usOptions Class
E04..::..e04usOptions Members
Set Overload


E04.e04usOptions Properties

[image] [image]

NAG Library for .NET Release 2
E04..::..e04usOptions Properties
E04..::..e04usOptions Class See Also Send Feedback

The E04..::..e04usOptions type exposes the following members.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e04us.
Warning | Set the method used for logging any warning or error messages from e04us.

See Also

E04..::..e04usOptions Class


Message Property

[image]

NAG Library for .NET Release 2
E04..::..e04usOptions..::Message Property
E04..::..e04usOptions Class See Also Send Feedback
Set the method used for logging any monitoring messages from e04us.

Syntax

C#
public PrintManager..::..MessageLogger Message { get; set; }
Visual Basic
Public Property Message As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Message {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Message : PrintManager..::..MessageLogger with get, set

See Also

E04..::..e04usOptions Class
E04..::..e04usOptions Members


Warning Property

[image]

NAG Library for .NET Release 2
E04..::..e04usOptions..::Warning Property
E04..::..e04usOptions Class See Also Send Feedback
Set the method used for logging any warning or error messages from e04us.

Syntax

C#
public PrintManager..::..MessageLogger Warning { get; set; }
Visual Basic
Public Property Warning As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Warning {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Warning : PrintManager..::..MessageLogger with get, set

See Also

E04..::..e04usOptions Class
E04..::..e04usOptions Members


E04.e04vhOptions Class

[image]

NAG Library for .NET Release 2
E04..::..e04vhOptions Class
E04 Class Members See Also Send Feedback
Options Class for e04vh

Syntax

C#
public class e04vhOptions
Visual Basic
Public Class e04vhOptions
Visual C++
public ref class e04vhOptions
F#
type e04vhOptions =  class end

Description of the Optional Parameters

For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
  • the keywords, where the minimum abbreviation of each keyword is underlined (if no characters of an optional qualifier are underlined, the qualifier may be omitted);
  • a parameter value, where the letters a, i​ and ​r denote options that take character, integer and real values respectively;
  • the default value, where the symbol ε is a generic notation for machine precision (see x02aj), and εr denotes the relative precision of the objective function Function Precision, and bigbnd signifies the value of Infinite Bound Size.
Keywords and character values are case and white space insensitive.
Central Difference Interval
When Derivative Option=0, the central-difference interval r is used near an optimal solution to obtain more accurate (but more expensive) estimates of gradients. Twice as many function evaluations are required compared to forward differencing. The interval used for the jth variable is hj=r 1+xj. The resulting derivative estimates should be accurate to O r 2, unless the functions are badly scaled.
If you supply a value for this optional parameter, a small value between 0.0 and 1.0 is appropriate.
Check Frequency
Every ith minor iteration after the most recent basis factorization, a numerical test is made to see if the current solution x satisfies the general linear constraints (the linear constraints and the linearized nonlinear constraints, if any). The constraints are of the form Ax-s=b, where s is the set of slack variables. To perform the numerical test, the residual vector r=b-Ax+s is computed. If the largest component of r is judged to be too large, the current basis is refactorized and the basic variables are recomputed to satisfy the general constraints more accurately. If i≤0, the value of i=99999999 is used and effectively no checks are made.
Check Frequency=1 is useful for debugging purposes, but otherwise this option should not be needed.
Crash Option
Crash Tolerance
Except on restarts, an internal Crash procedure is used to select an initial basis from certain rows and columns of the constraint matrix A-I. The Crash Option i determines which rows and columns of A are eligible initially, and how many times the Crash procedure is called. Columns of -I are used to pad the basis where necessary.
i | Meaning
0 | The initial basis contains only slack variables: B=I.
1 | The Crash procedure is called once, looking for a triangular basis in all rows and columns of A.
2 | The Crash procedure is called twice (if there are nonlinear constraints). The first call looks for a triangular basis in linear rows, and the iteration proceeds with simplex iterations until the linear constraints are satisfied. The Jacobian is then evaluated for the first major iteration and the Crash procedure is called again to find a triangular basis in the nonlinear rows (retaining the current basis for linear rows).
3 | The Crash procedure is called up to three times (if there are nonlinear constraints). The first two calls treat linear equalities and linear inequalities separately. As before, the last call treats nonlinear rows before the first major iteration.
If i≥1, certain slacks on inequality rows are selected for the basis first. (If i≥2, numerical values are used to exclude slacks that are close to a bound). The Crash procedure then makes several passes through the columns of A, searching for a basis matrix that is essentially triangular. A column is assigned to ‘pivot’ on a particular row if the column contains a suitably large element in a row that has not yet been assigned. (The pivot elements ultimately form the diagonals of the triangular basis.) For remaining unassigned rows, slack variables are inserted to complete the basis.
The Crash Tolerance r allows the starting Crash procedure to ignore certain ‘small’ nonzeros in each column of A. If amax is the largest element in column j, other nonzeros of a ij in the columns are ignored if a ij≤amax×r. (To be meaningful, r should be in the range 0≤r<1.)
When r>0.0, the basis obtained by the Crash procedure may not be strictly triangular, but it is likely to be nonsingular and almost triangular. The intention is to obtain a starting basis containing more columns of A and fewer (arbitrary) slacks. A feasible solution may be reached sooner on some problems.
For example, suppose the first m columns of A form the matrix shown under LU Factor Tolerance; i.e., a tridiagonal matrix with entries -1, 4, -1. To help the Crash procedure choose all m columns for the initial basis, we would specify a Crash Tolerance of r for some value of r>0.5.
Defaults
This special keyword may be used to reset all optional parameters to their default values.
Derivative Option
Optional parameter Derivative Option specifies which nonlinear function gradients are known analytically and will be supplied to e04vh by usrfun.
i | Meaning
0 | Some problem derivatives are unknown.
1 | All problem derivatives are known.
The value i=1 should be used whenever possible. It is the most reliable and will usually be the most efficient.
If i=0, e04vh will estimate the missing components of G x using finite differences. This may simplify the coding of usrfun. However, it could increase the total run-time substantially (since a special call to usrfun is required for each column of the Jacobian that has a missing element), and there is less assurance that an acceptable solution will be located. If the nonlinear variables are not well scaled, it may be necessary to specify a nonstandard optional parameter Difference Interval.
For each column of the Jacobian, one call to usrfun is needed to estimate all missing elements in that column, if any.
At times, central differences are used rather than forward differences. Twice as many calls to usrfun are needed. (This is not under your control.)
Derivative Linesearch
Nonderivative Linesearch
At each major iteration a linesearch is used to improve the merit function. Optional parameter Derivative Linesearch uses safeguarded cubic interpolation and requires both function and gradient values to compute estimates of the step αk. If some analytic derivatives are not provided, or optional parameter Nonderivative Linesearch is specified, e04vh employs a linesearch based upon safeguarded quadratic interpolation, which does not require gradient evaluations.
A nonderivative linesearch can be slightly less robust on difficult problems, and it is recommended that the default be used if the functions and derivatives can be computed at approximately the same cost. If the gradients are very expensive relative to the functions, a nonderivative linesearch may give a significant decrease in computation time.
If Nonderivative Linesearch is selected, e04vh signals the evaluation of the linesearch by calling usrfun with needg=0. Once the linesearch is completed, the problem functions are called again with needf=0 and needg=0. If the potential saving provided by a nonderivative linesearch is to be realised, it is essential that usrfun be coded so that derivatives are not computed when needg=0.
Difference Interval
This alters the interval r used to estimate gradients by forward differences. It does so in the following circumstances:
– | in the interval (‘cheap’) phase of verifying the problem derivatives;
– | for verifying the problem derivatives;
– | for estimating missing derivatives.
In all cases, a derivative with respect to xj is estimated by perturbing that component of x to the value xj+r 1+xj, and then evaluating Fobj x or f x at the perturbed point. The resulting gradient estimates should be accurate to O r unless the functions are badly scaled. Judicious alteration of r may sometimes lead to greater accuracy.
If you supply a value for this optional parameter, a small value between 0.0 and 1.0 is appropriate.
Dump File
Load File
Optional parameters Dump File and Load File are similar to optional parameters Punch File and Insert File, but they record solution information in a manner that is more direct and more easily modified. A full description of information recorded in optional parameters Dump File and Load File is given in Gill et al. (2005a).
If i 1>0, the last solution obtained will be output to the file with unit number i 1.
If i 2>0, the Load File, containing basis information, will be read. The file will usually have been output previously as a Dump File. The file will not be accessed if optional parameters Old Basis File or Insert File are specified.
Elastic Weight
This keyword determines the initial weight γ associated with the problem (12) (see [Treatment of Constraint Infeasibilities]).
At major iteration k, if elastic mode has not yet started, a scale factor σk=1+g xk∞ is defined from the current objective gradient. Elastic mode is then started if the QP subproblem is infeasible, or the QP dual variables are larger in magnitude than σk r. The QP is resolved in elastic mode with γ=σk r.
Thereafter, major iterations continue in elastic mode until they converge to a point that is optimal for (12) (see [Treatment of Constraint Infeasibilities]). If the point is feasible for equation (1) v=w=0, it is declared locally optimal. Otherwise, γ is increased by a factor of 10 and major iterations continue. If γ has already reached a maximum allowable value, equation (1) is declared locally infeasible.
Expand Frequency
This option is part of the anti-cycling procedure designed to make progress even on highly degenerate problems.
For linear models, the strategy is to force a positive step at every iteration, at the expense of violating the bounds on the variables by a small amount. Suppose that the optional parameter Minor Feasibility Tolerance is δ. Over a period of i iterations, the tolerance actually used by e04vh increases from 0.5 δ to δ (in steps of 0.5 δ/i).
For nonlinear models, the same procedure is used for iterations in which there is only one superbasic variable. (Cycling can occur only when the current solution is at a vertex of the feasible region.) Thus, zero steps are allowed if there is more than one superbasic variable, but otherwise positive steps are enforced.
Increasing i helps reduce the number of slightly infeasible nonbasic variables (most of which are eliminated during a resetting procedure). However, it also diminishes the freedom to choose a large pivot element (see optional parameter Pivot Tolerance).
Factorization Frequency
At most i basis changes will occur between factorizations of the basis matrix.
With linear programs, the basis factors are usually updated every iteration. The default i is reasonable for typical problems. Higher values up to i=100 (say) may be more efficient on well-scaled problems.
When the objective function is nonlinear, fewer basis updates will occur as an optimum is approached. The number of iterations between basis factorizations will therefore increase. During these iterations a test is made regularly (according to the optional parameter Check Frequency) to ensure that the general constraints are satisfied. If necessary the basis will be refactorized before the limit of i updates is reached.
Function Precision
The relative function precision εr is intended to be a measure of the relative accuracy with which the nonlinear functions can be computed. For example, if f x is computed as 1000.56789 for some relevant x and if the first 6 significant digits are known to be correct, the appropriate value for εr would be 1.0E−6.
Ideally the functions fi x should have magnitude of order 1. If all functions are substantially less than 1 in magnitude, εr should be the absolute precision. For example, if f x=1.23456789E−4 at some point and if the first 6 significant digits are known to be correct, the appropriate value for εr would be 1.0E−10.)
The default value of εr is appropriate for simple analytic functions.
In some cases the function values will be the result of extensive computation, possibly involving a costly iterative procedure that can provide few digits of precision. Specifying an appropriate Function Precision may lead to savings, by allowing the linesearch procedure to terminate when the difference between function values along the search direction becomes as small as the absolute error in the values.
Hessian Full Memory
Hessian Limited Memory
These options select the method for storing and updating the approximate Hessian. (e04vh uses a quasi-Newton approximation to the Hessian of the Lagrangian. A BFGS update is applied after each major iteration.)
If Hessian Full Memory is specified, the approximate Hessian is treated as a dense matrix and the BFGS updates are applied explicitly. This option is most efficient when the number of variables n is not too large (say, less than 75). In this case, the storage requirement is fixed and one can expect 1-step Q-superlinear convergence to the solution.
Hessian Limited Memory should be used on problems where n is very large. In this case a limited-memory procedure is used to update a diagonal Hessian approximation Hr a limited number of times. (Updates are accumulated as a list of vector pairs. They are discarded at regular intervals after Hr has been reset to their diagonal.)
Hessian Frequency
If optional parameter Hessian Full Memory is in effect and i BFGS updates have already been carried out, the Hessian approximation is reset to the identity matrix. (For certain problems, occasional resets may improve convergence, but in general they should not be necessary.)
Hessian Full Memory and Hessian Frequency=10 have a similar effect to Hessian Limited Memory and Hessian Updates=10 (except that the latter retains the current diagonal during resets).
Hessian Updates
If optional parameter Hessian Limited Memory is in effect and i BFGS updates have already been carried out, all but the diagonal elements of the accumulated updates are discarded and the updating process starts again.
Broadly speaking, the more updates stored, the better the quality of the approximate Hessian. However, the more vectors stored, the greater the cost of each QP iteration. The default value is likely to give a robust algorithm without significant expense, but faster convergence can sometimes be obtained with significantly fewer updates (e.g., i=5).
Infinite Bound Size
If r≥0, r defines the ‘infinite’ bound bigbnd in the definition of the problem constraints. Any upper bound greater than or equal to bigbnd will be regarded as +∞ (and similarly any lower bound less than or equal to -bigbnd will be regarded as -∞). If r<0, the default value is used.
Iterations Limit
The value of i specifies the maximum number of minor iterations allowed (i.e., iterations of the simplex method or the QP algorithm), summed over all major iterations. (See also the description of the optional parameter Minor Iterations Limit.)
Linesearch Tolerance
This tolerance, r, controls the accuracy with which a step length will be located along the direction of search each iteration. At the start of each linesearch a target directional derivative for the merit function is identified. This parameter determines the accuracy to which this target value is approximated, and it must be a value in the range 0.0≤r≤1.0.
The default value r=0.9 requests just moderate accuracy in the linesearch.
If the nonlinear functions are cheap to evaluate, a more accurate search may be appropriate; try r=0.1, ​0.01​ or ​0.001.
If the nonlinear functions are expensive to evaluate, a less accurate search may be appropriate. If all gradients are known, try r=0.99. (The number of major iterations might increase, but the total number of function evaluations may decrease enough to compensate.)
If not all gradients are known, a moderately accurate search remains appropriate. Each search will require only 1–5 function values (typically), but many function calls will then be needed to estimate missing gradients for the next iteration.
LU Density Tolerance
LU Singularity Tolerance
The density tolerance, r 1, is used during LU factorization of the basis matrix B. Columns of L and rows of U are formed one at a time, and the remaining rows and columns of the basis are altered appropriately. At any stage, if the density of the remaining matrix exceeds r 1, the Markowitz strategy for choosing pivots is terminated, and the remaining matrix is factored by a dense LU procedure. Raising the density tolerance towards 1.0 may give slightly sparser LU factors, with a slight increase in factorization time.
The singularity tolerance, r 2, helps guard against ill-conditioned basis matrices. After B is refactorized, the diagonal elements of U are tested as follows: if u jj≤r 2 or u jj<r 2 maxi u ij, the jth column of the basis is replaced by the corresponding slack variable. (This is most likely to occur after a restart.)
LU Factor Tolerance
LU Update Tolerance
The values of r 1 and r 2 affect the stability of the basis factorization B=LU, during refactorization and updates respectively. The lower triangular matrix L is a product of matrices of the form
10μ1
where the multipliers μ will satisfy μ≤ri. The default values of r 1 and r 2 usually strike a good compromise between stability and sparsity. They must satisfy r 1, r 2≥1.0.
For large and relatively dense problems, r 1=10.0​ or ​5.0 (say) may give a useful improvement in stability without impairing sparsity to a serious degree.
For certain very regular structures (e.g., band matrices) it may be necessary to reduce r 1​ and/or ​r 2 in order to achieve stability. For example, if the columns of A include a sub-matrix of the form
4-1-14-1-14-1………-14-1-14,
one should set both r 1 and r 2 to values in the range 1.0≤ri<4.0.
LU Partial Pivoting
LU Complete Pivoting
LU Rook Pivoting
The LU factorization implements a Markowitz-type search for pivots that locally minimize the fill-in subject to a threshold pivoting stability criterion. The default option is to use threshhold partial pivoting. The optional parameters LU Rook Pivoting and LU Complete Pivoting are more expensive than partial pivoting but are more stable and better at revealing rank, as long as LU Factor Tolerance is not too large (say <2.0). When numerical difficulties are encountered, e04vh automatically reduces the LU tolerance towards 1.0 and switches (if necessary) to rook or complete pivoting, before reverting to the default or specified options at the next refactorization (with System Information Yes, relevant messages are output to the Print File).
Major Feasibility Tolerance
This tolerance, r, specifies how accurately the nonlinear constraints should be satisfied. The default value is appropriate when the linear and nonlinear constraints contain data to about that accuracy.
Let vmax be the maximum nonlinear constraint violation, normalized by the size of the solution, which is required to satisfy
vmax=maxi vi​ ​/​ ​x≤r, (13)
where vi is the violation of the ith nonlinear constraint, for i=1,2,…,nf.
In the major iteration log (see [Minor Iteration Log]), vmax appears as the quantity labelled ‘Feasible’. If some of the problem functions are known to be of low accuracy, a larger Major Feasibility Tolerance may be appropriate.
Major Optimality Tolerance
This tolerance, r, specifies the final accuracy of the dual variables. On successful termination, e04vh will have computed a solution x,s,π such that
cmax=maxj cj​ ​/​ ​π≤r, (14)
where cj is an estimate of the complementarity slackness for variable j, for j=1,2,…,n+nf. The values ci are computed from the final QP solution using the reduced gradients dj=gj-πT aj (where gj is the jth component of the objective gradient, aj is the associated column of the constraint matrix A-I, and π is the set of QP dual variables):
cj=-dj min xj-lj,1if ​dj≥0;-djmin uj-xj,1if ​dj<0. (15)
In the Print File, cmax appears as the quantity labelled ‘Optimal’.
Major Iterations Limit
This is the maximum number of major iterations allowed. It is intended to guard against an excessive number of linearizations of the constraints. If i=0, optimality and feasibility are checked.
Major Print Level
This controls the amount of output to the optional parameters Print File and Summary File at each major iteration. Major Print Level=0 suppresses most output, except for error messages. Major Print Level=1 gives normal output for linear and nonlinear problems, and Major Print Level=11 gives additional details of the Jacobian factorization that commences each major iteration.
In general, the value being specified may be thought of as a binary number of the form
Major Print Level JFDXbs
where each letter stands for a digit that is either 0 or 1 as follows:
s | a single line that gives a summary of each major iteration. (This entry in JFDXbs is not strictly binary since the summary line is printed whenever JFDXbs≥1);
b | basis statistics, i.e., information relating to the basis matrix whenever it is refactorized. (This output is always provided if JFDXbs≥10);
X | xk, the nonlinear variables involved in the objective function or the constraints. These appear under the heading ‘Jacobian variables’;
D | πk, the dual variables for the nonlinear constraints. These appear under the heading ‘Multiplier estimates’;
F | f xk, the values of the nonlinear constraint functions;
J | J xk, the Jacobian matrix. This appears under the heading ‘x and Jacobian’.
To obtain output of any items JFDXbs, set the corresponding digit to 1, otherwise to 0.
If J=1, the Jacobian matrix will be output column-wise at the start of each major iteration. Column j will be preceded by the value of the corresponding variable xj and a key to indicate whether the variable is basic, superbasic or nonbasic. (Hence if J=1, there is no reason to specify X=1 unless the objective contains more nonlinear variables than the Jacobian.) A typical line of output is
 3 1.250000E+01 BS 1 1.00000E+00 4 2.00000E+00
which would mean that x 3 is basic at value 12.5, and the third column of the Jacobian has elements of 1.0 and 2.0 in rows 1 and 4.
Major Step Limit
This parameter limits the change in x during a linesearch. It applies to all nonlinear problems, once a ‘feasible solution’ or ‘feasible subproblem’ has been found.
1. | A linesearch determines a step α over the range 0<α≤β, where β is 1 if there are nonlinear constraints or is the step to the nearest upper or lower bound on x if all the constraints are linear. Normally, the first step length tried is α 1=min 1,β.
2. | In some cases, such as f x=a e bx or f x=a xb, even a moderate change in the components of x can lead to floating-point overflow. The parameter r is therefore used to define a limit β-=r 1+x/p (where p is the search direction), and the first evaluation of f x is at the potentially smaller step length α 1=min 1,β-,β.
3. | Wherever possible, upper and lower bounds on x should be used to prevent evaluation of nonlinear functions at meaningless points. The optional parameter Major Step Limit provides an additional safeguard. The default value r=2.0 should not affect progress on well behaved problems, but setting r=0.1​ or ​0.01 may be helpful when rapidly varying functions are present. A ‘good’ starting point may be required. An important application is to the class of nonlinear least squares problems.
4. | In cases where several local optima exist, specifying a small value for r may help locate an optimum near the starting point.
Minimize
Maximize
Feasible Point
The keywords Minimize and Maximize specify the required direction of optimization. It applies to both linear and nonlinear terms in the objective.
The keyword Feasible Point means ‘Ignore the objective function, while finding a feasible point for the linear and nonlinear constraints’. It can be used to check that the nonlinear constraints are feasible without altering the call to e04vh.
Minor Feasibility Tolerance
Feasibility Tolerance
e04vh tries to ensure that all variables eventually satisfy their upper and lower bounds to within this tolerance, r. This includes slack variables. Hence, general linear constraints should also be satisfied to within r.
Feasibility with respect to nonlinear constraints is judged by the optional parameter Major Feasibility Tolerance (not by r).
If the bounds and linear constraints cannot be satisfied to within r, the problem is declared infeasible. If sinf is quite small, it may be appropriate to raise r by a factor of 10 or 100. Otherwise, some error in the data should be suspected.
Nonlinear functions will be evaluated only at points that satisfy the bounds and linear constraints. If there are regions where a function is undefined, every attempt should be made to eliminate these regions from the problem.
For example, if f x=x 1+log x 2, it is essential to place lower bounds on both variables. If r=1.0E−6, the bounds x 1≥10-5 and x 2≥10-4 might be appropriate. (The log singularity is more serious. In general, keep x as far away from singularities as possible.)
If Scale Option≥1, feasibility is defined in terms of the scaled problem (since it is then more likely to be meaningful).
In reality, e04vh uses r as a feasibility tolerance for satisfying the bounds on x and s in each QP subproblem. If the sum of infeasibilities cannot be reduced to zero, the QP subproblem is declared infeasible. e04vh is then in elastic mode thereafter (with only the linearized nonlinear constraints defined to be elastic). See the description of the optional parameter Elastic Weight.
Minor Iterations Limit
If the number of minor iterations for the optimality phase of the QP subproblem exceeds i, then all nonbasic QP variables that have not yet moved are frozen at their current values and the reduced QP is solved to optimality.
Note that more than i minor iterations may be necessary to solve the reduced QP to optimality. These extra iterations are necessary to ensure that the terminated point gives a suitable direction for the linesearch.
In the major iteration log (see [Minor Iteration Log]) a t at the end of a line indicates that the corresponding QP was artificially terminated using the limit i.
Compare with the optional parameter Iterations Limit, which defines an independent absolute limit on the total number of minor iterations (summed over all QP subproblems).
Minor Print Level
This controls the amount of output to the Print File and Summary File during solution of the QP subproblems. The value of i has the following effect:
i | Meaning
0 | No minor iteration output except error messages.
≥1 | A single line of output at each minor iteration (controlled by optional parameters Print Frequency and Summary Frequency.
≥10 | Basis factorization statistics generated during the periodic refactorization of the basis (see the optional parameter Factorization Frequency). Statistics for the first factorization each major iteration are controlled by the optional parameter Major Print Level.
New Basis File
Backup Basis File
Save Frequency
New Basis File and Backup Basis File are sometimes referred to as basis maps. They contain the most compact representation of the state of each variable. They are intended for restarting the solution of a problem at a point that was reached by an earlier run. For nontrivial problems, it is advisable to save basis maps at the end of a run, in order to restart the run if necessary.
If i 1>0, a basis map will be saved in the file associated with unit i 1 every i 3th iteration. The first record of the file will contain the word PROCEEDING if the run is still in progress. A basis map will also be saved at the end of a run, with some other word indicating the final solution status.
Use of i 2>0 is intended as a safeguard against losing the results of a long run. Suppose that a New Basis File is being saved every 100 (Save Frequency) iterations, and that e04vh is about to save such a basis at iteration 2000. It is conceivable that the run may be interrupted during the next few milliseconds (in the middle of the save). In this case the Basis file will be corrupted and the run will have been essentially wasted.
To eliminate this risk, both a New Basis File and a Backup Basis File may be specified. The following would be suitable for the above example:
Backup Basis File 11New Basis File 12
The current basis will then be saved every 100 iterations, first in the file associated with unit 12 and then immediately in the file associated with unit 11. If the run is interrupted at iteration 2000 during the save in the file associated with unit 12, there will still be a usable basis in the file associated with unit 11 (corresponding to iteration 1900).
Note that a new basis will be saved in New Basis File at the end of a run if it terminates normally, but it will not be saved in Backup Basis File. In the above example, if an optimum solution is found at iteration 2050 (or if the iteration limit is 2050), the final basis in the file associated with unit 12 will correspond to iteration 2050, but the last basis saved in the file associated with unit 11 will be the one for iteration 2000.
A full description of information recorded in New Basis File and Backup Basis File is given in Gill et al. (2005a).
New Superbasics Limit
This option causes early termination of the QP subproblems if the number of free variables has increased significantly since the first feasible point. If the number of new superbasics is greater than i, the nonbasic variables that have not yet moved are frozen and the resulting smaller QP is solved to optimality.
In the major iteration log (see [Major Iteration Log]), a t at the end of a line indicates that the QP was terminated early in this way.
Nolist
List
For e04vh, normally each optional parameter specification is printed as it is supplied. Optional parameter Nolist may be used to suppress the printing and optional parameter List may be used to turn on printing.
Old Basis File
If i>0, the basis maps information will be obtained from this file. The file will usually have been output previously as a New Basis File or Backup Basis File. A full description of information recorded in New Basis File and Backup Basis File is given in Gill et al. (2005a).
The file will not be acceptable if the number of rows or columns in the problem has been altered.
Partial Price
This parameter is recommended for large problems that have significantly more variables than constraints. It reduces the work required for each ‘pricing’ operation (where a nonbasic variable is selected to become superbasic). When i=1, all columns of the constraint matrix A-I are searched. Otherwise, A and I are partitioned to give i roughly equal segments Aj and Ij, for j=1,2,…,i. If the previous pricing search was successful on A j-1 and I j-1, the next search begins on the segments Aj and Ij. (All subscripts here are modulo i.) If a reduced gradient is found that is larger than some dynamic tolerance, the variable with the largest such reduced gradient (of appropriate sign) is selected to become superbasic. If nothing is found, the search continues on the next segments A j+1 and I j+1, and so on.
For time-stage models having t time periods, Partial Price t (or t/2 or t/3) may be appropriate.
Pivot Tolerance
During the solution of QP subproblems, the pivot tolerance is used to prevent columns entering the basis if they would cause the basis to become almost singular.
When x changes to x+αp for some search direction p, a ‘ratio test’ determines which component of x reaches an upper or lower bound first. The corresponding element of p is called the pivot element. Elements of p are ignored (and therefore cannot be pivot elements) if they are smaller than the pivot tolerance r.
It is common for two or more variables to reach a bound at essentially the same time. In such cases, the Minor Feasibility Tolerance (say, t) provides some freedom to maximize the pivot element and thereby improve numerical stability. Excessively small values of t should therefore not be specified. To a lesser extent, the Expand Frequency (say, f) also provides some freedom to maximize the pivot element. Excessively large values of f should therefore not be specified.
Print File
If i>0, the following information is output to a file associated with unit i during the solution of each problem:
– | a listing of the optional parameters;
– | some statistics about the problem;
– | the amount of storage available for the LU factorization of the basis matrix;
– | notes about the initial basis resulting from a Crash procedure or a Basis file;
– | the iteration log;
– | basis factorization statistics;
– | the exit ifail condition and some statistics about the solution obtained;
– | the printed solution, if requested.
These items are described in [Further Comments] and [Description of Monitoring Information]. Further brief output may be directed to the Summary File.
Print Frequency
If i>0, one line of the iteration log will be printed every ith iteration. A value such as i=10 is suggested for those interested only in the final solution. If i≤0, the value of i=99999999 is used and effectively no checks are made.
Proximal Point Method
i=1​ or ​2 specifies minimization of x-x 0 1 or 12 x-x 0 22 when the starting point x 0 is changed to satisfy the linear constraints (where x 0 refers to nonlinear variables).
Punch File
Insert File
The Punch File from a previous run may be used as an Insert File for a later run on the same problem. A full description of information recorded in Insert File and Punch File is given in Gill et al. (2005a).
If i 1>0, the final solution obtained will be output to the file. For linear programs, this format is compatible with various commercial systems.
If i 2>0 the Insert File containing basis information will be read from unit i 2. The file will usually have been output previously as a Punch File. The file will not be accessed if Old Basis File is specified.
Scale Option
Scale Tolerance
Scale Print
Three scale options are available as follows:
i | Meaning
0 | No scaling. This is recommended if it is known that x and the constraint matrix never have very large elements (say, larger than 100).
1 | The constraints and variables are scaled by an iterative procedure that attempts to make the matrix coefficients as close as possible to 1.0 (see Fourer (1982)). This will sometimes improve the performance of the solution procedures.
2 | The constraints and variables are scaled by the iterative procedure. Also, a certain additional scaling is performed that may be helpful if the right-hand side b or the solution x is large. This takes into account columns of A-I that are fixed or have positive lower bounds or negative upper bounds.
Optional parameter Scale Tolerance affects how many passes might be needed through the constraint matrix. On each pass, the scaling procedure computes the ratio of the largest and smallest nonzero coefficients in each column:
ρj=maxj a ij/mini a ij a ij≠0.
If maxj ρj is less than r times its previous value, another scaling pass is performed to adjust the row and column scales. Raising r from 0.9 to 0.99 (say) usually increases the number of scaling passes through A. At most 10 passes are made. The value of r should lie in the range 0<r<1.
Scale Print causes the row scales r i and column scales c j to be printed to Print File, if System Information Yes has been specified. The scaled matrix coefficients are a-ij=a ij c j/r i, and the scaled bounds on the variables and slacks are l-j=lj/c j, u-j=uj/c j, where c j=r j-n if j>n.
Solution File
If i>0, the final solution will be output to file i (whether optimal or not). All numbers are printed in 1pe16.6 format.
To see more significant digits in the printed solution, it will sometimes be useful to make i refer to Print File.
Summary File
Summary Frequency
If i 1>0, a brief log will be output to the file associated with unit i 1, including one line of information every i 2th iteration. In an interactive environment, it is useful to direct this output to the terminal, to allow a run to be monitored online. (If something looks wrong, the run can be manually terminated.) Further details are given in [The Summary File].
Superbasics Limit
This option places a limit on the storage allocated for superbasic variables. Ideally, i should be set slightly larger than the ‘number of degrees of freedom’ expected at an optimal solution.
For nonlinear problems, the number of degrees of freedom is often called the ‘number of independent variables’. Normally, i need not be greater than n+1, where n 1 is the number of nonlinear variables. For many problems, i may be considerably smaller than n. This will save storage if n is very large.
Suppress Parameters
Normally e04vh prints the options file as it is being read, and then prints a complete list of the available keywords and their final values. The optional parameter Suppress Parameters tells e04vh not to print the full list.
System Information No
System Information Yes
This option prints additional information on the progress of major and minor iterations, and Crash statistics. See [Description of Monitoring Information].
Timing Level
If i>0, some timing information will be output to the Print file, if Print File>0.
Unbounded Objective
Unbounded Step Size
These parameters are intended to detect unboundedness in nonlinear problems. During a linesearch, Fobj is evaluated at points of the form x+αp, where x and p are fixed and α varies. If Fobj exceeds r 1 or α exceeds r 2, iterations are terminated with the exit message ifail=5.
If singularities are present, unboundedness in Fobj x may be manifested by a floating-point overflow (during the evaluation of Fobj x+αp), before the test against r 1 can be made.
Unboundedness in x is best avoided by placing finite upper and lower bounds on the variables.
Verify Level
This option refers to finite difference checks on the derivatives computed by the user-supplied methods. Derivatives are checked at the first point that satisfies all bounds and linear constraints.
i | Meaning
0 | Only a ‘cheap’ test will be performed, requiring two calls to usrfun.
1 | Individual gradients will be checked (with a more reliable test). A key of the form OK or Bad? indicates whether or not each component appears to be correct.
2 | Individual columns of the problem Jacobian will be checked.
3 | Options 2 and 1 will both occur (in that order).
-1 | Derivative checking is disabled.
Verify Level=3 should be specified whenever a new usrfun is being developed.
Violation Limit
This keyword defines an absolute limit on the magnitude of the maximum constraint violation, r, after the linesearch. On completion of the linesearch, the new iterate x k+1 satisfies the condition
vi x k+1≤r​ ​max 1,vi x 0,
where x 0 is the point at which the nonlinear constraints are first evaluated and vi x is the ith nonlinear constraint violation vi x=max 0,li-fi x,fi x-ui.
The effect of this violation limit is to restrict the iterates to lie in an expanded feasible region whose size depends on the magnitude of r. This makes it possible to keep the iterates within a region where the objective is expected to be well-defined and bounded below. If the objective is bounded below for all values of the variables, then r may be any large positive value.

Inheritance Hierarchy

System..::..Object
NagLibrary..::..E04..::..e04vhOptions

See Also

E04..::..e04vhOptions Members
NagLibrary Namespace
NAG Library Overview
e04vh


E04.e04vhOptions Members

[image] [image]

NAG Library for .NET Release 2
E04..::..e04vhOptions Members
E04..::..e04vhOptions Class Constructors Methods Properties See Also Send Feedback

An optimization problem involves minimizing a function (called the objective function) of several variables, possibly subject to restrictions on the values of the variables defined by a set of constraint functions. Most methods in the Library are concerned with function minimization only, since the problem of maximizing a given objective function F(x) is equivalent to minimizing -F x. Some methods allow you to specify whether you are solving a minimization or maximization problem, carrying out the required transformation of the objective function in the latter case.
In general methods in this chapter find a local minimum of a function f, that is a point x* s.t. for all x near x* f x≥f x*.
The E05 class contains methods to find the global minimum of a function f. At a global minimum x* f x≥f x* for all x.
The (H not in this release) contains methods typically regarded as belonging to the field of operations research.
This introduction is only a brief guide to the subject of optimization designed for the casual user. Anyone with a difficult or protracted problem to solve will find it beneficial to consult a more detailed text, such as Gill et al. (1981) or Fletcher (1987).
If you are unfamiliar with the mathematics of the subject you may find some sections difficult at first reading; if so, you should concentrate on [Types of Optimization Problems], [Geometric Representation and Terminology], [Scaling], [Analysis of Computed Results] and [Recommendations on Choice and Use of Available Methods] .

The E04..::..e04vhOptions type exposes the following members.

Constructors

Name | Description
E04..::..e04vhOptions | Constructor

Methods

Name | Description
Set | Overloaded.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e04vh.
Warning | Set the method used for logging any warning or error messages from e04vh.

See Also

E04..::..e04vhOptions Class


E04.e04vhOptions Constructor

[image]

NAG Library for .NET Release 2
E04..::..e04vhOptions Constructor
E04..::..e04vhOptions Class See Also Send Feedback
Constructor

Syntax

C#
public e04vhOptions()
Visual Basic
Public Sub New
Visual C++
public:
e04vhOptions()
F#
new : unit -> e04vhOptions

See Also

E04..::..e04vhOptions Class
E04..::..e04vhOptions Members


E04.e04vhOptions Methods

[image] [image]

NAG Library for .NET Release 2
E04..::..e04vhOptions Methods
E04..::..e04vhOptions Class See Also Send Feedback

Methods

Name | Description
Set | Overloaded.

See Also

E04..::..e04vhOptions Class


Set Method

[image] [image]

NAG Library for .NET Release 2
E04..::..e04vhOptions..::Set Method
E04..::..e04vhOptions Class See Also Send Feedback

Overload List

Name | Description
Set(String) | Set an Option for e04vh
Set(DataReader) | Set Options for from a DataReader Stream.
Set(String, Double) | Set an Option for e04vh
Set(String, Int32) | Set an Option for e04vh

See Also

E04..::..e04vhOptions Class
E04..::..e04vhOptions Members


Set Method (String)

[image]

NAG Library for .NET Release 2
E04..::..e04vhOptions..::Set Method (String)
E04..::..e04vhOptions Class See Also Send Feedback
Set an Option for e04vh

Syntax

C#
public void Set(
    string dnstring
)
Visual Basic
Public Sub Set ( _
    dnstring As String _
)
Visual C++
public:
void Set(
    String^ dnstring
)
F#
member Set :
        dnstring : string -> unit

Parameters

dnstring
Type: System..::..String
A string of the form option = value, or for boolean options, simply option.

See Also

E04..::..e04vhOptions Class
E04..::..e04vhOptions Members
Set Overload


Set Method (DataReader)

[image]

NAG Library for .NET Release 2
E04..::..e04vhOptions..::Set Method (DataReader)
E04..::..e04vhOptions Class See Also Send Feedback
Set Options for from a DataReader Stream.

Syntax

C#
public void Set(
    DataReader sr
)
Visual Basic
Public Sub Set ( _
    sr As DataReader _
)
Visual C++
public:
void Set(
    DataReader^ sr
)
F#
member Set :
        sr : DataReader -> unit

Parameters

sr
Type: NagLibrary..::..DataReader
A DataReader Stream, containing an option setting on each line.

See Also

E04..::..e04vhOptions Class
E04..::..e04vhOptions Members
Set Overload


Set Method (String, Double)

[image]

NAG Library for .NET Release 2
E04..::..e04vhOptions..::Set Method (String, Double)
E04..::..e04vhOptions Class See Also Send Feedback
Set an Option for e04vh

Syntax

C#
public void Set(
    string dnstring,
    double rvalue
)
Visual Basic
Public Sub Set ( _
    dnstring As String, _
    rvalue As Double _
)
Visual C++
public:
void Set(
    String^ dnstring,
    double rvalue
)
F#
member Set :
        dnstring : string *
        rvalue : float -> unit

Parameters

dnstring
Type: System..::..String
The name of an option.
rvalue
Type: System..::..Double
The option value.

See Also

E04..::..e04vhOptions Class
E04..::..e04vhOptions Members
Set Overload


Set Method (String, Int32)

[image]

NAG Library for .NET Release 2
E04..::..e04vhOptions..::Set Method (String, Int32)
E04..::..e04vhOptions Class See Also Send Feedback
Set an Option for e04vh

Syntax

C#
public void Set(
    string dnstring,
    int ivalue
)
Visual Basic
Public Sub Set ( _
    dnstring As String, _
    ivalue As Integer _
)
Visual C++
public:
void Set(
    String^ dnstring,
    int ivalue
)
F#
member Set :
        dnstring : string *
        ivalue : int -> unit

Parameters

dnstring
Type: System..::..String
The name of an option.
ivalue
Type: System..::..Int32
The option value.

See Also

E04..::..e04vhOptions Class
E04..::..e04vhOptions Members
Set Overload


E04.e04vhOptions Properties

[image] [image]

NAG Library for .NET Release 2
E04..::..e04vhOptions Properties
E04..::..e04vhOptions Class See Also Send Feedback

The E04..::..e04vhOptions type exposes the following members.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e04vh.
Warning | Set the method used for logging any warning or error messages from e04vh.

See Also

E04..::..e04vhOptions Class


Message Property

[image]

NAG Library for .NET Release 2
E04..::..e04vhOptions..::Message Property
E04..::..e04vhOptions Class See Also Send Feedback
Set the method used for logging any monitoring messages from e04vh.

Syntax

C#
public PrintManager..::..MessageLogger Message { get; set; }
Visual Basic
Public Property Message As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Message {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Message : PrintManager..::..MessageLogger with get, set

See Also

E04..::..e04vhOptions Class
E04..::..e04vhOptions Members


Warning Property

[image]

NAG Library for .NET Release 2
E04..::..e04vhOptions..::Warning Property
E04..::..e04vhOptions Class See Also Send Feedback
Set the method used for logging any warning or error messages from e04vh.

Syntax

C#
public PrintManager..::..MessageLogger Warning { get; set; }
Visual Basic
Public Property Warning As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Warning {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Warning : PrintManager..::..MessageLogger with get, set

See Also

E04..::..e04vhOptions Class
E04..::..e04vhOptions Members


E04.e04wdOptions Class

[image]

NAG Library for .NET Release 2
E04..::..e04wdOptions Class
E04 Class Members See Also Send Feedback
Options Class for e04wd

Syntax

C#
public class e04wdOptions
Visual Basic
Public Class e04wdOptions
Visual C++
public ref class e04wdOptions
F#
type e04wdOptions =  class end

Description of the Optional Parameters

For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
  • the keywords, where the minimum abbreviation of each keyword is underlined (if no characters of an optional qualifier are underlined, the qualifier may be omitted);
  • a parameter value, where the letters a, i​ and ​r denote options that take character, integer and real values respectively;
  • the default value, where the symbol ε is a generic notation for machine precision (see x02aj), and εr denotes the relative precision of the objective function Function Precision, and bigbnd signifies the value of Infinite Bound Size.
Keywords and character values are case and white space insensitive.
Central Difference Interval
When Derivative Level<3, the central-difference interval r is used near an optimal solution to obtain more accurate (but more expensive) estimates of gradients. Twice as many function evaluations are required compared to forward differencing. The interval used for the jth variable is hj=r 1+xj. The resulting derivative estimates should be accurate to O r 2, unless the functions are badly scaled.
If you supply a value for this optional parameter, a small value between 0.0 and 1.0 is appropriate.
Check Frequency
Every ith minor iteration after the most recent basis factorization, a numerical test is made to see if the current solution x satisfies the general linear constraints (the linear constraints and the linearized nonlinear constraints, if any). The constraints are of the form Ax-s=b, where s is the set of slack variables. To perform the numerical test, the residual vector r=b-Ax+s is computed. If the largest component of r is judged to be too large, the current basis is refactorized and the basic variables are recomputed to satisfy the general constraints more accurately. If i≤0, the value of i=99999999 is used and effectively no checks are made.
Check Frequency=1 is useful for debugging purposes, but otherwise this option should not be needed.
Cold Start
Warm Start
This option controls the specification of the initial working set in the procedure for finding a feasible point for the linear constraints and bounds and in the first QP subproblem thereafter. With a Cold Start, the first working set is chosen by e04wd based on the values of the variables and constraints at the initial point. Broadly speaking, the initial working set will include equality constraints and bounds or inequality constraints that violate or ‘nearly’ satisfy their bounds (to within Crash Tolerance).
With a Warm Start, you must set the istate array and define clamda and h as discussed in [Parameters]. istate values associated with bounds and linear constraints determine the initial working set of the procedure to find a feasible point with respect to the bounds and linear constraints. istate values associated with nonlinear constraints determine the initial working set of the first QP subproblem after such a feasible point has been found. e04wd will override your specification of istate if necessary, so that a poor choice of the working set will not cause a fatal error. For instance, any elements of istate which are set to -2, -1​ or ​4 will be reset to zero, as will any elements which are set to 3 when the corresponding elements of bl and bu are not equal. A warm start will be advantageous if a good estimate of the initial working set is available – for example, when e04wd is called repeatedly to solve related problems.
Crash Option
Crash Tolerance
If a Cold Start is specified, an internal Crash procedure is used to select an initial basis from certain rows and columns of the constraint matrix A-I. The optional parameter Crash Option i determines which rows and columns of A are eligible initially, and how many times the Crash procedure is called. Columns of -I are used to pad the basis where necessary.
i | Meaning
0 | The initial basis contains only slack variables: B=I.
1 | The Crash procedure is called once, looking for a triangular basis in all rows and columns of A.
2 | The Crash procedure is called twice (if there are nonlinear constraints). The first call looks for a triangular basis in linear rows, and the iteration proceeds with simplex iterations until the linear constraints are satisfied. The Jacobian is then evaluated for the first major iteration and the Crash procedure is called again to find a triangular basis in the nonlinear rows (retaining the current basis for linear rows).
3 | The Crash procedure is called up to three times (if there are nonlinear constraints). The first two calls treat linear equalities and linear inequalities separately. As before, the last call treats nonlinear rows before the first major iteration.
If i≥1, certain slacks on inequality rows are selected for the basis first. (If i≥2, numerical values are used to exclude slacks that are close to a bound). The Crash procedure then makes several passes through the columns of A, searching for a basis matrix that is essentially triangular. A column is assigned to ‘pivot’ on a particular row if the column contains a suitably large element in a row that has not yet been assigned. (The pivot elements ultimately form the diagonals of the triangular basis.) For remaining unassigned rows, slack variables are inserted to complete the basis.
The Crash Tolerance r allows the starting Crash procedure to ignore certain ‘small’ nonzeros in each column of A. If amax is the largest element in column j, other nonzeros of a ij in the columns are ignored if a ij≤amax×r. (To be meaningful, r must be in the range 0≤r<1.)
When r>0.0, the basis obtained by the Crash procedure may not be strictly triangular, but it is likely to be nonsingular and almost triangular. The intention is to obtain a starting basis containing more columns of A and fewer (arbitrary) slacks. A feasible solution may be reached sooner on some problems.
For example, suppose the first m columns of A form the matrix shown under LU Factor Tolerance; i.e., a tridiagonal matrix with entries -1, 4, -1. To help the Crash procedure choose all m columns for the initial basis, we would specify a Crash Tolerance of r for some value of r>0.5.
Defaults
This special keyword may be used to reset all optional parameters to their default values.
Derivative Level
Optional parameter Derivative Level specifies which nonlinear function gradients are known analytically and will be supplied to e04wd by user-supplied delegates objfun and confun.
i | Meaning
3 | All objective and constraint gradients are known.
2 | All constraint gradients are known, but some or all components of the objective gradient are unknown.
1 | The objective gradient is known, but some or all of the constraint gradients are unknown.
0 | Some components of the objective gradient are unknown and some of the constraint gradients are unknown.
The value i=3 should be used whenever possible. It is the most reliable and will usually be the most efficient.
If i=0 or 2, e04wd will estimate the missing components of the objective gradient, using finite differences. This may simplify the coding of objfun. However, it could increase the total run-time substantially (since a special call to objfun is required for each missing element), and there is less assurance that an acceptable solution will be located. If the nonlinear variables are not well scaled, it may be necessary to specify a non-default optional parameter Difference Interval.
If i=0 or 1, e04wd will estimate missing elements of the Jacobian. For each column of the Jacobian, one call to confun is needed to estimate all missing elements in that column, if any.
At times, central differences are used rather than forward differences. (This is not under your control.)
Derivative Linesearch
Nonderivative Linesearch
At each major iteration a linesearch is used to improve the merit function. Optional parameter Derivative Linesearch uses safeguarded cubic interpolation and requires both function and gradient values to compute estimates of the step αk. If some analytic derivatives are not provided, or optional parameter Nonderivative Linesearch is specified, e04wd employs a linesearch based upon safeguarded quadratic interpolation, which does not require gradient evaluations.
A nonderivative linesearch can be slightly less robust on difficult problems, and it is recommended that the default be used if the functions and derivatives can be computed at approximately the same cost. If the gradients are very expensive relative to the functions, a nonderivative linesearch may give a significant decrease in computation time.
If Nonderivative Linesearch is selected, e04wd signals the evaluation of the linesearch by calling objfun with mode=0. If the potential saving provided by a nonderivative linesearch is to be realised, it is essential that objfun be coded so that derivatives are not computed when mode=0.
Difference Interval
This alters the interval r used to estimate gradients by forward differences. It does so in the following circumstances:
– | in the interval (‘cheap’) phase of verifying the problem derivatives;
– | for verifying the problem derivatives;
– | for estimating missing derivatives.
In all cases, a derivative with respect to xj is estimated by perturbing that component of x to the value xj+r 1+xj, and then evaluating F x or c x at the perturbed point. The resulting gradient estimates should be accurate to O r unless the functions are badly scaled. Judicious alteration of r may sometimes lead to greater accuracy.
If you supply a value for this optional parameter, a small value between 0.0 and 1.0 is appropriate.
Dump File
Load File
Optional parameters Dump File and Load File are similar to optional parameters Punch File and Insert File, but they record solution information in a manner that is more direct and more easily modified. A full description of information recorded in optional parameters Dump File and Load File is given in Gill et al. (2005a).
If i 1>0, the last solution obtained will be output to the file with unit number i 1.
If i 2>0, the Load File, containing basis information, will be read. The file will usually have been output previously as a Dump File. The file will not be accessed if optional parameters Old Basis File or Insert File are specified.
Elastic Weight
This keyword determines the initial weight γ associated with the problem (11) (see [Treatment of Constraint Infeasibilities]).
At major iteration k, if elastic mode has not yet started, a scale factor σk=1+g xk∞ is defined from the current objective gradient. Elastic mode is then started if the QP subproblem is infeasible, or the QP dual variables are larger in magnitude than σk r. The QP is resolved in elastic mode with γ=σk r.
Thereafter, major iterations continue in elastic mode until they converge to a point that is optimal for (11) (see [Treatment of Constraint Infeasibilities]). If the point is feasible for equation (1) v=w=0, it is declared locally optimal. Otherwise, γ is increased by a factor of 10 and major iterations continue. If γ has already reached a maximum allowable value, equation (1) is declared locally infeasible.
Expand Frequency
This option is part of the anti-cycling procedure designed to make progress even on highly degenerate problems.
For linear models, the strategy is to force a positive step at every iteration, at the expense of violating the bounds on the variables by a small amount. Suppose that the optional parameter Minor Feasibility Tolerance is δ. Over a period of i iterations, the tolerance actually used by e04wd increases from 0.5 δ to δ (in steps of 0.5 δ/i).
For nonlinear models, the same procedure is used for iterations in which there is only one superbasic variable. (Cycling can occur only when the current solution is at a vertex of the feasible region.) Thus, zero steps are allowed if there is more than one superbasic variable, but otherwise positive steps are enforced.
Increasing i helps reduce the number of slightly infeasible nonbasic variables (most of which are eliminated during a resetting procedure). However, it also diminishes the freedom to choose a large pivot element (see optional parameter Pivot Tolerance).
Factorization Frequency
At most i basis changes will occur between factorizations of the basis matrix.
With linear programs, the basis factors are usually updated every iteration. The default i is reasonable for typical problems. Higher values up to i=100 (say) may be more efficient on well-scaled problems.
When the objective function is nonlinear, fewer basis updates will occur as an optimum is approached. The number of iterations between basis factorizations will therefore increase. During these iterations a test is made regularly (according to the optional parameter Check Frequency) to ensure that the general constraints are satisfied. If necessary the basis will be refactorized before the limit of i updates is reached.
Function Precision
The relative function precision εr is intended to be a measure of the relative accuracy with which the functions can be computed. For example, if F x is computed as 1000.56789 for some relevant x and if the first 6 significant digits are known to be correct, the appropriate value for εr would be 1.0E−6.
(Ideally the functions F x or ci x should have magnitude of order 1. If all functions are substantially less than 1 in magnitude, εr should be the absolute precision. For example, if F x=1.23456789E−4 at some point and if the first 6 significant digits are known to be correct, the appropriate value for εr would be 1.0E−10.)
The default value of εr is appropriate for simple analytic functions.
In some cases the function values will be the result of extensive computation, possibly involving a costly iterative procedure that can provide few digits of precision. Specifying an appropriate Function Precision may lead to savings, by allowing the linesearch procedure to terminate when the difference between function values along the search direction becomes as small as the absolute error in the values.
Hessian Full Memory
Hessian Limited Memory
These options select the method for storing and updating the approximate Hessian. (e04wd uses a quasi-Newton approximation to the Hessian of the Lagrangian. A BFGS update is applied after each major iteration.)
If Hessian Full Memory is specified, the approximate Hessian is treated as a dense matrix and the BFGS updates are applied explicitly. This option is most efficient when the number of variables n is not too large (say, less than 75). In this case, the storage requirement is fixed and one can expect 1-step Q-superlinear convergence to the solution.
Hessian Limited Memory should be used on problems where n is very large. In this case a limited-memory procedure is used to update a diagonal Hessian approximation Hr a limited number of times. (Updates are accumulated as a list of vector pairs. They are discarded at regular intervals after Hr has been reset to their diagonal.)
Hessian Frequency
If optional parameter Hessian Full Memory is in effect and i BFGS updates have already been carried out, the Hessian approximation is reset to the identity matrix. (For certain problems, occasional resets may improve convergence, but in general they should not be necessary.)
Hessian Full Memory and Hessian Frequency=10 have a similar effect to Hessian Limited Memory and Hessian Updates=10 (except that the latter retains the current diagonal during resets).
Hessian Updates
If optional parameter Hessian Limited Memory is in effect and i BFGS updates have already been carried out, all but the diagonal elements of the accumulated updates are discarded and the updating process starts again.
Broadly speaking, the more updates stored, the better the quality of the approximate Hessian. However, the more vectors stored, the greater the cost of each QP iteration. The default value is likely to give a robust algorithm without significant expense, but faster convergence can sometimes be obtained with significantly fewer updates (e.g., i=5).
Infinite Bound Size
If r>0, r defines the ‘infinite’ bound bigbnd in the definition of the problem constraints. Any upper bound greater than or equal to bigbnd will be regarded as +∞ (and similarly any lower bound less than or equal to -bigbnd will be regarded as -∞). If r<0, the default value is used.
Iterations Limit
The value of i specifies the maximum number of minor iterations allowed (i.e., iterations of the simplex method or the QP algorithm), summed over all major iterations. (See also the description of the optional parameter Minor Iterations Limit.)
Linesearch Tolerance
This tolerance, r, controls the accuracy with which a step length will be located along the direction of search each iteration. At the start of each linesearch a target directional derivative for the merit function is identified. This parameter determines the accuracy to which this target value is approximated, and it must be a value in the range 0.0≤r≤1.0.
The default value r=0.9 requests just moderate accuracy in the linesearch.
If the nonlinear functions are cheap to evaluate, a more accurate search may be appropriate; try r=0.1, ​0.01​ or ​0.001.
If the nonlinear functions are expensive to evaluate, a less accurate search may be appropriate. If all gradients are known, try r=0.99. (The number of major iterations might increase, but the total number of function evaluations may decrease enough to compensate.)
If not all gradients are known, a moderately accurate search remains appropriate. Each search will require only 1–5 function values (typically), but many function calls will then be needed to estimate missing gradients for the next iteration.
Nolist
List
For e04wd, normally each optional parameter specification is printed as it is supplied. Optional parameter Nolist may be used to suppress the printing and optional parameter List may be used to turn on printing.
LU Density Tolerance
LU Singularity Tolerance
The density tolerance, r 1, is used during LU factorization of the basis matrix B. Columns of L and rows of U are formed one at a time, and the remaining rows and columns of the basis are altered appropriately. At any stage, if the density of the remaining matrix exceeds r 1, the Markowitz strategy for choosing pivots is terminated, and the remaining matrix is factored by a dense LU procedure. Raising the density tolerance towards 1.0 may give slightly sparser LU factors, with a slight increase in factorization time.
The singularity tolerance, r 2, helps guard against ill-conditioned basis matrices. After B is refactorized, the diagonal elements of U are tested as follows: if u jj≤r 2 or u jj<r 2 maxi u ij, the jth column of the basis is replaced by the corresponding slack variable. (This is most likely to occur after a restart.)
LU Factor Tolerance
LU Update Tolerance
The values of r 1 and r 2 affect the stability of the basis factorization B=LU, during refactorization and updates respectively. The lower triangular matrix L is a product of matrices of the form
10μ1
where the multipliers μ will satisfy μ≤ri. The default values of r 1 and r 2 usually strike a good compromise between stability and sparsity. They must satisfy r 1, r 2≥1.0.
For large and relatively dense problems, r 1=10.0​ or ​5.0 (say) may give a useful improvement in stability without impairing sparsity to a serious degree.
For certain very regular structures (e.g., band matrices) it may be necessary to reduce r 1​ and/or ​r 2 in order to achieve stability. For example, if the columns of A include a sub-matrix of the form
4-1-14-1-14-1………-14-1-14,
one should set both r 1 and r 2 to values in the range 1.0≤ri<4.0.
LU Partial Pivoting
LU Complete Pivoting
LU Rook Pivoting
The LU factorization implements a Markowitz-type search for pivots that locally minimize the fill-in subject to a threshold pivoting stability criterion. The default option is to use threshhold partial pivoting. The optional parameters LU Rook Pivoting and LU Complete Pivoting are more expensive than partial pivoting but are more stable and better at revealing rank, as long as LU Factor Tolerance is not too large (say <2.0). When numerical difficulties are encountered, e04wd automatically reduces the LU tolerance towards 1.0 and switches (if necessary) to rook or complete pivoting, before reverting to the default or specified options at the next refactorization (with System Information Yes, relevant messages are output to the Print File).
Major Feasibility Tolerance
This tolerance, r, specifies how accurately the nonlinear constraints should be satisfied. The default value is appropriate when the linear and nonlinear constraints contain data to about that accuracy.
Let vmax be the maximum nonlinear constraint violation, normalized by the size of the solution, which is required to satisfy
vmax/=maxi vi/x≤r, (12)
where vi is the violation of the ith nonlinear constraint i=1:nL.
In the major iteration log (see [Minor Iteration Log], vmax appears as the quantity labelled ‘Feasible’. If some of the problem functions are known to be of low accuracy, a larger Major Feasibility Tolerance may be appropriate.
Major Optimality Tolerance
This tolerance, r, specifies the final accuracy of the dual variables. On successful termination, e04wd will have computed a solution x,s,π such that
cmax=maxj cj/π≤r, (13)
where cj is an estimate of the complementarity slackness for variable j where j=1:n+nL+nN. The values ci are computed from the final QP solution using the reduced gradients dj=gj-πT aj (where gj is the jth component of the objective gradient, aj is the associated column of the constraint matrix A-I, and π is the set of QP dual variables):
cj=-dj min xj-lj,1if ​dj≥0;-djmin uj-xj,1if ​dj<0. (14)
In the Print File, cmax appears as the quantity labelled ‘Optimal’.
Major Iterations Limit
This is the maximum number of major iterations allowed. It is intended to guard against an excessive number of linearizations of the constraints. If i=0, optimality and feasibility are checked.
Major Print Level
This controls the amount of output to the optional parameters Print File and Summary File at each major iteration. Major Print Level=0 suppresses most output, except for error messages. Major Print Level=1 gives normal output for linear and nonlinear problems, and Major Print Level=11 gives additional details of the Jacobian factorization that commences each major iteration.
In general, the value being specified may be thought of as a binary number of the form
Major Print Level JFDXbs
where each letter stands for a digit that is either 0 or 1 as follows:
s | a single line that gives a summary of each major iteration. (This entry in JFDXbs is not strictly binary since the summary line is printed whenever JFDXbs≥1);
b | basis statistics, i.e., information relating to the basis matrix whenever it is refactorized. (This output is always provided if JFDXbs≥10);
X | xk, the nonlinear variables involved in the objective function or the constraints. These appear under the heading ‘Jacobian variables’;
D | πk, the dual variables for the nonlinear constraints. These appear under the heading ‘Multiplier estimates’;
F | c xk, the values of the nonlinear constraint functions;
J | J xk, the Jacobian matrix. This appears under the heading ‘x and Jacobian’.
To obtain output of any items JFDXbs, set the corresponding digit to 1, otherwise to 0.
If J=1, the Jacobian matrix will be output column-wise at the start of each major iteration. Column j will be preceded by the value of the corresponding variable xj and a key to indicate whether the variable is basic, superbasic or nonbasic. (Hence if J=1, there is no reason to specify X=1 unless the objective contains more nonlinear variables than the Jacobian.) A typical line of output is
 3 1.250000E+01 BS 1 1.00000E+00 4 2.00000E+00
which would mean that x 3 is basic at value 12.5, and the third column of the Jacobian has elements of 1.0 and 2.0 in rows 1 and 4.
Major Step Limit
This parameter limits the change in x during a linesearch. It applies to all nonlinear problems, once a ‘feasible solution’ or ‘feasible subproblem’ has been found. A linesearch determines a step α over the range 0<α≤β, where β is 1 if there are nonlinear constraints, or is the step to the nearest upper or lower bound on x if all the constraints are linear. Normally, the first step length tried is α 1=min 1,β.
1. | In some cases, such as f x=a e bx or f x=a xb, even a moderate change in the components of x can lead to floating-point overflow. The parameter r is therefore used to define a limit β-=r 1+x/p (where p is the search direction), and the first evaluation of f x is at the potentially smaller step length α 1=min 1,β-,β.
2. | Wherever possible, upper and lower bounds on x should be used to prevent evaluation of nonlinear functions at meaningless points. The optional parameter Major Step Limit provides an additional safeguard. The default value r=2.0 should not affect progress on well behaved problems, but setting r=0.1​ or ​0.01 may be helpful when rapidly varying functions are present. A ‘good’ starting point may be required. An important application is to the class of nonlinear least squares problems.
3. | In cases where several local optima exist, specifying a small value for r may help locate an optimum near the starting point.
Minimize
Maximize
Feasible Point
The keywords Minimize and Maximize specify the required direction of optimization. It applies to both linear and nonlinear terms in the objective.
The keyword Feasible Point means ‘Ignore the objective function, while finding a feasible point for the linear and nonlinear constraints’. It can be used to check that the nonlinear constraints are feasible without altering the call to e04wd.
Minor Feasibility Tolerance
Feasibility Tolerance
e04wd tries to ensure that all variables eventually satisfy their upper and lower bounds to within this tolerance, r. This includes slack variables. Hence, general linear constraints should also be satisfied to within r.
Feasibility with respect to nonlinear constraints is judged by the optional parameter Major Feasibility Tolerance (not by r).
If the bounds and linear constraints cannot be satisfied to within r, the problem is declared infeasible. If the corresponding sum of infeasibilities is quite small, it may be appropriate to raise r by a factor of 10 or 100. Otherwise, some error in the data should be suspected.
Nonlinear functions will be evaluated only at points that satisfy the bounds and linear constraints. If there are regions where a function is undefined, every attempt should be made to eliminate these regions from the problem.
For example, if f x=x 1+log x 2, it is essential to place lower bounds on both variables. If r=1.0E−6, the bounds x 1≥10-5 and x 2≥10-4 might be appropriate. (The log singularity is more serious. In general, keep x as far away from singularities as possible.)
If Scale Option≥1, feasibility is defined in terms of the scaled problem (since it is then more likely to be meaningful).
In reality, e04wd uses r as a feasibility tolerance for satisfying the bounds on x and s in each QP subproblem. If the sum of infeasibilities cannot be reduced to zero, the QP subproblem is declared infeasible. e04wd is then in elastic mode thereafter (with only the linearized nonlinear constraints defined to be elastic). See the description of the optional parameter Elastic Weight.
Minor Iterations Limit
If the number of minor iterations for the optimality phase of the QP subproblem exceeds i, then all nonbasic QP variables that have not yet moved are frozen at their current values and the reduced QP is solved to optimality.
Note that more than i minor iterations may be necessary to solve the reduced QP to optimality. These extra iterations are necessary to ensure that the terminated point gives a suitable direction for the linesearch.
In the major iteration log (see [Minor Iteration Log]) a t at the end of a line indicates that the corresponding QP was artificially terminated using the limit i.
Compare with the optional parameter Iterations Limit, which defines an independent absolute limit on the total number of minor iterations (summed over all QP subproblems).
Minor Print Level
This controls the amount of output to the Print File and the Summary File during solution of the QP subproblems. The value of i has the following effect:
i | Output
0 | No minor iteration output except error messages.
≥1 | A single line of output at each minor iteration (controlled by optional parameters Print Frequency and Summary Frequency.
≥10 | Basis factorization statistics generated during the periodic refactorization of the basis (see the optional parameter Factorization Frequency). Statistics for the first factorization each major iteration are controlled by the optional parameter Major Print Level.
New Basis File
Backup Basis File
Save Frequency
New Basis File and Backup Basis File are sometimes referred to as basis maps. They contain the most compact representation of the state of each variable. They are intended for restarting the solution of a problem at a point that was reached by an earlier run. For nontrivial problems, it is advisable to save basis maps at the end of a run, in order to restart the run if necessary.
If i 1>0, a basis map will be saved on the file associated with unit i 1 every i 3th iteration. The first record of the file will contain the word PROCEEDING if the run is still in progress. A basis map will also be saved at the end of a run, with some other word indicating the final solution status.
Use of i 2>0 is intended as a safeguard against losing the results of a long run. Suppose that a New Basis File is being saved every 100 (Save Frequency) iterations, and that e04wd is about to save such a basis at iteration 2000. It is conceivable that the run may be interrupted during the next few milliseconds (in the middle of the save). In this case the Basis file will be corrupted and the run will have been essentially wasted.
To eliminate this risk, both a New Basis File and a Backup Basis File may be specified. The following would be suitable for the above example:
 Backup Basis File 11
 New Basis File 12
The current basis will then be saved every 100 iterations, first on the file associated with unit 12 and then immediately on the file associated with unit 11. If the run is interrupted at iteration 2000 during the save on the file associated with unit 12, there will still be a usable basis on the file associated with unit 11 (corresponding to iteration 1900).
Note that a new basis will be saved in New Basis File at the end of a run if it terminates normally, but it will not be saved in Backup Basis File. In the above example, if an optimum solution is found at iteration 2050 (or if the iteration limit is 2050), the final basis in the file associated with unit 12 will correspond to iteration 2050, but the last basis saved in the file associated with unit 11 will be the one for iteration 2000.
A full description of information recorded in New Basis File and Backup Basis File is given in Gill et al. (2005a).
New Superbasics Limit
This option causes early termination of the QP subproblems if the number of free variables has increased significantly since the first feasible point. If the number of new superbasics is greater than i, the nonbasic variables that have not yet moved are frozen and the resulting smaller QP is solved to optimality.
In the major iteration log (see [Major Iteration Log]), a t at the end of a line indicates that the QP was terminated early in this way.
Old Basis File
If i>0, the basis maps information will be obtained from this file. The file will usually have been output previously as a New Basis File or Backup Basis File. A full description of information recorded in New Basis File and Backup Basis File is given in Gill et al. (2005a).
The file will not be acceptable if the number of rows or columns in the problem has been altered.
Partial Price
This parameter is recommended for large problems that have significantly more variables than constraints. It reduces the work required for each ‘pricing’ operation (where a nonbasic variable is selected to become superbasic). When i=1, all columns of the constraint matrix A-I are searched. Otherwise, A and I are partitioned to give i roughly equal segments Aj and Ij, for j=1,2,…,i. If the previous pricing search was successful on A j-1 and I j-1, the next search begins on the segments Aj and Ij. (All subscripts here are modulo i.) If a reduced gradient is found that is larger than some dynamic tolerance, the variable with the largest such reduced gradient (of appropriate sign) is selected to become superbasic. If nothing is found, the search continues on the next segments A j+1 and I j+1, and so on.
For time-stage models having t time periods, Partial Price t (or t/2 or t/3) may be appropriate.
Pivot Tolerance
During the solution of QP subproblems, the pivot tolerance is used to prevent columns entering the basis if they would cause the basis to become almost singular.
When x changes to x+αp for some search direction p, a ‘ratio test’ determines which component of x reaches an upper or lower bound first. The corresponding element of p is called the pivot element. Elements of p are ignored (and therefore cannot be pivot elements) if they are smaller than the pivot tolerance r.
It is common for two or more variables to reach a bound at essentially the same time. In such cases, the Minor Feasibility Tolerance (say, t) provides some freedom to maximize the pivot element and thereby improve numerical stability. Excessively small values of t should therefore not be specified. To a lesser extent, the Expand Frequency (say, f) also provides some freedom to maximize the pivot element. Excessively large values of f should therefore not be specified.
Print File
If i>0, the following information is output to a file associated with unit i during the solution of each problem:
– | a listing of the optional parameters;
– | some statistics about the problem;
– | the amount of storage available for the LU factorization of the basis matrix;
– | notes about the initial basis resulting from a Crash procedure or a Basis file;
– | the iteration log;
– | basis factorization statistics;
– | the exit ifail condition and some statistics about the solution obtained;
– | the printed solution, if requested.
These items are described in [Further Comments] and [Description of Monitoring Information]. Further brief output may be directed to the Summary File.
Print Frequency
If i>0, one line of the iteration log will be printed every ith iteration. A value such as i=10 is suggested for those interested only in the final solution. If i≤0, the value of i=99999999 is used and effectively no checks are made.
Proximal Point Method
i=1​ or ​2 specifies minimization of x-x 0 1 or 12 x-x 0 22 when the starting point x 0 is changed to satisfy the linear constraints (where x 0 refers to nonlinear variables).
Punch File
Insert File
The Punch File from a previous run may be used as an Insert File for a later run on the same problem. A full description of information recorded in Insert File and Punch File is given in Gill et al. (2005a).
If i 1>0, the final solution obtained will be output to the file. For linear programs, this format is compatible with various commercial systems.
If i 2>0 the Insert File containing basis information will be read from unit i 2. The file will usually have been output previously as a Punch File. The file will not be accessed if Old Basis File is specified.
QPSolver Cholesky
QPSolver CG
QPSolver QN
Specifies the active-set algorithm used to solve subproblem (11) (see [Treatment of Constraint Infeasibilities]). QPSolver Cholesky holds the full Cholesky factor R of the reduced Hessian ZT HZ. As the QP iterations proceed, the dimension of R changes with the number of superbasic variables. If the number of superbasic variables needs to increase beyond the value of Reduced Hessian Dimension, the reduced Hessian cannot be stored and the solver switches to QPSolver CG. The Cholesky solver is reactivated if the number of superbasics stabilizes at a value less than Reduced Hessian Dimension.
QPSolver QN solves the QP using a quasi-Newton method. In this case, R is the factor of a quasi-Newton approximate Hessian.
QPSolver CG uses an active-set method similar to QPSolver QN, but uses the conjugate-gradient method to solve all systems involving the reduced Hessian.
The Cholesky QP solver is the most robust, but may require a significant amount of computation if there are many superbasics.
The quasi-Newton QP solver does not require computation of the exact R at the start of the subproblem in (11). It may be appropriate when the number of superbasics is large but relatively few iterations are needed to reach a solution (e.g., if e04wd is called with a Warm Start).
The conjugate-gradient QP solver is appropriate for problems with many degrees of freedom (say, more than 2000 superbasics).
Reduced Hessian Dimension
This specifies that an i by i triangular matrix R (to define the reduced Hessian according to RT R=ZT HZ) is to be available for use by the Cholesky QP solver.
Scale Option
Scale Tolerance
Scale Print
Three scale options are available as follows:
i | Meaning
0 | No scaling. This is recommended if it is known that x and the constraint matrix never have very large elements (say, larger than 100).
1 | The constraints and variables are scaled by an iterative procedure that attempts to make the matrix coefficients as close as possible to 1.0 (see Fourer (1982)). This will sometimes improve the performance of the solution procedures.
2 | The constraints and variables are scaled by the iterative procedure. Also, a certain additional scaling is performed that may be helpful if the right-hand side b or the solution x is large. This takes into account columns of A-I that are fixed or have positive lower bounds or negative upper bounds.
Optional parameter Scale Tolerance affects how many passes might be needed through the constraint matrix. On each pass, the scaling procedure computes the ratio of the largest and smallest nonzero coefficients in each column:
ρj=maxj a ij/mini a ij a ij≠0.
If maxj ρj is less than r times its previous value, another scaling pass is performed to adjust the row and column scales. Raising r from 0.9 to 0.99 (say) usually increases the number of scaling passes through A. At most 10 passes are made. The value of r should lie in the range 0<r<1.
Scale Print causes the row scales r i and column scales c j to be printed to Print File, if System Information Yes has been specified. The scaled matrix coefficients are a-ij=a ij c j/r i, and the scaled bounds on the variables and slacks are l-j=lj/c j, u-j=uj/c j, where c j=r j-n if j>n.
Solution File
If i>0, the final solution will be output to file i (whether optimal or not). All numbers are printed in 1pe16.6 format.
To see more significant digits in the printed solution, it will sometimes be useful to make i refer to Print File.
Start Objective Check At Variable
Stop Objective Check At Variable
Start Constraint Check At Variable
Stop Constraint Check At Variable
These keywords take effect only if Verify Level>0. They may be used to contol the verification of gradient elements computed by function objfun and/or Jacobian elements computed by function confun. For eample, if the first 30 elements of the objective gradient appeared to be correct in an earlier run, so that only element 31 remains questionable, it is reasonable to specify Start Objective Check At Variable=31. If the first 30 variables appear linearly in the objective, so that the corresponding gradient elements are constant, the above choice would also be appropriate.
Summary File
Summary Frequency
If i 1>0, a brief log will be output to the file associated with unit i 1, including one line of information every i 2th iteration. In an interactive environment, it is useful to direct this output to the terminal, to allow a run to be monitored online. (If something looks wrong, the run can be manually terminated.) Further details are given in [The Summary File].
Superbasics Limit
This option places a limit on the storage allocated for superbasic variables. Ideally, i should be set slightly larger than the ‘number of degrees of freedom’ expected at an optimal solution.
For nonlinear problems, the number of degrees of freedom is often called the ‘number of independent variables’. Normally, i need not be greater than nN+1, where nN is the number of nonlinear variables. For many problems, i may be considerably smaller than nN. This will save storage if nN is very large.
Suppress Parameters
Normally e04wd prints the options file as it is being read, and then prints a complete list of the available keywords and their final values. The optional parameter Suppress Parameters tells e04wd not to print the full list.
System Information No
System Information Yes
This option prints additional information on the progress of major and minor iterations, and Crash statistics. See [Description of Monitoring Information].
Timing Level
If i>0, some timing information will be output to the Print file, if Print File>0.
Unbounded Objective
Unbounded Step Size
These parameters are intended to detect unboundedness in nonlinear problems. During a linesearch, F is evaluated at points of the form x+αp, where x and p are fixed and α varies. If F exceeds r 1 or α exceeds r 2, iterations are terminated with the exit message ifail=5.
If singularities are present, unboundedness in F x may be manifested by a floating-point overflow (during the evaluation of F x+αp), before the test against r 1 can be made.
Unboundedness in x is best avoided by placing finite upper and lower bounds on the variables.
Verify Level
This option refers to finite difference checks on the derivatives computed by the user-supplied methods. Derivatives are checked at the first point that satisfies all bounds and linear constraints.
i | Meaning
0 | Only a ‘cheap’ test will be performed, requiring two calls to confun.
1 | Individual gradients will be checked (with a more reliable test). A key of the form OK or Bad? indicates whether or not each component appears to be correct.
2 | Individual columns of the problem Jacobian will be checked.
3 | Options 2 and 1 will both occur (in that order).
-1 | Derivative checking is disabled.
Verify Level=3 should be specified whenever a new function method is being developed. Missing derivatives are not checked, so they result in no overhead.
Violation Limit
This keyword defines an absolute limit on the magnitude of the maximum constraint violation, r, after the linesearch. On completion of the linesearch, the new iterate x k+1 satisfies the condition
vi x k+1≤r​ ​max 1,vi x 0,
where x 0 is the point at which the nonlinear constraints are first evaluated and vi x is the ith nonlinear constraint violation vi x=max 0,li-ci x,ci x-ui.
The effect of this violation limit is to restrict the iterates to lie in an expanded feasible region whose size depends on the magnitude of r. This makes it possible to keep the iterates within a region where the objective is expected to be well defined and bounded below. If the obective is bounded below for all values of the variables, then r may be any large positive value.

Inheritance Hierarchy

System..::..Object
NagLibrary..::..E04..::..e04wdOptions

See Also

E04..::..e04wdOptions Members
NagLibrary Namespace
NAG Library Overview
e04wd


E04.e04wdOptions Members

[image] [image]

NAG Library for .NET Release 2
E04..::..e04wdOptions Members
E04..::..e04wdOptions Class Constructors Methods Properties See Also Send Feedback

An optimization problem involves minimizing a function (called the objective function) of several variables, possibly subject to restrictions on the values of the variables defined by a set of constraint functions. Most methods in the Library are concerned with function minimization only, since the problem of maximizing a given objective function F(x) is equivalent to minimizing -F x. Some methods allow you to specify whether you are solving a minimization or maximization problem, carrying out the required transformation of the objective function in the latter case.
In general methods in this chapter find a local minimum of a function f, that is a point x* s.t. for all x near x* f x≥f x*.
The E05 class contains methods to find the global minimum of a function f. At a global minimum x* f x≥f x* for all x.
The (H not in this release) contains methods typically regarded as belonging to the field of operations research.
This introduction is only a brief guide to the subject of optimization designed for the casual user. Anyone with a difficult or protracted problem to solve will find it beneficial to consult a more detailed text, such as Gill et al. (1981) or Fletcher (1987).
If you are unfamiliar with the mathematics of the subject you may find some sections difficult at first reading; if so, you should concentrate on [Types of Optimization Problems], [Geometric Representation and Terminology], [Scaling], [Analysis of Computed Results] and [Recommendations on Choice and Use of Available Methods] .

The E04..::..e04wdOptions type exposes the following members.

Constructors

Name | Description
E04..::..e04wdOptions | Constructor

Methods

Name | Description
Set | Overloaded.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e04wd.
Warning | Set the method used for logging any warning or error messages from e04wd.

See Also

E04..::..e04wdOptions Class


E04.e04wdOptions Constructor

[image]

NAG Library for .NET Release 2
E04..::..e04wdOptions Constructor
E04..::..e04wdOptions Class See Also Send Feedback
Constructor

Syntax

C#
public e04wdOptions()
Visual Basic
Public Sub New
Visual C++
public:
e04wdOptions()
F#
new : unit -> e04wdOptions

See Also

E04..::..e04wdOptions Class
E04..::..e04wdOptions Members


E04.e04wdOptions Methods

[image] [image]

NAG Library for .NET Release 2
E04..::..e04wdOptions Methods
E04..::..e04wdOptions Class See Also Send Feedback

Methods

Name | Description
Set | Overloaded.

See Also

E04..::..e04wdOptions Class


Set Method

[image] [image]

NAG Library for .NET Release 2
E04..::..e04wdOptions..::Set Method
E04..::..e04wdOptions Class See Also Send Feedback

Overload List

Name | Description
Set(String) | Set an Option for e04wd
Set(DataReader) | Set Options for from a DataReader Stream.
Set(String, Double) | Set an Option for e04wd
Set(String, Int32) | Set an Option for e04wd

See Also

E04..::..e04wdOptions Class
E04..::..e04wdOptions Members


Set Method (String)

[image]

NAG Library for .NET Release 2
E04..::..e04wdOptions..::Set Method (String)
E04..::..e04wdOptions Class See Also Send Feedback
Set an Option for e04wd

Syntax

C#
public void Set(
    string dnstring
)
Visual Basic
Public Sub Set ( _
    dnstring As String _
)
Visual C++
public:
void Set(
    String^ dnstring
)
F#
member Set :
        dnstring : string -> unit

Parameters

dnstring
Type: System..::..String
A string of the form option = value, or for boolean options, simply option.

See Also

E04..::..e04wdOptions Class
E04..::..e04wdOptions Members
Set Overload


Set Method (DataReader)

[image]

NAG Library for .NET Release 2
E04..::..e04wdOptions..::Set Method (DataReader)
E04..::..e04wdOptions Class See Also Send Feedback
Set Options for from a DataReader Stream.

Syntax

C#
public void Set(
    DataReader sr
)
Visual Basic
Public Sub Set ( _
    sr As DataReader _
)
Visual C++
public:
void Set(
    DataReader^ sr
)
F#
member Set :
        sr : DataReader -> unit

Parameters

sr
Type: NagLibrary..::..DataReader
A DataReader Stream, containing an option setting on each line.

See Also

E04..::..e04wdOptions Class
E04..::..e04wdOptions Members
Set Overload


Set Method (String, Double)

[image]

NAG Library for .NET Release 2
E04..::..e04wdOptions..::Set Method (String, Double)
E04..::..e04wdOptions Class See Also Send Feedback
Set an Option for e04wd

Syntax

C#
public void Set(
    string dnstring,
    double rvalue
)
Visual Basic
Public Sub Set ( _
    dnstring As String, _
    rvalue As Double _
)
Visual C++
public:
void Set(
    String^ dnstring,
    double rvalue
)
F#
member Set :
        dnstring : string *
        rvalue : float -> unit

Parameters

dnstring
Type: System..::..String
The name of an option.
rvalue
Type: System..::..Double
The option value.

See Also

E04..::..e04wdOptions Class
E04..::..e04wdOptions Members
Set Overload


Set Method (String, Int32)

[image]

NAG Library for .NET Release 2
E04..::..e04wdOptions..::Set Method (String, Int32)
E04..::..e04wdOptions Class See Also Send Feedback
Set an Option for e04wd

Syntax

C#
public void Set(
    string dnstring,
    int ivalue
)
Visual Basic
Public Sub Set ( _
    dnstring As String, _
    ivalue As Integer _
)
Visual C++
public:
void Set(
    String^ dnstring,
    int ivalue
)
F#
member Set :
        dnstring : string *
        ivalue : int -> unit

Parameters

dnstring
Type: System..::..String
The name of an option.
ivalue
Type: System..::..Int32
The option value.

See Also

E04..::..e04wdOptions Class
E04..::..e04wdOptions Members
Set Overload


E04.e04wdOptions Properties

[image] [image]

NAG Library for .NET Release 2
E04..::..e04wdOptions Properties
E04..::..e04wdOptions Class See Also Send Feedback

The E04..::..e04wdOptions type exposes the following members.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e04wd.
Warning | Set the method used for logging any warning or error messages from e04wd.

See Also

E04..::..e04wdOptions Class


Message Property

[image]

NAG Library for .NET Release 2
E04..::..e04wdOptions..::Message Property
E04..::..e04wdOptions Class See Also Send Feedback
Set the method used for logging any monitoring messages from e04wd.

Syntax

C#
public PrintManager..::..MessageLogger Message { get; set; }
Visual Basic
Public Property Message As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Message {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Message : PrintManager..::..MessageLogger with get, set

See Also

E04..::..e04wdOptions Class
E04..::..e04wdOptions Members


Warning Property

[image]

NAG Library for .NET Release 2
E04..::..e04wdOptions..::Warning Property
E04..::..e04wdOptions Class See Also Send Feedback
Set the method used for logging any warning or error messages from e04wd.

Syntax

C#
public PrintManager..::..MessageLogger Warning { get; set; }
Visual Basic
Public Property Warning As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Warning {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Warning : PrintManager..::..MessageLogger with get, set

See Also

E04..::..e04wdOptions Class
E04..::..e04wdOptions Members


E04 Methods

[image] [image]

NAG Library for .NET Release 2
E04 Methods
E04 Class See Also Send Feedback

The E04 type exposes the following members.

Methods

Name Description
e04ab
e04ab searches for a minimum, in a given finite interval, of a continuous function of a single variable, using function values only. The method (based on quadratic interpolation) is intended for functions which have a continuous first derivative (although it will usually work if the derivative has occasional discontinuities).
e04bb
e04bb searches for a minimum, in a given finite interval, of a continuous function of a single variable, using function and first derivative values. The method (based on cubic interpolation) is intended for functions which have a continuous first derivative (although it will usually work if the derivative has occasional discontinuities).
e04cb
e04cb minimizes a general function F x of n independent variables x=x 1,x 2,…,xn T by the Nelder and Mead simplex method (see Nelder and Mead (1965)). Derivatives of the function need not be supplied.
e04cbk
Auxiliary for use as a delegate parameter
e04dg
e04dg minimizes an unconstrained nonlinear function of several variables using a pre-conditioned, limited memory quasi-Newton conjugate gradient method. First derivatives (or an ‘acceptable’ finite difference approximation to them) are required. It is intended for use on large scale problems.
e04fc
e04fc is a comprehensive algorithm for finding an unconstrained minimum of a sum of squares of m nonlinear functions in n variables m≥n. No derivatives are required.
The method is intended for functions which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04fdz
Auxiliary for use as a delegate parameter
e04fy
e04fy is an easy-to-use algorithm for finding an unconstrained minimum of a sum of squares of m nonlinear functions in n variables m≥n. No derivatives are required.
It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04gd
e04gd is a comprehensive modified Gauss–Newton algorithm for finding an unconstrained minimum of a sum of squares of m nonlinear functions in n variables m≥n. First derivatives are required.
The method is intended for functions which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04gy
e04gy is an easy-to-use quasi-Newton algorithm for finding an unconstrained minimum of a sum of squares of m nonlinear functions in n variables m≥n. First derivatives are required.
It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04gz
e04gz is an easy-to-use modified Gauss–Newton algorithm for finding an unconstrained minimum of a sum of squares of m nonlinear functions in n variables m≥n. First derivatives are required.
It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04hc
e04hc checks that a method for evaluating an objective function and its first derivatives produces derivative values which are consistent with the function values calculated.
e04hd
e04hd checks that a method for calculating second derivatives of an objective function is consistent with a method for calculating the corresponding first derivatives.
e04he
e04he is a comprehensive modified Gauss–Newton algorithm for finding an unconstrained minimum of a sum of squares of m nonlinear functions in n variables m≥n. First and second derivatives are required.
The method is intended for functions which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04hy
e04hy is an easy-to-use modified Gauss–Newton algorithm for finding an unconstrained minimum of a sum of squares of m nonlinear functions in n variables m≥n. First and second derivatives are required.
It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04jc
e04jc is an easy-to-use algorithm that uses methods of quadratic approximation to find a minimum of an objective function F over x∈Rn, subject to fixed lower and upper bounds on the independent variables x 1,x 2,…,xn. Derivatives of F are not required.
The method is intended for functions that are continuous and that have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities). Efficiency is maintained for large n.
e04jcp
Auxiliary for use as a delegate parameter
e04jy
e04jy is an easy-to-use quasi-Newton algorithm for finding a minimum of a function F x 1,x 2,…,xn, subject to fixed upper and lower bounds of the independent variables x 1,x 2,…,xn, using function values only.
It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04kd
e04kd is a comprehensive modified Newton algorithm for finding:
  • – an unconstrained minimum of a function of several variables;
  • – a minimum of a function of several variables subject to fixed upper and/or lower bounds on the variables.
First derivatives are required. The method is intended for functions which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04ky
e04ky is an easy-to-use quasi-Newton algorithm for finding a minimum of a function F x 1,x 2,…,xn, subject to fixed upper and lower bounds on the independent variables x 1,x 2,…,xn, when first derivatives of F are available.
It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04kz
e04kz is an easy-to-use modified Newton algorithm for finding a minimum of a function F x 1,x 2,…,xn, subject to fixed upper and lower bounds on the independent variables x 1,x 2,…,xn, when first derivatives of F are available. It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04lb
e04lb is a comprehensive modified Newton algorithm for finding:
  • an unconstrained minimum of a function of several variables
  • a minimum of a function of several variables subject to fixed upper and/or lower bounds on the variables.
First and second derivatives are required. The method is intended for functions which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04ly
e04ly is an easy-to-use modified-Newton algorithm for finding a minimum of a function, F x 1,x 2,…,xn subject to fixed upper and lower bounds on the independent variables, x 1,x 2,…,xn when first and second derivatives of F are available. It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).
e04mf
e04mf solves general linear programming problems. It is not intended for large sparse problems.
e04nc
e04nc solves linearly constrained linear least squares problems and convex quadratic programming problems. It is not intended for large sparse problems.
e04nf
e04nf solves general quadratic programming problems. It is not intended for large sparse problems.
e04nfu
Auxiliary for use as a delegate parameter
e04nk
e04nk solves sparse linear programming or convex quadratic programming problems.
e04nku
Auxiliary for use as a delegate parameter
e04nq
e04nq solves sparse linear programming or convex quadratic programming problems. The initialization method (E04NPF not in this release) must have been called before calling e04nq.
e04nsh
Auxiliary for use as a delegate parameter
e04pc
e04pc solves a linear least squares problem subject to fixed lower and upper bounds on the variables.
e04uc
e04uc is designed to minimize an arbitrary smooth function subject to constraints (which may include simple bounds on the variables, linear constraints and smooth nonlinear constraints) using a sequential quadratic programming (SQP) method. As many first derivatives as possible should be supplied by you; any unspecified derivatives are approximated by finite differences. It is not intended for large sparse problems.
e04uc may also be used for unconstrained, bound-constrained and linearly constrained optimization.
e04uc uses forward communication for evaluating the objective function, the nonlinear constraint functions, and any of their derivatives.
e04udm
Auxiliary for use as a delegate parameter
e04uf
e04uf is designed to minimize an arbitrary smooth function subject to constraints (which may include simple bounds on the variables, linear constraints and smooth nonlinear constraints) using a sequential quadratic programming (SQP) method. You should supply as many first derivatives as possible; any unspecified derivatives are approximated by finite differences. It is not intended for large sparse problems.
e04uf may also be used for unconstrained, bound-constrained and linearly constrained optimization.
e04uf uses reverse communication for evaluating the objective function, the nonlinear constraint functions and any of their derivatives.
e04ug
e04ug solves sparse nonlinear programming problems.
e04ugm
Auxiliary for use as a delegate parameter
e04ugn
Auxiliary for use as a delegate parameter
e04us
e04us is designed to minimize an arbitrary smooth sum of squares function subject to constraints (which may include simple bounds on the variables, linear constraints and smooth nonlinear constraints) using a sequential quadratic programming (SQP) method. As many first derivatives as possible should be supplied by you; any unspecified derivatives are approximated by finite differences. See the description of the optional parameter Derivative Level, in [Description of the Optional Parameters]. It is not intended for large sparse problems.
e04us may also be used for unconstrained, bound-constrained and linearly constrained optimization.
e04vh
e04vh solves sparse linear and nonlinear programming problems.
e04vj
e04vj may be used before e04vh to determine the sparsity pattern for the Jacobian.
e04wd
e04wd is designed to minimize an arbitrary smooth function subject to constraints (which may include simple bounds on the variables, linear constraints and smooth nonlinear constraints) using a sequential quadratic programming (SQP) method. As many first derivatives as possible should be supplied by you; any unspecified derivatives are approximated by finite differences. It is not intended for large sparse problems.
e04wd may also be used for unconstrained, bound-constrained and linearly constrained optimization.
e04wd uses forward communication for evaluating the objective function, the nonlinear constraint functions, and any of their derivatives.
The initialization method (E04WCF not in this release) must have been called before to calling e04wd.
e04wdp
Auxiliary for use as a delegate parameter
e04xa
e04xa computes an approximation to the gradient vector and/or the Hessian matrix for use in conjunction with, or following the use of an optimization method (such as e04uf).
e04ya
e04ya checks that a user-supplied method for evaluating a vector of functions and the matrix of their first derivatives produces derivative values which are consistent with the function values calculated.
e04yb
e04yb checks that a user-supplied method for evaluating the second derivative term of the Hessian matrix of a sum of squares is consistent with a user-supplied method for calculating the corresponding first derivatives.

See Also

E04 Class


e04ab Method

[image]

NAG Library for .NET Release 2
E04..::e04ab Method
E04 Class See Also Send Feedback
e04ab searches for a minimum, in a given finite interval, of a continuous function of a single variable, using function values only. The method (based on quadratic interpolation) is intended for functions which have a continuous first derivative (although it will usually work if the derivative has occasional discontinuities).

Syntax

C#
public static void e04ab(
    E04..::..E04AB_FUNCT funct,
    ref double e1,
    ref double e2,
    ref double a,
    ref double b,
    ref int maxcal,
    out double x,
    out double f,
    out int ifail
)
Visual Basic
Public Shared Sub e04ab ( _
    funct As E04..::..E04AB_FUNCT, _
    ByRef e1 As Double, _
    ByRef e2 As Double, _
    ByRef a As Double, _
    ByRef b As Double, _
    ByRef maxcal As Integer, _
    <OutAttribute> ByRef x As Double, _
    <OutAttribute> ByRef f As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04ab(
    E04..::..E04AB_FUNCT^ funct,
    double% e1,
    double% e2,
    double% a,
    double% b,
    int% maxcal,
    [OutAttribute] double% x,
    [OutAttribute] double% f,
    [OutAttribute] int% ifail
)
F#
static member e04ab :
        funct : E04..::..E04AB_FUNCT *
        e1 : float byref *
        e2 : float byref *
        a : float byref *
        b : float byref *
        maxcal : int byref *
        x : float byref *
        f : float byref *
        ifail : int byref -> unit

Parameters

funct
Type: NagLibrary..::..E04..::..E04AB_FUNCT
You must supply this method to calculate the value of the function F x at any point x in a,b. It should be tested separately before being used in conjunction with e04ab.

A delegate of type E04AB_FUNCT.

e1
Type: System..::..Double %
On entry: the relative accuracy to which the position of a minimum is required. (Note that, since e1 is a relative tolerance, the scaling of x is automatically taken into account.)
e1 should be no smaller than 2 ε, and preferably not much less than ε, where ε is the machine precision.
On exit: if you set e1 to 0.0 (or to any value less than ε), e1 will be reset to the default value ε before starting the minimization process.
e2
Type: System..::..Double %
On entry: the absolute accuracy to which the position of a minimum is required. e2 should be no smaller than 2 ε.
On exit: if you set e2 to 0.0 (or to any value less than ε), e2 will be reset to the default value ε.
a
Type: System..::..Double %
On entry: the lower bound a of the interval containing a minimum.
On exit: an improved lower bound on the position of the minimum.
b
Type: System..::..Double %
On entry: the upper bound b of the interval containing a minimum.
On exit: an improved upper bound on the position of the minimum.
maxcal
Type: System..::..Int32 %
On entry: the maximum number of calls of F x to be allowed.
Constraint: maxcal≥3. (Few problems will require more than 30.)
There will be an error exit (see [Error Indicators and Warnings]) after maxcal calls of funct
On exit: the total number of times that funct was actually called.
x
Type: System..::..Double %
On exit: the estimated position of the minimum.
f
Type: System..::..Double %
On exit: the function value at the final point given in x.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04ab is applicable to problems of the form:
Minimize F x  subject to  a≤x≤b.
It normally computes a sequence of x values which tend in the limit to a minimum of F x subject to the given bounds. It also progressively reduces the interval a,b in which the minimum is known to lie. It uses the safeguarded quadratic-interpolation method described in Gill and Murray (1973).
You must supply a funct to evaluate F x. The parameters e1 and e2 together specify the accuracy
Tol x=e1×x+e2
to which the position of the minimum is required. Note that funct is never called at any point which is closer than Tol x to a previous point.
If the original interval a,b contains more than one minimum, e04ab will normally find one of the minima.

References

Gill P E and Murray W (1973) Safeguarded steplength algorithms for optimization using descent methods NPL Report NAC 37 National Physical Laboratory

Error Indicators and Warnings

Note: e04ab may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail=1
On entry, | a+e2≥b,
or | maxcal<3,
ifail=2
The number of calls of funct has exceeded maxcal. This may have happened simply because maxcal was set too small for a particular problem, or may be due to a mistake in funct. If no mistake can be found in funct, restart e04ab (preferably with the values of a and b given on exit from the previous call of e04ab).
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

If F x is δ-unimodal for some δ<Tol x, where Tol x=e1×x+e2, then, on exit, x approximates the minimum of F x in the original interval a,b with an error less than 3×Tol x.

Parallelism and Performance

None.

Further Comments

Timing depends on the behaviour of F x, the accuracy demanded and the length of the interval a,b. Unless F x can be evaluated very quickly, the run time will usually be dominated by the time spent in funct.
If F x has more than one minimum in the original interval a,b, e04ab will determine an approximation x (and improved bounds a and b) for one of the minima.
If e04ab finds an x such that F x-δ 1>F x<F x+δ 2 for some δ 1,δ 2≥Tol x, the interval x-δ 1,x+δ 2 will be regarded as containing a minimum, even if F x is less than F x-δ 1 and F x+δ 2 only due to rounding errors in the method. Therefore funct should be programmed to calculate F x as accurately as possible, so that e04ab will not be liable to find a spurious minimum.

Example

A sketch of the function
F x=sin x x
shows that it has a minimum somewhere in the range 3.5,5.0. The following program shows how e04ab can be used to obtain a good approximation to the position of a minimum.

Example program (C#): e04abe.cs

Example program results: e04abe.r

See Also

E04 Class
E04 Members


e04bb Method

[image]

NAG Library for .NET Release 2
E04..::e04bb Method
E04 Class See Also Send Feedback
e04bb searches for a minimum, in a given finite interval, of a continuous function of a single variable, using function and first derivative values. The method (based on cubic interpolation) is intended for functions which have a continuous first derivative (although it will usually work if the derivative has occasional discontinuities).

Syntax

C#
public static void e04bb(
    E04..::..E04BB_FUNCT funct,
    ref double e1,
    ref double e2,
    ref double a,
    ref double b,
    ref int maxcal,
    out double x,
    out double f,
    out double g,
    out int ifail
)
Visual Basic
Public Shared Sub e04bb ( _
    funct As E04..::..E04BB_FUNCT, _
    ByRef e1 As Double, _
    ByRef e2 As Double, _
    ByRef a As Double, _
    ByRef b As Double, _
    ByRef maxcal As Integer, _
    <OutAttribute> ByRef x As Double, _
    <OutAttribute> ByRef f As Double, _
    <OutAttribute> ByRef g As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04bb(
    E04..::..E04BB_FUNCT^ funct,
    double% e1,
    double% e2,
    double% a,
    double% b,
    int% maxcal,
    [OutAttribute] double% x,
    [OutAttribute] double% f,
    [OutAttribute] double% g,
    [OutAttribute] int% ifail
)
F#
static member e04bb :
        funct : E04..::..E04BB_FUNCT *
        e1 : float byref *
        e2 : float byref *
        a : float byref *
        b : float byref *
        maxcal : int byref *
        x : float byref *
        f : float byref *
        g : float byref *
        ifail : int byref -> unit

Parameters

funct
Type: NagLibrary..::..E04..::..E04BB_FUNCT
You must supply this method to calculate the values of F x and dFdx at any point x in a,b.
It should be tested separately before being used in conjunction with e04bb.

A delegate of type E04BB_FUNCT.

e1
Type: System..::..Double %
On entry: the relative accuracy to which the position of a minimum is required. (Note that, since e1 is a relative tolerance, the scaling of x is automatically taken into account.)
e1 should be no smaller than 2 ε, and preferably not much less than ε, where ε is the machine precision.
On exit: if you set e1 to 0.0 (or to any value less than ε), e1 will be reset to the default value ε before starting the minimization process.
e2
Type: System..::..Double %
On entry: the absolute accuracy to which the position of a minimum is required. e2 should be no smaller than 2 ε.
On exit: if you set e2 to 0.0 (or to any value less than ε), e2 will be reset to the default value ε.
a
Type: System..::..Double %
On entry: the lower bound a of the interval containing a minimum.
On exit: an improved lower bound on the position of the minimum.
b
Type: System..::..Double %
On entry: the upper bound b of the interval containing a minimum.
On exit: an improved upper bound on the position of the minimum.
maxcal
Type: System..::..Int32 %
On entry: the maximum number of calls of funct to be allowed.
Constraint: maxcal≥2. (Few problems will require more than 20.)
There will be an error exit (see [Error Indicators and Warnings]) after maxcal calls of funct
On exit: the total number of times that funct was actually called.
x
Type: System..::..Double %
On exit: the estimated position of the minimum.
f
Type: System..::..Double %
On exit: the function value at the final point given in x.
g
Type: System..::..Double %
On exit: the value of the first derivative at the final point in x.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04bb is applicable to problems of the form:
Minimize F x  subject to  a≤x≤b
when the first derivative dFdx can be calculated. The method normally computes a sequence of x values which tend in the limit to a minimum of F x subject to the given bounds. It also progressively reduces the interval a,b in which the minimum is known to lie. It uses the safeguarded cubic-interpolation method described in Gill and Murray (1973).
You must supply a funct to evaluate F x and dFdx. The parameters e1 and e2 together specify the accuracy
Tol x=e1×x+e2
to which the position of the minimum is required. Note that funct is never called at a point which is closer than Tol x to a previous point.
If the original interval a,b contains more than one minimum, e04bb will normally find one of the minima.

References

Gill P E and Murray W (1973) Safeguarded steplength algorithms for optimization using descent methods NPL Report NAC 37 National Physical Laboratory

Error Indicators and Warnings

Note: e04bb may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail=1
On entry, | a+e2≥b,
or | maxcal<2.
ifail=2
The number of calls of funct has exceeded maxcal. This may have happened simply because maxcal was set too small for a particular problem, or may be due to a mistake in funct. If no mistake can be found in funct, restart e04bb (preferably with the values of a and b given on exit from the previous call of e04bb).
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

If F x is δ-unimodal for some δ<Tol x, where Tol x=e1×x+e2, then, on exit, x approximates the minimum of F x in the original interval a,b with an error less than 3×Tol x.

Parallelism and Performance

None.

Further Comments

Timing depends on the behaviour of F x, the accuracy demanded and the length of the interval a,b. Unless F x and dFdx can be evaluated very quickly, the run time will usually be dominated by the time spent in funct.
If F x has more than one minimum in the original interval a,b, e04bb will determine an approximation x (and improved bounds a and b) for one of the minima.
If e04bb finds an x such that F x-δ 1>F x<F x+δ 2 for some δ 1,δ 2≥Tol x, the interval x-δ 1,x+δ 2 will be regarded as containing a minimum, even if F x is less than F x-δ 1 and F x+δ 2 only due to rounding errors in the method. Therefore funct should be programmed to calculate F x as accurately as possible, so that e04bb will not be liable to find a spurious minimum. (For similar reasons, dFdx should be evaluated as accurately as possible.)

Example

A sketch of the function
F x=sin x x
shows that it has a minimum somewhere in the range 3.5,5.0. The following program shows how e04bb can be used to obtain a good approximation to the position of a minimum.

Example program (C#): e04bbe.cs

Example program results: e04bbe.r

See Also

E04 Class
E04 Members


e04cb Method

[image]

NAG Library for .NET Release 2
E04..::e04cb Method
E04 Class See Also Send Feedback
e04cb minimizes a general function F x of n independent variables x=x 1,x 2,…,xn T by the Nelder and Mead simplex method (see Nelder and Mead (1965)). Derivatives of the function need not be supplied.

Syntax

C#
public static void e04cb(
    int n,
    double[] x,
    out double f,
    double tolf,
    double tolx,
    E04..::..E04CB_FUNCT funct,
    E04..::..E04CB_MONIT monit,
    int maxcal,
    out int ifail
)
Visual Basic
Public Shared Sub e04cb ( _
    n As Integer, _
    x As Double(), _
    <OutAttribute> ByRef f As Double, _
    tolf As Double, _
    tolx As Double, _
    funct As E04..::..E04CB_FUNCT, _
    monit As E04..::..E04CB_MONIT, _
    maxcal As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04cb(
    int n,
    array<double>^ x,
    [OutAttribute] double% f,
    double tolf,
    double tolx,
    E04..::..E04CB_FUNCT^ funct,
    E04..::..E04CB_MONIT^ monit,
    int maxcal,
    [OutAttribute] int% ifail
)
F#
static member e04cb :
        n : int *
        x : float[] *
        f : float byref *
        tolf : float *
        tolx : float *
        funct : E04..::..E04CB_FUNCT *
        monit : E04..::..E04CB_MONIT *
        maxcal : int *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of variables.
Constraint: n≥1.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: a guess at the position of the minimum. Note that the problem should be scaled so that the values of the x[i-1] are of order unity.
On exit: the value of x corresponding to the function value in f.
f
Type: System..::..Double %
On exit: the lowest function value found.
tolf
Type: System..::..Double
On entry: the error tolerable in the function values, in the following sense. If fi, for i=1,2,…,n+1, are the individual function values at the vertices of the current simplex, and if fm is the mean of these values, then you can request that e04cb should terminate if
1 n+1∑i=1n+1 fi-fm 2<tolf. (1)
You may specify tolf=0 if you wish to use only the termination criterion (2) on the spatial values: see the description of tolx.
Constraint: tolf must be greater than or equal to the machine precision (see X02 class), or if tolf equals zero then tolx must be greater than or equal to the machine precision.
tolx
Type: System..::..Double
On entry: the error tolerable in the spatial values, in the following sense. If LV denotes the ‘linearized’ volume of the current simplex, and if LV init denotes the ‘linearized’ volume of the initial simplex, then you can request that e04cb should terminate if
LVLV init<tolx. (2)
You may specify tolx=0 if you wish to use only the termination criterion (1) on function values: see the description of tolf.
Constraint: tolx must be greater than or equal to the machine precision (see X02 class), or if tolx equals zero then tolf must be greater than or equal to the machine precision.
funct
Type: NagLibrary..::..E04..::..E04CB_FUNCT
funct must evaluate the function F at a specified point. It should be tested separately before being used in conjunction with e04cb.

A delegate of type E04CB_FUNCT.

monit
Type: NagLibrary..::..E04..::..E04CB_MONIT
monit may be used to monitor the optimization process. It is invoked once every iteration.
If no monitoring is required, monit may be the dummy monitoring method E04CBK supplied by the NAG Library.

A delegate of type E04CB_MONIT.

maxcal
Type: System..::..Int32
On entry: the maximum number of function evaluations to be allowed.
Constraint: maxcal≥1.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04cb finds an approximation to a minimum of a function F of n variables. You must supply a method to calculate the value of F for any set of values of the variables.
The method is iterative. A simplex of n+1 points is set up in the n-dimensional space of the variables (for example, in 2 dimensions the simplex is a triangle) under the assumption that the problem has been scaled so that the values of the independent variables at the minimum are of order unity. The starting point you have provided is the first vertex of the simplex, the remaining n vertices are generated by e04cb. The vertex of the simplex with the largest function value is reflected in the centre of gravity of the remaining vertices and the function value at this new point is compared with the remaining function values. Depending on the outcome of this test the new point is accepted or rejected, a further expansion move may be made, or a contraction may be carried out. See Nelder and Mead (1965) and Parkinson and Hutchinson (1972) for more details. When no further progress can be made the sides of the simplex are reduced in length and the method is repeated.
The method can be slow, but computational bottlenecks have been reduced following Singer and Singer (2004). However, e04cb is robust, and therefore very useful for functions that are subject to inaccuracies.
There are the following options for successful termination of the method: based only on the function values at the vertices of the current simplex (see (1)); based only on a volume ratio between the current simplex and the initial one (see (2)); or based on which one of the previous two tests passes first. The volume test may be useful if F is discontinuous, while the function-value test should be sufficient on its own if F is continuous.

References

Nelder J A and Mead R (1965) A simplex method for function minimization Comput. J. 7 308–313
Parkinson J M and Hutchinson D (1972) An investigation into the efficiency of variants of the simplex method Numerical Methods for Nonlinear Optimization (ed F A Lootsma) Academic Press
Singer S and Singer S (2004) Efficient implementation of the Nelder–Mead search algorithm Appl. Num. Anal. Comp. Math. 1(3) 524–534

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
An input parameter is invalid. The output message provides more details of the invalid argument.
ifail=2
maxcal function evaluations have been completed without termination test (1) or (2) passing. Check the coding of funct before increasing the value of maxcal.
ifail=-999
Internal memory allocation failed.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

On a successful exit the accuracy will be as defined by tolf or tolx, depending on which criterion was satisfied first.

Parallelism and Performance

None.

Further Comments

Local workspace arrays of fixed lengths (depending on n) are allocated internally by e04cb. The total size of these arrays amounts to n 2+6 n+2 real elements.
The time taken by e04cb depends on the number of variables, the behaviour of the function and the distance of the starting point from the minimum. Each iteration consists of 1 or 2 function evaluations unless the size of the simplex is reduced, in which case n+1 function evaluations are required.

Example

This example finds a minimum of the function
F x 1,x 2=e x 1 4 x 12+2 x 22+4 x 1x 2+2 x 2+1.
This example uses the initial point -1,1 (see []), and we expect to reach the minimum at 0.5,-1.

Example program (C#): e04cbe.cs

Example program results: e04cbe.r

See Also

E04 Class
E04 Members


e04cbk Method

[image]

NAG Library for .NET Release 2
E04..::e04cbk Method
E04 Class See Also Send Feedback
Auxiliary for use as a delegate parameter

Syntax

C#
public static void e04cbk(
    double fmin,
    double fmax,
    double[,] sim,
    int n,
    int ncall,
    double serror,
    double vratio
)
Visual Basic
Public Shared Sub e04cbk ( _
    fmin As Double, _
    fmax As Double, _
    sim As Double(,), _
    n As Integer, _
    ncall As Integer, _
    serror As Double, _
    vratio As Double _
)
Visual C++
public:
static void e04cbk(
    double fmin,
    double fmax,
    array<double,2>^ sim,
    int n,
    int ncall,
    double serror,
    double vratio
)
F#
static member e04cbk :
        fmin : float *
        fmax : float *
        sim : float[,] *
        n : int *
        ncall : int *
        serror : float *
        vratio : float -> unit

Parameters

fmin
Type: System..::..Double
On entry: the smallest function value in the current simplex.
fmax
Type: System..::..Double
On entry: the largest function value in the current simplex.
sim
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [n+1, n]
On entry: the n+1 position vectors of the current simplex.
n
Type: System..::..Int32
On entry: n, the number of variables.
ncall
Type: System..::..Int32
On entry: the number of times that _funct has been called so far.
serror
Type: System..::..Double
On entry: the current value of the standard deviation in function values used in termination test eqn1.
vratio
Type: System..::..Double
On entry: the current value of the linearized volume ratio used in termination test eqn2.

Description

Auxiliary for use as a delegate parameter

References

None.

Error Indicators and Warnings

None.

Accuracy

Not applicable.

Further Comments

None.

Example

None.

See Also

E04 Class
E04 Members


e04dg Method

[image]

NAG Library for .NET Release 2
E04..::e04dg Method
E04 Class See Also Send Feedback
e04dg minimizes an unconstrained nonlinear function of several variables using a pre-conditioned, limited memory quasi-Newton conjugate gradient method. First derivatives (or an ‘acceptable’ finite difference approximation to them) are required. It is intended for use on large scale problems.

Syntax

C#
public static void e04dg(
    int n,
    E04..::..E04DG_OBJFUN objfun,
    out int iter,
    out double objf,
    double[] objgrd,
    double[] x,
    E04..::..e04dgOptions options,
    out int ifail
)
Visual Basic
Public Shared Sub e04dg ( _
    n As Integer, _
    objfun As E04..::..E04DG_OBJFUN, _
    <OutAttribute> ByRef iter As Integer, _
    <OutAttribute> ByRef objf As Double, _
    objgrd As Double(), _
    x As Double(), _
    options As E04..::..e04dgOptions, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04dg(
    int n,
    E04..::..E04DG_OBJFUN^ objfun,
    [OutAttribute] int% iter,
    [OutAttribute] double% objf,
    array<double>^ objgrd,
    array<double>^ x,
    E04..::..e04dgOptions^ options,
    [OutAttribute] int% ifail
)
F#
static member e04dg :
        n : int *
        objfun : E04..::..E04DG_OBJFUN *
        iter : int byref *
        objf : float byref *
        objgrd : float[] *
        x : float[] *
        options : E04..::..e04dgOptions *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of variables.
Constraint: n>0.
objfun
Type: NagLibrary..::..E04..::..E04DG_OBJFUN
objfun must calculate the objective function F x and possibly its gradient as well for a specified n-element vector x.

A delegate of type E04DG_OBJFUN.

Note: objfun should be tested separately before being used in conjunction with e04dg. See also the description of the optional parameter Verify.
iter
Type: System..::..Int32 %
On exit: the total number of iterations performed.
objf
Type: System..::..Double %
On exit: the value of the objective function at the final iterate.
objgrd
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the gradient of the objective function at the final iterate (or its finite difference approximation).
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: an initial estimate of the solution.
On exit: the final estimate of the solution.
options
Type: NagLibrary..::..E04..::..e04dgOptions
An Object of type E04.e04dgOptions. Used to configure optional parameters to this method.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04dg is designed to solve unconstrained minimization problems of the form
minimize x∈Rn F x  subject to  -∞≤x≤∞,
where x is an n-element vector.
You must supply an initial estimate of the solution.
The method used by e04dg is described in [Algorithmic Details].

References

Gill P E and Murray W (1979) Conjugate-gradient methods for large-scale nonlinear optimization Technical Report SOL 79-15 Department of Operations Research, Stanford University
Gill P E, Murray W and Wright M H (1981) Practical Optimization Academic Press

Error Indicators and Warnings

Note: e04dg may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail<0
A negative value of ifail indicates an exit from e04dg because you set mode<0 in objfun. The value of ifail will be the same as your setting of mode.
ifail=1
Not used by this method.
ifail=2
Not used by this method.
ifail=3
The limiting number of iterations (as determined by the optional parameter Iteration Limit (default value=max 50,5 n) has been reached.
If the algorithm appears to be making satisfactory progress, then optional parameter Iteration Limit may be too small. If so, increase its value and rerun e04dg. If the algorithm seems to be making little or no progress, then you should check for incorrect gradients as described under ifail=7.
ifail=4
The computed upper bound on the step length taken during the linesearch was too small. A rerun with an increased value of the optional parameter Maximum Step Length (ρ say) may be successful unless ρ≥1020 (the default value), in which case the current point cannot be improved upon.
ifail=5
Not used by this method.
ifail=6
The conditions for an acceptable solution (see parameter ifail in [Parameters]) have not all been met, but a lower point could not be found.
If objfun computes the objective function and its gradient correctly, then this may occur because an overly stringent accuracy has been requested, i.e., the value of the optional parameter Optimality Tolerance (default value=ε 0.8) is too small or if αk≃0. In this case you should apply the three tests described under ifail=0 to determine whether or not the final solution is acceptable. For a discussion of attainable accuracy see Gill et al. (1981).
If many iterations have occurred in which essentially no progress has been made or e04dg has failed to move from the initial point, objfun may be incorrect. You should refer to the comments below under ifail=7 and check the gradients using the optional parameter Verify (default value=0). Unfortunately, there may be small errors in the objective gradients that cannot be detected by the verification process. Finite difference approximations to first derivatives are catastrophically affected by even small inaccuracies.
ifail=7
The user-supplied derivatives of the objective function appear to be incorrect.
Large errors were found in the derivatives of the objective function. This value of ifail will occur if the verification process indicated that at least one gradient element had no correct figures. You should refer to the printed output to determine which elements are suspected to be in error.
As a first step, you should check that the code for the objective values is correct – for example, by computing the function at a point where the correct value is known. However, care should be taken that the chosen point fully tests the evaluation of the function. It is remarkable how often the values x=0 or x=1 are used to test function evaluation procedures, and how often the special properties of these numbers make the test meaningless.
Special care should be used in this test if computation of the objective function involves subsidiary data communicated in storage. Although the first evaluation of the function may be correct, subsequent calculations may be in error because some of the subsidiary data has accidentally been overwritten.
Errors in programming the function may be quite subtle in that the function value is almost correct. For example, the function may not be accurate to full precision because of the inaccurate calculation of a subsidiary quantity, or the limited accuracy of data upon which the function depends. A common error on machines where numerical calculations are usually performed in double precision is to include even one single precision constant in the calculation of the function; since some compilers do not convert such constants to double precision, half the correct figures may be lost by such a seemingly trivial error.
ifail=8
The gradient g=∂F∂x at the starting point x 0 is ‘too small’. More precisely, the value of g x 0 T g x 0 is less than εr 1+F x 0, where εr is the value of the optional parameter Function Precision (default value=ε 0.9).
The problem should be rerun from a different starting point.
ifail=9
An input parameter is invalid.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

On successful exit (ifail=0) the accuracy of the solution will be as defined by the optional parameter Optimality Tolerance (default value=ε 0.8).

Parallelism and Performance

None.

Further Comments

To evaluate an ‘acceptable’ set of finite difference intervals using e04xa requires 2 function evaluations per variable for a well-scaled problem and up to 6 function evaluations per variable for a badly scaled problem.

Description of Printed Output

This section describes the intermediate printout and final printout produced by e04dg. You can control the level of printed output (see the description of the optional parameter Print Level). Note that the intermediate printout and final printout are produced only if Print Level≥10 (the default ).
The following line of summary output (<80 characters) is produced at every iteration. In all cases, the values of the quantities are those in effect on completion of the given iteration.
Itn | is the iteration count.
Step | is the step αk taken along the computed search direction. On reasonably well-behaved problems, the unit step (i.e., αk=1) will be taken as the solution is approached.
Nfun | is the cumulated number of evaluations of the objective function needed for the linesearch. Evaluations needed for the verification of the gradients by finite differences are not included. Nfun is printed as a guide to the amount of work required for the linesearch. e04dg will perform at most 11 function evaluations per iteration.
Objective | is the value of the objective function at xk.
Norm G | is the Euclidean norm of the gradient of the objective function at xk.
Norm X | is the Euclidean norm of xk.
Norm (X(k-1)-X(k)) | is the Euclidean norm of x k-1-xk.
The following describes the printout for each variable.
Variable | gives the name (Varbl) and index j, for j=1,2,…,n of the variable.
Value | is the value of the variable at the final iteration.
Gradient Value | is the value of the gradient of the objective function with respect to the jth variable at the final iteration.
Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.

Example

This example finds a minimum of the function
F=e x 1 4 x 12+2 x 22+4 x 1x 2+2 x 2+1.
The initial point is
x 0=-1.0,1.0 T,
and F x 0=1.8394 (to five figures).
The optimal solution is
x*=0.5,-1.0 T,
and F x*=0.

Example program (C#): e04dge.cs

Example program data: e04dge.d

Example program results: e04dge.r

Algorithmic Details

This section contains a description of the method used by e04dg.
e04dg uses a pre-conditioned conjugate gradient method and is based upon algorithm PLMA as described in Section 4.8.3 of Gill and Murray (1979) and Gill et al. (1981).
The algorithm proceeds as follows:
Let x 0 be a given starting point and let k denote the current iteration, starting with k=0. The iteration requires gk, the gradient vector evaluated at xk, the kth estimate of the minimum. At each iteration a vector pk (known as the direction of search) is computed and the new estimate x k+1 is given by xk+αkpk where αk (the step length) minimizes the function F xk+αkpk with respect to the scalar αk. A choice of initial step α 0 is taken as
α 0=min 1,2×Fk-Fest/gkT gk
where Fest is a user-supplied estimate of the function value at the solution. If Fest is not specified, the software always chooses the unit step length for α 0. Subsequent step length estimates are computed using cubic interpolation with safeguards.
A quasi-Newton method can be used to compute the search direction pk by updating the inverse of the approximate Hessian Hk and computing
p k+1=-H k+1g k+1. (1)
The updating formula for the approximate inverse is given by
H k+1=Hk-1 ykT sk Hkyk skT+sk ykT Hk+1 ykT sk 1+ykT HkykykT sk sk skT, (2)
where yk=g k-1-gk and sk=x k+1-xk=αkpk.
The method used to obtain the search direction is based upon computing p k+1 as -H k+1 g k+1 where H k+1 is a matrix obtained by updating the identity matrix with a limited number of quasi-Newton corrections. The storage of an n by n matrix is avoided by storing only the vectors that define the rank two corrections – hence the term ‘limited-memory’ quasi-Newton method. The precise method depends upon the number of updating vectors stored. For example, the direction obtained with the ‘one-step’ limited memory update is given by (1) using (2) with Hk equal to the identity matrix, viz.
p k+1=-g k+1+1 ykT sk skT g k+1yk+ykT g k+1sk-skT g k+1ykT sk 1+ykT ykykT sk sk.
Using a limited-memory quasi-Newton formula, such as the one above, guarantees p k+1 to be a descent direction if all the inner products ykT sk are positive for all vectors yk and sk used in the updating formula.

See Also

E04 Class
E04 Members


e04fc Method

[image]

NAG Library for .NET Release 2
E04..::e04fc Method
E04 Class See Also Send Feedback
e04fc is a comprehensive algorithm for finding an unconstrained minimum of a sum of squares of m nonlinear functions in n variables m≥n. No derivatives are required.
The method is intended for functions which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).

Syntax

C#
public static void e04fc(
    int m,
    int n,
    E04..::..E04FC_LSQFUN lsqfun,
    E04..::..E04FC_LSQMON lsqmon,
    int iprint,
    int maxcal,
    double eta,
    double xtol,
    double stepmx,
    double[] x,
    out double fsumsq,
    double[] fvec,
    double[,] fjac,
    double[] s,
    double[,] v,
    out int niter,
    out int nf,
    out int ifail
)
Visual Basic
Public Shared Sub e04fc ( _
    m As Integer, _
    n As Integer, _
    lsqfun As E04..::..E04FC_LSQFUN, _
    lsqmon As E04..::..E04FC_LSQMON, _
    iprint As Integer, _
    maxcal As Integer, _
    eta As Double, _
    xtol As Double, _
    stepmx As Double, _
    x As Double(), _
    <OutAttribute> ByRef fsumsq As Double, _
    fvec As Double(), _
    fjac As Double(,), _
    s As Double(), _
    v As Double(,), _
    <OutAttribute> ByRef niter As Integer, _
    <OutAttribute> ByRef nf As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04fc(
    int m,
    int n,
    E04..::..E04FC_LSQFUN^ lsqfun,
    E04..::..E04FC_LSQMON^ lsqmon,
    int iprint,
    int maxcal,
    double eta,
    double xtol,
    double stepmx,
    array<double>^ x,
    [OutAttribute] double% fsumsq,
    array<double>^ fvec,
    array<double,2>^ fjac,
    array<double>^ s,
    array<double,2>^ v,
    [OutAttribute] int% niter,
    [OutAttribute] int% nf,
    [OutAttribute] int% ifail
)
F#
static member e04fc :
        m : int *
        n : int *
        lsqfun : E04..::..E04FC_LSQFUN *
        lsqmon : E04..::..E04FC_LSQMON *
        iprint : int *
        maxcal : int *
        eta : float *
        xtol : float *
        stepmx : float *
        x : float[] *
        fsumsq : float byref *
        fvec : float[] *
        fjac : float[,] *
        s : float[] *
        v : float[,] *
        niter : int byref *
        nf : int byref *
        ifail : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: the number m of residuals, fi x, and the number n of variables, xj.
Constraint: 1≤n≤m.
n
Type: System..::..Int32
On entry: the number m of residuals, fi x, and the number n of variables, xj.
Constraint: 1≤n≤m.
lsqfun
Type: NagLibrary..::..E04..::..E04FC_LSQFUN
lsqfun must calculate the vector of values fi x at any point x. (However, if you do not wish to calculate the residuals at a particular x, there is the option of setting a parameter to cause e04fc to terminate immediately.)

A delegate of type E04FC_LSQFUN.

Note: lsqfun should be tested separately before being used in conjunction with e04fc.
lsqmon
Type: NagLibrary..::..E04..::..E04FC_LSQMON
If iprint≥0, you must supply lsqmon which is suitable for monitoring the minimization process. lsqmon must not change the values of any of its parameters.
If iprint<0, the dummy method E04FDZ can be used as lsqmon.

A delegate of type E04FC_LSQMON.

Note: you should normally print the sum of squares of residuals, so as to be able to examine the sequence of values of F x mentioned in [Accuracy]. It is usually helpful to print xc, the estimated gradient of the sum of squares, niter and nf.
iprint
Type: System..::..Int32
On entry: the frequency with which lsqmon is to be called.
If iprint>0, lsqmon is called once every iprint iterations and just before exit from e04fc.
If iprint=0, lsqmon is just called at the final point.
If iprint<0, lsqmon is not called at all.
iprint should normally be set to a small positive number.
Suggested value: iprint=1.
maxcal
Type: System..::..Int32
On entry: the limit you set on the number of times that lsqfun may be called by e04fc. There will be an error exit (see [Error Indicators and Warnings]) after maxcal calls of lsqfun.
Suggested value: maxcal=400×n.
Constraint: maxcal≥1.
eta
Type: System..::..Double
Every iteration of e04fc involves a linear minimization, i.e., minimization of F x k+α kp k with respect to α k.
On entry: specifies how accurately the linear minimizations are to be performed. The minimum with respect to α k will be located more accurately for small values of eta (say, 0.01) than for large values (say, 0.9). Although accurate linear minimizations will generally reduce the number of iterations performed by e04fc, they will increase the number of calls of lsqfun made each iteration. On balance it is usually more efficient to perform a low accuracy minimization.
Suggested value: eta=0.5 (eta=0.0 if n=1).
Constraint: 0.0≤eta<1.0.
xtol
Type: System..::..Double
On entry: the accuracy in x to which the solution is required.
If xtrue is the true value of x at the minimum, then xsol, the estimated position before a normal exit, is such that
xsol-xtrue<xtol×1.0+xtrue,
where y=∑j=1 n yj 2. For example, if the elements of xsol are not much larger than 1.0 in modulus and if xtol=1.0E−5, then xsol is usually accurate to about five decimal places. (For further details see [Accuracy].)
Suggested value: if F x and the variables are scaled roughly as described in [Further Comments] and ε is the machine precision, then a setting of order xtol=ε will usually be appropriate. If xtol is set to 0.0 or some positive value less than 10 ε, e04fc will use 10 ε instead of xtol, since 10 ε is probably the smallest reasonable setting.
Constraint: xtol≥0.0.
stepmx
Type: System..::..Double
On entry: an estimate of the Euclidean distance between the solution and the starting point supplied by you. (For maximum efficiency, a slight overestimate is preferable.) e04fc will ensure that, for each iteration,
∑j=1 n xj k-xj k-1 2≤stepmx 2,
where k is the iteration number. Thus, if the problem has more than one solution, e04fc is most likely to find the one nearest to the starting point. On difficult problems, a realistic choice can prevent the sequence x k entering a region where the problem is ill-behaved and can help avoid overflow in the evaluation of F x. However, an underestimate of stepmx can lead to inefficiency.
Suggested value: stepmx=100000.0.
Constraint: stepmx≥xtol.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x[j-1] must be set to a guess at the jth component of the position of the minimum, for j=1,2,…,n.
On exit: the final point x k. Thus, if ifail=0 on exit, x[j-1] is the jth component of the estimated position of the minimum.
fsumsq
Type: System..::..Double %
On exit: the value of F x, the sum of squares of the residuals fi x, at the final point given in x.
fvec
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: the value of the residual fi x at the final point given in x, for i=1,2,…,m.
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: the estimate of the first derivative ∂fi∂xj at the final point given in x, for i=1,2,…,m and j=1,2,…,n.
s
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the singular values of the estimated Jacobian matrix at the final point. Thus s may be useful as information about the structure of your problem.
v
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: the matrix V associated with the singular value decomposition
J=US VT
of the estimated Jacobian matrix at the final point, stored by columns. This matrix may be useful for statistical purposes, since it is the matrix of orthonormalized eigenvectors of JT J.
niter
Type: System..::..Int32 %
On exit: the number of iterations which have been performed in e04fc.
nf
Type: System..::..Int32 %
On exit: the number of times that the residuals have been evaluated (i.e., number of calls of lsqfun).
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04fc is essentially identical to the method LSQNDN in the NPL Algorithms Library. It is applicable to problems of the form
Minimize F x=∑i=1 m fi x 2
where x=x 1,x 2,…,xn T and m≥n. (The functions fi x are often referred to as ‘residuals’.)
You must supply lsqfun to calculate the values of the fi x at any point x.
From a starting point x 1 supplied by you, the method generates a sequence of points x 2,x 3,…, which is intended to converge to a local minimum of F x. The sequence of points is given by
x k+1=x k+α kp k
where the vector p k is a direction of search, and α k is chosen such that F x k+α kp k is approximately a minimum with respect to α k.
The vector p k used depends upon the reduction in the sum of squares obtained during the last iteration. If the sum of squares was sufficiently reduced, then p k is an approximation to the Gauss–Newton direction; otherwise additional function evaluations are made so as to enable p k to be a more accurate approximation to the Newton direction.
The method is designed to ensure that steady progress is made whatever the starting point, and to have the rapid ultimate convergence of Newton's method.

References

Gill P E and Murray W (1978) Algorithms for the solution of the nonlinear least squares problem SIAM J. Numer. Anal. 15 977–992

Error Indicators and Warnings

Note: e04fc may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDFJAC, LDV, IW, LIW, W, LW) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail<0
A negative value of ifail indicates an exit from e04fc because you have set iflag negative in lsqfun. The value of ifail will be the same as your setting of iflag.
ifail=1
On entry, | n<1,
or | m<n,
or | maxcal<1,
or | eta<0.0,
or | eta≥1.0,
or | xtol<0.0,
or | stepmx<xtol,
When this exit occurs, no values will have been assigned to fsumsq, or to the elements of fvec, fjac, s or v.
ifail=2
There have been maxcal calls of lsqfun. If steady reductions in the sum of squares, F x, were monitored up to the point where this exit occurred, then the exit probably occurred simply because maxcal was set too small, so the calculations should be restarted from the final point held in x. This exit may also indicate that F x has no minimum.
ifail=3
The conditions for a minimum have not all been satisfied, but a lower point could not be found. This could be because xtol has been set so small that rounding errors in the evaluation of the residuals make attainment of the convergence conditions impossible.
ifail=4
The method for computing the singular value decomposition of the estimated Jacobian matrix has failed to converge in a reasonable number of sub-iterations. It may be worth applying e04fc again starting with an initial approximation which is not too close to the point at which the failure occurred.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
The values ifail=2, 3 or 4 may also be caused by mistakes in lsqfun, by the formulation of the problem or by an awkward function. If there are no such mistakes it is worth restarting the calculations from a different starting point (not the point at which the failure occurred) in order to avoid the region which caused the failure.

Accuracy

A successful exit (ifail=0) is made from e04fc when (B1, B2 and B3) or B4 or B5 hold, where
B1≡α k×p k<xtol+ε×1.0+x kB2≡F k-F k-1<xtol+ε 2×1.0+F kB3≡g k<ε 1/3+xtol×1.0+F kB4≡F k<ε 2B5≡g k<ε×F k1/2
and where . and ε are as defined in [Parameters], and F k and g k are the values of F x and its vector of estimated first derivatives at x k. If ifail=0 then the vector in x on exit, xsol, is almost certainly an estimate of xtrue, the position of the minimum to the accuracy specified by xtol.
If ifail=3, then xsol may still be a good estimate of xtrue, but to verify this you should make the following checks. If
(a) | the sequence F x k converges to F xsol at a superlinear or a fast linear rate, and
(b) | g xsol T g xsol<10 ε, where T denotes transpose, then it is almost certain that xsol is a close approximation to the minimum. When (b) is true, then usually F xsol is a close approximation to F xtrue. The values of F x k can be calculated in lsqmon, and the vector g xsol can be calculated from the contents of fvec and fjac on exit from e04fc.
Further suggestions about confirmation of a computed solution are given in the E04 class.

Parallelism and Performance

None.

Further Comments

The number of iterations required depends on the number of variables, the number of residuals, the behaviour of F x, the accuracy demanded and the distance of the starting point from the solution. The number of multiplications performed per iteration of e04fc varies, but for m≫n is approximately n×m 2+O n 3. In addition, each iteration makes at least n+1 calls of lsqfun. So, unless the residuals can be evaluated very quickly, the run time will be dominated by the time spent in lsqfun.
Ideally, the problem should be scaled so that, at the solution, F x and the corresponding values of the xj are each in the range -1,+1, and so that at points one unit away from the solution, F x differs from its value at the solution by approximately one unit. This will usually imply that the Hessian matrix of F x at the solution is well-conditioned. It is unlikely that you will be able to follow these recommendations very closely, but it is worth trying (by guesswork), as sensible scaling will reduce the difficulty of the minimization problem, so that e04fc will take less computer time.
When the sum of squares represents the goodness-of-fit of a nonlinear model to observed data, elements of the variance-covariance matrix of the estimated regression coefficients can be computed by a subsequent call to (E04YCF not in this release), using information returned in the arrays s and v. See (E04YCF not in this release) for further details.

Example

This example finds least squares estimates of x 1,x 2 and x 3 in the model
y=x 1+t 1 x 2t 2+x 3t 3
using the 15 sets of data given in the following table.
yt 1t 2t 30.141.015.01.00.182.014.02.00.223.013.03.00.254.012.04.00.295.011.05.00.326.010.06.00.357.09.07.00.398.08.08.00.379.07.07.00.5810.06.06.00.7311.05.05.00.9612.04.04.01.3413.03.03.02.1014.02.02.04.3915.01.01.0
The program uses 0.5,1.0,1.5 as the initial guess at the position of the minimum.

Example program (C#): e04fce.cs

Example program data: e04fce.d

Example program results: e04fce.r

See Also

E04 Class
E04 Members


e04fdz Method

[image]

NAG Library for .NET Release 2
E04..::e04fdz Method
E04 Class See Also Send Feedback
Auxiliary for use as a delegate parameter

Syntax

C#
public static void e04fdz(
    int m,
    int n,
    double[] xc,
    double[] fvec,
    double[,] fjac,
    double[] s,
    int igrade,
    int niter,
    int nf
)
Visual Basic
Public Shared Sub e04fdz ( _
    m As Integer, _
    n As Integer, _
    xc As Double(), _
    fvec As Double(), _
    fjac As Double(,), _
    s As Double(), _
    igrade As Integer, _
    niter As Integer, _
    nf As Integer _
)
Visual C++
public:
static void e04fdz(
    int m,
    int n,
    array<double>^ xc,
    array<double>^ fvec,
    array<double,2>^ fjac,
    array<double>^ s,
    int igrade,
    int niter,
    int nf
)
F#
static member e04fdz :
        m : int *
        n : int *
        xc : float[] *
        fvec : float[] *
        fjac : float[,] *
        s : float[] *
        igrade : int *
        niter : int *
        nf : int -> unit

Parameters

m
Type: System..::..Int32
On entry: the numbers m and n of residuals and variables, respectively.
n
Type: System..::..Int32
On entry: the numbers m and n of residuals and variables, respectively.
xc
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the coordinates of the current point x.
fvec
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: the values of the residuals fi at the current point x.
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [ldfjac, n]
On entry: fjac[i-1,j-1] contains the value of ∂fi∂xj at the current point x, for i=1,2,…,m and j=1,2,…,n.
s
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the singular values of the current approximation to the Jacobian matrix. Thus s may be useful as information about the structure of your problem.
igrade
Type: System..::..Int32
On entry: e04fd estimates the dimension of the subspace for which the Jacobian matrix can be used as a valid approximation to the curvature (see Gill and Murray (1978)). This estimate is called the grade of the Jacobian matrix, and igrade gives its current value.
niter
Type: System..::..Int32
On entry: the number of iterations which have been performed in e04fd.
nf
Type: System..::..Int32
On entry: the number of times that _lsqfun has been called so far. (However, for intermediate calls of _lsqmon, nf is calculated on the assumption that the latest linear search has been successful. If this is not the case, then the n evaluations allowed for approximating the Jacobian at the new point will not in fact have been made. nf will be accurate at the final call of _lsqmon.)

Description

Auxiliary for use as a delegate parameter

References

Gill P E and Murray W (1978) Algorithms for the solution of the nonlinear least squares problem SIAM J. Numer. Anal. 15 977–992

Error Indicators and Warnings

None.

Accuracy

Not applicable.

Further Comments

None.

Example

None.

See Also

E04 Class
E04 Members


e04fy Method

[image]

NAG Library for .NET Release 2
E04..::e04fy Method
E04 Class See Also Send Feedback
e04fy is an easy-to-use algorithm for finding an unconstrained minimum of a sum of squares of m nonlinear functions in n variables m≥n. No derivatives are required.
It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).

Syntax

C#
public static void e04fy(
    int m,
    int n,
    E04..::..E04FY_LSFUN1 lsfun1,
    double[] x,
    out double fsumsq,
    out int ifail
)
Visual Basic
Public Shared Sub e04fy ( _
    m As Integer, _
    n As Integer, _
    lsfun1 As E04..::..E04FY_LSFUN1, _
    x As Double(), _
    <OutAttribute> ByRef fsumsq As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04fy(
    int m,
    int n,
    E04..::..E04FY_LSFUN1^ lsfun1,
    array<double>^ x,
    [OutAttribute] double% fsumsq,
    [OutAttribute] int% ifail
)
F#
static member e04fy :
        m : int *
        n : int *
        lsfun1 : E04..::..E04FY_LSFUN1 *
        x : float[] *
        fsumsq : float byref *
        ifail : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: the number m of residuals, fi x, and the number n of variables, xj.
Constraint: 1≤n≤m.
n
Type: System..::..Int32
On entry: the number m of residuals, fi x, and the number n of variables, xj.
Constraint: 1≤n≤m.
lsfun1
Type: NagLibrary..::..E04..::..E04FY_LSFUN1
You must supply this method to calculate the vector of values fi x at any point x. It should be tested separately before being used in conjunction with e04fy (see the E04 class).

A delegate of type E04FY_LSFUN1.

x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x[j-1] must be set to a guess at the jth component of the position of the minimum, for j=1,2,…,n.
On exit: the lowest point found during the calculations. Thus, if ifail=0 on exit, x[j-1] is the jth component of the position of the minimum.
fsumsq
Type: System..::..Double %
On exit: the value of the sum of squares, F x, corresponding to the final point stored in x.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04fy is essentially identical to the method LSNDN1 in the NPL Algorithms Library. It is applicable to problems of the form
MinimizeF x=∑i=1 m fi x 2
where x=x 1,x 2,…,xn T and m≥n. (The functions fi x are often referred to as ‘residuals’.)
You must supply a method to evaluate functions fi x at any point x.
From a starting point supplied by you, a sequence of points is generated which is intended to converge to a local minimum of the sum of squares. These points are generated using estimates of the curvature of F x.

References

Gill P E and Murray W (1978) Algorithms for the solution of the nonlinear least squares problem SIAM J. Numer. Anal. 15 977–992

Error Indicators and Warnings

Note: e04fy may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail=1
On entry, | n<1,
or | m<n,
or | lw<7×n+n×n+2×m×n+3×m+n×n-1/2, when n>1,
or | lw<9+5×m, when n=1.
ifail=2
There have been 400×n calls of lsfun1, yet the algorithm does not seem to have converged. This may be due to an awkward function or to a poor starting point, so it is worth restarting e04fy from the final point held in x.
ifail=3
The final point does not satisfy the conditions for acceptance as a minimum, but no lower point could be found.
ifail=4
An auxiliary method has been unable to complete a singular value decomposition in a reasonable number of sub-iterations.
ifail=5
ifail=6
ifail=7
ifail=8
There is some doubt about whether the point x x found by e04fy is a minimum of F x. The degree of confidence in the result decreases as ifail increases. Thus, when ifail=5, it is probable that the final x gives a good estimate of the position of a minimum, but when ifail=8 it is very unlikely that the method has found a minimum.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
If you are not satisfied with the result (e.g., because ifail lies between 3 and 8), it is worth restarting the calculations from a different starting point (not the point at which the failure occurred) in order to avoid the region which caused the failure. Repeated failure may indicate some defect in the formulation of the problem.

Accuracy

If the problem is reasonably well scaled and a successful exit is made, then, for a computer with a mantissa of t decimals, one would expect to get about t/2-1 decimals accuracy in the components of x and between t-1 (if F x is of order 1 at the minimum) and 2 t-2 (if F x is close to zero at the minimum) decimals accuracy in F x.

Parallelism and Performance

None.

Further Comments

The number of iterations required depends on the number of variables, the number of residuals and their behaviour, and the distance of the starting point from the solution. The number of multiplications performed per iteration of e04fy varies, but for m≫n is approximately n×m 2+O n 3. In addition, each iteration makes at least n+1 calls of lsfun1. So, unless the residuals can be evaluated very quickly, the run time will be dominated by the time spent in lsfun1.
Ideally, the problem should be scaled so that the minimum value of the sum of squares is in the range 0,+1, and so that at points a unit distance away from the solution the sum of squares is approximately a unit value greater than at the minimum. It is unlikely that you will be able to follow these recommendations very closely, but it is worth trying (by guesswork), as sensible scaling will reduce the difficulty of the minimization problem, so that e04fy will take less computer time.
When the sum of squares represents the goodness-of-fit of a nonlinear model to observed data, elements of the variance-covariance matrix of the estimated regression coefficients can be computed by a subsequent call to (E04YCF not in this release), using information returned in segments of the workspace array w. See (E04YCF not in this release) for further details.

Example

This example finds least squares estimates of x 1, x 2 and x 3 in the model
y=x 1+t 1 x 2t 2+x 3t 3
using the 15 sets of data given in the following table.
y 0t 1 0t 2 0t 3 00.141.015.01.00.182.014.02.00.223.013.03.00.254.012.04.00.295.011.05.00.326.010.06.00.357.09.07.00.398.08.08.00.379.07.07.00.5810.06.06.00.7311.05.05.00.9612.04.04.01.3413.03.03.02.1014.02.02.04.3915.01.01.0
The program uses 0.5,1.0,1.5 as the initial guess at the position of the minimum.

Example program (C#): e04fye.cs

Example program data: e04fye.d

Example program results: e04fye.r

See Also

E04 Class
E04 Members


e04gd Method

[image]

NAG Library for .NET Release 2
E04..::e04gd Method
E04 Class See Also Send Feedback
e04gd is a comprehensive modified Gauss–Newton algorithm for finding an unconstrained minimum of a sum of squares of m nonlinear functions in n variables m≥n. First derivatives are required.
The method is intended for functions which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).

Syntax

C#
public static void e04gd(
    int m,
    int n,
    E04..::..E04GD_LSQFUN lsqfun,
    E04..::..E04GD_LSQMON lsqmon,
    int iprint,
    int maxcal,
    double eta,
    double xtol,
    double stepmx,
    double[] x,
    out double fsumsq,
    double[] fvec,
    double[,] fjac,
    double[] s,
    double[,] v,
    out int niter,
    out int nf,
    out int ifail
)
Visual Basic
Public Shared Sub e04gd ( _
    m As Integer, _
    n As Integer, _
    lsqfun As E04..::..E04GD_LSQFUN, _
    lsqmon As E04..::..E04GD_LSQMON, _
    iprint As Integer, _
    maxcal As Integer, _
    eta As Double, _
    xtol As Double, _
    stepmx As Double, _
    x As Double(), _
    <OutAttribute> ByRef fsumsq As Double, _
    fvec As Double(), _
    fjac As Double(,), _
    s As Double(), _
    v As Double(,), _
    <OutAttribute> ByRef niter As Integer, _
    <OutAttribute> ByRef nf As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04gd(
    int m,
    int n,
    E04..::..E04GD_LSQFUN^ lsqfun,
    E04..::..E04GD_LSQMON^ lsqmon,
    int iprint,
    int maxcal,
    double eta,
    double xtol,
    double stepmx,
    array<double>^ x,
    [OutAttribute] double% fsumsq,
    array<double>^ fvec,
    array<double,2>^ fjac,
    array<double>^ s,
    array<double,2>^ v,
    [OutAttribute] int% niter,
    [OutAttribute] int% nf,
    [OutAttribute] int% ifail
)
F#
static member e04gd :
        m : int *
        n : int *
        lsqfun : E04..::..E04GD_LSQFUN *
        lsqmon : E04..::..E04GD_LSQMON *
        iprint : int *
        maxcal : int *
        eta : float *
        xtol : float *
        stepmx : float *
        x : float[] *
        fsumsq : float byref *
        fvec : float[] *
        fjac : float[,] *
        s : float[] *
        v : float[,] *
        niter : int byref *
        nf : int byref *
        ifail : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: the number m of residuals, fi x, and the number n of variables, xj.
Constraint: 1≤n≤m.
n
Type: System..::..Int32
On entry: the number m of residuals, fi x, and the number n of variables, xj.
Constraint: 1≤n≤m.
lsqfun
Type: NagLibrary..::..E04..::..E04GD_LSQFUN
lsqfun must calculate the vector of values fi x and Jacobian matrix of first derivatives ∂fi∂xj at any point x. (However, if you do not wish to calculate the residuals or first derivatives at a particular x, there is the option of setting a parameter to cause e04gd to terminate immediately.)

A delegate of type E04GD_LSQFUN.

Note: lsqfun should be tested separately before being used in conjunction with e04gd.
lsqmon
Type: NagLibrary..::..E04..::..E04GD_LSQMON
If iprint≥0, you must supply lsqmon which is suitable for monitoring the minimization process. lsqmon must not change the values of any of its parameters.
If iprint<0, the dummy method E04FDZ can be used as lsqmon.

A delegate of type E04GD_LSQMON.

Note: you should normally print the sum of squares of residuals, so as to be able to examine the sequence of values of F x mentioned in [Accuracy]. It is usually also helpful to print xc, the gradient of the sum of squares, niter and nf.
iprint
Type: System..::..Int32
On entry: the frequency with which lsqmon is to be called.
iprint>0
lsqmon is called once every iprint iterations and just before exit from e04gd.
iprint=0
lsqmon is just called at the final point.
iprint<0
lsqmon is not called at all.
iprint should normally be set to a small positive number.
Suggested value: iprint=1.
maxcal
Type: System..::..Int32
On entry: enables you to limit the number of times that lsqfun is called by e04gd. There will be an error exit (see [Error Indicators and Warnings]) after maxcal evaluations of the residuals (i.e., calls of lsqfun with iflag set to 2). It should be borne in mind that, in addition to the calls of lsqfun which are limited directly by maxcal, there will be calls of lsqfun (with iflag set to 1) to evaluate only first derivatives.
Suggested value: maxcal=50×n.
Constraint: maxcal≥1.
eta
Type: System..::..Double
On entry: every iteration of e04gd involves a linear minimization, i.e., minimization of F x k+α kp k with respect to α k. eta specifies how accurately these linear minimizations are to be performed. The minimum with respect to α k will be located more accurately for small values of eta (say, 0.01) than for large values (say, 0.9).
Although accurate linear minimizations will generally reduce the number of iterations, they will tend to increase the number of calls of lsqfun (with iflag set to 2) needed for each linear minimization. On balance it is usually efficient to perform a low accuracy linear minimization.
Suggested value: eta=0.5 (eta=0.0 if n=1).
Constraint: 0.0≤eta<1.0.
xtol
Type: System..::..Double
On entry: the accuracy in x to which the solution is required.
If xtrue is the true value of x at the minimum, then xsol, the estimated position before a normal exit, is such that
xsol-xtrue<xtol×1.0+xtrue
where y=∑j=1 n yj 2. For example, if the elements of xsol are not much larger than 1.0 in modulus and if xtol=1.0E−5, then xsol is usually accurate to about five decimal places. (For further details see [Accuracy].)
If F x and the variables are scaled roughly as described in [Further Comments] and ε is the machine precision, then a setting of order xtol=ε will usually be appropriate. If xtol is set to 0.0 or some positive value less than 10 ε, e04gd will use 10 ε instead of xtol, since 10 ε is probably the smallest reasonable setting.
Constraint: xtol≥0.0.
stepmx
Type: System..::..Double
On entry: an estimate of the Euclidean distance between the solution and the starting point supplied by you. (For maximum efficiency, a slight overestimate is preferable.) e04gd will ensure that, for each iteration,
∑j=1 n xj k-xj k-1 2≤stepmx 2
where k is the iteration number. Thus, if the problem has more than one solution, e04gd is most likely to find the one nearest to the starting point. On difficult problems, a realistic choice can prevent the sequence of x k entering a region where the problem is ill-behaved and can help avoid overflow in the evaluation of F x. However, an underestimate of stepmx can lead to inefficiency.
Suggested value: stepmx=100000.0.
Constraint: stepmx≥xtol.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x[j-1] must be set to a guess at the jth component of the position of the minimum, for j=1,2,…,n.
On exit: the final point x k. Thus, if ifail=0 on exit, x[j-1] is the jth component of the estimated position of the minimum.
fsumsq
Type: System..::..Double %
On exit: the value of F x, the sum of squares of the residuals fi x, at the final point given in x.
fvec
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: the value of the residual fi x at the final point given in x, for i=1,2,…,m.
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: the value of the first derivative ∂fi∂xj evaluated at the final point given in x, for i=1,2,…,m and j=1,2,…,n.
s
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the singular values of the Jacobian matrix at the final point. Thus s may be useful as information about the structure of your problem.
v
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: the matrix V associated with the singular value decomposition
J=US VT
of the Jacobian matrix at the final point, stored by columns. This matrix may be useful for statistical purposes, since it is the matrix of orthonormalized eigenvectors of JT J.
niter
Type: System..::..Int32 %
On exit: the number of iterations which have been performed in e04gd.
nf
Type: System..::..Int32 %
On exit: the number of times that the residuals have been evaluated (i.e., number of calls of lsqfun with iflag set to 2).
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04gd is essentially identical to the method LSQFDN in the NPL Algorithms Library. It is applicable to problems of the form
Minimize F x=∑i=1 m fi x 2
where x=x 1,x 2,…,xn T and m≥n. (The functions fi x are often referred to as ‘residuals’.)
You must supply a method to calculate the values of the fi x and their first derivatives ∂fi∂xj at any point x.
From a starting point x 1 supplied by you, the method generates a sequence of points x 2,x 3,…, which is intended to converge to a local minimum of F x. The sequence of points is given by
x k+1=x k+α kp k
where the vector p k is a direction of search, and α k is chosen such that F x k+α kp k is approximately a minimum with respect to α k.
The vector p k used depends upon the reduction in the sum of squares obtained during the last iteration. If the sum of squares was sufficiently reduced, then p k is the Gauss–Newton direction; otherwise finite difference estimates of the second derivatives of the fi x are taken into account.
The method is designed to ensure that steady progress is made whatever the starting point, and to have the rapid ultimate convergence of Newton's method.

References

Gill P E and Murray W (1978) Algorithms for the solution of the nonlinear least squares problem SIAM J. Numer. Anal. 15 977–992

Error Indicators and Warnings

Note: e04gd may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDFJAC, LDV, IW, LIW, W, LW) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail<0
A negative value of ifail indicates an exit from e04gd because you have set iflag negative in lsqfun. The value of ifail will be the same as your setting of iflag.
ifail=1
On entry, | n<1,
or | m<n,
or | maxcal<1,
or | eta<0.0,
or | eta≥1.0,
or | xtol<0.0,
or | stepmx<xtol,
When this exit occurs, no values will have been assigned to fsumsq, or to the elements of fvec, fjac, s or v.
ifail=2
There have been maxcal evaluations of the residuals. If steady reductions in the sum of squares, F x, were monitored up to the point where this exit occurred, then the exit probably occurred simply because maxcal was set too small, so the calculations should be restarted from the final point held in x. This exit may also indicate that F x has no minimum.
ifail=3
The conditions for a minimum have not all been satisfied, but a lower point could not be found. This could be because xtol has been set so small that rounding errors in the evaluation of the residuals and derivatives make attainment of the convergence conditions impossible.
ifail=4
The method for computing the singular value decomposition of the Jacobian matrix has failed to converge in a reasonable number of sub-iterations. It may be worth applying e04gd again starting with an initial approximation which is not too close to the point at which the failure occurred.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
The values ifail=2, 3 or 4 may also be caused by mistakes in lsqfun, by the formulation of the problem or by an awkward function. If there are no such mistakes it is worth restarting the calculations from a different starting point (not the point at which the failure occurred) in order to avoid the region which caused the failure.

Accuracy

A successful exit (ifail=0) is made from e04gd when the matrix of approximate second derivatives of F x is positive definite, and when (B1, B2 and B3) or B4 or B5 hold, where
B1≡α k×p k<xtol+ε×1.0+x kB2≡F k-F k-1<xtol+ε 2×1.0+F kB3≡g k<ε 1/3×1.0+F kB4≡F k<ε 2B5≡g k<ε×F k 1/2
and where . and ε are as defined in xtol, and F k and g k are the values of F x and its vector of estimated first derivatives at x k.
If ifail=0 then the vector in x on exit, xsol, is almost certainly an estimate of xtrue, the position of the minimum to the accuracy specified by xtol.
If ifail=3, then xsol may still be a good estimate of xtrue, but to verify this you should make the following checks. If
(a) | the sequence F x k converges to F xsol at a superlinear or a fast linear rate, and
(b) | g xsol T g xsol<10 ε, where T denotes transpose, then it is almost certain that xsol is a close approximation to the minimum.
When (b) is true, then usually F xsol is a close approximation to F xtrue. The values of F x k can be calculated in lsqmon, and the vector g xsol can be calculated from the contents of fvec and fjac on exit from e04gd.
Further suggestions about confirmation of a computed solution are given in the E04 class.

Parallelism and Performance

None.

Further Comments

The number of iterations required depends on the number of variables, the number of residuals, the behaviour of F x, the accuracy demanded and the distance of the starting point from the solution. The number of multiplications performed per iteration of e04gd varies, but for m≫n is approximately n×m 2+O n 3. In addition, each iteration makes at least one call of lsqfun. So, unless the residuals and their derivatives can be evaluated very quickly, the run time will be dominated by the time spent in lsqfun.
Ideally, the problem should be scaled so that, at the solution, F x and the corresponding values of the xj are each in the range -1,+1, and so that at points one unit away from the solution, F x differs from its value at the solution by approximately one unit. This will usually imply that the Hessian matrix of F x at the solution is well-conditioned. It is unlikely that you will be able to follow these recommendations very closely, but it is worth trying (by guesswork), as sensible scaling will reduce the difficulty of the minimization problem, so that e04gd will take less computer time.
When the sum of squares represents the goodness-of-fit of a nonlinear model to observed data, elements of the variance-covariance matrix of the estimated regression coefficients can be computed by a subsequent call to (E04YCF not in this release), using information returned in the arrays s and v. See (E04YCF not in this release) for further details.

Example

Example program (C#): e04gde.cs

Example program data: e04gde.d

Example program results: e04gde.r

See Also

E04 Class
E04 Members


e04gy Method

[image]

NAG Library for .NET Release 2
E04..::e04gy Method
E04 Class See Also Send Feedback
e04gy is an easy-to-use quasi-Newton algorithm for finding an unconstrained minimum of a sum of squares of m nonlinear functions in n variables m≥n. First derivatives are required.
It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).

Syntax

C#
public static void e04gy(
    int m,
    int n,
    E04..::..E04GY_LSFUN2 lsfun2,
    double[] x,
    out double fsumsq,
    out int ifail
)
Visual Basic
Public Shared Sub e04gy ( _
    m As Integer, _
    n As Integer, _
    lsfun2 As E04..::..E04GY_LSFUN2, _
    x As Double(), _
    <OutAttribute> ByRef fsumsq As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04gy(
    int m,
    int n,
    E04..::..E04GY_LSFUN2^ lsfun2,
    array<double>^ x,
    [OutAttribute] double% fsumsq,
    [OutAttribute] int% ifail
)
F#
static member e04gy :
        m : int *
        n : int *
        lsfun2 : E04..::..E04GY_LSFUN2 *
        x : float[] *
        fsumsq : float byref *
        ifail : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: the number m of residuals, fi x, and the number n of variables, xj.
Constraint: 1≤n≤m.
n
Type: System..::..Int32
On entry: the number m of residuals, fi x, and the number n of variables, xj.
Constraint: 1≤n≤m.
lsfun2
Type: NagLibrary..::..E04..::..E04GY_LSFUN2
You must supply this method to calculate the vector of values fi x and the Jacobian matrix of first derivatives ∂fi∂xj at any point x. It should be tested separately before being used in conjunction with e04gy (see the E04 class).

A delegate of type E04GY_LSFUN2.

x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x[j-1] must be set to a guess at the jth component of the position of the minimum, for j=1,2,…,n. The method checks the first derivatives calculated by lsfun2 at the starting point and so is more likely to detect an error in your method if the initial x[j-1] are nonzero and mutually distinct.
On exit: the lowest point found during the calculations. Thus, if ifail=0 on exit, x[j-1] is the jth component of the position of the minimum.
fsumsq
Type: System..::..Double %
On exit: the value of the sum of squares, F x, corresponding to the final point stored in x.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04gy is similar to the method LSFDQ2 in the NPL Algorithms Library. It is applicable to problems of the form
Minimize F x=∑i=1 m fi x 2
where x=x 1,x 2,…,xn T and m≥n. (The functions fi x are often referred to as ‘residuals’.) You must supply a method to evaluate the residuals and their first derivatives at any point x.
Before attempting to minimize the sum of squares, the algorithm checks the method for consistency. Then, from a starting point supplied by you, a sequence of points is generated which is intended to converge to a local minimum of the sum of squares. These points are generated using estimates of the curvature of F x.

References

Gill P E and Murray W (1978) Algorithms for the solution of the nonlinear least squares problem SIAM J. Numer. Anal. 15 977–992

Error Indicators and Warnings

Note: e04gy may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail=1
On entry, | n<1,
or | m<n,
or | lw<8×n+2×n×n+2×m×n+3×m, when n>1,
or | lw<11+5×m, when n=1.
ifail=2
There have been 50×n calls of lsfun2, yet the algorithm does not seem to have converged. This may be due to an awkward function or to a poor starting point, so it is worth restarting e04gy from the final point held in x.
ifail=3
The final point does not satisfy the conditions for acceptance as a minimum, but no lower point could be found.
ifail=4
An auxiliary method has been unable to complete a singular value decomposition in a reasonable number of sub-iterations.
ifail=5
ifail=6
ifail=7
ifail=8
There is some doubt about whether the point x x found by e04gy is a minimum of F x. The degree of confidence in the result decreases as ifail increases. Thus, when ifail=5, it is probable that the final x gives a good estimate of the position of a minimum, but when ifail=8 it is very unlikely that the method has found a minimum.
ifail=9
It is very likely that you have made an error in forming the derivatives ∂fi∂xj in lsfun2.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
If you are not satisfied with the result (e.g., because ifail lies between 3 and 8), it is worth restarting the calculations from a different starting point (not the point at which the failure occurred) in order to avoid the region which caused the failure. Repeated failure may indicate some defect in the formulation of the problem.

Accuracy

If the problem is reasonably well scaled and a successful exit is made then, for a computer with a mantissa of t decimals, one would expect to get t/2-1 decimals accuracy in the components of x and between t-1 (if F x is of order 1 at the minimum) and 2 t-2 (if F x is close to zero at the minimum) decimals accuracy in F x.

Parallelism and Performance

None.

Further Comments

The number of iterations required depends on the number of variables, the number of residuals and their behaviour, and the distance of the starting point from the solution. The number of multiplications performed per iteration of e04gy varies, but for m≫n is approximately n×m 2+O n 3. In addition, each iteration makes at least one call of lsfun2. So, unless the residuals and their derivatives can be evaluated very quickly, the run time will be dominated by the time spent in lsfun2.
Ideally the problem should be scaled so that the minimum value of the sum of squares is in the range 0,1 and so that at points a unit distance away from the solution the sum of squares is approximately a unit value greater than at the minimum. It is unlikely that you will be able to follow these recommendations very closely, but it is worth trying (by guesswork), as sensible scaling will reduce the difficulty of the minimization problem, so that e04gy will take less computer time.
When the sum of squares represents the goodness-of-fit of a nonlinear model to observed data, elements of the variance-covariance matrix of the estimated regression coefficients can be computed by a subsequent call to (E04YCF not in this release), using information returned in segments of the workspace array w. See (E04YCF not in this release) for further details.

Example

This example finds the least squares estimates of x 1, x 2 and x 3 in the model
y=x 1+t 1 x 2t 2+x 3t 3
using the 15 sets of data given in the following table.
yt 1t 2t 30.141.015.01.00.182.014.02.00.223.013.03.00.254.012.04.00.295.011.05.00.326.010.06.00.357.09.07.00.398.08.08.00.379.07.07.00.5810.06.06.00.7311.05.05.00.9612.04.04.01.3413.03.03.02.1014.02.02.04.3915.01.01.0
The program uses 0.5,1.0,1.5 as the initial guess at the position of the minimum.

Example program (C#): e04gye.cs

Example program data: e04gye.d

Example program results: e04gye.r

See Also

E04 Class
E04 Members


e04gz Method

[image]

NAG Library for .NET Release 2
E04..::e04gz Method
E04 Class See Also Send Feedback
e04gz is an easy-to-use modified Gauss–Newton algorithm for finding an unconstrained minimum of a sum of squares of m nonlinear functions in n variables m≥n. First derivatives are required.
It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).

Syntax

C#
public static void e04gz(
    int m,
    int n,
    E04..::..E04GZ_LSFUN2 lsfun2,
    double[] x,
    out double fsumsq,
    out int ifail
)
Visual Basic
Public Shared Sub e04gz ( _
    m As Integer, _
    n As Integer, _
    lsfun2 As E04..::..E04GZ_LSFUN2, _
    x As Double(), _
    <OutAttribute> ByRef fsumsq As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04gz(
    int m,
    int n,
    E04..::..E04GZ_LSFUN2^ lsfun2,
    array<double>^ x,
    [OutAttribute] double% fsumsq,
    [OutAttribute] int% ifail
)
F#
static member e04gz :
        m : int *
        n : int *
        lsfun2 : E04..::..E04GZ_LSFUN2 *
        x : float[] *
        fsumsq : float byref *
        ifail : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: the number m of residuals, fi x, and the number n of variables, xj.
Constraint: 1≤n≤m.
n
Type: System..::..Int32
On entry: the number m of residuals, fi x, and the number n of variables, xj.
Constraint: 1≤n≤m.
lsfun2
Type: NagLibrary..::..E04..::..E04GZ_LSFUN2
You must supply this method to calculate the vector of values fi x and the Jacobian matrix of first derivatives ∂fi∂xj at any point x. It should be tested separately before being used in conjunction with e04gz.

A delegate of type E04GZ_LSFUN2.

x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x[j-1] must be set to a guess at the jth component of the position of the minimum, for j=1,2,…,n. The method checks the first derivatives calculated by lsfun2 at the starting point and so is more likely to detect any error in your methods if the initial x[j-1] are nonzero and mutually distinct.
On exit: the lowest point found during the calculations. Thus, if ifail=0 on exit, x[j-1] is the jth component of the position of the minimum.
fsumsq
Type: System..::..Double %
On exit: the value of the sum of squares, F x, corresponding to the final point stored in x.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04gz is similar to the method LSFDN2 in the NPL Algorithms Library. It is applicable to problems of the form
Minimize F x=∑i=1 m fi x 2
where x=x 1,x 2,…,xn T and m≥n. (The functions fi x are often referred to as ‘residuals’.)
You must supply a method to evaluate the residuals and their first derivatives at any point x.
Before attempting to minimize the sum of squares, the algorithm checks the method for consistency. Then, from a starting point supplied by you, a sequence of points is generated which is intended to converge to a local minimum of the sum of squares. These points are generated using estimates of the curvature of F x.

References

Gill P E and Murray W (1978) Algorithms for the solution of the nonlinear least squares problem SIAM J. Numer. Anal. 15 977–992

Error Indicators and Warnings

Note: e04gz may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail=1
On entry, | n<1,
or | m<n,
or | lw<8×n+2×n×n+2×m×n+3×m, when n>1,
or | lw<11+5×m, when n=1.
ifail=2
There have been 50×n calls of lsfun2, yet the algorithm does not seem to have converged. This may be due to an awkward function or to a poor starting point, so it is worth restarting e04gz from the final point held in x.
ifail=3
The final point does not satisfy the conditions for acceptance as a minimum, but no lower point could be found.
ifail=4
An auxiliary method has been unable to complete a singular value decomposition in a reasonable number of sub-iterations.
ifail=5
ifail=6
ifail=7
ifail=8
There is some doubt about whether the point x x found by e04gz is a minimum of F x. The degree of confidence in the result decreases as ifail increases. Thus, when ifail=5, it is probable that the final x gives a good estimate of the position of a minimum, but when ifail=8 it is very unlikely that the method has found a minimum.
ifail=9
It is very likely that you have made an error in forming the derivatives ∂fi∂xj in lsfun2.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
If you are not satisfied with the result (e.g., because ifail lies between 3 and 8), it is worth restarting the calculations from a different starting point (not the point at which the failure occurred) in order to avoid the region which caused the failure. Repeated failure may indicate some defect in the formulation of the problem.

Accuracy

If the problem is reasonably well scaled and a successful exit is made, then, for a computer with a mantissa of t decimals, one would expect to get about t/2-1 decimals accuracy in the components of x and between t-1 (if F x is of order 1 at the minimum) and 2 t-2 (if F x is close to zero at the minimum) decimals accuracy in F x.

Parallelism and Performance

None.

Further Comments

The number of iterations required depends on the number of variables, the number of residuals and their behaviour, and the distance of the starting point from the solution. The number of multiplications performed per iteration of e04gz varies, but for m≫n is approximately n×m 2+O n 3. In addition, each iteration makes at least one call of lsfun2. So, unless the residuals and their derivatives can be evaluated very quickly, the run time will be dominated by the time spent in lsfun2.
Ideally, the problem should be scaled so that the minimum value of the sum of squares is in the range 0,+1 and so that at points a unit distance away from the solution the sum of squares is approximately a unit value greater than at the minimum. It is unlikely that you will be able to follow these recommendations very closely, but it is worth trying (by guesswork), as sensible scaling will reduce the difficulty of the minimization problem, so that e04gz will take less computer time.
When the sum of squares represents the goodness-of-fit of a nonlinear model to observed data, elements of the variance-covariance matrix of the estimated regression coefficients can be computed by a subsequent call to (E04YCF not in this release), using information returned in segments of the workspace array w. See (E04YCF not in this release) for further details.

Example

This example finds least squares estimates of x 1, x 2 and x 3 in the model
y=x 1+t 1 x 2t 2+x 3t 3
using the 15 sets of data given in the following table.
yt 1t 2t 30.141.015.01.00.182.014.02.00.223.013.03.00.254.012.04.00.295.011.05.00.326.010.06.00.357.09.07.00.398.08.08.00.379.07.07.00.5810.06.06.00.7311.05.05.00.9612.04.04.01.3413.03.03.02.1014.02.02.04.3915.01.01.0
The program uses 0.5,1.0,1.5 as the initial guess at the position of the minimum.

Example program (C#): e04gze.cs

Example program data: e04gze.d

Example program results: e04gze.r

See Also

E04 Class
E04 Members


e04hc Method

[image]

NAG Library for .NET Release 2
E04..::e04hc Method
E04 Class See Also Send Feedback
e04hc checks that a method for evaluating an objective function and its first derivatives produces derivative values which are consistent with the function values calculated.

Syntax

C#
public static void e04hc(
    int n,
    E04..::..E04HC_FUNCT funct,
    double[] x,
    out double f,
    double[] g,
    out int ifail
)
Visual Basic
Public Shared Sub e04hc ( _
    n As Integer, _
    funct As E04..::..E04HC_FUNCT, _
    x As Double(), _
    <OutAttribute> ByRef f As Double, _
    g As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04hc(
    int n,
    E04..::..E04HC_FUNCT^ funct,
    array<double>^ x,
    [OutAttribute] double% f,
    array<double>^ g,
    [OutAttribute] int% ifail
)
F#
static member e04hc :
        n : int *
        funct : E04..::..E04HC_FUNCT *
        x : float[] *
        f : float byref *
        g : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: the number n of independent variables in the objective function.
Constraint: n≥1.
funct
Type: NagLibrary..::..E04..::..E04HC_FUNCT
funct must evaluate the function and its first derivatives at a given point. (The minimization methods mentioned in [Description] gives you the option of resetting parameters of funct to cause the minimization process to terminate immediately. e04hc will also terminate immediately, without finishing the checking process, if the parameter in question is reset.)

A delegate of type E04HC_FUNCT.

x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x[j-1], for j=1,2,…,n, must be set to the coordinates of a suitable point at which to check the derivatives calculated by funct. ‘Obvious’ settings, such as 0.0​ or ​1.0, should not be used since, at such particular points, incorrect terms may take correct values (particularly zero), so that errors could go undetected. Similarly, it is preferable that no two elements of x should be the same.
f
Type: System..::..Double %
On exit: unless you set iflag negative in the first call of funct, f contains the value of the objective function F x at the point given by you in x.
g
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: unless you set iflag negative in the first call of funct, g[j-1] contains the value of the derivative ∂F∂xj at the point given in x, as calculated by funct, for j=1,2,…,n.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Routines for minimizing a function of several variables may require you to supply a method to evaluate the objective function F x 1,x 2,…,xn and its first derivatives. e04hc is designed to check the derivatives calculated by such user-supplied delegates . As well as the method to be checked ( funct), you must supply a point x=x 1,x 2,…,xn T at which the check will be made. Note that e04hc checks methods of the form required for e04kd and e04lb.
e04hc first calls funct to evaluate F and its first derivatives gj=∂F∂xj, for j=1,2,…,n at x. The components of the user-supplied derivatives along two orthogonal directions (defined by unit vectors p 1 and p 2, say) are then calculated; these will be gT p 1 and gT p 2 respectively. The same components are also estimated by finite differences, giving quantities
vk=F x+h pk-F x h,  k=1,2
where h is a small positive scalar. If the relative difference between v 1 and gT p 1 or between v 2 and gT p 2 is judged too large, an error indicator is set.

References

None.

Error Indicators and Warnings

Note: e04hc may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail<0
A negative value of ifail indicates an exit from e04hc because you have set iflag negative in funct. The setting of ifail will be the same as your setting of iflag. The check on funct will not have been completed.
ifail=1
On entry, | n<1,
or | liw<1,
or | lw<3×n.
ifail=2
You should check carefully the derivation and programming of expressions for the derivatives of F x, because it is very unlikely that funct is calculating them correctly.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

ifail is set to 2 if
vk-gT pk 2≥h×gT pk 2+1
for k=1​ or ​2. (See [Description] for definitions of the quantities involved.) The scalar h is set equal to ε, where ε is the machine precision as given by x02aj.

Parallelism and Performance

None.

Further Comments

funct is called 3 times.
Before using e04hc to check the calculation of first derivatives, you should be confident that funct is calculating F correctly. The usual way of checking the calculation of the function is to compare values of F x calculated by funct at nontrivial points x with values calculated independently. (‘Non-trivial’ means that, as when setting x before calling e04hc, coordinates such as 0.0 or 1.0 should be avoided.)
e04hc only checks the derivatives calculated when iflag=2. So, if funct is intended for use in conjunction with a minimization method which may set iflag to 1, you must check that, for given settings of the xc[j-1], funct produces the same values for the gc[j-1] when iflag is set to 1 as when iflag is set to 2.

Example

Example program (C#): e04hce.cs

Example program results: e04hce.r

See Also

E04 Class
E04 Members


e04hd Method

[image]

NAG Library for .NET Release 2
E04..::e04hd Method
E04 Class See Also Send Feedback
e04hd checks that a method for calculating second derivatives of an objective function is consistent with a method for calculating the corresponding first derivatives.

Syntax

C#
public static void e04hd(
    int n,
    E04..::..E04HD_FUNCT funct,
    E04..::..E04HD_H h,
    double[] x,
    double[] g,
    double[] hesl,
    double[] hesd,
    out int ifail
)
Visual Basic
Public Shared Sub e04hd ( _
    n As Integer, _
    funct As E04..::..E04HD_FUNCT, _
    h As E04..::..E04HD_H, _
    x As Double(), _
    g As Double(), _
    hesl As Double(), _
    hesd As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04hd(
    int n,
    E04..::..E04HD_FUNCT^ funct,
    E04..::..E04HD_H^ h,
    array<double>^ x,
    array<double>^ g,
    array<double>^ hesl,
    array<double>^ hesd,
    [OutAttribute] int% ifail
)
F#
static member e04hd :
        n : int *
        funct : E04..::..E04HD_FUNCT *
        h : E04..::..E04HD_H *
        x : float[] *
        g : float[] *
        hesl : float[] *
        hesd : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: the number n of independent variables in the objective function.
Constraint: n≥1.
funct
Type: NagLibrary..::..E04..::..E04HD_FUNCT
funct must evaluate the function and its first derivatives at a given point. (e04lb gives you the option of resetting parameters of funct to cause the minimization process to terminate immediately. e04hd will also terminate immediately, without finishing the checking process, if the parameter in question is reset.)

A delegate of type E04HD_FUNCT.

e04hc should be used to check the first derivatives calculated by funct before e04hd is used to check the second derivatives, since e04hd assumes that the first derivatives are correct.
h
Type: NagLibrary..::..E04..::..E04HD_H
h must evaluate the second derivatives of the function at a given point. (As with funct, a parameter can be set to cause immediate termination.)

A delegate of type E04HD_H.

x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x[j-1], for j=1,2,…,n must contain the coordinates of a suitable point at which to check the derivatives calculated by funct. ‘Obvious’ settings, such as 0.0​ or ​1.0, should not be used since, at such particular points, incorrect terms may take correct values (particularly zero), so that errors could go undetected. Similarly, it is advisable that no two elements of x should be the same.
g
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: unless you set iflag negative in the first call of funct, g[j-1] contains the value of the first derivative ∂F∂xj at the point given in x, as calculated by funct, for j=1,2,…,n.
hesl
Type: array< System..::..Double >[]()[][]
An array of size [lh]
On exit: unless you set iflag negative in h, hesl contains the strict lower triangle of the second derivative matrix of F, as evaluated by h at the point given in x, stored by rows.
hesd
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: unless you set iflag negative in h, hesd contains the diagonal elements of the second derivative matrix of F, as evaluated by h at the point given in x.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Routines for minimizing a function F x 1,x 2,…,xn of the variables x 1,x 2,…,xn may require you to provide a method to evaluate the second derivatives of F. e04hd is designed to check the second derivatives calculated by such user-supplied delegates. As well as the method to be checked (h), you must supply a method (funct) to evaluate the first derivatives, and a point x=x 1,x 2,…,xn T at which the checks will be made. Note that e04hd checks methods of the form required for e04lb.
e04hd first calls user-supplied delegates funct and h to evaluate the first and second derivatives of F at x. The user-supplied Hessian matrix (H, say) is projected onto two orthogonal vectors y and z to give the scalars yT Hy and zT Hz respectively. The same projections of the Hessian matrix are also estimated by finite differences, giving
p=yT g x+hy-yT g x/handq=zT g x+hz-zT g x/h
respectively, where g denotes the vector of first derivatives at the point in brackets and h is a small positive scalar. If the relative difference between p and yT Hy or between q and zT Hz is judged too large, an error indicator is set.

References

None.

Error Indicators and Warnings

Note: e04hd may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (IW, LIW, W, LW) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail<0
A negative value of ifail indicates an exit from e04hd because you have set iflag negative in funct or h. The value of ifail will be the same as the value you set for iflag. The check on h will not have been completed.
ifail=1
On entry, | n<1,
or | lh<max 1,n×n-1/2,
ifail=2
You should check carefully the derivation and programming of expressions for the second derivatives of F x, because it is very unlikely that h is calculating them correctly.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

ifail is set to 2 if
yT Hy-p≥h×yT Hy+1.0  or ​zT Hz-q≥h×zT Hz+1.0
where h is set equal to ε (ε being the machine precision as given by x02aj) and other quantities are as defined in [Description].

Parallelism and Performance

None.

Further Comments

e04hd calls h once and funct three times.

Example

Example program (C#): e04hde.cs

Example program results: e04hde.r

See Also

E04 Class
E04 Members


e04he Method

[image]

NAG Library for .NET Release 2
E04..::e04he Method
E04 Class See Also Send Feedback
e04he is a comprehensive modified Gauss–Newton algorithm for finding an unconstrained minimum of a sum of squares of m nonlinear functions in n variables m≥n. First and second derivatives are required.
The method is intended for functions which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).

Syntax

C#
public static void e04he(
    int m,
    int n,
    E04..::..E04HE_LSQFUN lsqfun,
    E04..::..E04HE_LSQHES lsqhes,
    E04..::..E04HE_LSQMON lsqmon,
    int iprint,
    int maxcal,
    double eta,
    double xtol,
    double stepmx,
    double[] x,
    out double fsumsq,
    double[] fvec,
    double[,] fjac,
    double[] s,
    double[,] v,
    out int niter,
    out int nf,
    out int ifail
)
Visual Basic
Public Shared Sub e04he ( _
    m As Integer, _
    n As Integer, _
    lsqfun As E04..::..E04HE_LSQFUN, _
    lsqhes As E04..::..E04HE_LSQHES, _
    lsqmon As E04..::..E04HE_LSQMON, _
    iprint As Integer, _
    maxcal As Integer, _
    eta As Double, _
    xtol As Double, _
    stepmx As Double, _
    x As Double(), _
    <OutAttribute> ByRef fsumsq As Double, _
    fvec As Double(), _
    fjac As Double(,), _
    s As Double(), _
    v As Double(,), _
    <OutAttribute> ByRef niter As Integer, _
    <OutAttribute> ByRef nf As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04he(
    int m,
    int n,
    E04..::..E04HE_LSQFUN^ lsqfun,
    E04..::..E04HE_LSQHES^ lsqhes,
    E04..::..E04HE_LSQMON^ lsqmon,
    int iprint,
    int maxcal,
    double eta,
    double xtol,
    double stepmx,
    array<double>^ x,
    [OutAttribute] double% fsumsq,
    array<double>^ fvec,
    array<double,2>^ fjac,
    array<double>^ s,
    array<double,2>^ v,
    [OutAttribute] int% niter,
    [OutAttribute] int% nf,
    [OutAttribute] int% ifail
)
F#
static member e04he :
        m : int *
        n : int *
        lsqfun : E04..::..E04HE_LSQFUN *
        lsqhes : E04..::..E04HE_LSQHES *
        lsqmon : E04..::..E04HE_LSQMON *
        iprint : int *
        maxcal : int *
        eta : float *
        xtol : float *
        stepmx : float *
        x : float[] *
        fsumsq : float byref *
        fvec : float[] *
        fjac : float[,] *
        s : float[] *
        v : float[,] *
        niter : int byref *
        nf : int byref *
        ifail : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: the number m of residuals, fi x, and the number n of variables, xj.
Constraint: 1≤n≤m.
n
Type: System..::..Int32
On entry: the number m of residuals, fi x, and the number n of variables, xj.
Constraint: 1≤n≤m.
lsqfun
Type: NagLibrary..::..E04..::..E04HE_LSQFUN
lsqfun must calculate the vector of values fi x and Jacobian matrix of first derivatives ∂fi∂xj at any point x. (However, if you do not wish to calculate the residuals or first derivatives at a particular x, there is the option of setting a parameter to cause e04he to terminate immediately.)

A delegate of type E04HE_LSQFUN.

Note: lsqfun should be tested separately before being used in conjunction with e04he.
lsqhes
Type: NagLibrary..::..E04..::..E04HE_LSQHES
lsqhes must calculate the elements of the symmetric matrix
B x=∑i=1 m fi x Gi x,
at any point x, where Gi x is the Hessian matrix of fi x. (As with lsqfun, there is the option of causing e04he to terminate immediately.)

A delegate of type E04HE_LSQHES.

Note: lsqhes should be tested separately before being used in conjunction with e04he.
lsqmon
Type: NagLibrary..::..E04..::..E04HE_LSQMON
If iprint≥0, you must supply lsqmon which is suitable for monitoring the minimization process. lsqmon must not change the values of any of its parameters.
If iprint<0, the dummy method E04FDZ can be used as lsqmon.

A delegate of type E04HE_LSQMON.

Note: you should normally print the sum of squares of residuals, so as to be able to examine the sequence of values of F x mentioned in [Accuracy]. It is usually helpful to also print xc, the gradient of the sum of squares, niter and nf.
iprint
Type: System..::..Int32
On entry: specifies the frequency with which lsqmon is to be called.
iprint>0
lsqmon is called once every iprint iterations and just before exit from e04he.
iprint=0
lsqmon is just called at the final point.
iprint<0
lsqmon is not called at all.
iprint should normally be set to a small positive number.
Suggested value: iprint=1.
maxcal
Type: System..::..Int32
On entry: this parameter is present so as to enable you to limit the number of times that lsqfun is called by e04he. There will be an error exit (see [Error Indicators and Warnings]) after maxcal calls of lsqfun.
Suggested value: maxcal=50×n.
Constraint: maxcal≥1.
eta
Type: System..::..Double
On entry: every iteration of e04he involves a linear minimization (i.e., minimization of F x k+α kp k with respect to α k). eta must lie in the range 0.0≤eta<1.0, and specifies how accurately these linear minimizations are to be performed. The minimum with respect to α k will be located more accurately for small values of eta (say, 0.01) than for large values (say, 0.9).
Although accurate linear minimizations will generally reduce the number of iterations performed by e04he, they will increase the number of calls of lsqfun made each iteration. On balance it is usually more efficient to perform a low accuracy minimization.
Suggested value: eta=0.5 (eta=0.0 if n=1).
Constraint: 0.0≤eta<1.0.
xtol
Type: System..::..Double
On entry: the accuracy in x to which the solution is required.
If xtrue is the true value of x at the minimum, then xsol, the estimated position before a normal exit, is such that
xsol-xtrue<xtol×1.0+xtrue,
where y=∑j=1 n yj 2. For example, if the elements of xsol are not much larger than 1.0 in modulus and if xtol=1.0E−5, then xsol is usually accurate to about five decimal places. (For further details see [Accuracy].)
If F x and the variables are scaled roughly as described in [Further Comments] and ε is the machine precision, then a setting of order xtol=ε will usually be appropriate. If xtol is set to 0.0 or some positive value less than 10 ε, e04he will use 10 ε instead of xtol, since 10 ε is probably the smallest reasonable setting.
Constraint: xtol≥0.0.
stepmx
Type: System..::..Double
On entry: an estimate of the Euclidean distance between the solution and the starting point supplied by you. (For maximum efficiency, a slight overestimate is preferable.)
e04he will ensure that, for each iteration
∑j=1 n xj k-xj k-1 2≤stepmx 2,
where k is the iteration number. Thus, if the problem has more than one solution, e04he is most likely to find the one nearest to the starting point. On difficult problems, a realistic choice can prevent the sequence of x k entering a region where the problem is ill-behaved and can help avoid overflow in the evaluation of F x. However, an underestimate of stepmx can lead to inefficiency.
Suggested value: stepmx=100000.0.
Constraint: stepmx≥xtol.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x[j-1] must be set to a guess at the jth component of the position of the minimum, for j=1,2,…,n.
On exit: the final point x k. Thus, if ifail=0 on exit, x[j-1] is the jth component of the estimated position of the minimum.
fsumsq
Type: System..::..Double %
On exit: the value of F x, the sum of squares of the residuals fi x, at the final point given in x.
fvec
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: the value of the residual fi x at the final point given in x, for i=1,2,…,m.
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: the value of the first derivative ∂fi∂xj evaluated at the final point given in x, for i=1,2,…,m and j=1,2,…,n.
s
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the singular values of the Jacobian matrix at the final point. Thus s may be useful as information about the structure of your problem.
v
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: the matrix V associated with the singular value decomposition
J=US VT
of the Jacobian matrix at the final point, stored by columns. This matrix may be useful for statistical purposes, since it is the matrix of orthonormalized eigenvectors of JT J.
niter
Type: System..::..Int32 %
On exit: the number of iterations which have been performed in e04he.
nf
Type: System..::..Int32 %
On exit: the number of times that the residuals and Jacobian matrix have been evaluated (i.e., number of calls of lsqfun).
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04he is essentially identical to the method LSQSDN in the NPL Algorithms Library. It is applicable to problems of the form:
Minimize F x=∑i=1 m fi x 2
where x=x 1,x 2,…,xn T and m≥n. (The functions fi x are often referred to as ‘residuals’.)
You must supply methods to calculate the values of the fi x and their first derivatives and second derivatives at any point x.
From a starting point x 1 supplied by you, the method generates a sequence of points x 2,x 3,…, which is intended to converge to a local minimum of F x. The sequence of points is given by
x k+1=x k+α kp k
where the vector p k is a direction of search, and α k is chosen such that F x k+α kp k is approximately a minimum with respect to α k.
The vector p k used depends upon the reduction in the sum of squares obtained during the last iteration. If the sum of squares was sufficiently reduced, then p k is the Gauss–Newton direction; otherwise the second derivatives of the fi x are taken into account.
The method is designed to ensure that steady progress is made whatever the starting point, and to have the rapid ultimate convergence of Newton's method.

References

Gill P E and Murray W (1978) Algorithms for the solution of the nonlinear least squares problem SIAM J. Numer. Anal. 15 977–992

Error Indicators and Warnings

Note: e04he may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDFJAC, LDV, IW, LIW, W, LW) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail<0
A negative value of ifail indicates an exit from e04he because you have set iflag negative in lsqfun or lsqhes. The value of ifail will be the same as your setting of iflag.
ifail=1
On entry, | n<1,
or | m<n,
or | maxcal<1,
or | eta<0.0,
or | eta≥1.0,
or | xtol<0.0,
or | stepmx<xtol,
When this exit occurs, no values will have been assigned to fsumsq, or to the elements of fvec, fjac, s or v.
ifail=2
There have been maxcal calls of lsqfun. If steady reductions in the sum of squares, F x, were monitored up to the point where this exit occurred, then the exit probably occurred simply because maxcal was set too small, so the calculations should be restarted from the final point held in x. This exit may also indicate that F x has no minimum.
ifail=3
The conditions for a minimum have not all been satisfied, but a lower point could not be found. This could be because xtol has been set so small that rounding errors in the evaluation of the residuals and derivatives make attainment of the convergence conditions impossible.
ifail=4
The method for computing the singular value decomposition of the Jacobian matrix has failed to converge in a reasonable number of sub-iterations. It may be worth applying e04he again starting with an initial approximation which is not too close to the point at which the failure occurred.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
The values ifail=2, 3 and 4 may also be caused by mistakes in lsqfun or lsqhes, by the formulation of the problem or by an awkward function. If there are no such mistakes it is worth restarting the calculations from a different starting point (not the point at which the failure occurred) in order to avoid the region which caused the failure.

Accuracy

A successful exit (ifail=0) is made from e04he when the matrix of second derivatives of F x is positive definite, and when (B1, B2 and B3) or B4 or B5 hold, where
B1≡α k×p k<xtol+ε×1.0+x kB2≡F k-F k-1<xtol+ε 2×1.0+F kB3≡g k<ε 1/3×1.0+F kB4≡F k<ε 2B5≡g k<ε×F k1/2
and where . and ε are as defined in [Parameters], and F k and g k are the values of F x and its vector of first derivatives at x k.
If ifail=0, then the vector in x on exit, xsol, is almost certainly an estimate of xtrue, the position of the minimum to the accuracy specified by xtol.
If ifail=3, then xsol may still be a good estimate of xtrue, but to verify this you should make the following checks. If
(a) | the sequence F x k converges to F xsol at a superlinear or a fast linear rate, and
(b) | g xsol T g xsol<10 ε, where T denotes transpose, then it is almost certain that xsol is a close approximation to the minimum.
When (b) is true, then usually F xsol is a close approximation to F xtrue. The values of F x k can be calculated in lsqmon, and the vector g xsol can be calculated from the contents of fvec and fjac on exit from e04he.
Further suggestions about confirmation of a computed solution are given in the E04 class.

Parallelism and Performance

None.

Further Comments

The number of iterations required depends on the number of variables, the number of residuals, the behaviour of F x, the accuracy demanded and the distance of the starting point from the solution. The number of multiplications performed per iteration of e04he varies, but for m≫n is approximately n×m 2+O n 3. In addition, each iteration makes at least one call of lsqfun and some iterations may call lsqhes. So, unless the residuals and their derivatives can be evaluated very quickly, the run time will be dominated by the time spent in lsqfun (and, to a lesser extent, in lsqhes).
Ideally, the problem should be scaled so that, at the solution, F x and the corresponding values of the xj are each in the range -1,+1, and so that at points one unit away from the solution, F x differs from its value at the solution by approximately one unit. This will usually imply that the Hessian matrix of F x at the solution is well-conditioned. It is unlikely that you will be able to follow these recommendations very closely, but it is worth trying (by guesswork), as sensible scaling will reduce the difficulty of the minimization problem, so that e04he will take less computer time.
When the sum of squares represents the goodness-of-fit of a nonlinear model to observed data, elements of the variance-covariance matrix of the estimated regression coefficients can be computed by a subsequent call to (E04YCF not in this release), using information returned in the arrays s and v. See (E04YCF not in this release) for further details.

Example

Example program (C#): e04hee.cs

Example program data: e04hee.d

Example program results: e04hee.r

See Also

E04 Class
E04 Members


e04hy Method

[image]

NAG Library for .NET Release 2
E04..::e04hy Method
E04 Class See Also Send Feedback
e04hy is an easy-to-use modified Gauss–Newton algorithm for finding an unconstrained minimum of a sum of squares of m nonlinear functions in n variables m≥n. First and second derivatives are required.
It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).

Syntax

C#
public static void e04hy(
    int m,
    int n,
    E04..::..E04HY_LSFUN2 lsfun2,
    E04..::..E04HY_LSHES2 lshes2,
    double[] x,
    out double fsumsq,
    out int ifail
)
Visual Basic
Public Shared Sub e04hy ( _
    m As Integer, _
    n As Integer, _
    lsfun2 As E04..::..E04HY_LSFUN2, _
    lshes2 As E04..::..E04HY_LSHES2, _
    x As Double(), _
    <OutAttribute> ByRef fsumsq As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04hy(
    int m,
    int n,
    E04..::..E04HY_LSFUN2^ lsfun2,
    E04..::..E04HY_LSHES2^ lshes2,
    array<double>^ x,
    [OutAttribute] double% fsumsq,
    [OutAttribute] int% ifail
)
F#
static member e04hy :
        m : int *
        n : int *
        lsfun2 : E04..::..E04HY_LSFUN2 *
        lshes2 : E04..::..E04HY_LSHES2 *
        x : float[] *
        fsumsq : float byref *
        ifail : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: the number m of residuals, fi x, and the number n of variables, xj.
Constraint: 1≤n≤m.
n
Type: System..::..Int32
On entry: the number m of residuals, fi x, and the number n of variables, xj.
Constraint: 1≤n≤m.
lsfun2
Type: NagLibrary..::..E04..::..E04HY_LSFUN2
You must supply this method to calculate the vector of values fi x and the Jacobian matrix of first derivatives ∂fi∂xj at any point x. It should be tested separately before being used in conjunction with e04hy (see the E04 class).

A delegate of type E04HY_LSFUN2.

lshes2
Type: NagLibrary..::..E04..::..E04HY_LSHES2
You must supply this method to calculate the elements of the symmetric matrix
B x=∑i=1 m fi x Gi x,
at any point x, where Gi x is the Hessian matrix of fi x. It should be tested separately before being used in conjunction with e04hy (see the E04 class).

A delegate of type E04HY_LSHES2.

x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x[j-1] must be set to a guess at the jth component of the position of the minimum, for j=1,2,…,n. The method checks lsfun2 and lshes2 at the starting point and so is more likely to detect any error in your methods if the initial x[j-1] are nonzero and mutually distinct.
On exit: the lowest point found during the calculations. Thus, if ifail=0 on exit, x[j-1] is the jth component of the position of the minimum.
fsumsq
Type: System..::..Double %
On exit: the value of the sum of squares, F x, corresponding to the final point stored in x.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04hy is similar to the method LSSDN2 in the NPL Algorithms Library. It is applicable to problems of the form:
Minimize F x=∑i=1 m fi x 2
where x=x 1,x 2,…,xn T and m≥n. (The functions fi x are often referred to as ‘residuals’.)
You must supply a method to evaluate the residuals and their first derivatives at any point x, and a method to evaluate the elements of the second derivative term of the Hessian matrix of F x.
Before attempting to minimize the sum of squares, the algorithm checks the user-supplied delegates for consistency. Then, from a starting point supplied by you, a sequence of points is generated which is intended to converge to a local minimum of the sum of squares. These points are generated using estimates of the curvature of F x.

References

Gill P E and Murray W (1978) Algorithms for the solution of the nonlinear least squares problem SIAM J. Numer. Anal. 15 977–992

Error Indicators and Warnings

Note: e04hy may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail=1
On entry, | n<1,
or | m<n,
or | lw<8×n+2×n×n+2×m×n+3×m, when n>1,
or | lw<11+5×m, when n=1.
ifail=2
There have been 50×n calls of lsfun2, yet the algorithm does not seem to have converged. This may be due to an awkward function or to a poor starting point, so it is worth restarting e04hy from the final point held in x.
ifail=3
The final point does not satisfy the conditions for acceptance as a minimum, but no lower point could be found.
ifail=4
An auxiliary method has been unable to complete a singular value decomposition in a reasonable number of sub-iterations.
ifail=5
ifail=6
ifail=7
ifail=8
There is some doubt about whether the point x x found by e04hy is a minimum of F x. The degree of confidence in the result decreases as ifail increases. Thus, when ifail=5, it is probable that the final x gives a good estimate of the position of a minimum, but when ifail=8 it is very unlikely that the method has found a minimum.
ifail=9
It is very likely that you have made an error in forming the derivatives ∂fi∂xj in lsfun2.
ifail=10
It is very likely that you have made an error in forming the quantities B jk in lshes2.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
If you are not satisfied with the result (e.g., because ifail lies between 3 and 8), it is worth restarting the calculations from a different starting point (not the point at which the failure occurred) in order to avoid the region which caused the failure. Repeated failure may indicate some defect in the formulation of the problem.

Accuracy

If the problem is reasonably well scaled and a successful exit is made, then, for a computer with a mantissa of t decimals, one would expect to get about t/2-1 decimals accuracy in the components of x and between t-1 (if F x is of order 1 at the minimum) and 2 t-2 (if F x is close to zero at the minimum) decimals accuracy in F x.

Parallelism and Performance

None.

Further Comments

The number of iterations required depends on the number of variables, the number of residuals and their behaviour, and the distance of the starting point from the solution. The number of multiplications performed per iteration of e04hy varies, but for m≫n is approximately n×m 2+O n 3. In addition, each iteration makes at least one call of lsfun2 and some iterations may call lshes2. So, unless the residuals and their derivatives can be evaluated very quickly, the run time will be dominated by the time spent in lsfun2 (and, to a lesser extent, in lshes2).
Ideally, the problem should be scaled so that the minimum value of the sum of squares is in the range 0,+1 and so that at points a unit distance away from the solution the sum of squares is approximately a unit value greater than at the minimum. It is unlikely that you will be able to follow these recommendations very closely, but it is worth trying (by guesswork), as sensible scaling will reduce the difficulty of the minimization problem, so that e04hy will take less computer time.
When the sum of squares represents the goodness-of-fit of a nonlinear model to observed data, elements of the variance-covariance matrix of the estimated regression coefficients can be computed by a subsequent call to (E04YCF not in this release), using information returned in segments of the workspace array w. See (E04YCF not in this release) for further details.

Example

This example finds least squares estimates of x 1, x 2 and x 3 in the model
y=x 1+t 1 x 2t 2+x 3t 3
using the 15 sets of data given in the following table.
yt 1t 2t 30.141.015.01.00.182.014.02.00.223.013.03.00.254.012.04.00.295.011.05.00.326.010.06.00.357.09.07.00.398.08.08.00.379.07.07.00.5810.06.06.00.7311.05.05.00.9612.04.04.01.3413.03.03.02.1014.02.02.04.3915.01.01.0
The program uses 0.5,1.0,1.5 as the initial guess at the position of the minimum.

Example program (C#): e04hye.cs

Example program data: e04hye.d

Example program results: e04hye.r

See Also

E04 Class
E04 Members


e04jc Method

[image]

NAG Library for .NET Release 2
E04..::e04jc Method
E04 Class See Also Send Feedback
e04jc is an easy-to-use algorithm that uses methods of quadratic approximation to find a minimum of an objective function F over x∈Rn, subject to fixed lower and upper bounds on the independent variables x 1,x 2,…,xn. Derivatives of F are not required.
The method is intended for functions that are continuous and that have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities). Efficiency is maintained for large n.

Syntax

C#
public static void e04jc(
    E04..::..E04JC_OBJFUN objfun,
    int n,
    int npt,
    double[] x,
    double[] bl,
    double[] bu,
    double rhobeg,
    double rhoend,
    E04..::..E04JC_MONFUN monfun,
    int maxcal,
    out double f,
    out int nf,
    out int ifail
)
Visual Basic
Public Shared Sub e04jc ( _
    objfun As E04..::..E04JC_OBJFUN, _
    n As Integer, _
    npt As Integer, _
    x As Double(), _
    bl As Double(), _
    bu As Double(), _
    rhobeg As Double, _
    rhoend As Double, _
    monfun As E04..::..E04JC_MONFUN, _
    maxcal As Integer, _
    <OutAttribute> ByRef f As Double, _
    <OutAttribute> ByRef nf As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04jc(
    E04..::..E04JC_OBJFUN^ objfun,
    int n,
    int npt,
    array<double>^ x,
    array<double>^ bl,
    array<double>^ bu,
    double rhobeg,
    double rhoend,
    E04..::..E04JC_MONFUN^ monfun,
    int maxcal,
    [OutAttribute] double% f,
    [OutAttribute] int% nf,
    [OutAttribute] int% ifail
)
F#
static member e04jc :
        objfun : E04..::..E04JC_OBJFUN *
        n : int *
        npt : int *
        x : float[] *
        bl : float[] *
        bu : float[] *
        rhobeg : float *
        rhoend : float *
        monfun : E04..::..E04JC_MONFUN *
        maxcal : int *
        f : float byref *
        nf : int byref *
        ifail : int byref -> unit

Parameters

objfun
Type: NagLibrary..::..E04..::..E04JC_OBJFUN
objfun must evaluate the objective function F at a specified vector x.

A delegate of type E04JC_OBJFUN.

n
Type: System..::..Int32
On entry: n, the number of independent variables.
Constraint: n≥2 and nr≥2, where nr denotes the number of non-fixed variables.
npt
Type: System..::..Int32
On entry: m, the number of interpolation conditions imposed on the quadratic approximation at each iteration.
Suggested value: npt=2×nr+1, where nr denotes the number of non-fixed variables.
Constraint: nr+2≤npt≤nr+1×nr+2 2, where nr denotes the number of non-fixed variables.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: an estimate of the position of the minimum. If any component is out-of-bounds it is replaced internally by the bound it violates.
On exit: the lowest point found during the calculations. Thus, if ifail=0 on exit, x is the position of the minimum.
bl
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the fixed vectors of bounds: the lower bounds ℓ and the upper bounds u, respectively. To signify that a variable is unbounded you should choose a large scalar r appropriate to your problem, then set the lower bound on that variable to -r and the upper bound to r. For well-scaled problems r=rmax 14 may be suitable, where rmax denotes the largest positive model number (see x02al).
Constraints:
  • if x[i-1] is to be fixed at bl[i-1], then bl[i-1]=bu[i-1];
  • otherwise bu[i-1]-bl[i-1]≥2.0×rhobeg, for i=1,2,…,n.
bu
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the fixed vectors of bounds: the lower bounds ℓ and the upper bounds u, respectively. To signify that a variable is unbounded you should choose a large scalar r appropriate to your problem, then set the lower bound on that variable to -r and the upper bound to r. For well-scaled problems r=rmax 14 may be suitable, where rmax denotes the largest positive model number (see x02al).
Constraints:
  • if x[i-1] is to be fixed at bl[i-1], then bl[i-1]=bu[i-1];
  • otherwise bu[i-1]-bl[i-1]≥2.0×rhobeg, for i=1,2,…,n.
rhobeg
Type: System..::..Double
On entry: an initial lower bound on the value of the trust-region radius.
Suggested value: rhobeg should be about one tenth of the greatest expected overall change to a variable: the initial quadratic model will be constructed by taking steps from the initial x of length rhobeg along each coordinate direction.
Constraints:
  • rhobeg>0.0;
  • rhobeg≥rhoend.
rhoend
Type: System..::..Double
On entry: a final lower bound on the value of the trust-region radius.
Suggested value: rhoend should indicate the absolute accuracy that is required in the final values of the variables.
Constraint: rhoend>0.0.
monfun
Type: NagLibrary..::..E04..::..E04JC_MONFUN
monfun may be used to monitor the optimization process. It is invoked every time a new trust-region radius is chosen.
If no monitoring is required, monfun may be the dummy monitoring method E04JCP supplied by the NAG Library.

A delegate of type E04JC_MONFUN.

maxcal
Type: System..::..Int32
On entry: the maximum permitted number of calls to objfun.
Constraint: maxcal≥1.
f
Type: System..::..Double %
On exit: the function value at the lowest point found (x).
nf
Type: System..::..Int32 %
On exit: unless ifail=1 or -999 on exit, the total number of calls made to objfun.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04jc is applicable to problems of the form:
minimize x∈Rn F x  subject to  ℓ≤x≤u  and  ℓ≤u,
where F is a nonlinear scalar function whose derivatives may be unavailable, and where the bound vectors are elements of Rn. Relational operators between vectors are interpreted elementwise.
Fixing variables (that is, setting ℓi=ui for some i) is allowed in e04jc.
You must supply a method to calculate the value of F at any given point x.
The method used by e04jc is based on BOBYQA, the method of Bound Optimization BY Quadratic Approximation described in Powell (2009). In particular, each iteration of e04jc generates a quadratic approximation Q to F that agrees with F at m automatically chosen interpolation points. The value of m is a constant prescribed by you. Updates to the independent variables mostly occur from approximate solutions to trust-region subproblems, using the current quadratic model.

References

Powell M J D (2009) The BOBYQA algorithm for bound constrained optimization without derivatives Report DAMTP 2009/NA06 University of Cambridge http://www.damtp.cam.ac.uk/user/na/NA_papers/NA2009_06.pdf

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
An input parameter is invalid.
ifail=2
The function evaluations limit was reached: objfun has been called maxcal times.
ifail=3
The predicted reduction in a trust-region step was non-positive. Check your specification of objfun and whether the function needs rescaling. Try a different initial x.
ifail=4
A rescue procedure has been called in order to correct damage from rounding errors when computing an update to a quadratic approximation of F, but no further progess could be made. Check your specification of objfun and whether the function needs rescaling. Try a different initial x.
ifail=5
You terminated the solver.
You indicated that you wished to halt solution of the current problem by setting inform to a negative value in either objfun or monfun.
ifail=-999
Internal memory allocation failed.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Experience shows that, in many cases, on successful termination the ∞-norm distance from the best point x to a local minimum of F is less than 10×rhoend, unless rhoend is so small that such accuracy is unattainable.

Parallelism and Performance

None.

Further Comments

For each invocation of e04jc, local workspace arrays of fixed length are allocated internally. The total size of these arrays amounts to npt+6×npt+nr+nr×3 nr+21 2 real elements and nr integer elements, where nr denotes the number of non-fixed variables; that is, the total size is O nr 4. If you follow the recommendation for the choice of npt on entry, this total size reduces to O nr 2.
Usually the total number of function evaluations (nf) is substantially less than O nr 2, and often, if npt=2×nr+1 on entry, nf is only of magnitude nr or less.

Example

This example involves the minimization of
F=x 1+10 x 2 2+5⁢x 3-x 4 2+x 2-2 x 3 4+10⁢x 1-x 4 4
subject to
-1≤x 1≤3,-2≤x 2≤0,-1≤x 4≤3,
starting from the initial guess 3,-1,0,1.

Example program (C#): e04jce.cs

Example program results: e04jce.r

See Also

E04 Class
E04 Members


e04jcp Method

[image]

NAG Library for .NET Release 2
E04..::e04jcp Method
E04 Class See Also Send Feedback
Auxiliary for use as a delegate parameter

Syntax

C#
public static void e04jcp(
    int n,
    int nf,
    double[] x,
    double f,
    double rho,
    out int inform
)
Visual Basic
Public Shared Sub e04jcp ( _
    n As Integer, _
    nf As Integer, _
    x As Double(), _
    f As Double, _
    rho As Double, _
    <OutAttribute> ByRef inform As Integer _
)
Visual C++
public:
static void e04jcp(
    int n,
    int nf,
    array<double>^ x,
    double f,
    double rho,
    [OutAttribute] int% inform
)
F#
static member e04jcp :
        n : int *
        nf : int *
        x : float[] *
        f : float *
        rho : float *
        inform : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the numbers of variables.
nf
Type: System..::..Int32
On entry: the cumulative number of calls made to _objfun.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: an estimate of the position of the minimum. If any component is out-of-bounds it is replaced internally by the bound it violates.
On exit: the lowest point found during the calculations. Thus, if ifail=0 on exit, x is the position of the minimum.
f
Type: System..::..Double
On entry: the value of _objfun at x.
rho
Type: System..::..Double
On entry: a lower bound on the current trust-region radius.
inform
Type: System..::..Int32 %
On exit: must be set to a value describing the action to be taken by the solver on return from _monfun. Specifically, if the value is negative the solution of the current problem will terminate immediately; otherwise, computations will continue.
On exit: must be set to a value describing the action to be taken by the solver on return from _monfun. Specifically, if the value is negative the solution of the current problem will terminate immediately; otherwise, computations will continue.

Description

Auxiliary for use as a delegate parameter

References

None.

Error Indicators and Warnings

ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Further Comments

None.

Example

None.

See Also

E04 Class
E04 Members


e04jy Method

[image]

NAG Library for .NET Release 2
E04..::e04jy Method
E04 Class See Also Send Feedback
e04jy is an easy-to-use quasi-Newton algorithm for finding a minimum of a function F x 1,x 2,…,xn, subject to fixed upper and lower bounds of the independent variables x 1,x 2,…,xn, using function values only.
It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).

Syntax

C#
public static void e04jy(
    int n,
    int ibound,
    E04..::..E04JY_FUNCT1 funct1,
    double[] bl,
    double[] bu,
    double[] x,
    out double f,
    out int nftotl,
    int[] bndinfo,
    out int freevar,
    double[] fdiff,
    out double phm,
    out int ifail
)
Visual Basic
Public Shared Sub e04jy ( _
    n As Integer, _
    ibound As Integer, _
    funct1 As E04..::..E04JY_FUNCT1, _
    bl As Double(), _
    bu As Double(), _
    x As Double(), _
    <OutAttribute> ByRef f As Double, _
    <OutAttribute> ByRef nftotl As Integer, _
    bndinfo As Integer(), _
    <OutAttribute> ByRef freevar As Integer, _
    fdiff As Double(), _
    <OutAttribute> ByRef phm As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04jy(
    int n,
    int ibound,
    E04..::..E04JY_FUNCT1^ funct1,
    array<double>^ bl,
    array<double>^ bu,
    array<double>^ x,
    [OutAttribute] double% f,
    [OutAttribute] int% nftotl,
    array<int>^ bndinfo,
    [OutAttribute] int% freevar,
    array<double>^ fdiff,
    [OutAttribute] double% phm,
    [OutAttribute] int% ifail
)
F#
static member e04jy :
        n : int *
        ibound : int *
        funct1 : E04..::..E04JY_FUNCT1 *
        bl : float[] *
        bu : float[] *
        x : float[] *
        f : float byref *
        nftotl : int byref *
        bndinfo : int[] *
        freevar : int byref *
        fdiff : float[] *
        phm : float byref *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: the number n of independent variables.
Constraint: n≥1.
ibound
Type: System..::..Int32
On entry: indicates whether the facility for dealing with bounds of special forms is to be used.
It must be set to one of the following values:
ibound=0
If you are supplying all the lj and uj individually.
ibound=1
If there are no bounds on any xj.
ibound=2
If all the bounds are of the form 0≤xj.
ibound=3
If l 1=l 2=…=ln and u 1=u 2=…=un.
funct1
Type: NagLibrary..::..E04..::..E04JY_FUNCT1
You must supply funct1 to calculate the value of the function F x at any point x. It should be tested separately before being used with e04jy (see the E04 class).

A delegate of type E04JY_FUNCT1.

bl
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the lower bounds lj.
If ibound is set to 0, you must set bl[j-1] to lj, for j=1,2,…,n. (If a lower bound is not specified for a particular xj, the corresponding bl[j-1] should be set to -106.)
If ibound is set to 3, you must set bl[0] to l 1; e04jy will then set the remaining elements of bl equal to bl[0].
On exit: the lower bounds actually used by e04jy.
bu
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the upper bounds uj.
If ibound is set to 0, you must set bu[j-1] to uj, for j=1,2,…,n. (If an upper bound is not specified for a particular xj, the corresponding bu[j-1] should be set to 106.)
If ibound is set to 3, you must set bu[0] to u 1; e04jy will then set the remaining elements of bu equal to bu[0].
On exit: the upper bounds actually used by e04jy.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x[j-1] must be set to an estimate of the jth component of the position of the minimum, for j=1,2,…,n.
On exit: the lowest point found during the calculations. Thus, if ifail=0 on exit, x[j-1] is the jth component of the position of the minimum.
f
Type: System..::..Double %
On exit: the value of F x corresponding to the final point stored in x.
nftotl
Type: System..::..Int32 %
On exit: this is used to return the total number of function evaluations.
bndinfo
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On exit: if ifail=0, 3 or 5, bndinfo contain information about which variables are currently on their bounds and which are free. Specifically, if xi is:
– fixed on its upper bound, bndinfo[i-1] is -1;
– fixed on its lower bound, bndinfo[i-1] is -2;
– effectively a constant (i.e., lj=uj), bndinfo[i-1] is -3;
– free, bndinfo[i-1] gives its position in the sequence of free variables.
freevar
Type: System..::..Int32 %
On exit:
contains the number of free variables (i.e., nz).
fdiff
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: if ifail=0, 3 or 5, fdiff[i-1] contains a finite-difference approximation to the ith element of the projected gradient vector gz, for i=1,2,…,n
phm
Type: System..::..Double %
On exit: contains an estimate of the condition number of the projected Hessian matrix (i.e., k)
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04jy is applicable to problems of the form:
MinimizeF x 1,x 2,…,xn  subject to  lj≤xj≤uj,  j=1,2,…,n
when derivatives of F x are unavailable.
Special provision is made for problems which actually have no bounds on the xj, problems which have only non-negativity bounds and problems in which l 1=l 2=⋯=ln and u 1=u 2=⋯=un. You must supply a method to calculate the value of F x at any point x.
From a starting point you supplied there is generated, on the basis of estimates of the gradient and the curvature of F x, a sequence of feasible points which is intended to converge to a local minimum of the constrained function. An attempt is made to verify that the final point is a minimum.
A typical iteration starts at the current point x where nz (say) variables are free from both their bounds. The projected gradient vector gz, whose elements are finite difference approximations to the derivatives of F x with respect to the free variables, is known. A unit lower triangular matrix L and a diagonal matrix D (both of dimension nz), such that LD LT is a positive definite approximation of the matrix of second derivatives with respect to the free variables (i.e., the projected Hessian) are also held. The equations
LD LT pz=-gz
are solved to give a search direction pz, which is expanded to an n-vector p by an insertion of appropriate zero elements. Then α is found such that F x+αp is approximately a minimum (subject to the fixed bounds) with respect to α; x is replaced by x+αp, and the matrices L and D are updated so as to be consistent with the change produced in the estimated gradient by the step αp. If any variable actually reaches a bound during the search along p, it is fixed and nz is reduced for the next iteration. Most iterations calculate gz using forward differences, but central differences are used when they seem necessary.
There are two sets of convergence criteria – a weaker and a stronger. Whenever the weaker criteria are satisfied, the Lagrange multipliers are estimated for all the active constraints. If any Lagrange multiplier estimate is significantly negative, then one of the variables associated with a negative Lagrange multiplier estimate is released from its bound and the next search direction is computed in the extended subspace (i.e., nz is increased). Otherwise minimization continues in the current subspace provided that this is practicable. When it is not, or when the stronger convergence criteria are already satisfied, then, if one or more Lagrange multiplier estimates are close to zero, a slight perturbation is made in the values of the corresponding variables in turn until a lower function value is obtained. The normal algorithm is then resumed from the perturbed point.
If a saddle point is suspected, a local search is carried out with a view to moving away from the saddle point. A local search is also performed when a point is found which is thought to be a constrained minimum.

References

Gill P E and Murray W (1976) Minimization subject to bounds on the variables NPL Report NAC 72 National Physical Laboratory

Error Indicators and Warnings

Note: e04jy may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (IW, LIW, W, LW) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | n<1,
or | ibound<0,
or | ibound>3,
or | ibound=0 and bl[j-1]>bu[j-1] for some j,
or | ibound=3 and bl[0]>bu[0],
ifail=2
There have been 400×n function evaluations, yet the algorithm does not seem to be converging. The calculations can be restarted from the final point held in x. The error may also indicate that F x has no minimum.
ifail=3
The conditions for a minimum have not all been met but a lower point could not be found and the algorithm has failed.
ifail=4
An overflow has occurred during the computation. This is an unlikely failure, but if it occurs you should restart at the latest point given in x.
ifail=5
ifail=6
ifail=7
ifail=8
There is some doubt about whether the point x found by e04jy is a minimum. The degree of confidence in the result decreases as ifail increases. Thus, when ifail=5 it is probable that the final x gives a good estimate of the position of a minimum, but when ifail=8 it is very unlikely that the method has found a minimum.
ifail=9
In the search for a minimum, the modulus of one of the variables has become very large ∼106. This indicates that there is a mistake in funct1, that your problem has no finite solution, or that the problem needs rescaling (see [Further Comments]).
ifail=10
The computed set of forward-difference intervals (stored in w[9×n],w[9×n+1],…,w[10×n-1]) is such that x[i-1]+w[9×n+i-1]≤x[i-1] for some i.
This is an unlikely failure, but if it occurs you should attempt to select another starting point.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail= -4000
Invalid dimension for array value
If you are dissatisfied with the result (e.g., because ifail=5, 6, 7 or 8), it is worth restarting the calculations from a different starting point (not the point at which the failure occurred) in order to avoid the region which caused the failure. If persistent trouble occurs and the gradient can be calculated, it may be advisable to change to a method which uses gradients (see the E04 class).

Accuracy

A successful exit (ifail=0) is made from e04jy when (B1, B2 and B3) or B4 hold, and the local search confirms a minimum, where
  • B1≡α k×p k<xtol+ε×1.0+x k
  • B2≡F k-F k-1<xtol 2+ε×1.0+F k
  • B3≡gz k<ε 1/3+xtol×1.0+F k
  • B4≡gz k<0.01×ε.
(Quantities with superscript k are the values at the kth iteration of the quantities mentioned in [Description], xtol=100 ε, ε is the machine precision and . denotes the Euclidean norm. The vector gz is returned in the array w.)
If ifail=0, then the vector in x on exit, xsol, is almost certainly an estimate of the position of the minimum, xtrue, to the accuracy specified by xtol.
If ifail=3 or 5, xsol may still be a good estimate of xtrue, but the following checks should be made. Let k denote an estimate of the condition number of the projected Hessian matrix at xsol. (The value of k is returned in w[n]). If
(i) | the sequence F x k converges to F xsol at a superlinear or a fast linear rate,
(ii) | gz xxol 2<10.0×ε, and
(iii) | k<1.0/gz xsol,
then it is almost certain that xsol is a close approximation to the position of a minimum. When (ii) is true, then usually F xsol is a close approximation to F xtrue.
When a successful exit is made then, for a computer with a mantissa of t decimals, one would expect to get about t/2-1 decimals accuracy in x and about t-1 decimals accuracy in F, provided the problem is reasonably well scaled.

Parallelism and Performance

None.

Further Comments

The number of iterations required depends on the number of variables, the behaviour of F x and the distance of the starting point from the solution. The number of operations performed in an iteration of e04jy is roughly proportional to n 2. In addition, each iteration makes at least m+1 calls of funct1, where m is the number of variables not fixed on bounds. So, unless F x can be evaluated very quickly, the run time will be dominated by the time spent in funct1.
Ideally the problem should be scaled so that at the solution the value of F x and the corresponding values of x 1,x 2,…,xn are each in the range -1,+1, and so that at points a unit distance away from the solution, F is approximately a unit value greater than at the minimum. It is unlikely that you will be able to follow these recommendations very closely, but it is worth trying (by guesswork), as sensible scaling will reduce the difficulty of the minimization problem, so that e04jy will take less computer time.

Example

To minimize
F=x 1+10 x 2 2+5⁢x 3-x 4 2+x 2-2 x 3 4+10⁢x 1-x 4 4
subject to
-1≤x 1≤3,-2≤x 2≤0,-1≤x 4≤3,
starting from the initial guess 3,-1,0,1.

Example program (C#): e04jye.cs

Example program results: e04jye.r

See Also

E04 Class
E04 Members


e04kd Method

[image]

NAG Library for .NET Release 2
E04..::e04kd Method
E04 Class See Also Send Feedback
e04kd is a comprehensive modified Newton algorithm for finding:
  • – an unconstrained minimum of a function of several variables;
  • – a minimum of a function of several variables subject to fixed upper and/or lower bounds on the variables.
First derivatives are required. The method is intended for functions which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).

Syntax

C#
public static void e04kd(
    int n,
    E04..::..E04KD_FUNCT funct,
    E04..::..E04KD_MONIT monit,
    int iprint,
    int maxcal,
    double eta,
    double xtol,
    double delta,
    double stepmx,
    int ibound,
    double[] bl,
    double[] bu,
    double[] x,
    double[] hesl,
    double[] hesd,
    int[] istate,
    out double f,
    double[] g,
    out int ifail
)
Visual Basic
Public Shared Sub e04kd ( _
    n As Integer, _
    funct As E04..::..E04KD_FUNCT, _
    monit As E04..::..E04KD_MONIT, _
    iprint As Integer, _
    maxcal As Integer, _
    eta As Double, _
    xtol As Double, _
    delta As Double, _
    stepmx As Double, _
    ibound As Integer, _
    bl As Double(), _
    bu As Double(), _
    x As Double(), _
    hesl As Double(), _
    hesd As Double(), _
    istate As Integer(), _
    <OutAttribute> ByRef f As Double, _
    g As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04kd(
    int n,
    E04..::..E04KD_FUNCT^ funct,
    E04..::..E04KD_MONIT^ monit,
    int iprint,
    int maxcal,
    double eta,
    double xtol,
    double delta,
    double stepmx,
    int ibound,
    array<double>^ bl,
    array<double>^ bu,
    array<double>^ x,
    array<double>^ hesl,
    array<double>^ hesd,
    array<int>^ istate,
    [OutAttribute] double% f,
    array<double>^ g,
    [OutAttribute] int% ifail
)
F#
static member e04kd :
        n : int *
        funct : E04..::..E04KD_FUNCT *
        monit : E04..::..E04KD_MONIT *
        iprint : int *
        maxcal : int *
        eta : float *
        xtol : float *
        delta : float *
        stepmx : float *
        ibound : int *
        bl : float[] *
        bu : float[] *
        x : float[] *
        hesl : float[] *
        hesd : float[] *
        istate : int[] *
        f : float byref *
        g : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: the number n of independent variables.
Constraint: n≥1.
funct
Type: NagLibrary..::..E04..::..E04KD_FUNCT
funct must evaluate the function F x and its first derivatives ∂F∂xj at a specified point. (However, if you do not wish to calculate F or its first derivatives at a particular x, there is the option of setting a parameter to cause e04kd to terminate immediately.)

A delegate of type E04KD_FUNCT.

Note: funct should be tested separately before being used in conjunction with e04kd.
monit
Type: NagLibrary..::..E04..::..E04KD_MONIT
If iprint≥0, you must supply monit which is suitable for monitoring the minimization process. monit must not change the values of any of its parameters.
If iprint<0, a monit with the correct parameter list must still be supplied, although it will not be called.

A delegate of type E04KD_MONIT.

You should normally print fc, gpjnrm and cond to be able to compare the quantities mentioned in [Accuracy]. It is usually helpful to examine xc, posdef and nf too.
iprint
Type: System..::..Int32
On entry: the frequency with which monit is to be called.
iprint>0
monit is called once every iprint iterations and just before exit from e04kd.
iprint=0
monit is just called at the final point.
iprint<0
monit is not called at all.
iprint should normally be set to a small positive number.
Suggested value: iprint=1.
maxcal
Type: System..::..Int32
On entry: the maximum permitted number of evaluations of F x, i.e., the maximum permitted number of calls of funct with iflag set to 2. It should be borne in mind that, in addition to the calls of funct which are limited directly by maxcal, there will be calls of funct (with iflag set to 1) to evaluate only first derivatives.
Suggested value: maxcal=50×n.
Constraint: maxcal≥1.
eta
Type: System..::..Double
On entry: every iteration of e04kd involves a linear minimization (i.e., minimization of F x+αp with respect to α). eta specifies how accurately these linear minimizations are to be performed. The minimum with respect to α will be located more accurately for small values of eta (say, 0.01) than large values (say, 0.9).
Although accurate linear minimizations will generally reduce the number of iterations (and hence the number of calls of funct to estimate the second derivatives), they will tend to increase the number of calls of funct needed for each linear minimization. On balance, it is usually more efficient to perform a low accuracy linear minimization when n is small and a high accuracy minimization when n is large.
Suggested values:
  • eta=0.5 if 1<n<10;
  • eta=0.1 if 10≤n≤20;
  • eta=0.01 if n>20.
If n=1, eta should be set to 0.0 (also when the problem is effectively one-dimensional even though n>1; i.e., if for all except one of the variables the lower and upper bounds are equal).
Constraint: 0.0≤eta<1.0.
xtol
Type: System..::..Double
On entry: the accuracy in x to which the solution is required.
If xtrue is the true value of x at the minimum, then xsol, the estimated position before a normal exit, is such that xsol-xtrue<xtol×1.0+xtrue where y=∑j=1 n yj 2. For example, if the elements of xsol are not much larger than 1.0 in modulus, and if xtol is set to 10-5, then xsol is usually accurate to about five decimal places. (For further details see [Accuracy].)
If the problem is scaled as described in [Scaling] and ε is the machine precision, then ε is probably the smallest reasonable choice for xtol. This is because, normally, to machine accuracy, F x+ε ej=F x, for any j where ej is the jth column of the identity matrix. If you set xtol to 0.0 (or any positive value less than ε), e04kd will use 10.0×ε instead of xtol.
Suggested value: xtol=0.0.
Constraint: xtol≥0.0.
delta
Type: System..::..Double
On entry: the differencing interval to be used for approximating the second derivatives of F x. Thus, for the finite difference approximations, the first derivatives of F x are evaluated at points which are delta apart. If ε is the machine precision, then ε will usually be a suitable setting for delta. If you set delta to 0.0 (or to any positive value less than ε), e04kd will automatically use ε as the differencing interval.
Suggested value: delta=0.0.
Constraint: delta≥0.0.
stepmx
Type: System..::..Double
On entry: an estimate of the Euclidean distance between the solution and the starting point supplied by you. (For maximum efficiency a slight overestimate is preferable.)
e04kd will ensure that, for each iteration,
∑j=1 n xj k-xj k-1 2≤stepmx,
where k is the iteration number. Thus, if the problem has more than one solution, e04kd is most likely to find the one nearest to the starting point. On difficult problems, a realistic choice can prevent the sequence of x k entering a region where the problem is ill-behaved and can also help to avoid possible overflow in the evaluation of F x. However, an underestimate of stepmx can lead to inefficiency.
Suggested value: stepmx=100000.0.
Constraint: stepmx≥xtol.
ibound
Type: System..::..Int32
On entry: indicates whether the problem is unconstrained or bounded. If there are bounds on the variables, ibound can be used to indicate whether the facility for dealing with bounds of special forms is to be used. It must be set to one of the following values:
ibound=0
If the variables are bounded and you are supplying all the lj and uj individually.
ibound=1
If the problem is unconstrained.
ibound=2
If the variables are bounded, but all the bounds are of the form 0≤xj.
ibound=3
If all the variables are bounded, and l 1=l 2=⋯=ln and u 1=u 2=⋯=un.
ibound=4
If the problem is unconstrained. (The ibound=4 option is provided for consistency with other methods. In e04kd it produces the same effect as ibound=1.)
Constraint: 0≤ibound≤4.
bl
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the fixed lower bounds lj.
If ibound is set to 0, you must set bl[j-1] to lj, for j=1,2,…,n. (If a lower bound is not specified for any xj, the corresponding bl[j-1] should be set to a large negative number, e.g., -106.)
If ibound is set to 3, you must set bl[0] to l 1; e04kd will then set the remaining elements of bl equal to bl[0].
If ibound is set to 1, 2 or 4, bl will be initialized by e04kd.
On exit: the lower bounds actually used by e04kd, e.g., if ibound=2, bl[0]=bl[1]=⋯=bl[n-1]=0.0.
bu
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the fixed upper bounds uj.
If ibound is set to 0, you must set bu[j-1] to uj, for j=1,2,…,n. (If an upper bound is not specified for any variable, the corresponding bu[j-1] should be set to a large positive number, e.g., 106.)
If ibound is set to 3, you must set bu[0] to u 1; e04kd will then set the remaining elements of bu equal to bu[0].
If ibound is set to 1, 2 or 4, bu will be initialized by e04kd.
On exit: the upper bounds actually used by e04kd, e.g., if ibound=2, bu[0]=bu[1]=⋯=bu[n-1]=106.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x[j-1] must be set to a guess at the jth component of the position of the minimum, for j=1,2,…,n.
On exit: the final point x k. Thus, if ifail=0 on exit, x[j-1] is the jth component of the estimated position of the minimum.
hesl
Type: array< System..::..Double >[]()[][]
An array of size [lh]
On exit: during the determination of a direction pz (see [Description]), H+E is decomposed into the product LD LT, where L is a unit lower triangular matrix and D is a diagonal matrix. (The matrices H, E, L and D are all of dimension nz, where nz is the number of variables free from their bounds. H consists of those rows and columns of the full estimated second derivative matrix which relate to free variables. E is chosen so that H+E is positive definite.)
hesl and hesd are used to store the factors L and D. The elements of the strict lower triangle of L are stored row by row in the first nz nz-1/2 positions of hesl. The diagonal elements of D are stored in the first nz positions of hesd. In the last factorization before a normal exit, the matrix E will be zero, so that hesl and hesd will contain, on exit, the factors of the final estimated second derivative matrix H. The elements of hesd are useful for deciding whether to accept the results produced by e04kd (see [Accuracy]).
hesd
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: during the determination of a direction pz (see [Description]), H+E is decomposed into the product LD LT, where L is a unit lower triangular matrix and D is a diagonal matrix. (The matrices H, E, L and D are all of dimension nz, where nz is the number of variables free from their bounds. H consists of those rows and columns of the full estimated second derivative matrix which relate to free variables. E is chosen so that H+E is positive definite.)
hesl and hesd are used to store the factors L and D. The elements of the strict lower triangle of L are stored row by row in the first nz nz-1/2 positions of hesl. The diagonal elements of D are stored in the first nz positions of hesd. In the last factorization before a normal exit, the matrix E will be zero, so that hesl and hesd will contain, on exit, the factors of the final estimated second derivative matrix H. The elements of hesd are useful for deciding whether to accept the results produced by e04kd (see [Accuracy]).
istate
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On exit: information about which variables are currently on their bounds and which are free. If istate[j-1] is:
  • – equal to -1, xj is fixed on its upper bound;
  • – equal to -2, xj is fixed on its lower bound;
  • – equal to -3, xj is effectively a constant (i.e., lj=uj);
  • – positive, istate[j-1] gives the position of xj in the sequence of free variables.
f
Type: System..::..Double %
On exit: the function value at the final point given in x.
g
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the first derivative vector corresponding to the final point given in x. The components of g corresponding to free variables should normally be close to zero.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04kd is applicable to problems of the form:
Minimize F x 1,x 2,…,xn  subject to  lj≤xj≤uj,  j=1,2,…,n.
Special provision is made for unconstrained minimization (i.e., problems which actually have no bounds on the xj), problems which have only non-negativity bounds, and problems in which l 1=l 2=⋯=ln and u 1=u 2=⋯=un. It is possible to specify that a particular xj should be held constant. You must supply a starting point, and a funct to calculate the value of F x and its first derivatives ∂F∂xj at any point x.
A typical iteration starts at the current point x where nz (say) variables are free from their bounds. The vector gz, whose elements are the derivatives of F x with respect to the free variables, is known. The matrix of second derivatives with respect to the free variables, H, is estimated by finite differences. (Note that gz and H are both of dimension nz.) The equations
H+E pz=-gz
are solved to give a search direction pz. (The matrix E is chosen so that H+E is positive definite.)
pz is then expanded to an n-vector p by the insertion of appropriate zero elements, α is found such that F x+αp is approximately a minimum (subject to the fixed bounds) with respect to α; and x is replaced by x+αp. (If a saddle point is found, a special search is carried out so as to move away from the saddle point.) If any variable actually reaches a bound, it is fixed and nz is reduced for the next iteration.
There are two sets of convergence criteria – a weaker and a stronger. Whenever the weaker criteria are satisfied, the Lagrange multipliers are estimated for all the active constraints. If any Lagrange multiplier estimate is significantly negative, then one of the variables associated with a negative Lagrange multiplier estimate is released from its bound and the next search direction is computed in the extended subspace (i.e., nz is increased). Otherwise minimization continues in the current subspace until the stronger convergence criteria are satisfied. If at this point there are no negative or near-zero Lagrange multiplier estimates, the process is terminated.
If you specify that the problem is unconstrained, e04kd sets the lj to -106 and the uj to 106. Thus, provided that the problem has been sensibly scaled, no bounds will be encountered during the minimization process and e04kd will act as an unconstrained minimization algorithm.

References

Gill P E and Murray W (1973) Safeguarded steplength algorithms for optimization using descent methods NPL Report NAC 37 National Physical Laboratory
Gill P E and Murray W (1974) Newton-type methods for unconstrained and linearly constrained optimization Math. Programming 7 311–350
Gill P E and Murray W (1976) Minimization subject to bounds on the variables NPL Report NAC 72 National Physical Laboratory

Error Indicators and Warnings

Note: e04kd may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (IW, LIW, W, LW) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail<0
A negative value of ifail indicates an exit from e04kd because you have set iflag negative in funct. The value of ifail will be the same as your setting of iflag.
ifail=1
On entry, | n<1,
or | maxcal<1,
or | eta<0.0,
or | eta≥1.0,
or | xtol<0.0,
or | delta<0.0,
or | stepmx<xtol,
or | ibound<0,
or | ibound>4,
or | bl[j-1]>bu[j-1] for some j if ibound=0,
or | bl[0]>bu[0] if ibound=3,
or | lh<max 1,n×n-1/2,
(Note that if you have set xtol or delta to 0.0, e04kd uses the default values and continues without failing.) When this exit occurs, no values will have been assigned to f or to the elements of hesl, hesd or g.
ifail=2
There have been maxcal function evaluations. If steady reductions in F x were monitored up to the point where this exit occurred, then the exit probably occurred simply because maxcal was set too small, so the calculations should be restarted from the final point held in x. This exit may also indicate that F x has no minimum.
ifail=3
The conditions for a minimum have not all been met, but a lower point could not be found.
Provided that, on exit, the first derivatives of F x with respect to the free variables are sufficiently small, and that the estimated condition number of the second derivative matrix is not too large, this error exit may simply mean that, although it has not been possible to satisfy the specified requirements, the algorithm has in fact found the minimum as far as the accuracy of the machine permits. Such a situation can arise, for instance, if xtol has been set so small that rounding errors in the evaluation of F x or its derivatives make it impossible to satisfy the convergence conditions.
If the estimated condition number of the second derivative matrix at the final point is large, it could be that the final point is a minimum, but that the smallest eigenvalue of the Hessian matrix is so close to zero that it is not possible to recognize the point as a minimum.
ifail=4
Not used. (This is done to make the significance of ifail=5 similar for e04kd and e04lb.)
ifail=5
All the Lagrange multiplier estimates which are not indisputably positive lie relatively close to zero, but it is impossible either to continue minimizing on the current subspace or to find a feasible lower point by releasing and perturbing any of the fixed variables. You should investigate as for ifail=3.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
The values ifail=2, 3 or 5 may also be caused by mistakes in funct, by the formulation of the problem or by an awkward function. If there are no such mistakes, it is worth restarting the calculations from a different starting point (not the point at which the failure occurred) in order to avoid the region which caused the failure.

Accuracy

A successful exit (ifail=0) is made from e04kd when H k is positive definite and when (B1, B2 and B3) or B4 hold, where
B1≡α k×p k<xtol+ε×1.0+x kB2≡F k-F k-1<xtol 2+ε×1.0+F kB3≡gz k<ε 1/3+xtol×1.0+F kB4≡gz k<0.01×ε.
(Quantities with superscript k are the values at the kth iteration of the quantities mentioned in [Description], ε is the machine precision and . denotes the Euclidean norm.)
If ifail=0, then the vector in x on exit, xsol, is almost certainly an estimate of the position of the minimum, xtrue, to the accuracy specified by xtol.
If ifail=3 or 5, xsol may still be a good estimate of xtrue, but the following checks should be made. Let the largest of the first nz elements of hesd be hesd[b-1], let the smallest be hesd[s-1], and define k=hesd[b-1]/hesd[s-1]. The scalar k is usually a good estimate of the condition number of the projected Hessian matrix at xsol. If
(i) | the sequence F x k converges to F xsol at a superlinear or fast linear rate,
(ii) | gz xsol 2<10.0×ε, and
(iii) | k<1.0/gz xsol,
then it is almost certain that xsol is a close approximation to the position of a minimum. When (ii) is true, then usually F xsol is a close approximation to F xtrue. The quantities needed for these checks are all available via monit; in particular the value of cond in the last call of monit before exit gives k.
Further suggestions about confirmation of a computed solution are given in the E04 class.

Parallelism and Performance

None.

Further Comments

Timing

The number of iterations required depends on the number of variables, the behaviour of F x, the accuracy demanded and the distance of the starting point from the solution. The number of multiplications performed in an iteration of e04kd is nz 3 6+O nz 2. In addition, each iteration makes nz calls of funct (with iflag set to 1) in approximating the projected Hessian matrix, and at least one other call of funct (with iflag set to 2). So, unless F x and its first derivatives can be evaluated very quickly, the run time will be dominated by the time spent in funct.

Scaling

Ideally, the problem should be scaled so that, at the solution, F x and the corresponding values of xj are each in the range -1,+1, and so that at points one unit away from the solution, F x differs from its value at the solution by approximately one unit. This will usually imply that the Hessian matrix at the solution is well-conditioned. It is unlikely that you will be able to follow these recommendations very closely, but it is worth trying (by guesswork), as sensible scaling will reduce the difficulty of the minimization problem, so that e04kd will take less computer time.

Unconstrained Minimization

If a problem is genuinely unconstrained and has been scaled sensibly, the following points apply:
(a) | nz will always be n,
(b) | hesl and hesd will be factors of the full estimated second derivative matrix with elements stored in the natural order,
(c) | the elements of g should all be close to zero at the final point,
(d) | the values of the istate[j-1] given by monit and on exit from e04kd are unlikely to be of interest (unless they are negative, which would indicate that the modulus of one of the xj has reached 106 for some reason),
(e) | monit's parameter gpjnrm simply gives the norm of the first derivative vector.

Example

Example program (C#): e04kde.cs

Example program results: e04kde.r

See Also

E04 Class
E04 Members


e04ky Method

[image]

NAG Library for .NET Release 2
E04..::e04ky Method
E04 Class See Also Send Feedback
e04ky is an easy-to-use quasi-Newton algorithm for finding a minimum of a function F x 1,x 2,…,xn, subject to fixed upper and lower bounds on the independent variables x 1,x 2,…,xn, when first derivatives of F are available.
It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).

Syntax

C#
public static void e04ky(
    int n,
    int ibound,
    E04..::..E04KY_FUNCT2 funct2,
    double[] bl,
    double[] bu,
    double[] x,
    out double f,
    double[] g,
    int[] iw,
    double[] w,
    out int ifail
)
Visual Basic
Public Shared Sub e04ky ( _
    n As Integer, _
    ibound As Integer, _
    funct2 As E04..::..E04KY_FUNCT2, _
    bl As Double(), _
    bu As Double(), _
    x As Double(), _
    <OutAttribute> ByRef f As Double, _
    g As Double(), _
    iw As Integer(), _
    w As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04ky(
    int n,
    int ibound,
    E04..::..E04KY_FUNCT2^ funct2,
    array<double>^ bl,
    array<double>^ bu,
    array<double>^ x,
    [OutAttribute] double% f,
    array<double>^ g,
    array<int>^ iw,
    array<double>^ w,
    [OutAttribute] int% ifail
)
F#
static member e04ky :
        n : int *
        ibound : int *
        funct2 : E04..::..E04KY_FUNCT2 *
        bl : float[] *
        bu : float[] *
        x : float[] *
        f : float byref *
        g : float[] *
        iw : int[] *
        w : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: the number n of independent variables.
Constraint: n≥1.
ibound
Type: System..::..Int32
On entry: indicates whether the facility for dealing with bounds of special forms is to be used. It must be set to one of the following values:
ibound=0
If you are supplying all the lj and uj individually.
ibound=1
If there are no bounds on any xj.
ibound=2
If all the bounds are of the form 0≤xj.
ibound=3
If l 1=l 2=⋯=ln and u 1=u 2=⋯=un.
Constraint: 0≤ibound≤3.
funct2
Type: NagLibrary..::..E04..::..E04KY_FUNCT2
You must supply funct2 to calculate the values of the function F x and its first derivative ∂F∂xj at any point x. It should be tested separately before being used in conjunction with e04ky (see the E04 class).

A delegate of type E04KY_FUNCT2.

bl
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the lower bounds lj.
If ibound is set to 0, you must set bl[j-1] to lj, for j=1,2,…,n. (If a lower bound is not specified for a particular xj, the corresponding bl[j-1] should be set to -106.)
If ibound is set to 3, you must set bl[0] to l 1; e04ky will then set the remaining elements of bl equal to bl[0].
On exit: the lower bounds actually used by e04ky.
bu
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the upper bounds uj.
If ibound is set to 0, you must set bu[j-1] to uj, for j=1,2,…,n. (If an upper bound is not specified for a particular xj, the corresponding bu[j-1] should be set to 106.)
If ibound is set to 3, you must set bu[0] to u 1; e04ky will then set the remaining elements of bu equal to bu[0].
On exit: the upper bounds actually used by e04ky.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x[j-1] must be set to a guess at the jth component of the position of the minimum, for j=1,2,…,n. The method checks the gradient at the starting point, and is more likely to detect any error in your programming if the initial x[j-1] are nonzero and mutually distinct.
On exit: the lowest point found during the calculations. Thus, if ifail=0 on exit, x[j-1] is the jth component of the position of the minimum.
f
Type: System..::..Double %
On exit: the value of F x corresponding to the final point stored in x.
g
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the value of ∂F∂xj corresponding to the final point stored in x, for j=1,2,…,n; the value of g[j-1] for variables not on a bound should normally be close to zero.
iw
Type: array< System..::..Int32 >[]()[][]
An array of size [liw]
On exit: if ifail=0, 3 or 5, the first n elements of iw contain information about which variables are currently on their bounds and which are free. Specifically, if xi is:
– fixed on its upper bound, iw[i-1] is -1;
– fixed on its lower bound, iw[i-1] is -2;
– effectively a constant (i.e., lj=uj), iw[i-1] is -3;
– free, iw[i-1] gives its position in the sequence of free variables.
In addition, iw[n] contains the number of free variables (i.e., nz). The rest of the array is used as workspace.
w
Type: array< System..::..Double >[]()[][]
An array of size [lw]
On exit: if ifail=0, 3 or 5, w[i-1] contains the ith element of the projected gradient vector gz, for i=1,2,…,n. In addition, w[n] contains an estimate of the condition number of the projected Hessian matrix (i.e., k). The rest of the array is used as workspace.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04ky is applicable to problems of the form:
Minimize F x 1,x 2,…,xn  subject to  lj≤xj≤uj,  j=1,2,…,n
when first derivatives are available.
Special provision is made for problems which actually have no bounds on the xj, problems which have only non-negativity bounds, and problems in which l 1=l 2=…=ln and u 1=u 2=…=un. You must supply a method to calculate the values of F x and its first derivatives at any point x.
From a starting point you supplied there is generated, on the basis of estimates of the curvature of F x, a sequence of feasible points which is intended to converge to a local minimum of the constrained function. An attempt is made to verify that the final point is a minimum.
A typical iteration starts at the current point x where nz (say) variables are free from both their bounds. The projected gradient vector gz, whose elements are the derivatives of F x with respect to the free variables, is known. A unit lower triangular matrix L and a diagonal matrix D (both of dimension nz), such that LD LT is a positive definite approximation of the matrix of second derivatives with respect to the free variables (i.e., the projected Hessian) are also held. The equations
LD LT pz=-gz
are solved to give a search direction pz, which is expanded to an n-vector p by an insertion of appropriate zero elements. Then α is found such that F x+αp is approximately a minimum (subject to the fixed bounds) with respect to α; x is replaced by x+αp, and the matrices L and D are updated so as to be consistent with the change produced in the gradient by the step αp. If any variable actually reaches a bound during the search along p, it is fixed and nz is reduced for the next iteration.
There are two sets of convergence criteria – a weaker and a stronger. Whenever the weaker criteria are satisfied, the Lagrange multipliers are estimated for all the active constraints. If any Lagrange multiplier estimate is significantly negative, then one of the variables associated with a negative Lagrange multiplier estimate is released from its bound and the next search direction is computed in the extended subspace (i.e., nz is increased). Otherwise minimization continues in the current subspace provided that this is practicable. When it is not, or when the stronger convergence criteria are already satisfied, then, if one or more Lagrange multiplier estimates are close to zero, a slight perturbation is made in the values of the corresponding variables in turn until a lower function value is obtained. The normal algorithm is then resumed from the perturbed point.
If a saddle point is suspected, a local search is carried out with a view to moving away from the saddle point. A local search is also performed when a point is found which is thought to be a constrained minimum.

References

Gill P E and Murray W (1976) Minimization subject to bounds on the variables NPL Report NAC 72 National Physical Laboratory

Error Indicators and Warnings

Note: e04ky may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail=1
On entry, | n<1,
or | ibound<0,
or | ibound>3,
or | ibound=0 and bl[j-1]>bu[j-1] for some j,
or | ibound=3 and bl[0]>bu[0],
or | liw<n+2,
or | lw<max 11,10×n+n×n-1/2.
ifail=2
There have been 100×n function evaluations, yet the algorithm does not seem to be converging. The calculations can be restarted from the final point held in x. The error may also indicate that F x has no minimum.
ifail=3
The conditions for a minimum have not all been met but a lower point could not be found and the algorithm has failed.
ifail=4
An overflow has occurred during the computation. This is an unlikely failure, but if it occurs you should restart at the latest point given in x.
ifail=5
ifail=6
ifail=7
ifail=8
There is some doubt about whether the point x found by e04ky is a minimum. The degree of confidence in the result decreases as ifail increases. Thus, when ifail=5 it is probable that the final x gives a good estimate of the position of a minimum, but when ifail=8 it is very unlikely that the method has found a minimum.
ifail=9
In the search for a minimum, the modulus of one of the variables has become very large ∼106. This indicates that there is a mistake in funct2, that your problem has no finite solution, or that the problem needs rescaling (see [Further Comments]).
ifail=10
It is very likely that you have made an error in forming the gradient.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
If you are dissatisfied with the result (e.g., because ifail=5, 6, 7 or 8), it is worth restarting the calculations from a different starting point (not the point at which the failure occurred) in order to avoid the region which caused the failure. If persistent trouble occurs it may be advisable to try e04kz.

Accuracy

A successful exit (ifail=0) is made from e04ky when (B1, B2 and B3) or B4 hold, and the local search confirms a minimum, where
  • B1≡α k×p k<xtol+ε×1.0+x k
  • B2≡F k-F k-1<xtol 2+ε×1.0+F k
  • B3≡gz k<ε 1/3+xtol×1.0+F k
  • B4≡gz k<0.01×ε.
(Quantities with superscript k are the values at the kth iteration of the quantities mentioned in [Description], xtol=100 ε, ε is the machine precision and . denotes the Euclidean norm. The vector gz is returned in the array w.)
If ifail=0, then the vector in x on exit, xsol, is almost certainly an estimate of the position of the minimum, xtrue, to the accuracy specified by xtol.
If ifail=3 or 5, xsol may still be a good estimate of xtrue, but the following checks should be made. Let k denote an estimate of the condition number of the projected Hessian matrix at xsol. (The value of k is returned in w[n]). If
(i) | the sequence F x k converges to F xsol at a superlinear or a fast linear rate,
(ii) | gz xxol 2<10.0×ε and
(iii) | k<1.0/gz xsol,
then it is almost certain that xsol is a close approximation to the position of a minimum. When (ii) is true, then usually F xsol is a close approximation to F xtrue.
When a successful exit is made then, for a computer with a mantissa of t decimals, one would expect to get about t/2-1 decimals accuracy in x, and about t-1 decimals accuracy in F, provided the problem is reasonably well scaled.

Parallelism and Performance

None.

Further Comments

The number of iterations required depends on the number of variables, the behaviour of F x and the distance of the starting point from the solution. The number of operations performed in an iteration of e04ky is roughly proportional to n 2. In addition, each iteration makes at least one call of funct2. So, unless F x and the gradient vector can be evaluated very quickly, the run time will be dominated by the time spent in funct2.
Ideally the problem should be scaled so that at the solution the value of F x and the corresponding values of x 1,x 2,…,xn are each in the range -1,+1, and so that at points a unit distance away from the solution, F is approximately a unit value greater than at the minimum. It is unlikely that you will be able to follow these recommendations very closely, but it is worth trying (by guesswork), as sensible scaling will reduce the difficulty of the minimization problem, so that e04ky will take less computer time.

Example

A program to minimize
F=x 1+10 x 2 2+5⁢x 3-x 4 2+x 2-2 x 3 4+10⁢x 1-x 4 4
subject to
-1≤x 1≤3,-2≤x 2≤0,-1≤x 4≤3,
starting from the initial guess 3,-1,0,1.

Example program (C#): e04kye.cs

Example program results: e04kye.r

See Also

E04 Class
E04 Members


e04kz Method

[image]

NAG Library for .NET Release 2
E04..::e04kz Method
E04 Class See Also Send Feedback
e04kz is an easy-to-use modified Newton algorithm for finding a minimum of a function F x 1,x 2,…,xn, subject to fixed upper and lower bounds on the independent variables x 1,x 2,…,xn, when first derivatives of F are available. It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).

Syntax

C#
public static void e04kz(
    int n,
    int ibound,
    E04..::..E04KZ_FUNCT2 funct2,
    double[] bl,
    double[] bu,
    double[] x,
    out double f,
    double[] g,
    out int ifail
)
Visual Basic
Public Shared Sub e04kz ( _
    n As Integer, _
    ibound As Integer, _
    funct2 As E04..::..E04KZ_FUNCT2, _
    bl As Double(), _
    bu As Double(), _
    x As Double(), _
    <OutAttribute> ByRef f As Double, _
    g As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04kz(
    int n,
    int ibound,
    E04..::..E04KZ_FUNCT2^ funct2,
    array<double>^ bl,
    array<double>^ bu,
    array<double>^ x,
    [OutAttribute] double% f,
    array<double>^ g,
    [OutAttribute] int% ifail
)
F#
static member e04kz :
        n : int *
        ibound : int *
        funct2 : E04..::..E04KZ_FUNCT2 *
        bl : float[] *
        bu : float[] *
        x : float[] *
        f : float byref *
        g : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: the number n of independent variables.
Constraint: n≥1.
ibound
Type: System..::..Int32
On entry: indicates whether the facility for dealing with bounds of special forms is to be used. It must be set to one of the following values:
ibound=0
If you are supplying all the lj and uj individually.
ibound=1
If there are no bounds on any xj.
ibound=2
If all the bounds are of the form 0≤xj.
ibound=3
If l 1=l 2=⋯=ln and u 1=u 2=⋯=un.
Constraint: 0≤ibound≤3.
funct2
Type: NagLibrary..::..E04..::..E04KZ_FUNCT2
You must supply this method to calculate the values of the function F x and its first derivatives ∂F∂xj at any point x. It should be tested separately before being used in conjunction with e04kz (see E04 class).

A delegate of type E04KZ_FUNCT2.

bl
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the lower bounds lj.
If ibound is set to 0, you must set bl[j-1] to lj, for j=1,2,…,n. (If a lower bound is not specified for a particular xj, the corresponding bl[j-1] should be set to -106.)
If ibound is set to 3, you must set bl[0] to l 1; e04kz will then set the remaining elements of bl equal to bl[0].
On exit: the lower bounds actually used by e04kz.
bu
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the upper bounds uj.
If ibound is set to 0, you must set bu[j-1] to uj, for j=1,2,…,n. (If an upper bound is not specified for a particular xj, the corresponding bu[j-1] should be set to 106.)
If ibound is set to 3, you must set bu[0] to u 1; e04kz will then set the remaining elements of bu equal to bu[0].
On exit: the upper bounds actually used by e04kz.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x[j-1] must be set to a guess at the jth component of the position of the minimum, for j=1,2,…,n. The method checks the gradient at the starting point, and is more likely to detect any error in your programming if the initial x[j-1] are nonzero and mutually distinct.
On exit: the lowest point found during the calculations of the position of the minimum.
f
Type: System..::..Double %
On exit: the value of F x corresponding to the final point stored in x.
g
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the value of ∂F∂xj corresponding to the final point stored in x, for j=1,2,…,n; the value of g[j-1] for variables not on a bound should normally be close to zero.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04kz is applicable to problems of the form:
Minimize F x 1,x 2,…,xn  subject to  lj≤xj≤uj,  j=1,2,…,n
when first derivatives are known.
Special provision is made for problems which actually have no bounds on the xj, problems which have only non-negativity bounds, and problems in which l 1=l 2=⋯=ln and u 1=u 2=⋯=un. You must supply a method to calculate the values of F x and its first derivatives at any point x.
From a starting point you supplied there is generated, on the basis of estimates of the gradient of the curvature of F x, a sequence of feasible points which is intended to converge to a local minimum of the constrained function.

References

Gill P E and Murray W (1976) Minimization subject to bounds on the variables NPL Report NAC 72 National Physical Laboratory

Error Indicators and Warnings

Note: e04kz may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail=1
On entry, | n<1,
or | ibound<0,
or | ibound>3,
or | ibound=0 and bl[j-1]>bu[j-1] for some j,
or | ibound=3 and bl[0]>bu[0],
or | liw<n+2,
or | lw<max 10,n×n+7.
ifail=2
There has been a large number of function evaluations, yet the algorithm does not seem to be converging. The calculations can be restarted from the final point held in x. The error may also indicate that F x has no minimum.
ifail=3
The conditions for a minimum have not all been met but a lower point could not be found and the algorithm has failed.
ifail=4
Not used. (This value of the parameter is included to make the significance of ifail=5 etc. consistent in the easy-to-use methods.)
ifail=5
ifail=6
ifail=7
ifail=8
There is some doubt about whether the point x found by e04kz is a minimum. The degree of confidence in the result decreases as ifail increases. Thus, when ifail=5 it is probable that the final x gives a good estimate of the position of a minimum, but when ifail=8 it is very unlikely that the method has found a minimum.
ifail=9
In the search for a minimum, the modulus of one of the variables has become very large ∼106. This indicates that there is a mistake in funct2, that your problem has no finite solution, or that the problem needs rescaling (see [Further Comments]).
ifail=10
It is very likely that you have made an error in forming the gradient.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
If you are dissatisfied with the result (e.g., because ifail=5, 6, 7 or 8), it is worth restarting the calculations from a different starting point (not the point at which the failure occurred) in order to avoid the region which caused the failure. If persistent trouble occurs and it is possible to calculate second derivatives it may be advisable to change to a method which uses second derivatives (see the E04 class).

Accuracy

When a successful exit is made then, for a computer with a mantissa of t decimals, one would expect to get about t/2-1 decimals accuracy in x and about t-1 decimals accuracy in F, provided the problem is reasonably well scaled.

Parallelism and Performance

None.

Further Comments

The number of iterations required depends on the number of variables, the behaviour of F x and the distance of the starting point from the solution. The number of operations performed in an iteration of e04kz is roughly proportional to n 3+O n 2. In addition, each iteration makes at least m+1 calls of funct2 where m is the number of variables not fixed on bounds. So unless F x and the gradient vector can be evaluated very quickly, the run time will be dominated by the time spent in funct2.
Ideally the problem should be scaled so that at the solution the value of F x and the corresponding values of x 1,x 2,…,xn are in the range -1,+1, and so that at points a unit distance away from the solution, F is approximately a unit value greater than at the minimum. It is unlikely that you will be able to follow these recommendations very closely, but it is worth trying (by guesswork), as sensible scaling will reduce the difficulty of the minimization problem, so that e04kz will take less computer time.

Example

A program to minimize
F=x 1+10 x 2 2+5⁢x 3-x 4 2+x 2-2 x 3 4+10⁢x 1-x 4 4
subject to
1≤x 1≤3-2≤x 2≤01≤x 4≤3
starting from the initial guess 3,-1,0,1.
In practice, it is worth trying to make funct2 as efficient as possible. This has not been done in the example program for reasons of clarity.

Example program (C#): e04kze.cs

Example program results: e04kze.r

See Also

E04 Class
E04 Members


e04lb Method

[image]

NAG Library for .NET Release 2
E04..::e04lb Method
E04 Class See Also Send Feedback
e04lb is a comprehensive modified Newton algorithm for finding:
  • an unconstrained minimum of a function of several variables
  • a minimum of a function of several variables subject to fixed upper and/or lower bounds on the variables.
First and second derivatives are required. The method is intended for functions which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).

Syntax

C#
public static void e04lb(
    int n,
    E04..::..E04LB_FUNCT funct,
    E04..::..E04LB_H h,
    E04..::..E04LB_MONIT monit,
    int iprint,
    int maxcal,
    double eta,
    double xtol,
    double stepmx,
    int ibound,
    double[] bl,
    double[] bu,
    double[] x,
    double[] hesl,
    double[] hesd,
    int[] istate,
    out double f,
    double[] g,
    out int ifail
)
Visual Basic
Public Shared Sub e04lb ( _
    n As Integer, _
    funct As E04..::..E04LB_FUNCT, _
    h As E04..::..E04LB_H, _
    monit As E04..::..E04LB_MONIT, _
    iprint As Integer, _
    maxcal As Integer, _
    eta As Double, _
    xtol As Double, _
    stepmx As Double, _
    ibound As Integer, _
    bl As Double(), _
    bu As Double(), _
    x As Double(), _
    hesl As Double(), _
    hesd As Double(), _
    istate As Integer(), _
    <OutAttribute> ByRef f As Double, _
    g As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04lb(
    int n,
    E04..::..E04LB_FUNCT^ funct,
    E04..::..E04LB_H^ h,
    E04..::..E04LB_MONIT^ monit,
    int iprint,
    int maxcal,
    double eta,
    double xtol,
    double stepmx,
    int ibound,
    array<double>^ bl,
    array<double>^ bu,
    array<double>^ x,
    array<double>^ hesl,
    array<double>^ hesd,
    array<int>^ istate,
    [OutAttribute] double% f,
    array<double>^ g,
    [OutAttribute] int% ifail
)
F#
static member e04lb :
        n : int *
        funct : E04..::..E04LB_FUNCT *
        h : E04..::..E04LB_H *
        monit : E04..::..E04LB_MONIT *
        iprint : int *
        maxcal : int *
        eta : float *
        xtol : float *
        stepmx : float *
        ibound : int *
        bl : float[] *
        bu : float[] *
        x : float[] *
        hesl : float[] *
        hesd : float[] *
        istate : int[] *
        f : float byref *
        g : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: the number n of independent variables.
Constraint: n≥1.
funct
Type: NagLibrary..::..E04..::..E04LB_FUNCT
funct must evaluate the function F x and its first derivatives ∂F∂xj at any point x. (However, if you do not wish to calculate F x or its first derivatives at a particular x, there is the option of setting a parameter to cause e04lb to terminate immediately.)

A delegate of type E04LB_FUNCT.

Note: funct should be tested separately before being used in conjunction with e04lb.
h
Type: NagLibrary..::..E04..::..E04LB_H
h must calculate the second derivatives of F at any point x. (As with funct, there is the option of causing e04lb to terminate immediately.)

A delegate of type E04LB_H.

Note: h should be tested separately before being used in conjunction with e04lb.
monit
Type: NagLibrary..::..E04..::..E04LB_MONIT
If iprint≥0, you must supply monit which is suitable for monitoring the minimization process. monit must not change the values of any of its parameters.
If iprint<0, a monit with the correct parameter list should still be supplied, although it will not be called.

A delegate of type E04LB_MONIT.

You should normally print out fc, gpjnrm and cond so as to be able to compare the quantities mentioned in [Accuracy]. It is normally helpful to examine xc, posdef and nf as well.
iprint
Type: System..::..Int32
On entry: the frequency with which monit is to be called.
iprint>0
monit is called once every iprint iterations and just before exit from e04lb.
iprint=0
monit is just called at the final point.
iprint<0
monit is not called at all.
iprint should normally be set to a small positive number.
Suggested value: iprint=1.
maxcal
Type: System..::..Int32
On entry: the maximum permitted number of evaluations of F x, i.e., the maximum permitted number of calls of funct.
Suggested value: maxcal=50×n.
Constraint: maxcal≥1.
eta
Type: System..::..Double
On entry: every iteration of e04lb involves a linear minimization (i.e., minimization of F x+αp with respect to α). eta specifies how accurately these linear minimizations are to be performed. The minimum with respect to α will be located more accurately for small values of eta (say, 0.01) than for large values (say, 0.9).
Although accurate linear minimizations will generally reduce the number of iterations of e04lb, this usually results in an increase in the number of function and gradient evaluations required for each iteration. On balance, it is usually more efficient to perform a low accuracy linear minimization.
Suggested value: eta=0.9 is usually a good choice although a smaller value may be warranted if the matrix of second derivatives is expensive to compute compared with the function and first derivatives.
If n=1, eta should be set to 0.0 (also when the problem is effectively one-dimensional even though n>1; i.e., if for all except one of the variables the lower and upper bounds are equal).
Constraint: 0.0≤eta<1.0.
xtol
Type: System..::..Double
On entry: the accuracy in x to which the solution is required.
If xtrue is the true value of x at the minimum, then xsol, the estimated position before a normal exit, is such that xsol-xtrue<xtol×1.0+xtrue, where y=∑j=1 n yj 2. For example, if the elements of xsol are not much larger than 1.0 in modulus, and if xtol is set to 10-5 then xsol is usually accurate to about five decimal places. (For further details see [Accuracy].)
If the problem is scaled roughly as described in [Further Comments] and ε is the machine precision, then ε is probably the smallest reasonable choice for xtol. (This is because, normally, to machine accuracy, F x+ε,ej=F x where ej is any column of the identity matrix.)
If you set xtol to 0.0 (or any positive value less than ε), e04lb will use 10.0×ε instead of xtol.
Suggested value: xtol=0.0.
Constraint: xtol≥0.0.
stepmx
Type: System..::..Double
On entry: an estimate of the Euclidean distance between the solution and the starting point supplied by you. (For maximum efficiency a slight overestimate is preferable.)
e04lb will ensure that, for each iteration,
∑j=1 n xj k-xj k-1 2≤stepmx
where k is the iteration number. Thus, if the problem has more than one solution, e04lb is most likely to find the one nearest to the starting point. On difficult problems, a realistic choice can prevent the sequence of x k entering a region where the problem is ill-behaved and can also help to avoid possible overflow in the evaluation of F x. However, an underestimate of stepmx can lead to inefficiency.
Suggested value: stepmx=100000.0.
Constraint: stepmx≥xtol.
ibound
Type: System..::..Int32
On entry: specifies whether the problem is unconstrained or bounded. If there are bounds on the variables, ibound can be used to indicate whether the facility for dealing with bounds of special forms is to be used. It must be set to one of the following values:
ibound=0
If the variables are bounded and you are supplying all the lj and uj individually.
ibound=1
If the problem is unconstrained.
ibound=2
If the variables are bounded, but all the bounds are of the form 0≤xj.
ibound=3
If all the variables are bounded, and l 1=l 2=⋯=ln and u 1=u 2=⋯=un.
ibound=4
If the problem is unconstrained. (The ibound=4 option is provided purely for consistency with other methods. In e04lb it produces the same effect as ibound=1.)
Constraint: 0≤ibound≤4.
bl
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the fixed lower bounds lj.
If ibound is set to 0, you must set bl[j-1] to lj, for j=1,2,…,n. (If a lower bound is not specified for any xj, the corresponding bl[j-1] should be set to a large negative number, e.g., -106.)
If ibound is set to 3, you must set bl[0] to l 1; e04lb will then set the remaining elements of bl equal to bl[0].
If ibound is set to 1, 2 or 4, bl will be initialized by e04lb.
On exit: the lower bounds actually used by e04lb, e.g., if ibound=2, bl[0]=bl[1]=⋯=bl[n-1]=0.0.
bu
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the fixed upper bounds uj.
If ibound is set to 0, you must set bu[j-1] to uj, for j=1,2,…,n. (If an upper bound is not specified for any variable, the corresponding bu[j-1] should be set to a large positive number, e.g., 106.)
If ibound is set to 3, you must set bu[0] to u 1; e04lb will then set the remaining elements of bu equal to bu[0].
If ibound is set to 1, 2 or 4, bu will then be initialized by e04lb.
On exit: the upper bounds actually used by e04lb, e.g., if ibound=2, bu[0]=bu[1]=⋯=bu[n-1]=106.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x[j-1] must be set to a guess at the jth component of the position of the minimum, for j=1,2,…,n.
On exit: the final point x k. Thus, if ifail=0 on exit, x[j-1] is the jth component of the estimated position of the minimum.
hesl
Type: array< System..::..Double >[]()[][]
An array of size [lh]
On exit: during the determination of a direction pz (see [Description]), H+E is decomposed into the product LD LT, where L is a unit lower triangular matrix and D is a diagonal matrix. (The matrices H, E, L and D are all of dimension nz, where nz is the number of variables free from their bounds. H consists of those rows and columns of the full estimated second derivative matrix which relate to free variables. E is chosen so that H+E is positive definite.)
hesl and hesd are used to store the factors L and D. The elements of the strict lower triangle of L are stored row by row in the first nz nz-1/2 positions of hesl. The diagonal elements of D are stored in the first nz positions of hesd. In the last factorization before a normal exit, the matrix E will be zero, so that hesl and hesd will contain, on exit, the factors of the final estimated second derivative matrix H. The elements of hesd are useful for deciding whether to accept the results produced by e04lb (see [Accuracy]).
hesd
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: during the determination of a direction pz (see [Description]), H+E is decomposed into the product LD LT, where L is a unit lower triangular matrix and D is a diagonal matrix. (The matrices H, E, L and D are all of dimension nz, where nz is the number of variables free from their bounds. H consists of those rows and columns of the full second derivative matrix which relate to free variables. E is chosen so that H+E is positive definite.)
hesl and hesd are used to store the factors L and D. The elements of the strict lower triangle of L are stored row by row in the first nz nz-1/2 positions of hesl. The diagonal elements of D are stored in the first nz positions of hesd.
In the last factorization before a normal exit, the matrix E will be zero, so that hesl and hesd will contain, on exit, the factors of the final second derivative matrix H. The elements of hesd are useful for deciding whether to accept the result produced by e04lb (see [Accuracy]).
istate
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On exit: information about which variables are currently on their bounds and which are free. If istate[j-1] is:
  • – equal to -1, xj is fixed on its upper bound;
  • – equal to -2, xj is fixed on its lower bound;
  • – equal to -3, xj is effectively a constant (i.e., lj=uj);
  • – positive, istate[j-1] gives the position of xj in the sequence of free variables.
f
Type: System..::..Double %
On exit: the function value at the final point given in x.
g
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the first derivative vector corresponding to the final point given in x. The components of g corresponding to free variables should normally be close to zero.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04lb is applicable to problems of the form:
MinimizeF x 1,x 2,…,xn subject to ​lj≤xj≤uj,  j=1,2,…,n.
Special provision is made for unconstrained minimization (i.e., problems which actually have no bounds on the xj), problems which have only non-negativity bounds, and problems in which l 1=l 2=⋯=ln and u 1=u 2=⋯=un. It is possible to specify that a particular xj should be held constant. You must supply a starting point, a funct to calculate the value of F x and its first derivatives ∂F∂xj at any point x, and a h to calculate the second derivatives ∂2 F∂xi∂xj.
A typical iteration starts at the current point x where nz (say) variables are free from both their bounds. The vector of first derivatives of F x with respect to the free variables, gz, and the matrix of second derivatives with respect to the free variables, H, are obtained. (These both have dimension nz.)
The equations
H+E pz=-gz
are solved to give a search direction pz. (The matrix E is chosen so that H+E is positive definite.)
pz is then expanded to an n-vector p by the insertion of appropriate zero elements; α is found such that F x+αp is approximately a minimum (subject to the fixed bounds) with respect to α, and x is replaced by x+αp. (If a saddle point is found, a special search is carried out so as to move away from the saddle point.)
If any variable actually reaches a bound, it is fixed and nz is reduced for the next iteration.
There are two sets of convergence criteria – a weaker and a stronger. Whenever the weaker criteria are satisfied, the Lagrange multipliers are estimated for all active constraints. If any Lagrange multiplier estimate is significantly negative, then one of the variables associated with a negative Lagrange multiplier estimate is released from its bound and the next search direction is computed in the extended subspace (i.e., nz is increased). Otherwise, minimization continues in the current subspace until the stronger criteria are satisfied. If at this point there are no negative or near-zero Lagrange multiplier estimates, the process is terminated.
If you specify that the problem is unconstrained, e04lb sets the lj to -106 and the uj to 106. Thus, provided that the problem has been sensibly scaled, no bounds will be encountered during the minimization process and e04lb will act as an unconstrained minimization algorithm.

References

Gill P E and Murray W (1973) Safeguarded steplength algorithms for optimization using descent methods NPL Report NAC 37 National Physical Laboratory
Gill P E and Murray W (1974) Newton-type methods for unconstrained and linearly constrained optimization Math. Programming 7 311–350
Gill P E and Murray W (1976) Minimization subject to bounds on the variables NPL Report NAC 72 National Physical Laboratory

Error Indicators and Warnings

Note: e04lb may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (IW, LIW, W, LW) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail<0
A negative value of ifail indicates an exit from e04lb because you have set iflag negative in funct or h. The value of ifail will be the same as your setting of iflag.
ifail=1
On entry, | n<1,
or | maxcal<1,
or | eta<0.0,
or | eta≥1.0,
or | xtol<0.0,
or | stepmx<xtol,
or | ibound<0,
or | ibound>4,
or | bl[j-1]>bu[j-1] for some j if ibound=0,
or | bl[0]>bu[0] if ibound=3,
or | lh<max 1,n×n-1/2,
(Note that if you have set xtol to 0.0, e04lb uses the default value and continues without failing.) When this exit occurs no values will have been assigned to f or to the elements of hesl, hesd or g.
ifail=2
There have been maxcal function evaluations. If steady reductions in F x were monitored up to the point where this exit occurred, then the exit probably occurred simply because maxcal was set too small, so the calculations should be restarted from the final point held in x. This exit may also indicate that F x has no minimum.
ifail=3
The conditions for a minimum have not all been met, but a lower point could not be found.
Provided that, on exit, the first derivatives of F x with respect to the free variables are sufficiently small, and that the estimated condition number of the second derivative matrix is not too large, this error exit may simply mean that, although it has not been possible to satisfy the specified requirements, the algorithm has in fact found the minimum as far as the accuracy of the machine permits. Such a situation can arise, for instance, if xtol has been set so small that rounding errors in the evaluation of F x or its derivatives make it impossible to satisfy the convergence conditions.
If the estimated condition number of the second derivative matrix at the final point is large, it could be that the final point is a minimum, but that the smallest eigenvalue of the Hessian matrix is so close to zero that it is not possible to recognize the point as a minimum.
ifail=4
Not used. (This is done to make the significance of ifail=5 similar for e04kd and e04lb.)
ifail=5
All the Lagrange multiplier estimates which are not indisputably positive lie relatively close to zero, but it is impossible either to continue minimizing on the current subspace or to find a feasible lower point by releasing and perturbing any of the fixed variables. You should investigate as for ifail=3.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
The values ifail=2, 3 or 5 may also be caused by mistakes in user-supplied delegates funct or h, by the formulation of the problem or by an awkward function. If there are no such mistakes, it is worth restarting the calculations from a different starting point (not the point at which the failure occurred) in order to avoid the region which caused the failure.

Accuracy

A successful exit (ifail=0) is made from e04lb when H k is positive definite and when (B1, B2 and B3) or B4 hold, where
B1≡α k×p k<xtol+ε×1.0+x kB2≡F k-F k-1<xtol 2+ε×1.0+F kB3≡gz k<ε 1/3+xtol×1.0+F kB4≡gz k<0.01×ε.
(Quantities with superscript k are the values at the kth iteration of the quantities mentioned in [Description]. ε is the machine precision and . denotes the Euclidean norm.)
If ifail=0, then the vector in x on exit, xsol, is almost certainly an estimate of the position of the minimum, xtrue, to the accuracy specified by xtol.
If ifail=3 or 5, xsol may still be a good estimate of xtrue, but the following checks should be made. Let the largest of the first nz elements of hesd be hesd[b-1], let the smallest be hesd[s-1], and define k=hesd[b-1]/hesd[s-1]. The scalar k is usually a good estimate of the condition number of the projected Hessian matrix at xsol. If
(i) | the sequence F x k converges to F xsol at a superlinear or fast linear rate,
(ii) | gz xsol 2<10.0×ε, and
(iii) | k<1.0/gz xsol,
then it is almost certain that xsol is a close approximation to the position of a minimum. When (ii) is true, then usually F xsol is a close approximation to F xtrue. The quantities needed for these checks are all available via monit; in particular the value of cond in the last call of monit before exit gives k.
Further suggestions about confirmation of a computed solution are given in the E04 class.

Parallelism and Performance

None.

Further Comments

Timing

The number of iterations required depends on the number of variables, the behaviour of F x, the accuracy demanded and the distance of the starting point from the solution. The number of multiplications performed in an iteration of e04lb is nz 3 6+O nz 2. In addition, each iteration makes one call of h and at least one call of funct. So, unless F x and its derivatives can be evaluated very quickly, the run time will be dominated by the time spent in funct and h.

Scaling

Ideally, the problem should be scaled so that, at the solution, F x and the corresponding values of the xj are each in the range -1,+1, and so that at points one unit away from the solution, F x differs from its value at the solution by approximately one unit. This will usually imply that the Hessian matrix at the solution is well-conditioned. It is unlikely that you will be able to follow these recommendations very closely, but it is worth trying (by guesswork), as sensible scaling will reduce the difficulty of the minimization problem, so that e04lb will take less computer time.

Unconstrained Minimization

If a problem is genuinely unconstrained and has been scaled sensibly, the following points apply:
(a) | nz will always be n,
(b) | hesl and hesd will be factors of the full second derivative matrix with elements stored in the natural order,
(c) | the elements of g should all be close to zero at the final point,
(d) | the values of the istate[j-1] given by monit and on exit from e04lb are unlikely to be of interest (unless they are negative, which would indicate that the modulus of one of the xj has reached 106 for some reason),
(e) | monit's parameter gpjnrm simply gives the norm of the first derivative vector.

Example

Example program (C#): e04lbe.cs

Example program results: e04lbe.r

See Also

E04 Class
E04 Members


e04ly Method

[image]

NAG Library for .NET Release 2
E04..::e04ly Method
E04 Class See Also Send Feedback
e04ly is an easy-to-use modified-Newton algorithm for finding a minimum of a function, F x 1,x 2,…,xn subject to fixed upper and lower bounds on the independent variables, x 1,x 2,…,xn when first and second derivatives of F are available. It is intended for functions which are continuous and which have continuous first and second derivatives (although it will usually work even if the derivatives have occasional discontinuities).

Syntax

C#
public static void e04ly(
    int n,
    int ibound,
    E04..::..E04LY_FUNCT2 funct2,
    E04..::..E04LY_HESS2 hess2,
    double[] bl,
    double[] bu,
    double[] x,
    out double f,
    double[] g,
    out int ifail
)
Visual Basic
Public Shared Sub e04ly ( _
    n As Integer, _
    ibound As Integer, _
    funct2 As E04..::..E04LY_FUNCT2, _
    hess2 As E04..::..E04LY_HESS2, _
    bl As Double(), _
    bu As Double(), _
    x As Double(), _
    <OutAttribute> ByRef f As Double, _
    g As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04ly(
    int n,
    int ibound,
    E04..::..E04LY_FUNCT2^ funct2,
    E04..::..E04LY_HESS2^ hess2,
    array<double>^ bl,
    array<double>^ bu,
    array<double>^ x,
    [OutAttribute] double% f,
    array<double>^ g,
    [OutAttribute] int% ifail
)
F#
static member e04ly :
        n : int *
        ibound : int *
        funct2 : E04..::..E04LY_FUNCT2 *
        hess2 : E04..::..E04LY_HESS2 *
        bl : float[] *
        bu : float[] *
        x : float[] *
        f : float byref *
        g : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: the number n of independent variables.
Constraint: n≥1.
ibound
Type: System..::..Int32
On entry: indicates whether the facility for dealing with bounds of special forms is to be used. It must be set to one of the following values:
ibound=0
If you are supplying all the lj and uj individually.
ibound=1
If there are no bounds on any xj.
ibound=2
If all the bounds are of the form 0≤xj.
ibound=3
If l 1=l 2=⋯=ln and u 1=u 2=⋯=un.
Constraint: 0≤ibound≤3.
funct2
Type: NagLibrary..::..E04..::..E04LY_FUNCT2
You must supply this method to calculate the values of the function F x and its first derivatives ∂F∂xj at any point x. It should be tested separately before being used in conjunction with e04ly (see the E04 class).

A delegate of type E04LY_FUNCT2.

hess2
Type: NagLibrary..::..E04..::..E04LY_HESS2
You must supply this method to evaluate the elements H ij=∂2 F∂xi∂xj of the matrix of second derivatives of F x at any point x. It should be tested separately before being used in conjunction with e04ly (see the E04 class).

A delegate of type E04LY_HESS2.

bl
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the lower bounds lj.
If ibound is set to 0, bl[j-1] must be set to lj, for j=1,2,…,n. (If a lower bound is not specified for any xj, the corresponding bl[j-1] should be set to -106.)
If ibound is set to 3, you must set bl[0] to l 1; e04ly will then set the remaining elements of bl equal to bl[0].
On exit: the lower bounds actually used by e04ly.
bu
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the upper bounds uj.
If ibound is set to 0, bu[j-1] must be set to uj, for j=1,2,…,n. (If an upper bound is not specified for any xj the corresponding bu[j-1] should be set to 106.)
If ibound is set to 3, you must set bu[0] to u 1; e04ly will then set the remaining elements of bu equal to bu[0].
On exit: the upper bounds actually used by e04ly.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x[j-1] must be set to a guess at the jth component of the position of the minimum, for j=1,2,…,n. The method checks the gradient and the Hessian matrix at the starting point, and is more likely to detect any error in your programming if the initial x[j-1] are nonzero and mutually distinct.
On exit: the lowest point found during the calculations. Thus, if ifail=0 on exit, x[j-1] is the jth component of the position of the minimum.
f
Type: System..::..Double %
On exit: the value of F x corresponding to the final point stored in x.
g
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the value of ∂F∂xj corresponding to the final point stored in x, for j=1,2,…,n; the value of g[j-1] for variables not on a bound should normally be close to zero.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04ly is applicable to problems of the form:
Minimize F x 1,x 2,…,xn  subject to  lj≤xj≤uj,  j=1,2,…,n
when first and second derivatives of F x are available.
Special provision is made for problems which actually have no bounds on the xj, problems which have only non-negativity bounds and problems in which l 1=l 2=⋯=ln and u 1=u 2=⋯=un. You must supply a method to calculate the values of F x and its first derivatives at any point x and a method to calculate the second derivatives.
From a starting point you supplied there is generated, on the basis of estimates of the curvature of F x, a sequence of feasible points which is intended to converge to a local minimum of the constrained function.

References

Gill P E and Murray W (1976) Minimization subject to bounds on the variables NPL Report NAC 72 National Physical Laboratory

Error Indicators and Warnings

Note: e04ly may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail=1
On entry, | n<1,
or | ibound<0,
or | ibound>3,
or | ibound=0 and bl[j-1]>bu[j-1] for some j,
or | ibound=3 and bl[0]>bu[0],
or | liw<n+2,
or | lw<max 10,n×n+7.
ifail=2
There have been 50×n function evaluations, yet the algorithm does not seem to be converging. The calculations can be restarted from the final point held in x. The error may also indicate that F x has no minimum.
ifail=3
The conditions for a minimum have not all been met but a lower point could not be found and the algorithm has failed.
ifail=4
Not used. (This value of the parameter is included so as to make the significance of ifail=5 etc. consistent in the easy-to-use methods.)
ifail=5
ifail=6
ifail=7
ifail=8
There is some doubt about whether the point x found by e04ly is a minimum. The degree of confidence in the result decreases as ifail increases. Thus, when ifail=5 it is probable that the final x gives a good estimate of the position of a minimum, but when ifail=8 it is very unlikely that the method has found a minimum.
ifail=9
In the search for a minimum, the modulus of one of the variables has become very large ∼106. This indicates that there is a mistake in user-supplied delegates funct2 or hess2, that your problem has no finite solution, or that the problem needs rescaling (see [Further Comments]).
ifail=10
It is very likely that you have made an error in forming the gradient.
ifail=11
It is very likely that you have made an error in forming the second derivatives.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
If you are dissatisfied with the result (e.g., because ifail=5, 6, 7 or 8), it is worth restarting the calculations from a different starting point (not the point at which the failure occurred) in order to avoid the region which caused the failure.

Accuracy

When a successful exit is made then, for a computer with a mantissa of t decimals, one would expect to get about t/2-1 decimals accuracy in x, and about t-1 decimals accuracy in F, provided the problem is reasonably well scaled.

Parallelism and Performance

None.

Further Comments

The number of iterations required depends on the number of variables, the behaviour of F x and the distance of the starting point from the solution. The number of operations performed in an iteration of e04ly is roughly proportional to n 3+O n 2. In addition, each iteration makes one call of hess2 and at least one call of funct2. So, unless F x, the gradient vector and the matrix of second derivatives can be evaluated very quickly, the run time will be dominated by the time spent in user-supplied delegates funct2 and hess2.
Ideally the problem should be scaled so that at the solution the value of F x and the corresponding values of x 1,x 2,…xn are each in the range -1,+1, and so that at points a unit distance away from the solution, F is approximately a unit value greater than at the minimum. It is unlikely that you will be able to follow these recommendations very closely, but it is worth trying (by guesswork), as sensible scaling will reduce the difficulty of the minimization problem, so that e04ly will take less computer time.

Example

A program to minimize
F=x 1+10 x 2 2+5⁢x 3-x 4 2+x 2-2 x 3 4+10⁢x 1-x 4 4
subject to
1≤x 1≤3-2≤x 2≤01≤x 4≤3.
starting from the initial guess 3,-1,0,1. (In practice, it is worth trying to make user-supplied delegates funct2 and hess2 as efficient as possible. This has not been done in the example program for reasons of clarity.)

Example program (C#): e04lye.cs

Example program results: e04lye.r

See Also

E04 Class
E04 Members


e04mf Method

[image]

NAG Library for .NET Release 2
E04..::e04mf Method
E04 Class See Also Send Feedback
e04mf solves general linear programming problems. It is not intended for large sparse problems.

Syntax

C#
public static void e04mf(
    int n,
    int nclin,
    double[,] a,
    double[] bl,
    double[] bu,
    double[] cvec,
    int[] istate,
    double[] x,
    out int iter,
    out double obj,
    double[] ax,
    double[] clamda,
    E04..::..e04mfOptions options,
    out int ifail
)
Visual Basic
Public Shared Sub e04mf ( _
    n As Integer, _
    nclin As Integer, _
    a As Double(,), _
    bl As Double(), _
    bu As Double(), _
    cvec As Double(), _
    istate As Integer(), _
    x As Double(), _
    <OutAttribute> ByRef iter As Integer, _
    <OutAttribute> ByRef obj As Double, _
    ax As Double(), _
    clamda As Double(), _
    options As E04..::..e04mfOptions, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04mf(
    int n,
    int nclin,
    array<double,2>^ a,
    array<double>^ bl,
    array<double>^ bu,
    array<double>^ cvec,
    array<int>^ istate,
    array<double>^ x,
    [OutAttribute] int% iter,
    [OutAttribute] double% obj,
    array<double>^ ax,
    array<double>^ clamda,
    E04..::..e04mfOptions^ options,
    [OutAttribute] int% ifail
)
F#
static member e04mf :
        n : int *
        nclin : int *
        a : float[,] *
        bl : float[] *
        bu : float[] *
        cvec : float[] *
        istate : int[] *
        x : float[] *
        iter : int byref *
        obj : float byref *
        ax : float[] *
        clamda : float[] *
        options : E04..::..e04mfOptions *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of variables.
Constraint: n>0.
nclin
Type: System..::..Int32
On entry: mL, the number of general linear constraints.
Constraint: nclin≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,nclin
Note: the second dimension of the array a must be at least n if nclin>0 and at least 1 if nclin=0.
On entry: the ith row of a must contain the coefficients of the ith general linear constraint, for i=1,2,…,mL.
If nclin=0, a is not referenced.
bl
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin]
On entry: must contain the lower bounds and bu the upper bounds, for all the constraints in the following order. The first n elements of each array must contain the bounds on the variables, and the next mL elements the bounds for the general linear constraints (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j-1]≤-bigbnd, and to specify a nonexistent upper bound (i.e., uj=+∞), set bu[j-1]≥bigbnd; the default value of bigbnd is 1020, but this may be changed by the optional parameter Infinite Bound Size. To specify the jth constraint as an equality, set bl[j-1]=bu[j-1]=β, say, where β<bigbnd.
Constraints:
  • bl[j-1]≤bu[j-1], for j=1,2,…,n+nclin;
  • if bl[j-1]=bu[j-1]=β, β<bigbnd.
bu
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin]
On entry: must contain the lower bounds and bu the upper bounds, for all the constraints in the following order. The first n elements of each array must contain the bounds on the variables, and the next mL elements the bounds for the general linear constraints (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j-1]≤-bigbnd, and to specify a nonexistent upper bound (i.e., uj=+∞), set bu[j-1]≥bigbnd; the default value of bigbnd is 1020, but this may be changed by the optional parameter Infinite Bound Size. To specify the jth constraint as an equality, set bl[j-1]=bu[j-1]=β, say, where β<bigbnd.
Constraints:
  • bl[j-1]≤bu[j-1], for j=1,2,…,n+nclin;
  • if bl[j-1]=bu[j-1]=β, β<bigbnd.
cvec
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array cvec must be at least n if the problem is of type LP (the default), and at least 1 otherwise.
On entry: the coefficients of the objective function when the problem is of type LP.
If the problem is of type FP, cvec is not referenced.
istate
Type: array< System..::..Int32 >[]()[][]
An array of size [n+nclin]
On entry: need not be set if the (default) optional parameter Cold Start is used.
If the optional parameter Warm Start has been chosen, istate specifies the desired status of the constraints at the start of the feasibility phase. More precisely, the first n elements of istate refer to the upper and lower bounds on the variables, and the next mL elements refer to the general linear constraints (if any). Possible values for istate[j-1] are as follows:
istate[j-1] | Meaning
0 | The corresponding constraint should not be in the initial working set.
1 | The constraint should be in the initial working set at its lower bound.
2 | The constraint should be in the initial working set at its upper bound.
3 | The constraint should be in the initial working set as an equality. This value must not be specified unless bl[j-1]=bu[j-1].
The values -2, -1 and 4 are also acceptable but will be reset to zero by the method. If e04mf has been called previously with the same values of n and nclin, istate already contains satisfactory information. (See also the description of the optional parameter Warm Start.) The method also adjusts (if necessary) the values supplied in x to be consistent with istate.
Constraint: -2≤istate[j-1]≤4, for j=1,2,…,n+nclin.
On exit: the status of the constraints in the working set at the point returned in x. The significance of each possible value of istate[j-1] is as follows:
istate[j-1] | Meaning
-2 | The constraint violates its lower bound by more than the feasibility tolerance.
-1 | The constraint violates its upper bound by more than the feasibility tolerance.
-0 | The constraint is satisfied to within the feasibility tolerance, but is not in the working set.
-1 | This inequality constraint is included in the working set at its lower bound.
-2 | This inequality constraint is included in the working set at its upper bound.
-3 | This constraint is included in the working set as an equality. This value of istate can occur only when bl[j-1]=bu[j-1].
-4 | This corresponds to optimality being declared with x[j-1] being temporarily fixed at its current value. This value of istate can occur only when ifail=1 on exit.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: an initial estimate of the solution.
On exit: the point at which e04mf terminated. If ifail=0, 1 or 4, x contains an estimate of the solution.
iter
Type: System..::..Int32 %
On exit: the total number of iterations performed.
obj
Type: System..::..Double %
On exit: the value of the objective function at x if x is feasible, or the sum of infeasibiliites at x otherwise. If the problem is of type FP and x is feasible, obj is set to zero.
ax
Type: array< System..::..Double >[]()[][]
An array of size [max 1,nclin]
On exit: the final values of the linear constraints Ax.
If nclin=0, ax is not referenced.
clamda
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin]
On exit: the values of the Lagrange multipliers for each constraint with respect to the current working set. The first n elements contain the multipliers for the bound constraints on the variables, and the next mL elements contain the multipliers for the general linear constraints (if any). If istate[j-1]=0 (i.e., constraint j is not in the working set), clamda[j-1] is zero. If x is optimal, clamda[j-1] should be non-negative if istate[j-1]=1, non-positive if istate[j-1]=2 and zero if istate[j-1]=4.
options
Type: NagLibrary..::..E04..::..e04mfOptions
An Object of type E04.e04mfOptions. Used to configure optional parameters to this method.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04mf is designed to solve linear programming (LP) problems of the form
minimize x∈Rn cT x,   subject to  l≤xAx≤u,
where c is an n-element vector and A is an mL by n matrix.
This is the default type of problem, referred to as type LP. The optional parameter Problem Type may be used to specify an alternative problem type FP, in which the objective function is omitted and the method attempts to find a feasible point for the set of constraints.
The constraints involving A are called the general constraints. Note that upper and lower bounds are specified for all the variables and for all the general constraints. An equality constraint can be specified by setting li=ui. If certain bounds are not present, the associated elements of l or u can be set to special values that will be treated as -∞ or +∞. (See the description of the optional parameter Infinite Bound Size.)
You must supply an initial estimate of the solution.
The method used by e04mf is described in detail in [Algorithmic Details].

References

Gill P E, Hammarling S, Murray W, Saunders M A and Wright M H (1986) Users' guide for LSSOL (Version 1.0) Report SOL 86-1 Department of Operations Research, Stanford University
Gill P E and Murray W (1978) Numerically stable methods for quadratic programming Math. Programming 14 349–372
Gill P E, Murray W, Saunders M A and Wright M H (1984) Procedures for optimization problems with a mixture of bounds and general linear constraints ACM Trans. Math. Software 10 282–298
Gill P E, Murray W, Saunders M A and Wright M H (1989) A practical anti-cycling procedure for linearly constrained optimization Math. Programming 45 437–474
Gill P E, Murray W, Saunders M A and Wright M H (1991) Inertia-controlling methods for general quadratic programming SIAM Rev. 33 1–36
Gill P E, Murray W and Wright M H (1981) Practical Optimization Academic Press

Error Indicators and Warnings

Note: e04mf may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
x is a weak local minimum (the projected gradient is negligible and the Lagrange multipliers are optimal but there is a small multiplier). This means that the solution is not unique.
ifail=2
The solution appears to be unbounded, i.e., the objective function is not bounded below in the feasible region. This value of ifail occurs if a step larger than Infinite Step Size (default value=1020) would have to be taken in order to continue the algorithm, or the next step would result in an element of x having magnitude larger than optional parameter Infinite Bound Size (default value=1020).
ifail=3
No feasible point was found, i.e., it was not possible to satisfy all the constraints to within the feasibility tolerance. In this case, the constraint violations at the final x will reveal a value of the tolerance for which a feasible point will exist – for example, when the feasibility tolerance for each violated constraint exceeds its Slack (see [Description of the Printed Output]) at the final point. The modified problem (with an altered feasibility tolerance) may then be solved using a Warm Start. You should check that there are no constraint redundancies. If the data for the constraints are accurate only to the absolute precision σ, you should ensure that the value of the optional parameter Feasibility Tolerance (default value=ε, where ε is the machine precision) is greater than σ. For example, if all elements of A are of order unity and are accurate only to three decimal places, the Feasibility Tolerance should be at least 10-3.
ifail=4
The limiting number of iterations was reached before normal termination occurred.
The value of the optional parameter Iteration Limit (default value=max 50,5 n+mL) may be too small. If the method appears to be making progress (e.g., the objective function is being satisfactorily reduced), either rerun e04mf with a larger value of Iteration Limit or, alternatively, rerun e04mf using the Warm Start facility to specify the initial working set.
ifail=5
Not used by this method.
ifail=6
An input parameter is invalid.
ifail=7
The designated problem type was not FP or LP. Rerun e04mf with the optional parameter Problem Type set to one of these values.
Overflow
If the printed output before the overflow error contains a warning about serious ill-conditioning in the working set when adding the jth constraint, it may be possible to avoid the difficulty by increasing the magnitude of the Feasibility Tolerance (default value=ε, where ε is the machine precision) and rerunning the program. If the message recurs even after this change, the offending linearly dependent constraint (with index ‘j’) must be removed from the problem.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

e04mf implements a numerically stable active set strategy and returns solutions that are as accurate as the condition of the problem warrants on the machine.

Parallelism and Performance

None.

Further Comments

This section contains some comments on scaling and a description of the printed output.

Scaling

Sensible scaling of the problem is likely to reduce the number of iterations required and make the problem less sensitive to perturbations in the data, thus improving the condition of the problem. In the absence of better information it is usually sensible to make the Euclidean lengths of each constraint of comparable magnitude. See the E04 class and Gill et al. (1981) for further information and advice.

Description of the Printed Output

This section describes the intermediate printout and final printout produced by e04mf. The intermediate printout is a subset of the monitoring information produced by the method at every iteration (see [Description of Monitoring Information]). You can control the level of printed output (see the description of the optional parameter Print Level). Note that the intermediate printout and final printout are produced only if Print Level≥10 (the default for e04mf, by default no output is produced by ).
The following line of summary output (<80 characters) is produced at every iteration. In all cases, the values of the quantities printed are those in effect on completion of the given iteration.
Itn | is the iteration count.
Step | is the step taken along the computed search direction. If a constraint is added during the current iteration, Step will be the step to the nearest constraint. When the problem is of type LP, the step can be greater than one during the optimality phase.
Ninf | is the number of violated constraints (infeasibilities). This will be zero during the optimality phase.
Sinf/Objective | is the value of the current objective function. If x is not feasible, Sinf gives a weighted sum of the magnitudes of constraint violations. If x is feasible, Objective is the value of the objective function of (1). The output line for the final iteration of the feasibility phase (i.e., the first iteration for which Ninf is zero) will give the value of the true objective at the first feasible point. During the optimality phase the value of the objective function will be nonincreasing. During the feasibility phase the number of constraint infeasibilities will not increase until either a feasible point is found or the optimality of the multipliers implies that no feasible point exists. Once optimal multipliers are obtained the number of infeasibilities can increase, but the sum of infeasibilities will either remain constant or be reduced until the minimum sum of infeasibilities is found.
Norm Gz | is ZRT gFR, the Euclidean norm of the reduced gradient with respect to ZR. During the optimality phase, this norm will be approximately zero after a unit step. (See [Definition of Search Direction] and [Choosing the Initial Working Set].)
The final printout includes a listing of the status of every variable and constraint.
The following describes the printout for each variable. A full stop (.) is printed for any numerical value that is zero.
Varbl | gives the name (V) and index j, for j=1,2,…,n, of the variable.
State gives the state of the variable (FR if neither bound is in the working set, EQ if a fixed variable, LL if on its lower bound, UL if on its upper bound, TF if temporarily fixed at its current value). If Value lies outside the upper or lower bounds by more than the Feasibility Tolerance, State will be ++ or -- respectively.
A key is sometimes printed before State.
A | Alternative optimum possible. The variable is active at one of its bounds, but its Lagrange multiplier is essentially zero. This means that if the variable were allowed to start moving away from its bound then there would be no change to the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case the values of the Lagrange multipliers might also change.
D | Degenerate. The variable is free, but it is equal to (or very close to) one of its bounds.
I | Infeasible. The variable is currently violating one of its bounds by more than the Feasibility Tolerance.
Value | is the value of the variable at the final iteration.
Lower Bound | is the lower bound specified for the variable. None indicates that bl[j-1]≤-bigbnd.
Upper Bound | is the upper bound specified for the variable. None indicates that bu[j-1]≥bigbnd.
Lagr Mult | is the Lagrange multiplier for the associated bound. This will be zero if State is FR unless bl[j-1]≤-bigbnd and bu[j-1]≥bigbnd, in which case the entry will be blank. If x is optimal, the multiplier should be non-negative if State is LL and non-positive if State is UL.
Slack | is the difference between the variable Value and the nearer of its (finite) bounds bl[j-1] and bu[j-1]. A blank entry indicates that the associated variable is not bounded (i.e., bl[j-1]≤-bigbnd and bu[j-1]≥bigbnd).
The meaning of the printout for general constraints is the same as that given above for variables, with ‘variable’ replaced by ‘constraint’, bl[j-1] and bu[j-1] are replaced by bl[n+j-1] and bu[n+j-1] respectively, and with the following change in the heading:
L Con gives the name (L) and index j, for j=1,2,…,nL, of the linear constraint.
Note that movement off a constraint (as opposed to a variable moving away from its bound) can be interpreted as allowing the entry in the Slack column to become positive.
Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.

Example

This example minimizes the function
-0.02 x 1-0.2 x 2-0.2 x 3-0.2 x 4-0.2 x 5+0.04 x 6+0.04 x 7
subject to the bounds
-0.01≤x 1≤0.01-0.1 0≤x 2≤0.15-0.01≤x 3≤0.03-0.04≤x 4≤0.02-0.1 0≤x 5≤0.05-0.01≤x 6≤0.00-0.01≤x 7≤0.00
and the general constraints
x 1+x 2+x 3+x 4+x 5+x 6+x 7=-0.130.15 x 1+0.04 x 2+0.02 x 3+0.04 x 4+0.02 x 5+0.01 x 6+0.03 x 7≤-0.00490.03 x 1+0.05 x 2+0.08 x 3+0.02 x 4+0.06 x 5+0.01 x 6≤-0.00640 0.02 x 1+0.04 x 2+0.01 x 3+0.02 x 4+0.02 x 5≤-0.00370.02 x 1+0.03 x 2+0.01 x 5≤-0.0012-0.0992≤0.70 x 1+0.75 x 2+0.80 x 3+0.75 x 4+0.80 x 5+0.97 x 6-0.003≤0.02 x 1+0.06 x 2+0.08 x 3+0.12 x 4+0.02 x 5+0.01 x 6+0.97 x 7≤-0.002
The initial point, which is infeasible, is
x 0=-0.01,-0.03,0.0,-0.01,-0.1,0.02,0.01 T.
The optimal solution (to five figures) is
x*=-0.01,-0.1,0.03,0.02,-0.067485,-0.0022801,-0.00023453 T.
Four bound constraints and three general constraints are active at the solution.

Example program (C#): e04mfe.cs

Example program data: e04mfe.d

Example program results: e04mfe.r

Algorithmic Details

This section contains a detailed description of the method used by e04mf.

Overview

e04mf is based on an inertia-controlling method due to Gill and Murray (1978), and is described in detail by Gill et al. (1991). Here we briefly summarise the main features of the method. Where possible, explicit reference is made to the names of variables that are parameters of e04mf or appear in the printed output. e04mf has two phases: finding an initial feasible point by minimizing the sum of infeasibilities (the feasibility phase), and minimizing the linear objective function within the feasible region (the optimality phase). The computations in both phases are performed by the same methods. The two-phase nature of the algorithm is reflected by changing the function being minimized from the sum of infeasibilities to the linear objective function. The feasibility phase does not perform the standard simplex method (i.e., it does not necessarily find a vertex), except in the case when mL≤n. Once any iterate is feasible, all subsequent iterates remain feasible.
In general, an iterative process is required to solve a linear program. (For simplicity, we shall always consider a typical iteration and avoid reference to the index of the iteration.) Each new iterate x- is defined by
x-=x+αp, (1)
where the step length α is a non-negative scalar, and p is called the search direction.
At each point x, a working set of constraints is defined to be a linearly independent subset of the constraints that are satisfied ‘exactly’ (to within the tolerance defined by the optional parameter Feasibility Tolerance). The working set is the current prediction of the constraints that hold with equality at a solution of an LP problem. The search direction is constructed so that the constraints in the working set remain unaltered for any value of the step length. For a bound constraint in the working set, this property is achieved by setting the corresponding element of the search direction to zero. Thus, the associated variable is fixed, and specification of the working set induces a partition of x into fixed and free variables. During a given iteration, the fixed variables are effectively removed from the problem; since the relevant elements of the search direction are zero, the columns of A corresponding to fixed variables may be ignored.
Let mW denote the number of general constraints in the working set and let nFX denote the number of variables fixed at one of their bounds (mW and nFX are the quantities Lin and Bnd in the monitoring file output from e04mf; see [Description of Monitoring Information]). Similarly, let nFR (nFR=n-nFX) denote the number of free variables. At every iteration, the variables are reordered so that the last nFX variables are fixed, with all other relevant vectors and matrices ordered accordingly.

Definition of Search Direction

Let AFR denote the mW by nFR sub-matrix of general constraints in the working set corresponding to the free variables, and let pFR denote the search direction with respect to the free variables only. The general constraints in the working set will be unaltered by any move along p if
AFRpFR=0. (2)
In order to compute pFR, the TQ factorization of AFR is used:
AFRQFR=0 T, (3)
where T is a nonsingular mW by mW upper triangular matrix (i.e., t ij=0 if i>j), and the nonsingular nFR by nFR matrix QFR is the product of orthogonal transformations (see Gill et al. (1984)). If the columns of QFR are partitioned so that
QFR=Z Y,
where Y is nFR by mW, then the nZ (nZ=nFR-mW) columns of Z form a basis for the null space of AFR. Let nR be an integer such that 0≤nR≤nZ, and let ZR denote a matrix whose nR columns are a subset of the columns of Z. (The integer nR is the quantity Zr in the monitoring file output from e04mf. In many cases, ZR will include all the columns of Z.) The direction pFR will satisfy (2) if
pFR=ZRpR (4)
where pR is any nR-vector.

Main Iteration

Let Q denote the n by n matrix
Q=QFRIFX,
where IFX is the identity matrix of order nFX. Let gQ denote the transformed gradient
gQ=QT c
and let the vector of the first nR elements of gQ be denoted by gR. The quantity gR is known as the reduced gradient of cT x. If the reduced gradient is zero, x is a constrained stationary point in the subspace defined by Z. During the feasibility phase, the reduced gradient will usually be zero only at a vertex (although it may be zero at non-vertices in the presence of constraint dependencies). During the optimality phase, a zero reduced gradient implies that x minimizes the linear objective when the constraints in the working set are treated as equalities. At a constrained stationary point, Lagrange multipliers λC and λB for the general and bound constraints are defined from the equations
AFRT λC=gFR  and  λB=gFX-AFXT λC. (5)
Given a positive constant δ of the order of the machine precision, a Lagrange multiplier λj corresponding to an inequality constraint in the working set is said to be optimal if λj≤δ when the associated constraint is at its upper bound, or if λj≥-δ when the associated constraint is at its lower bound. If a multiplier is nonoptimal, the objective function (either the true objective or the sum of infeasibilities) can be reduced by deleting the corresponding constraint (with index Jdel; see [Description of Monitoring Information]) from the working set.
If optimal multipliers occur during the feasibility phase and the sum of infeasibilities is nonzero, there is no feasible point, and you can force e04mf to continue until the minimum value of the sum of infeasibilities has been found; see the discussion of the optional parameter Minimum Sum of Infeasibilities. At such a point, the Lagrange multiplier λj corresponding to an inequality constraint in the working set will be such that -1+δ≤λj≤δ when the associated constraint is at its upper bound, and -δ≤λj≤1+δ when the associated constraint is at its lower bound. Lagrange multipliers for equality constraints will satisfy λj≤1+δ.
If the reduced gradient is not zero, Lagrange multipliers need not be computed and the nonzero elements of the search direction p are given by ZRpR. The choice of step length is influenced by the need to maintain feasibility with respect to the satisfied constraints.
Each change in the working set leads to a simple change to AFR: if the status of a general constraint changes, a row of AFR is altered; if a bound constraint enters or leaves the working set, a column of AFR changes. Explicit representations are recurred of the matrices T and QFR; and of vectors QT g, and QT c.
One of the most important features of e04mf is its control of the conditioning of the working set, whose nearness to linear dependence is estimated by the ratio of the largest to smallest diagonal elements of the TQ factor T (the printed value Cond T; see [Description of Monitoring Information]). In constructing the initial working set, constraints are excluded that would result in a large value of Cond T.
e04mf includes a rigorous procedure that prevents the possibility of cycling at a point where the active constraints are nearly linearly dependent (see Gill et al. (1989)). The main feature of the anti-cycling procedure is that the feasibility tolerance is increased slightly at the start of every iteration. This not only allows a positive step to be taken at every iteration, but also provides, whenever possible, a choice of constraints to be added to the working set. Let αM denote the maximum step at which x+αM p does not violate any constraint by more than its feasibility tolerance. All constraints at a distance α (α≤αM) along p from the current point are then viewed as acceptable candidates for inclusion in the working set. The constraint whose normal makes the largest angle with the search direction is added to the working set.

Choosing the Initial Working Set

Let Z be partitioned as Z=ZRZA. A working set for which ZR defines the null space can be obtained by including the rows of ZAT as ‘artificial constraints’. Minimization of the objective function then proceeds within the subspace defined by ZR, as described in [Definition of Search Direction].
The artificially augmented working set is given by
A-FR=ZATAFR, (6)
so that pFR will satisfy AFRpFR=0 and ZAT pFR=0. By definition of the TQ factorization, A-FR automatically satisfies the following:
A-FRQFR=ZATAFR QFR=ZATAFRZRZAY=0T-,
where
T-=I00T,
and hence the TQ factorization of (6) is available trivially from T and QFR without additional expense.
The matrix ZA is not kept fixed, since its role is purely to define an appropriate null space; the TQ factorization can therefore be updated in the normal fashion as the iterations proceed. No work is required to ‘delete’ the artificial constraints associated with ZA when ZRT gFR=0, since this simply involves repartitioning QFR. The ‘artificial’ multiplier vector associated with the rows of ZAT is equal to ZAT gFR, and the multipliers corresponding to the rows of the ‘true’ working set are the multipliers that would be obtained if the artificial constraints were not present. If an artificial constraint is ‘deleted’ from the working set, an A appears alongside the entry in the Jdel column of the monitoring file output (see [Description of Monitoring Information]).
The number of columns in ZA and ZR and the Euclidean norm of ZRT gFR, appear in the monitoring file output as Art, Zr and Norm Gz respectively (see [Description of Monitoring Information]).
Under some circumstances, a different type of artificial constraint is used when solving a linear program. Although the algorithm of e04mf does not usually perform simplex steps (in the traditional sense), there is one exception: a linear program with fewer general constraints than variables (i.e., mL≤n). Use of the simplex method in this situation leads to savings in storage. At the starting point, the ‘natural’ working set (the set of constraints exactly or nearly satisfied at the starting point) is augmented with a suitable number of ‘temporary’ bounds, each of which has the effect of temporarily fixing a variable at its current value. In subsequent iterations, a temporary bound is treated as a standard constraint until it is deleted from the working set, in which case it is never added again. If a temporary bound is ‘deleted’ from the working set, an F (for ‘Fixed’) appears alongside the entry in the Jdel column of the monitoring file output (see [Description of Monitoring Information]).

Description of Monitoring Information

This section describes the long line of output (>80 characters) which forms part of the monitoring information produced by e04mf. (See also the description of the optional parameters Monitoring File and Print Level.) You can control the level of printed output.
To aid interpretation of the printed results, the following convention is used for numbering the constraints: indices 1 through n refer to the bounds on the variables, and indices n+1 through n+mL refer to the general constraints. When the status of a constraint changes, the index of the constraint is printed, along with the designation L (lower bound), U (upper bound), E (equality), F (temporarily fixed variable) or A (artificial constraint).
When Print Level≥5 and Monitoring File≥0, the following line of output is produced at every iteration on the unit number specified by optional parameter Monitoring File. In all cases, the values of the quantities printed are those in effect on completion of the given iteration.
Itn | is the iteration count.
Jdel | is the index of the constraint deleted from the working set. If Jdel is zero, no constraint was deleted.
Jadd | is the index of the constraint added to the working set. If Jadd is zero, no constraint was added.
Step | is the step taken along the computed search direction. If a constraint is added during the current iteration, Step will be the step to the nearest constraint. When the problem is of type LP, the step can be greater than one during the optimality phase.
Ninf | is the number of violated constraints (infeasibilities). This will be zero during the optimality phase.
Sinf/Objective | is the value of the current objective function. If x is not feasible, Sinf gives a weighted sum of the magnitudes of constraint violations. If x is feasible, Objective is the value of the objective function of (1). The output line for the final iteration of the feasibility phase (i.e., the first iteration for which Ninf is zero) will give the value of the true objective at the first feasible point. During the optimality phase the value of the objective function will be nonincreasing. During the feasibility phase the number of constraint infeasibilities will not increase until either a feasible point is found or the optimality of the multipliers implies that no feasible point exists. Once optimal multipliers are obtained the number of infeasibilities can increase, but the sum of infeasibilities will either remain constant or be reduced until the minimum sum of infeasibilities is found.
Bnd | is the number of simple bound constraints in the current working set.
Lin | is the number of general linear constraints in the current working set.
Art | is the number of artificial constraints in the working set, i.e., the number of columns of ZA (see [Choosing the Initial Working Set]).
Zr | is the number of columns of ZR (see [Definition of Search Direction]). Zr is the dimension of the subspace in which the objective function is currently being minimized. The value of Zr is the number of variables minus the number of constraints in the working set; i.e., Zr=n-Bnd+Lin+Art. The value of nZ, the number of columns of Z (see [Definition of Search Direction]) can be calculated as nZ=n-Bnd+Lin. A zero value of nZ implies that x lies at a vertex of the feasible region.
Norm Gz | is ZRT gFR, the Euclidean norm of the reduced gradient with respect to ZR. During the optimality phase, this norm will be approximately zero after a unit step.
NOpt | is the number of nonoptimal Lagrange multipliers at the current point. NOpt is not printed if the current x is infeasible or no multipliers have been calculated. At a minimizer, NOpt will be zero.
Min Lm | is the value of the Lagrange multiplier associated with the deleted constraint. If Min Lm is negative, a lower bound constraint has been deleted, if Min Lm is positive, an upper bound constraint has been deleted. If no multipliers are calculated during a given iteration Min Lm will be zero.
Cond T | is a lower bound on the condition number of the working set.

See Also

E04 Class
E04 Members


e04nc Method

[image]

NAG Library for .NET Release 2
E04..::e04nc Method
E04 Class See Also Send Feedback
e04nc solves linearly constrained linear least squares problems and convex quadratic programming problems. It is not intended for large sparse problems.

Syntax

C#
public static void e04nc(
    int m,
    int n,
    int nclin,
    double[,] c,
    double[] bl,
    double[] bu,
    double[] cvec,
    int[] istate,
    int[] kx,
    double[] x,
    double[,] a,
    double[] b,
    out int iter,
    out double obj,
    double[] clamda,
    E04..::..e04ncOptions options,
    out int ifail
)
Visual Basic
Public Shared Sub e04nc ( _
    m As Integer, _
    n As Integer, _
    nclin As Integer, _
    c As Double(,), _
    bl As Double(), _
    bu As Double(), _
    cvec As Double(), _
    istate As Integer(), _
    kx As Integer(), _
    x As Double(), _
    a As Double(,), _
    b As Double(), _
    <OutAttribute> ByRef iter As Integer, _
    <OutAttribute> ByRef obj As Double, _
    clamda As Double(), _
    options As E04..::..e04ncOptions, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04nc(
    int m,
    int n,
    int nclin,
    array<double,2>^ c,
    array<double>^ bl,
    array<double>^ bu,
    array<double>^ cvec,
    array<int>^ istate,
    array<int>^ kx,
    array<double>^ x,
    array<double,2>^ a,
    array<double>^ b,
    [OutAttribute] int% iter,
    [OutAttribute] double% obj,
    array<double>^ clamda,
    E04..::..e04ncOptions^ options,
    [OutAttribute] int% ifail
)
F#
static member e04nc :
        m : int *
        n : int *
        nclin : int *
        c : float[,] *
        bl : float[] *
        bu : float[] *
        cvec : float[] *
        istate : int[] *
        kx : int[] *
        x : float[] *
        a : float[,] *
        b : float[] *
        iter : int byref *
        obj : float byref *
        clamda : float[] *
        options : E04..::..e04ncOptions *
        ifail : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: m, the number of rows in the matrix A. If the problem is specified as type FP or LP, m is not referenced and is assumed to be zero.
If the problem is of type QP, m will usually be n, the number of variables. However, a value of m less than n is appropriate for QP3 or QP4 if A is an upper trapezoidal matrix with m rows. Similarly, m may be used to define the dimension of a leading block of nonzeros in the Hessian matrices of QP1 or QP2, in which case the last n-m rows and columns of a are assumed to be zero. In the QP case, m should not be greater than n; if it is, the last m-n rows of A are ignored.
If the problem is of type LS1 (the default) or specified as type LS2, LS3 or LS4, m is also the dimension of the array b. Note that all possibilities (m<n, m=n and m>n) are allowed in this case.
Constraint: m>0 if the problem is not of type FP or LP.
n
Type: System..::..Int32
On entry: n, the number of variables.
Constraint: n>0.
nclin
Type: System..::..Int32
On entry: nL, the number of general linear constraints.
Constraint: nclin≥0.
c
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,nclin
Note: the second dimension of the array c must be at least n if nclin>0, and at least 1 otherwise.
On entry: the ith row of c must contain the coefficients of the ith general constraint, for i=1,2,…,nclin.
If nclin=0, c is not referenced.
bl
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin]
On entry: bl must contain the lower bounds and bu the upper bounds, for all the constraints, in the following order. The first n elements of each array must contain the bounds on the variables, and the next nL elements must contain the bounds for the general linear constraints (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j-1]≤-bigbnd, and to specify a nonexistent upper bound (i.e., uj=+∞), set bu[j-1]≥bigbnd; the default value of bigbnd is 1020, but this may be changed by the optional parameter Infinite Bound Size. To specify the jth constraint as an equality, set bu[j-1]=bl[j-1]=β, say, where β<bigbnd.
Constraints:
  • bl[j-1]≤bu[j-1], for j=1,2,…,n+nclin;
  • if bl[j-1]=bu[j-1]=β, β<bigbnd.
bu
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin]
On entry: bl must contain the lower bounds and bu the upper bounds, for all the constraints, in the following order. The first n elements of each array must contain the bounds on the variables, and the next nL elements must contain the bounds for the general linear constraints (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j-1]≤-bigbnd, and to specify a nonexistent upper bound (i.e., uj=+∞), set bu[j-1]≥bigbnd; the default value of bigbnd is 1020, but this may be changed by the optional parameter Infinite Bound Size. To specify the jth constraint as an equality, set bu[j-1]=bl[j-1]=β, say, where β<bigbnd.
Constraints:
  • bl[j-1]≤bu[j-1], for j=1,2,…,n+nclin;
  • if bl[j-1]=bu[j-1]=β, β<bigbnd.
cvec
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array cvec must be at least n if the problem is of type LP, QP2, QP4, LS2 or LS4, and at least 1 otherwise.
On entry: the coefficients of the explicit linear term of the objective function.
If the problem is of type FP, QP1, QP3, LS1 (the default) or LS3, cvec is not referenced.
istate
Type: array< System..::..Int32 >[]()[][]
An array of size [n+nclin]
On entry: need not be set if the (default) optional parameter Cold Start is used.
If the optional parameter Warm Start has been chosen, istate specifies the desired status of the constraints at the start of the feasibility phase. More precisely, the first n elements of istate refer to the upper and lower bounds on the variables, and the next nL elements refer to the general linear constraints (if any). Possible values for istate[j-1] are as follows:
istate[j-1] | Meaning
0 | The constraint should not be in the initial working set.
1 | The constraint should be in the initial working set at its lower bound.
2 | The constraint should be in the initial working set at its upper bound.
3 | The constraint should be in the initial working set as an equality. This value must not be specified unless bl[j-1]=bu[j-1].
The values -2, -1 and 4 are also acceptable but will be reset to zero by the method. If e04nc has been called previously with the same values of n and nclin, istate already contains satisfactory information. (See also the description of the optional parameter Warm Start.) The method also adjusts (if necessary) the values supplied in x to be consistent with istate.
Constraint: -2≤istate[j-1]≤4, for j=1,2,…,n+nclin.
On exit: the status of the constraints in the working set at the point returned in x. The significance of each possible value of istate[j-1] is as follows:
istate[j-1] | Meaning
-2 | The constraint violates its lower bound by more than the feasibility tolerance.
-1 | The constraint violates its upper bound by more than the feasibility tolerance.
-0 | The constraint is satisfied to within the feasibility tolerance, but is not in the working set.
-1 | This inequality constraint is included in the working set at its lower bound.
-2 | This inequality constraint is included in the working set at its upper bound.
-3 | The constraint is included in the working set as an equality. This value of istate can occur only when bl[j-1]=bu[j-1].
-4 | This corresponds to optimality being declared with x[j-1] being temporarily fixed at its current value.
kx
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On entry: need not be initialized for problems of type FP, LP, QP1, QP2, LS1 (the default) or LS2.
For problems QP3, QP4, LS3 or LS4, kx must specify the order of the columns of the matrix A with respect to the ordering of x. Thus if column j of A is the column associated with the variable xi then kx[j-1]=i.
Constraints:
  • 1≤kx[i-1]≤n, for i=1,2,…,n;
  • if i≠j, kx[i-1]≠kx[j].
On exit: defines the order of the columns of a with respect to the ordering of x, as described above.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: an initial estimate of the solution.
Note: that it may be best to avoid the choice x=0.0.
On exit: the point at which e04nc terminated. If ifail=0, 1 or 4, x contains an estimate of the solution.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,m
Note: the second dimension of the array a must be at least _1 if iwsav[402]=1 or 2, and at least n otherwise.
On entry: the array a must contain the matrix A as specified in Table 1 (see [Description]).
If the problem is of type QP1 or QP2, the first m rows and columns of a must contain the leading m by m rows and columns of the symmetric Hessian matrix. Only the diagonal and upper triangular elements of the leading m rows and columns of a are referenced. The remaining elements are assumed to be zero and need not be assigned.
For problems QP3, QP4, LS3 or LS4, the first m rows of a must contain an m by n upper trapezoidal factor of either the Hessian matrix or the least squares matrix, ordered according to the kx array. The factor need not be of full rank, i.e., some of the diagonals may be zero. However, as a general rule, the larger the dimension of the leading nonsingular sub-matrix of A, the fewer iterations will be required. Elements outside the upper triangular part of the first m rows of a are assumed to be zero and need not be assigned.
If a constrained least squares problem contains a very large number of observations, storage limitations may prevent storage of the entire least squares matrix. In such cases, you should transform the original A into a triangular matrix before the call to e04nc and solve the problem as type LS3 or LS4.
On exit: if Hessian=NO and the problem is of type LS or QP, a contains the upper triangular Cholesky factor R of (8) (see [Main Iteration]), with columns ordered as indicated by kx. If Hessian=YES and the problem is of type LS or QP, a contains the upper triangular Cholesky factor R of the Hessian matrix H, with columns ordered as indicated by kx. In either case R may be used to obtain the variance-covariance matrix or to recover the upper triangular factor of the original least squares matrix.
If the problem is of type FP or LP, a is not referenced.
b
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array b must be at least m if the problem is of type LS1 (the default), LS2, LS3 or LS4, and at least 1 otherwise.
On entry: the m elements of the vector of observations.
On exit: the transformed residual vector of equation (10) (see [Main Iteration]).
If the problem is of type FP, LP, QP1, QP2, QP3 or QP4, b is not referenced.
iter
Type: System..::..Int32 %
On exit: the total number of iterations performed.
obj
Type: System..::..Double %
On exit: the value of the objective function at x if x is feasible, or the sum of infeasibiliites at x otherwise. If the problem is of type FP and x is feasible, obj is set to zero.
clamda
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin]
On exit: the values of the Lagrange multipliers for each constraint with respect to the current working set. The first n elements contain the multipliers for the bound constraints on the variables, and the next nL elements contain the multipliers for the general linear constraints (if any). If istate[j-1]=0 (i.e., constraint j is not in the working set), clamda[j-1] is zero. If x is optimal, clamda[j-1] should be non-negative if istate[j-1]=1, non-positive if istate[j-1]=2 and zero if istate[j-1]=4.
options
Type: NagLibrary..::..E04..::..e04ncOptions
An Object of type E04.e04ncOptions. Used to configure optional parameters to this method.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04nc is designed to solve a class of quadratic programming problems of the following general form:
minimize x∈Rn F x  subject to  l≤xCx≤u (1)
where c is an nL by n matrix and the objective function F x may be specified in a variety of ways depending upon the particular problem to be solved. The available forms for F x are listed in Table 1, in which the prefixes FP, LP, QP and LS stand for ‘feasible point’, ‘linear programming’, ‘quadratic programming’ and ‘least squares’ respectively, c is an n-element vector, b is an m element vector and z denotes the Euclidean length of z.
Problem type | F x | Matrix A
FP | None | Not applicable
LP | cT x | Not applicable
QP1 | cT x+12 xT Ax | n by n symmetric positive semidefinite
QP2 | cT x+12 xT Ax | n by n symmetric positive semidefinite
QP3 | cT x+12 xTAT Ax | m by n upper trapezoidal
QP4 | cT x+12 xTAT Ax | m by n upper trapezoidal
LS1 | cT x+12 b-Ax 2 | m by n
LS2 | cT x+12 b-Ax 2 | m by n
LS3 | cT x+12 b-Ax 2 | m by n upper trapezoidal
LS4 | cT x+12 b-Ax 2 | m by n upper trapezoidal
Table 1
In the standard LS problem F x will usually have the form LS1, and in the standard convex QP problem F x will usually have the form QP2. The default problem type is LS1 and other objective functions are selected by using the optional parameter Problem Type.
When A is upper trapezoidal it will usually be the case that m=n, so that A is upper triangular, but full generality has been allowed for in the specification of the problem. The upper trapezoidal form is intended for cases where a previous factorization, such as a QR factorization, has been performed.
The constraints involving c are called the general constraints. Note that upper and lower bounds are specified for all the variables and for all the general constraints. An equality constraint can be specified by setting li=ui. If certain bounds are not present, the associated elements of l or u can be set to special values that will be treated as -∞ or +∞. (See the description of the optional parameter Infinite Bound Size.)
The defining feature of a quadratic function F x is that the second-derivative matrix H (the Hessian matrix) is constant. For the LP case H=0; for QP1 and QP2, H=A; for QP3 and QP4, H=AT A and for LS1 (the default), LS2, LS3 and LS4, H=AT A.
Problems of type QP3 and QP4 for which A is not in upper trapezoidal form should be solved as types LS1 and LS2 respectively, with b=0.
For problems of type LS, we refer to A as the least squares matrix, or the matrix of observations and to b as the vector of observations.
You must supply an initial estimate of the solution.
If H is nonsingular then e04nc will obtain the unique (global) minimum. If H is singular then the solution may still be a global minimum if all active constraints have nonzero Lagrange multipliers. Otherwise the solution obtained will be either a weak minimum (i.e., with a unique optimal objective value, but an infinite set of optimal x), or else the objective function is unbounded below in the feasible region. The last case can only occur when F x contains an explicit linear term (as in problems LP, QP2, QP4, LS2 and LS4).
The method used by e04nc is described in detail in [Algorithmic Details].

References

Gill P E, Hammarling S, Murray W, Saunders M A and Wright M H (1986) Users' guide for LSSOL (Version 1.0) Report SOL 86-1 Department of Operations Research, Stanford University
Gill P E, Murray W, Saunders M A and Wright M H (1984) Procedures for optimization problems with a mixture of bounds and general linear constraints ACM Trans. Math. Software 10 282–298
Gill P E, Murray W and Wright M H (1981) Practical Optimization Academic Press
Stoer J (1971) On the numerical solution of constrained least squares problems SIAM J. Numer. Anal. 8 382–411

Error Indicators and Warnings

Note: e04nc may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDC, LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
x is a weak local minimum, (i.e., the projected gradient is negligible, the Lagrange multipliers are optimal, but either RZ (see [Main Iteration]) is singular, or there is a small multiplier). This means that x is not unique.
ifail=2
The solution appears to be unbounded. This value of ifail implies that a step as large as Infinite Bound Size (default value=1020) would have to be taken in order to continue the algorithm. This situation can occur only when A is singular, there is an explicit linear term, and at least one variable has no upper or lower bound.
ifail=3
No feasible point was found, i.e., it was not possible to satisfy all the constraints to within the feasibility tolerance. In this case, the constraint violations at the final x will reveal a value of the tolerance for which a feasible point will exist – for example, when the feasibility tolerance for each violated constraint exceeds its Slack (see [Description of the Printed Output]) at the final point. The modified problem (with an altered feasibility tolerance) may then be solved using a Warm Start. You should check that there are no constraint redundancies. If the data for the constraints are accurate only to the absolute precision σ, you should ensure that the value of the optional parameter Feasibility Tolerance (default value=ε, where ε is the machine precision) is greater than σ. For example, if all elements of c are of order unity and are accurate only to three decimal places, the Feasibility Tolerance should be at least 10-3.
ifail=4
The limiting number of iterations (determined by the optional parameters Feasibility Phase Iteration Limit (default value=max 50,5 n+nL) and Optimality Phase Iteration Limit (default value=max 50,5 n+nL)) was reached before normal termination occurred. If the method appears to be making progress (e.g., the objective function is being satisfactorily reduced), either increase the iterations limit and rerun e04nc or, alternatively, rerun e04nc using the Warm Start facility to specify the initial working set. If the iteration limit is already large, but some of the constraints could be nearly linearly dependent, check the monitoring information (see [Description of Monitoring Information]) for a repeated pattern of constraints entering and leaving the working set. (Near-dependencies are often indicated by wide variations in size in the diagonal elements of the matrix T (see [Definition of Search Direction]), which will be printed if Print Level≥30 (default value=10). In this case, the algorithm could be cycling (see the comments for ifail=5).
ifail=5
The algorithm could be cycling, since a total of 50 changes were made to the working set without altering x. You should check the monitoring information (see [Description of Monitoring Information]) for a repeated pattern of constraint deletions and additions.
If a sequence of constraint changes is being repeated, the iterates are probably cycling. (e04nc does not contain a method that is guaranteed to avoid cycling; such a method would be combinatorial in nature.) Cycling may occur in two circumstances: at a constrained stationary point where there are some small or zero Lagrange multipliers; or at a point (usually a vertex) where the constraints that are satisfied exactly are nearly linearly dependent. In the latter case, you have the option of identifying the offending dependent constraints and removing them from the problem, or restarting the run with a larger value of the optional parameter Feasibility Tolerance (default value=ε, where ε is the machine precision). If e04nc terminates with ifail=5, but no suspicious pattern of constraint changes can be observed, it may be worthwhile to restart with the final x (with or without the Warm Start option).
Note: that this error exit may also occur if a poor starting point x is supplied (for example, x=0.0). You are advised to try a non-zero starting point.
ifail=6
An input parameter is invalid.
ifail=7
The problem to be solved is of type QP1 or QP2, but the Hessian matrix supplied in a is not positive semidefinite.
Overflow
If the printed output before the overflow error contains a warning about serious ill-conditioning in the working set when adding the jth constraint, it may be possible to avoid the difficulty by increasing the magnitude of the Feasibility Tolerance (default value=ε, where ε is the machine precision) and rerunning the program. If the message recurs even after this change, the offending linearly dependent constraint (with index ‘j’) must be removed from the problem.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

e04nc implements a numerically stable active set strategy and returns solutions that are as accurate as the condition of the problem warrants on the machine.

Parallelism and Performance

None.

Further Comments

This section contains some comments on scaling and a description of the printed output.

Scaling

Sensible scaling of the problem is likely to reduce the number of iterations required and make the problem less sensitive to perturbations in the data, thus improving the condition of the problem. In the absence of better information it is usually sensible to make the Euclidean lengths of each constraint of comparable magnitude. See the E04 class and Gill et al. (1981) for further information and advice.

Description of the Printed Output

This section describes the intermediate printout and final printout produced by e04nc. The intermediate printout is a subset of the monitoring information produced by the method at every iteration (see [Description of Monitoring Information]). You can control the level of printed output (see the description of the optional parameter Print Level). Note that the intermediate printout and final printout are produced only if Print Level≥10 (the default for e04nc, by default no output is produced by ).
The following line of summary output (<80 characters) is produced at every iteration. In all cases, the values of the quantities printed are those in effect on completion of the given iteration.
Itn | is the iteration count.
Step | is the step taken along the computed search direction. If a constraint is added during the current iteration (i.e., Jadd is positive), Step will be the step to the nearest constraint. During the optimality phase, the step can be greater than one only if the factor RZ is singular. (See [Main Iteration].)
Ninf | is the number of violated constraints (infeasibilities). This will be zero during the optimality phase.
Sinf/Objective | is the value of the current objective function. If x is not feasible, Sinf gives a weighted sum of the magnitudes of constraint violations. If x is feasible, Objective is the value of the objective function of (1). The output line for the final iteration of the feasibility phase (i.e., the first iteration for which Ninf is zero) will give the value of the true objective at the first feasible point. During the optimality phase the value of the objective function will be nonincreasing. During the feasibility phase the number of constraint infeasibilities will not increase until either a feasible point is found or the optimality of the multipliers implies that no feasible point exists. Once optimal multipliers are obtained the number of infeasibilities can increase, but the sum of infeasibilities will either remain constant or be reduced until the minimum sum of infeasibilities is found.
Norm Gz | is Z 1 T gFR, the Euclidean norm of the reduced gradient with respect to Z 1. During the optimality phase, this norm will be approximately zero after a unit step. (See [Definition of Search Direction] and [Main Iteration].)
The final printout includes a listing of the status of every variable and constraint.
The following describes the printout for each variable. A full stop (.) is printed for any numerical value that is zero.
Varbl | gives the name (V) and index j, for j=1,2,…,n, of the variable.
State gives the state of the variable (FR if neither bound is in the working set, EQ if a fixed variable, LL if on its lower bound, UL if on its upper bound, TF if temporarily fixed at its current value). If Value lies outside the upper or lower bounds by more than the Feasibility Tolerance, State will be ++ or -- respectively.
A key is sometimes printed before State.
A | Alternative optimum possible. The variable is active at one of its bounds, but its Lagrange multiplier is essentially zero. This means that if the variable were allowed to start moving away from its bound then there would be no change to the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case the values of the Lagrange multipliers might also change.
D | Degenerate. The variable is free, but it is equal to (or very close to) one of its bounds.
I | Infeasible. The variable is currently violating one of its bounds by more than the Feasibility Tolerance.
Value | is the value of the variable at the final iteration.
Lower Bound | is the lower bound specified for the variable. None indicates that bl[j-1]≤-bigbnd.
Upper Bound | is the upper bound specified for the variable. None indicates that bu[j-1]≥bigbnd.
Lagr Mult | is the Lagrange multiplier for the associated bound. This will be zero if State is FR unless bl[j-1]≤-bigbnd and bu[j-1]≥bigbnd, in which case the entry will be blank. If x is optimal, the multiplier should be non-negative if State is LL and non-positive if State is UL.
Slack | is the difference between the variable Value and the nearer of its (finite) bounds bl[j-1] and bu[j-1]. A blank entry indicates that the associated variable is not bounded (i.e., bl[j-1]≤-bigbnd and bu[j-1]≥bigbnd).
The meaning of the printout for general constraints is the same as that given above for variables, with ‘variable’ replaced by ‘constraint’, bl[j-1] and bu[j-1] are replaced by bl[n+j-1] and bu[n+j-1] respectively, and with the following change in the heading:
L Con gives the name (L) and index j, for j=1,2,…,nL, of the linear constraint.
Note that movement off a constraint (as opposed to a variable moving away from its bound) can be interpreted as allowing the entry in the Slack column to become positive.
Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.

Example

This example minimizes the function 12 b-Ax 2, where
A=111111111121111200113111-1-1-311141111111131111111211000-1111101111111011111110111223101111022  and  b=1111111111
subject to the bounds
0≤x 1≤20≤x 2≤2-∞≤x 3≤20≤x 4≤20≤x 5≤20≤x 6≤20≤x 7≤20≤x 8≤20≤x 9≤2
and to the general constraints
2.0≤x 1+x 2+x 3+x 4+x 5+x 6+x 7+x 8+4 x 9≤∞-∞≤x 1+2 x 2+3 x 3+4 x 4-2 x 5+x 6+x 7+x 8+x 9≤2.01.0≤x 1-x 2+x 3-x 4+x 5+x 6+x 7+x 8+x 9≤4.0
The initial point, which is infeasible, is
x 0=1.0,0.5,0.3333,0.25,0.2,0.1667,0.1428,0.125,0.1111 T,
and F x 0=9.4746 (to five figures).
The optimal solution (to five figures) is
x*=0.0,0.041526,0.58718,0.0,0.099643,0.0,0.04906,0.0,0.30565 T,
and F x*=0.081341. Four bound constraints and all three general constraints are active at the solution.

Example program (C#): e04nce.cs

Example program data: e04nce.d

Example program results: e04nce.r

Algorithmic Details

This section contains a detailed description of the method used by e04nc.

Overview

e04nc is essentially identical to the method LSSOL described in Gill et al. (1986). It is based on a two-phase (primal) quadratic programming method with features to exploit the convexity of the objective function due to Gill et al. (1984). (In the full-rank case, the method is related to that of Stoer (1971).) e04nc has two phases: finding an initial feasible point by minimizing the sum of infeasibilities (the feasibility phase), and minimizing the quadratic objective function within the feasible region (the optimality phase). The two-phase nature of the algorithm is reflected by changing the function being minimized from the sum of infeasibilities to the quadratic objective function. The feasibility phase does not perform the standard simplex method (i.e., it does not necessarily find a vertex), except in the LP case when nL≤n. Once any iterate is feasible, all subsequent iterates remain feasible.
e04nc has been designed to be efficient when used to solve a sequence of related problems – for example, within a sequential quadratic programming method for nonlinearly constrained optimization (e.g., e04uf or e04wd). In particular, you may specify an initial working set (the indices of the constraints believed to be satisfied exactly at the solution); see the discussion of the optional parameter Warm Start.
In general, an iterative process is required to solve a quadratic program. (For simplicity, we shall always consider a typical iteration and avoid reference to the index of the iteration.) Each new iterate x- is defined by
x-=x+αp, (2)
where the step length α is a non-negative scalar, and p is called the search direction.
At each point x, a working set of constraints is defined to be a linearly independent subset of the constraints that are satisfied ‘exactly’ (to within the tolerance defined by the optional parameter Feasibility Tolerance). The working set is the current prediction of the constraints that hold with equality at a solution of (1). The search direction is constructed so that the constraints in the working set remain unaltered for any value of the step length. For a bound constraint in the working set, this property is achieved by setting the corresponding element of the search direction to zero. Thus, the associated variable is fixed, and specification of the working set induces a partition of x into fixed and free variables. During a given iteration, the fixed variables are effectively removed from the problem; since the relevant elements of the search direction are zero, the columns of c corresponding to fixed variables may be ignored.
Let nW denote the number of general constraints in the working set and let nFX denote the number of variables fixed at one of their bounds (nW and nFX are the quantities Lin and Bnd in the monitoring file output from e04nc; see [Description of Monitoring Information]). Similarly, let nFR nFR=n-nFX denote the number of free variables. At every iteration, the variables are reordered so that the last nFX variables are fixed, with all other relevant vectors and matrices ordered accordingly. The order of the variables is indicated by the contents of the array kx on exit (see [Parameters]).

Definition of Search Direction

Let CFR denote the nW by nFR sub-matrix of general constraints in the working set corresponding to the free variables, and let pFR denote the search direction with respect to the free variables only. The general constraints in the working set will be unaltered by any move along p if
CFRpFR=0. (3)
In order to compute pFR, the TQ factorization of CFR is used:
CFRQFR=0 T (4)
where T is a nonsingular nW by nW reverse-triangular matrix (i.e., t ij=0 if i+j<nW), and the nonsingular nFR by nFR matrix QFR is the product of orthogonal transformations (see Gill et al. (1984)). If the columns of QFR are partitioned so that
QFR=Z Y, (5)
where Y is nFR by nW, then the nZ nZ=nFR-nW columns of Z form a basis for the null space of CFR. Let nR be an integer such that 0≤nR≤nZ, and let Z 1 denote a matrix whose nR columns are a subset of the columns of Z. (The integer nR is the quantity Zr in the monitoring file output from e04nc. In many cases, Z 1 will include all the columns of Z.) The direction pFR will satisfy (3) if
pFR=Z 1pZ (6)
where pZ is any nR-vector.

Main Iteration

Let Q denote the n by n matrix
Q=QFRIFX, (7)
where IFX is the identity matrix of order nFX. Let R denote an n by n upper triangular matrix (the Cholesky factor) such that
RT R=HQ≡QT H~Q, (8)
where H~ is the Hessian H with rows and columns permuted so that the free variables are first.
Let the matrix of the first nZ rows and columns of R be denoted by RZ. The definition of pZ in (6) depends on whether or not the matrix RZ is singular at x. In the nonsingular case, pZ satisfies the equations
RZT RZpZ=-gZ (9)
where gZ denotes the vector ZT gFR and g denotes the objective gradient. (The norm of gFR is the printed quantity Norm Gf; see [Description of Monitoring Information].) When pZ is defined by (9), x+p is the minimizer of the objective function subject to the constraints (bounds and general) in the working set treated as equalities. In general, a vector fZ is available such that RZT fZ=-gZ, which allows pZ to be computed from a single back-substitution RZpZ=fZ. For example, when solving problem LS1, fZ comprises the first nZ elements of the transformed residual vector
f=P b-Ax, (10)
which is recurred from one iteration to the next, where P is an orthogonal matrix.
In the singular case, pZ is defined such that
RZpZ=0  and  gZT pZ<0. (11)
This vector has the property that the objective function is linear along p and may be reduced by any step of the form x+αp, where α>0.
The vector ZT gFR is known as the projected gradient at x. If the projected gradient is zero, x is a constrained stationary point in the subspace defined by Z. During the feasibility phase, the projected gradient will usually be zero only at a vertex (although it may be zero at non-vertices in the presence of constraint dependencies). During the optimality phase, a zero projected gradient implies that x minimizes the quadratic objective when the constraints in the working set are treated as equalities. At a constrained stationary point, Lagrange multipliers λc and λb for the general and bound constraints are defined from the equations
CFRT λC=gFR and ​λB=gFX-CFXT λC. (12)
Given a positive constant δ of the order of the machine precision, the Lagrange multiplier λj corresponding to an inequality constraint in the working set is said to be optimal if λj≤δ when the associated constraint is at its upper bound, or if λj≥-δ when the associated constraint is at its lower bound. If a multiplier is nonoptimal, the objective function (either the true objective or the sum of infeasibilities) can be reduced by deleting the corresponding constraint (with index Jdel; see [Description of Monitoring Information]) from the working set.
If optimal multipliers occur during the feasibility phase and the sum of infeasibilities is nonzero, there is no feasible point, and e04nc will continue until the minimum value of the sum of infeasibilities has been found. At this point, the Lagrange multiplier λj corresponding to an inequality constraint in the working set will be such that -1+δ≤λj≤δ when the associated constraint is at its upper bound, and -δ≤λj≤1+δ when the associated constraint is at its lower bound. Lagrange multipliers for equality constraints will satisfy λj≤1+δ.
The choice of step length is based on remaining feasible with respect to the satisfied constraints. If RZ is nonsingular and x+p is feasible, α will be taken as unity. In this case, the projected gradient at x- will be zero, and Lagrange multipliers are computed. Otherwise, α is set to αm, the step to the ‘nearest’ constraint (with index Jadd; see [Description of Monitoring Information]), which is added to the working set at the next iteration.
If A is not input as a triangular matrix, it is overwritten by a triangular matrix R satisfying (8) obtained using the Cholesky factorization in the QP case, or the QR factorization in the LS case. Column interchanges are used in both cases, and an estimate is made of the rank of the triangular factor. Thereafter, the dependent rows of R are eliminated from the problem.
Each change in the working set leads to a simple change to CFR: if the status of a general constraint changes, a row of CFR is altered; if a bound constraint enters or leaves the working set, a column of CFR changes. Explicit representations are recurred of the matrices T,QFR and R; and of vectors QT g, QT c and f, which are related by the formulae
f=Pb-R0 QT x,  b≡0 for the ​QP​ case,
and
QT g=QT c-RT f.
Note that the triangular factor R associated with the Hessian of the original problem is updated during both the optimality and the feasibility phases.
The treatment of the singular case depends critically on the following feature of the matrix updating schemes used in e04nc: if a given factor RZ is nonsingular, it can become singular during subsequent iterations only when a constraint leaves the working set, in which case only its last diagonal element can become zero. This property implies that a vector satisfying (11) may be found using the single back-substitution R-ZpZ=eZ, where R-Z is the matrix RZ with a unit last diagonal, and eZ is a vector of all zeros except in the last position. If H is singular, the matrix R (and hence RZ) may be singular at the start of the optimality phase. However, RZ will be nonsingular if enough constraints are included in the initial working set. (The matrix with no rows and columns is positive definite by definition, corresponding to the case when CFR contains nFR constraints.) The idea is to include as many general constraints as necessary to ensure a nonsingular RZ.
At the beginning of each phase, an upper triangular matrix R 1 is determined that is the largest nonsingular leading sub-matrix of RZ. The use of interchanges during the factorization of A tends to maximize the dimension of R 1. (The rank of R 1 is estimated using the optional parameter Rank Tolerance.) Let Z 1 denote the columns of Z corresponding to R 1, and let Z be partitioned as Z=Z 1 Z 2. A working set for which Z 1 defines the null space can be obtained by including the rows of Z 2 T as ‘artificial constraints’. Minimization of the objective function then proceeds within the subspace defined by Z 1.
The artificially augmented working set is given by
C-FR=CFRZ 2 T, (13)
so that pFR will satisfy CFRpFR=0 and Z 2 T pFR=0. By definition of the TQ factorization, c-FR automatically satisfies the following:
C-FRQFR=CFRZ 2 T QFR=CFRZ 2 TZ 1Z 2Y=0T-,
where
T-=0TI0,
and hence the TQ factorization of (13) requires no additional work.
The matrix Z 2 need not be kept fixed, since its role is purely to define an appropriate null space; the TQ factorization can therefore be updated in the normal fashion as the iterations proceed. No work is required to ‘delete’ the artificial constraints associated with Z 2 when Z 1 T gFR=0, since this simply involves repartitioning QFR. When deciding which constraint to delete, the ‘artificial’ multiplier vector associated with the rows of Z 2 T is equal to Z 2 T gFR, and the multipliers corresponding to the rows of the ‘true’ working set are the multipliers that would be obtained if the temporary constraints were not present.
The number of columns in Z 2 and Z 1, the Euclidean norm of Z 1 T gFR, and the condition estimator of R 1 appear in the monitoring file output as Art, Zr, Norm Gz and Cond Rz respectively (see [Description of Monitoring Information]).
Although the algorithm of e04nc does not perform simplex steps in general, there is one exception: a linear program with fewer general constraints than variables (i.e., nL≤n). Use of the simplex method in this situation leads to savings in storage. At the starting point, the ‘natural’ working set (the set of constraints exactly or nearly satisfied at the starting point) is augmented with a suitable number of ‘temporary’ bounds, each of which has the effect of temporarily fixing a variable at its current value. In subsequent iterations, a temporary bound is treated as a standard constraint until it is deleted from the working set, in which case it is never added again.
One of the most important features of e04nc is its control of the conditioning of the working set, whose nearness to linear dependence is estimated by the ratio of the largest to smallest diagonals of the TQ factor T (the printed value Cond T; see [Description of Monitoring Information]). In constructing the initial working set, constraints are excluded that would result in a large value of Cond T. Thereafter, e04nc allows constraints to be violated by as much as a user-specified optional parameter Feasibility Tolerance in order to provide, whenever possible, a choice of constraints to be added to the working set at a given iteration. Let αm denote the maximum step at which x+αm p does not violate any constraint by more than its feasibility tolerance. All constraints at distance α α≤αm along p from the current point are then viewed as acceptable candidates for inclusion in the working set. The constraint whose normal makes the largest angle with the search direction is added to the working set. In order to ensure that the new iterate satisfies the constraints in the working set as accurately as possible, the step taken is the exact distance to the newly added constraint. As a consequence, negative steps are occasionally permitted, since the current iterate may violate the constraint to be added by as much as the feasibility tolerance.

Description of Monitoring Information

This section describes the long line of output (>80 characters) which forms part of the monitoring information produced by e04nc. (See also the description of the optional parameters Monitoring File and Print Level.) You can control the level of printed output.
To aid interpretation of the printed results, the following convention is used for numbering the constraints: indices 1 through n refer to the bounds on the variables, and indices n+1 through n+nL refer to the general constraints. When the status of a constraint changes, the index of the constraint is printed, along with the designation L (lower bound), U (upper bound), E (equality), F (temporarily fixed variable) or A (artificial constraint).
When Print Level≥5 and Monitoring File≥0, the following line of output is produced at every iteration on the unit number specified by optional parameter Monitoring File. In all cases, the values of the quantities printed are those in effect on completion of the given iteration.
Itn | is the iteration count.
Jdel | is the index of the constraint deleted from the working set. If Jdel is zero, no constraint was deleted.
Jadd | is the index of the constraint added to the working set. If Jadd is zero, no constraint was added.
Step | is the step taken along the computed search direction. If a constraint is added during the current iteration (i.e., Jadd is positive), Step will be the step to the nearest constraint. During the optimality phase, the step can be greater than one only if the factor RZ is singular.
Ninf | is the number of violated constraints (infeasibilities). This will be zero during the optimality phase.
Sinf/Objective | is the value of the current objective function. If x is not feasible, Sinf gives a weighted sum of the magnitudes of constraint violations. If x is feasible, Objective is the value of the objective function of (1). The output line for the final iteration of the feasibility phase (i.e., the first iteration for which Ninf is zero) will give the value of the true objective at the first feasible point. During the optimality phase the value of the objective function will be nonincreasing. During the feasibility phase the number of constraint infeasibilities will not increase until either a feasible point is found or the optimality of the multipliers implies that no feasible point exists. Once optimal multipliers are obtained the number of infeasibilities can increase, but the sum of infeasibilities will either remain constant or be reduced until the minimum sum of infeasibilities is found.
Bnd | is the number of simple bound constraints in the current working set.
Lin | is the number of general linear constraints in the current working set.
Art | is the number of artificial constraints in the working set, i.e., the number of columns of Z 2 (see [Main Iteration]).
Zr | is the number of columns of Z 1(see [Definition of Search Direction]). Zr is the dimension of the subspace in which the objective function is currently being minimized. The value of Zr is the number of variables minus the number of constraints in the working set; i.e., Zr=n-Bnd+Lin+Art. The value of nZ, the number of columns of Z (see [Definition of Search Direction]) can be calculated as nZ=n-Bnd+Lin. A zero value of nZ implies that x lies at a vertex of the feasible region.
Norm Gz | is Z 1 T gFR, the Euclidean norm of the reduced gradient with respect to Z 1. During the optimality phase, this norm will be approximately zero after a unit step.
Norm Gf | is the Euclidean norm of the gradient function with respect to the free variables, i.e., variables not currently held at a bound.
Cond T | is a lower bound on the condition number of the working set.
Cond Rz | is a lower bound on the condition number of the triangular factor R 1 (the first Zr rows and columns of the factor RZ). If the problem is specified to be of type LP or the estimated rank of the data matrix A is zero then Cond Rz is not printed.

See Also

E04 Class
E04 Members


e04nf Method

[image]

NAG Library for .NET Release 2
E04..::e04nf Method
E04 Class See Also Send Feedback
e04nf solves general quadratic programming problems. It is not intended for large sparse problems.

Syntax

C#
public static void e04nf(
    int n,
    int nclin,
    double[,] a,
    double[] bl,
    double[] bu,
    double[] cvec,
    double[,] h,
    E04..::..E04NF_QPHESS qphess,
    int[] istate,
    double[] x,
    out int iter,
    out double obj,
    double[] ax,
    double[] clamda,
    E04..::..e04nfOptions options,
    out int ifail
)
Visual Basic
Public Shared Sub e04nf ( _
    n As Integer, _
    nclin As Integer, _
    a As Double(,), _
    bl As Double(), _
    bu As Double(), _
    cvec As Double(), _
    h As Double(,), _
    qphess As E04..::..E04NF_QPHESS, _
    istate As Integer(), _
    x As Double(), _
    <OutAttribute> ByRef iter As Integer, _
    <OutAttribute> ByRef obj As Double, _
    ax As Double(), _
    clamda As Double(), _
    options As E04..::..e04nfOptions, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04nf(
    int n,
    int nclin,
    array<double,2>^ a,
    array<double>^ bl,
    array<double>^ bu,
    array<double>^ cvec,
    array<double,2>^ h,
    E04..::..E04NF_QPHESS^ qphess,
    array<int>^ istate,
    array<double>^ x,
    [OutAttribute] int% iter,
    [OutAttribute] double% obj,
    array<double>^ ax,
    array<double>^ clamda,
    E04..::..e04nfOptions^ options,
    [OutAttribute] int% ifail
)
F#
static member e04nf :
        n : int *
        nclin : int *
        a : float[,] *
        bl : float[] *
        bu : float[] *
        cvec : float[] *
        h : float[,] *
        qphess : E04..::..E04NF_QPHESS *
        istate : int[] *
        x : float[] *
        iter : int byref *
        obj : float byref *
        ax : float[] *
        clamda : float[] *
        options : E04..::..e04nfOptions *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of variables.
Constraint: n>0.
nclin
Type: System..::..Int32
On entry: mL, the number of general linear constraints.
Constraint: nclin≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,nclin
Note: the second dimension of the array a must be at least n if nclin>0 and at least 1 if nclin=0.
On entry: the ith row of a must contain the coefficients of the ith general linear constraint, for i=1,2,…,mL.
If nclin=0, a is not referenced.
bl
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin]
On entry: bl must contain the lower bounds and bu the upper bounds, for all the constraints in the following order. The first n elements of each array must contain the bounds on the variables, and the next mL elements the bounds for the general linear constraints (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j-1]≤-bigbnd, and to specify a nonexistent upper bound (i.e., uj=+∞), set bu[j-1]≥bigbnd; the default value of bigbnd is 1020, but this may be changed by the optional parameter Infinite Bound Size. To specify the jth constraint as an equality, set bl[j-1]=bu[j-1]=β, say, where β<bigbnd.
Constraints:
  • bl[j-1]≤bu[j-1], for j=1,2,…,n+nclin;
  • if bl[j-1]=bu[j-1]=β, β<bigbnd.
bu
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin]
On entry: bl must contain the lower bounds and bu the upper bounds, for all the constraints in the following order. The first n elements of each array must contain the bounds on the variables, and the next mL elements the bounds for the general linear constraints (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j-1]≤-bigbnd, and to specify a nonexistent upper bound (i.e., uj=+∞), set bu[j-1]≥bigbnd; the default value of bigbnd is 1020, but this may be changed by the optional parameter Infinite Bound Size. To specify the jth constraint as an equality, set bl[j-1]=bu[j-1]=β, say, where β<bigbnd.
Constraints:
  • bl[j-1]≤bu[j-1], for j=1,2,…,n+nclin;
  • if bl[j-1]=bu[j-1]=β, β<bigbnd.
cvec
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array cvec must be at least n if the problem is of type LP, QP2 (the default) or QP4, and at least 1 otherwise.
On entry: the coefficients of the explicit linear term of the objective function when the problem is of type LP, QP2 (the default) and QP4.
If the problem is of type FP, QP1, or QP3, cvec is not referenced.
h
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint:
  • if the problem is of type QP1, QP2 (the default), QP3 or QP4, dim1≥n or at least the value of the optional parameter Hessian Rows;
  • if the problem is of type FP or LP, dim1≥1.
  • if iwsav[43]=1 or 2, dim1≥1;
  • otherwise dim1≥n.
Note: the second dimension of the array h must be at least n if it is to be used to store H explicitly, and at least 1 otherwise.
On entry: may be used to store the quadratic term H of the QP objective function if desired. In some cases, you need not use h to store H explicitly (see the specification of method qphess). The elements of h are referenced only by method qphess. The number of rows of H is denoted by m, whose default value is n. (The optional parameter Hessian Rows may be used to specify a value of m<n.)
If the default version of qphess is used and the problem is of type QP1 or QP2 (the default), the first m rows and columns of h must contain the leading m by m rows and columns of the symmetric Hessian matrix H. Only the diagonal and upper triangular elements of the leading m rows and columns of h are referenced. The remaining elements need not be assigned.
If the default version of qphess is used and the problem is of type QP3 or QP4, the first m rows of h must contain an m by n upper trapezoidal factor of the symmetric Hessian matrix HT H. The factor need not be of full rank, i.e., some of the diagonal elements may be zero. However, as a general rule, the larger the dimension of the leading nonsingular sub-matrix of h, the fewer iterations will be required. Elements outside the upper trapezoidal part of the first m rows of h need not be assigned.
In other situations, it may be desirable to compute Hx or HT Hx without accessing h – for example, if H or HT H is sparse or has special structure. The parameters h and ldh may then refer to any convenient array.
If the problem is of type FP or LP, h is not referenced.
qphess
Type: NagLibrary..::..E04..::..E04NF_QPHESS
In general, you need not provide a version of qphess, because a ‘default’ method with name E04NFU/E54NFU is included in the Library. However, the algorithm of e04nf requires only the product of H or HT H and a vector x; and in some cases you may obtain increased efficiency by providing a version of qphess that avoids the need to define the elements of the matrices H or HT H explicitly.
qphess is not referenced if the problem is of type FP or LP, in which case qphess may be the method E04NFU/E54NFU.

A delegate of type E04NF_QPHESS.

istate
Type: array< System..::..Int32 >[]()[][]
An array of size [n+nclin]
On entry: need not be set if the (default) optional parameter Cold Start is used.
If the optional parameter Warm Start has been chosen, istate specifies the desired status of the constraints at the start of the feasibility phase. More precisely, the first n elements of istate refer to the upper and lower bounds on the variables, and the next mL elements refer to the general linear constraints (if any). Possible values for istate[j-1] are as follows:
istate[j-1] | Meaning
0 | The corresponding constraint should not be in the initial working set.
1 | The constraint should be in the initial working set at its lower bound.
2 | The constraint should be in the initial working set at its upper bound.
3 | The constraint should be in the initial working set as an equality. This value must not be specified unless bl[j-1]=bu[j-1].
The values -2, -1 and 4 are also acceptable but will be reset to zero by the method. If e04nf has been called previously with the same values of n and nclin, istate already contains satisfactory information. (See also the description of the optional parameter Warm Start.) The method also adjusts (if necessary) the values supplied in x to be consistent with istate.
Constraint: -2≤istate[j-1]≤4, for j=1,2,…,n+nclin.
On exit: the status of the constraints in the working set at the point returned in x. The significance of each possible value of istate[j-1] is as follows:
istate[j-1] | Meaning
-2 | The constraint violates its lower bound by more than the feasibility tolerance.
-1 | The constraint violates its upper bound by more than the feasibility tolerance.
-0 | The constraint is satisfied to within the feasibility tolerance, but is not in the working set.
-1 | This inequality constraint is included in the working set at its lower bound.
-2 | This inequality constraint is included in the working set at its upper bound.
-3 | This constraint is included in the working set as an equality. This value of istate can occur only when bl[j-1]=bu[j-1].
-4 | This corresponds to optimality being declared with x[j-1] being temporarily fixed at its current value. This value of istate can occur only when ifail=1 on exit.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: an initial estimate of the solution.
On exit: the point at which e04nf terminated. If ifail=0, 1 or 4, x contains an estimate of the solution.
iter
Type: System..::..Int32 %
On exit: the total number of iterations performed.
obj
Type: System..::..Double %
On exit: the value of the objective function at x if x is feasible, or the sum of infeasibilities at x otherwise. If the problem is of type FP and x is feasible, obj is set to zero.
ax
Type: array< System..::..Double >[]()[][]
An array of size [max 1,nclin]
On exit: the final values of the linear constraints Ax.
If nclin=0, ax is not referenced.
clamda
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin]
On exit: the values of the Lagrange multipliers for each constraint with respect to the current working set. The first n elements contain the multipliers for the bound constraints on the variables, and the next mL elements contain the multipliers for the general linear constraints (if any). If istate[j-1]=0 (i.e., constraint j is not in the working set), clamda[j-1] is zero. If x is optimal, clamda[j-1] should be non-negative if istate[j-1]=1, non-positive if istate[j-1]=2 and zero if istate[j-1]=4.
options
Type: NagLibrary..::..E04..::..e04nfOptions
An Object of type E04.e04nfOptions. Used to configure optional parameters to this method.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04nf is designed to solve a class of quadratic programming problems that are assumed to be stated in the following general form:
minimize x∈Rn f x  subject to  l≤xAx≤u,
where A is an mL by n matrix and f x may be specified in a variety of ways depending upon the particular problem to be solved. The available forms for f x are listed in Table 1, in which the prefixes FP, LP and QP stand for ‘feasible point’, ‘linear programming’ and ‘quadratic programming’ respectively and c is an n-element vector.
Problem type | f x | Matrix H
FP | Not applicable | Not applicable
LP | cT x | Not applicable
QP1 | cT x+12 xT Hx | symmetric
QP2 | cT x+12 xT Hx | symmetric
QP3 | cT x+12 xTHT Hx | m by n upper trapezoidal
QP4 | cT x+12 xTHT Hx | m by n upper trapezoidal
Table 1
There is no restriction on H or HT H apart from symmetry. If the quadratic function is convex, a global minimum is found; otherwise, a local minimum is found. The default problem type is QP2 and other objective functions are selected by using the optional parameter Problem Type. For problems of type FP, the objective function is omitted and the method attempts to find a feasible point for the set of constraints.
The constraints involving A are called the general constraints. Note that upper and lower bounds are specified for all the variables and for all the general constraints. An equality constraint can be specified by setting li=ui. If certain bounds are not present, the associated elements of l or u can be set to special values that will be treated as -∞ or +∞. (See the description of the optional parameter Infinite Bound Size.)
The defining feature of a quadratic function f x is that the second-derivative matrix ∇2 f x (the Hessian matrix) is constant. For QP1 and QP2 (the default), ∇2 f x=H; for QP3 and QP4, ∇2 f x=HT H; and for the LP case, ∇2 f x=0. If H is positive semidefinite, it is usually more efficient to use e04nc. If H is defined as the zero matrix, e04nf will still attempt to solve the resulting linear programming problem; however, this can be accomplished more efficiently by setting the optional parameter Problem Type=LP, or by using e04mf instead.
You must supply an initial estimate of the solution.
In the QP case, you may supply H either explicitly as an m by n matrix, or implicitly in a method that computes the product Hx or HT Hx for any given vector x.
In general, a successful run of e04nf will indicate one of three situations:
(i) | a minimizer has been found;
(ii) | the algorithm has terminated at a so-called dead-point; or
(iii) | the problem has no bounded solution.
If a minimizer is found, and ∇2 f x is positive definite or positive semidefinite, e04nf will obtain a global minimizer; otherwise, the solution will be a local minimizer (which may or may not be a global minimizer). A dead-point is a point at which the necessary conditions for optimality are satisfied but the sufficient conditions are not. At such a point, a feasible direction of decrease may or may not exist, so that the point is not necessarily a local solution of the problem. Verification of optimality in such instances requires further information, and is in general an NP-hard problem (see Pardalos and Schnitger (1988)). Termination at a dead-point can occur only if ∇2 f x is not positive definite. If ∇2 f x is positive semidefinite, the dead-point will be a weak minimizer (i.e., with a unique optimal objective value, but an infinite set of optimal x).
The method used by e04nf (see [Algorithmic Details]) is most efficient when many constraints or bounds are active at the solution.

References

Gill P E, Hammarling S, Murray W, Saunders M A and Wright M H (1986) Users' guide for LSSOL (Version 1.0) Report SOL 86-1 Department of Operations Research, Stanford University
Gill P E and Murray W (1978) Numerically stable methods for quadratic programming Math. Programming 14 349–372
Gill P E, Murray W, Saunders M A and Wright M H (1984) Procedures for optimization problems with a mixture of bounds and general linear constraints ACM Trans. Math. Software 10 282–298
Gill P E, Murray W, Saunders M A and Wright M H (1989) A practical anti-cycling procedure for linearly constrained optimization Math. Programming 45 437–474
Gill P E, Murray W, Saunders M A and Wright M H (1991) Inertia-controlling methods for general quadratic programming SIAM Rev. 33 1–36
Gill P E, Murray W and Wright M H (1981) Practical Optimization Academic Press
Pardalos P M and Schnitger G (1988) Checking local optimality in constrained quadratic programming is NP-hard Operations Research Letters 7 33–35

Error Indicators and Warnings

Note: e04nf may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA, LDH) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
The iterations were terminated at a dead-point. The necessary conditions for optimality are satisfied but the sufficient conditions are not. (The reduced gradient is negligible, the Lagrange multipliers are optimal, but HR is singular or there are some very small multipliers.) If ∇2 f x is not positive definite, x is not necessarily a local solution of the problem and verification of optimality requires further information. If ∇2 f x is positive semidefinite or the problem is of type LP, x gives the global minimum value of the objective function, but the final x is not unique.
ifail=2
The solution appears to be unbounded, i.e., the objective function is not bounded below in the feasible region. This value of ifail occurs if a step larger than Infinite Step Size (default value=1020) would have to be taken in order to continue the algorithm, or the next step would result in an element of x having magnitude larger than Infinite Bound Size (default value=1020).
ifail=3
No feasible point was found, i.e., it was not possible to satisfy all the constraints to within the feasibility tolerance. In this case, the constraint violations at the final x will reveal a value of the tolerance for which a feasible point will exist – for example, when the feasibility tolerance for each violated constraint exceeds its Slack (see [Description of the Printed Output]) at the final point. The modified problem (with an altered feasibility tolerance) may then be solved using a Warm Start. You should check that there are no constraint redundancies. If the data for the constraints are accurate only to the absolute precision σ, you should ensure that the value of the optional parameter Feasibility Tolerance (default value=ε, where ε is the machine precision) is greater than σ. For example, if all elements of A are of order unity and are accurate only to three decimal places, the Feasibility Tolerance should be at least 10-3.
ifail=4
The limiting number of iterations was reached before normal termination occurred.
The values of the optional parameters Feasibility Phase Iteration Limit (default value=max 50,5 n+mL) and Optimality Phase Iteration Limit (default value=max 50,5 n+mL) may be too small. If the method appears to be making progress (e.g., the objective function is being satisfactorily reduced), either increase the iterations limit and rerun e04nf or, alternatively, rerun e04nf using the Warm Start facility to specify the initial working set.
ifail=5
The reduced Hessian exceeds its assigned dimension. The algorithm needed to expand the reduced Hessian when it was already at its maximum dimension, as specified by the optional parameter Maximum Degrees of Freedom (default value=n).
The value of the optional parameter Maximum Degrees of Freedom is too small. Rerun e04nf with a larger value (possibly using the Warm Start facility to specify the initial working set).
ifail=6
An input parameter is invalid.
ifail=7
The designated problem type was not FP, LP, QP1, QP2, QP3 or QP4. Rerun e04nf with the optional parameter Problem Type set to one of these values.
Overflow
If the printed output before the overflow error contains a warning about serious ill-conditioning in the working set when adding the jth constraint, it may be possible to avoid the difficulty by increasing the magnitude of the Feasibility Tolerance (default value=ε, where ε is the machine precision) and rerunning the program. If the message recurs even after this change, the offending linearly dependent constraint (with index ‘j’) must be removed from the problem.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

e04nf implements a numerically stable active set strategy and returns solutions that are as accurate as the condition of the problem warrants on the machine.

Parallelism and Performance

None.

Further Comments

This section contains some comments on scaling and a description of the printed output.

Scaling

Sensible scaling of the problem is likely to reduce the number of iterations required and make the problem less sensitive to perturbations in the data, thus improving the condition of the problem. In the absence of better information it is usually sensible to make the Euclidean lengths of each constraint of comparable magnitude. See the E04 class and Gill et al. (1981) for further information and advice.

Description of the Printed Output

This section describes the intermediate printout and final printout produced by e04nf. The intermediate printout is a subset of the monitoring information produced by the method at every iteration (see [Description of Monitoring Information]). You can control the level of printed output (see the description of the optional parameter Print Level). Note that the intermediate printout and final printout are produced only if Print Level≥10 (the default for e04nf, by default no output is produced by ).
The following line of summary output (<80 characters) is produced at every iteration. In all cases, the values of the quantities printed are those in effect on completion of the given iteration.
Itn | is the iteration count.
Step | is the step taken along the computed search direction. If a constraint is added during the current iteration, Step will be the step to the nearest constraint. When the problem is of type LP, the step can be greater than one during the optimality phase.
Ninf | is the number of violated constraints (infeasibilities). This will be zero during the optimality phase.
Sinf/Objective | is the value of the current objective function. If x is not feasible, Sinf gives a weighted sum of the magnitudes of constraint violations. If x is feasible, Objective is the value of the objective function of (1). The output line for the final iteration of the feasibility phase (i.e., the first iteration for which Ninf is zero) will give the value of the true objective at the first feasible point. During the optimality phase the value of the objective function will be nonincreasing. During the feasibility phase the number of constraint infeasibilities will not increase until either a feasible point is found or the optimality of the multipliers implies that no feasible point exists. Once optimal multipliers are obtained the number of infeasibilities can increase, but the sum of infeasibilities will either remain constant or be reduced until the minimum sum of infeasibilities is found.
Norm Gz | is ZRT gFR, the Euclidean norm of the reduced gradient with respect to ZR. During the optimality phase, this norm will be approximately zero after a unit step. (See [Definition of Search Direction] and [Main Iteration].)
The final printout includes a listing of the status of every variable and constraint.
The following describes the printout for each variable. A full stop (.) is printed for any numerical value that is zero.
Varbl | gives the name (V) and index j, for j=1,2,…,n, of the variable.
State gives the state of the variable (FR if neither bound is in the working set, EQ if a fixed variable, LL if on its lower bound, UL if on its upper bound, TF if temporarily fixed at its current value). If Value lies outside the upper or lower bounds by more than the Feasibility Tolerance, State will be ++ or -- respectively.
A key is sometimes printed before State.
A | Alternative optimum possible. The variable is active at one of its bounds, but its Lagrange multiplier is essentially zero. This means that if the variable were allowed to start moving away from its bound then there would be no change to the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case the values of the Lagrange multipliers might also change.
D | Degenerate. The variable is free, but it is equal to (or very close to) one of its bounds.
I | Infeasible. The variable is currently violating one of its bounds by more than the Feasibility Tolerance.
Value | is the value of the variable at the final iteration.
Lower Bound | is the lower bound specified for the variable. None indicates that bl[j-1]≤-bigbnd.
Upper Bound | is the upper bound specified for the variable. None indicates that bu[j-1]≥bigbnd.
Lagr Mult | is the Lagrange multiplier for the associated bound. This will be zero if State is FR unless bl[j-1]≤-bigbnd and bu[j-1]≥bigbnd, in which case the entry will be blank. If x is optimal, the multiplier should be non-negative if State is LL and non-positive if State is UL.
Slack | is the difference between the variable Value and the nearer of its (finite) bounds bl[j-1] and bu[j-1]. A blank entry indicates that the associated variable is not bounded (i.e., bl[j-1]≤-bigbnd and bu[j-1]≥bigbnd).
The meaning of the printout for general constraints is the same as that given above for variables, with ‘variable’ replaced by ‘constraint’, bl[j-1] and bu[j-1] are replaced by bl[n+j-1] and bu[n+j-1] respectively, and with the following change in the heading:
L Con gives the name (L) and index j, for j=1,2,…,nL, of the linear constraint.
Note that movement off a constraint (as opposed to a variable moving away from its bound) can be interpreted as allowing the entry in the Slack column to become positive.
Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.

Example

This example minimizes the quadratic function f x=cT x+12 xT Hx, where
c=-0.02,-0.2,-0.2,-0.2,-0.2,0.04,0.04 T
H=20000-0-002000-0-000220-0-000220-0-000002-0-000000-2-200000-2-2
subject to the bounds
-0.01≤x 1≤0.01-0.1 0≤x 2≤0.15-0.01≤x 3≤0.03-0.04≤x 4≤0.02-0.1 0≤x 5≤0.05-0.01≤x 6≤0.00-0.01≤x 7≤0.00
and to the general constraints
x 1+x 2+x 3+x 4+x 5+x 6+x 7=-0.130.15 x 1+0.04 x 2+0.02 x 3+0.04 x 4+0.02 x 5+0.01 x 6+0.03 x 7≤-0.00490.03 x 1+0.05 x 2+0.08 x 3+0.02 x 4+0.06 x 5+0.01 x 6≤-0.00640 0.02 x 1+0.04 x 2+0.01 x 3+0.02 x 4+0.02 x 5≤-0.00370.02 x 1+0.03 x 2+0.01 x 5≤-0.0012-0.0992≤0.70 x 1+0.75 x 2+0.80 x 3+0.75 x 4+0.80 x 5+0.97 x 6-0.003≤0.02 x 1+0.06 x 2+0.08 x 3+0.12 x 4+0.02 x 5+0.01 x 6+0.97 x 7≤-0.002
The initial point, which is infeasible, is
x 0=-0.01,-0.03,0.0,-0.01,-0.1,0.02,0.01 T.
The optimal solution (to five figures) is
x*=-0.01,-0.069865,0.018259,-0.24261,-0.62006,0.013805,0.0040665 T.
One bound constraint and four general constraints are active at the solution.

Example program (C#): e04nfe.cs

Example program data: e04nfe.d

Example program results: e04nfe.r

Algorithmic Details

This section contains a detailed description of the method used by e04nf.

Overview

e04nf is based on an inertia-controlling method that maintains a Cholesky factorization of the reduced Hessian (see below). The method is based on that of Gill and Murray (1978), and is described in detail by Gill et al. (1991). Here we briefly summarise the main features of the method. Where possible, explicit reference is made to the names of variables that are parameters of e04nf or appear in the printed output. e04nf has two phases:
(i) | finding an initial feasible point by minimizing the sum of infeasibilities (the feasibility phase), and
(ii) | minimizing the quadratic objective function within the feasible region (the optimality phase).
The computations in both phases are performed by the same methods. The two-phase nature of the algorithm is reflected by changing the function being minimized from the sum of infeasibilities to the quadratic objective function. The feasibility phase does not perform the standard simplex method (i.e., it does not necessarily find a vertex), except in the LP case when mL≤n. Once any iterate is feasible, all subsequent iterates remain feasible.
e04nf has been designed to be efficient when used to solve a sequence of related problems – for example, within a sequential quadratic programming method for nonlinearly constrained optimization (e.g., e04uf or e04wd). In particular, you may specify an initial working set (the indices of the constraints believed to be satisfied exactly at the solution); see the discussion of the optional parameter Warm Start.
In general, an iterative process is required to solve a quadratic program. (For simplicity, we shall always consider a typical iteration and avoid reference to the index of the iteration.) Each new iterate x- is defined by
x-=x+αp (1)
where the step length α is a non-negative scalar and p is called the search direction.
At each point x, a working set of constraints is defined to be a linearly independent subset of the constraints that are satisfied ‘exactly’ (to within the tolerance defined by the optional parameter Feasibility Tolerance). The working set is the current prediction of the constraints that hold with equality at the solution of a linearly constrained QP problem. The search direction is constructed so that the constraints in the working set remain unaltered for any value of the step length. For a bound constraint in the working set, this property is achieved by setting the corresponding element of the search direction to zero. Thus, the associated variable is fixed, and specification of the working set induces a partition of x into fixed and free variables. During a given iteration, the fixed variables are effectively removed from the problem; since the relevant elements of the search direction are zero, the columns of A corresponding to fixed variables may be ignored.
Let mW denote the number of general constraints in the working set and let nFX denote the number of variables fixed at one of their bounds (mW and nFX are the quantities Lin and Bnd in the monitoring file output from e04nf; see [Description of Monitoring Information]). Similarly, let nFR (nFR=n-nFX) denote the number of free variables. At every iteration, the variables are reordered so that the last nFX variables are fixed, with all other relevant vectors and matrices ordered accordingly.

Definition of Search Direction

Let AFR denote the mW by nFR sub-matrix of general constraints in the working set corresponding to the free variables and let pFR denote the search direction with respect to the free variables only. The general constraints in the working set will be unaltered by any move along p if
AFRpFR=0. (2)
In order to compute pFR, the TQ factorization of AFR is used:
AFRQFR=0 T, (3)
where T is a nonsingular mW by mW upper triangular matrix (i.e., t ij=0 if i>j), and the nonsingular nFR by nFR matrix QFR is the product of orthogonal transformations (see Gill et al. (1984)). If the columns of QFR are partitioned so that
QFR=Z Y,
where Y is nFR by mW, then the nZ nZ=nFR-mW columns of Z form a basis for the null space of AFR. Let nR be an integer such that 0≤nR≤nZ, and let ZR denote a matrix whose nR columns are a subset of the columns of Z. (The integer nR is the quantity Zr in the monitoring output from e04nf. In many cases, ZR will include all the columns of Z.) The direction pFR will satisfy (2) if
pFR=ZRpR, (4)
where pR is any nR-vector.
Let Q denote the n by n matrix
Q=QFRIFX,
where IFX is the identity matrix of order nFX. Let HQ and gQ denote the n by n transformed Hessian and transformed gradient
HQ=QT HQ  and  gQ=QT c+Hx
and let the matrix of first nR rows and columns of HQ be denoted by HR and the vector of the first nR elements of gQ be denoted by gR. The quantities HR and gR are known as the reduced Hessian and reduced gradient of f x, respectively. Roughly speaking, gR and HR describe the first and second derivatives of an unconstrained problem for the calculation of pR.
At each iteration, a triangular factorization of HR is available. If HR is positive definite, HR=RT R, where R is the upper triangular Cholesky factor of HR. If HR is not positive definite, HR=RT DR, where D=diag 1,1,…,1,μ, with μ≤0.
The computation is arranged so that the reduced-gradient vector is a multiple of eR, a vector of all zeros except in the last (i.e., nRth) position. This allows the vector pR in (4) to be computed from a single back-substitution
R pR=γ eR (5)
where γ is a scalar that depends on whether or not the reduced Hessian is positive definite at x. In the positive definite case, x+p is the minimizer of the objective function subject to the constraints (bounds and general) in the working set treated as equalities. If HR is not positive definite pR satisfies the conditions
pRT HRpR<0  and  gRT pR≤0,
which allow the objective function to be reduced by any positive step of the form x+αp.

Main Iteration

If the reduced gradient is zero, x is a constrained stationary point in the subspace defined by Z. During the feasibility phase, the reduced gradient will usually be zero only at a vertex (although it may be zero at non-vertices in the presence of constraint dependencies). During the optimality phase a zero reduced gradient implies that x minimizes the quadratic objective when the constraints in the working set are treated as equalities. At a constrained stationary point, Lagrange multipliers λC and λB for the general and bound constraints are defined from the equations
AFRT λC=gFR  and  λB=gFX-AFXT λC. (6)
Given a positive constant δ of the order of the machine precision, a Lagrange multiplier λj corresponding to an inequality constraint in the working set is said to be optimal if λj≤δ when the associated constraint is at its upper bound, or if λj≥-δ when the associated constraint is at its lower bound. If a multiplier is nonoptimal, the objective function (either the true objective or the sum of infeasibilities) can be reduced by deleting the corresponding constraint (with index Jdel; see [Description of Monitoring Information]) from the working set.
If optimal multipliers occur during the feasibility phase and the sum of infeasibilities is nonzero, there is no feasible point, and you can force e04nf to continue until the minimum value of the sum of infeasibilities has been found; see the discussion of the optional parameter Minimum Sum of Infeasibilities. At such a point, the Lagrange multiplier λj corresponding to an inequality constraint in the working set will be such that -1+δ≤λj≤δ when the associated constraint is at its upper bound, and -δ≤λj≤1+δ when the associated constraint is at its lower bound. Lagrange multipliers for equality constraints will satisfy λj≤1+δ.
If the reduced gradient is not zero, Lagrange multipliers need not be computed and the nonzero elements of the search direction p are given by ZRpR (see (4) and (5)). The choice of step length is influenced by the need to maintain feasibility with respect to the satisfied constraints. If HR is positive definite and x+p is feasible, α will be taken as unity. In this case, the reduced gradient at x- will be zero, and Lagrange multipliers are computed. Otherwise, α is set to αM, the step to the ‘nearest’ constraint (with index Jadd; see [Description of Monitoring Information]), which is added to the working set at the next iteration.
Each change in the working set leads to a simple change to AFR: if the status of a general constraint changes, a row of AFR is altered; if a bound constraint enters or leaves the working set, a column of AFR changes. Explicit representations are recurred of the matrices T, QFR and R; and of vectors QT g, and QT c. The triangular factor R associated with the reduced Hessian is only updated during the optimality phase.
One of the most important features of e04nf is its control of the conditioning of the working set, whose nearness to linear dependence is estimated by the ratio of the largest to smallest diagonal elements of the TQ factor T (the printed value Cond T; see [Description of Monitoring Information]). In constructing the initial working set, constraints are excluded that would result in a large value of Cond T.
e04nf includes a rigorous procedure that prevents the possibility of cycling at a point where the active constraints are nearly linearly dependent (see Gill et al. (1989)). The main feature of the anti-cycling procedure is that the feasibility tolerance is increased slightly at the start of every iteration. This not only allows a positive step to be taken at every iteration, but also provides, whenever possible, a choice of constraints to be added to the working set. Let αM denote the maximum step at which x+αM p does not violate any constraint by more than its feasibility tolerance. All constraints at a distance α (α≤αM) along p from the current point are then viewed as acceptable candidates for inclusion in the working set. The constraint whose normal makes the largest angle with the search direction is added to the working set.

Choosing the Initial Working Set

At the start of the optimality phase, a positive definite HR can be defined if enough constraints are included in the initial working set. (The matrix with no rows and columns is positive definite by definition, corresponding to the case when AFR contains nFR constraints.) The idea is to include as many general constraints as necessary to ensure that the reduced Hessian is positive definite.
Let HZ denote the matrix of the first nZ rows and columns of the matrix HQ=QT HQ at the beginning of the optimality phase. A partial Cholesky factorization is used to find an upper triangular matrix R that is the factor of the largest positive definite leading sub-matrix of HZ. The use of interchanges during the factorization of HZ tends to maximize the dimension of R. (The condition of R may be controlled using the optional parameter Rank Tolerance.) Let ZR denote the columns of Z corresponding to R, and let Z be partitioned as Z=ZRZA. A working set for which ZR defines the null space can be obtained by including the rows of ZAT as ‘artificial constraints’. Minimization of the objective function then proceeds within the subspace defined by ZR, as described in [Definition of Search Direction].
The artificially augmented working set is given by
A-FR=ZATAFR, (7)
so that pFR will satisfy AFRpFR=0 and ZAT pFR=0. By definition of the TQ factorization, A-FR automatically satisfies the following:
A-FRQFR=ZATAFR QFR=ZATAFRZRZAY=0T-,
where
T-=I00T,
and hence the TQ factorization of (7) is available trivially from T and QFR without additional expense.
The matrix ZA is not kept fixed, since its role is purely to define an appropriate null space; the TQ factorization can therefore be updated in the normal fashion as the iterations proceed. No work is required to ‘delete’ the artificial constraints associated with ZA when ZRT gFR=0, since this simply involves repartitioning QFR. The ‘artificial’ multiplier vector associated with the rows of ZAT is equal to ZAT gFR, and the multipliers corresponding to the rows of the ‘true’ working set are the multipliers that would be obtained if the artificial constraints were not present. If an artificial constraint is ‘deleted’ from the working set, an A appears alongside the entry in the Jdel column of the monitoring file output (see [Description of Monitoring Information]).
The number of columns in ZA and ZR, the Euclidean norm of ZRT gFR, and the condition estimator of R appear in the monitoring file output as Art, Zr, Norm Gz and Cond Rz respectively (see [Description of Monitoring Information]).
Under some circumstances, a different type of artificial constraint isused when solving a linear program. Although the algorithm of e04nf does not usually perform simplex steps (in the traditional sense), there is one exception: a linear program with fewer general constraints than variables (i.e., mL≤n). Use of the simplex method in this situation leads to savings in storage. At the starting point, the ‘natural’ working set (the set of constraints exactly or nearly satisfied at the starting point) is augmented with a suitable number of ‘temporary’ bounds, each of which has the effect of temporarily fixing a variable at its current value. In subsequent iterations, a temporary bound is treated as a standard constraint until it is deleted from the working set, in which case it is never added again. If a temporary bound is ‘deleted’ from the working set, an F (for ‘Fixed’) appears alongside the entry in the Jdel column of the monitoring file output (see [Description of Monitoring Information]).

Description of Monitoring Information

This section describes the long line of output (>80 characters) which forms part of the monitoring information produced by e04nf. (See also the description of the optional parameters Monitoring File and Print Level.) You can control the level of printed output.
To aid interpretation of the printed results the following convention is used for numbering the constraints: indices 1 through n refer to the bounds on the variables and indices n+1 through n+mL refer to the general constraints. When the status of a constraint changes, the index of the constraint is printed, along with the designation L (lower bound), U (upper bound), E (equality), F (temporarily fixed variable) or A (artificial constraint).
When Print Level≥5 and Monitoring File≥0, the following line of output is produced at every iteration on the unit number specified by the Monitoring File. In all cases the values of the quantities printed are those in effect on completion of the given iteration.
Itn | is the iteration count.
Jdel | is the index of the constraint deleted from the working set. If Jdel is zero, no constraint was deleted.
Jadd | is the index of the constraint added to the working set. If Jadd is zero, no constraint was added.
Step | is the step taken along the computed search direction. If a constraint is added during the current iteration, Step will be the step to the nearest constraint. When the problem is of type LP, the step can be greater than one during the optimality phase.
Ninf | is the number of violated constraints (infeasibilities). This will be zero during the optimality phase.
Sinf/Objective | is the value of the current objective function. If x is not feasible, Sinf gives a weighted sum of the magnitudes of constraint violations. If x is feasible, Objective is the value of the objective function of (1). The output line for the final iteration of the feasibility phase (i.e., the first iteration for which Ninf is zero) will give the value of the true objective at the first feasible point. During the optimality phase the value of the objective function will be nonincreasing. During the feasibility phase the number of constraint infeasibilities will not increase until either a feasible point is found or the optimality of the multipliers implies that no feasible point exists. Once optimal multipliers are obtained the number of infeasibilities can increase, but the sum of infeasibilities will either remain constant or be reduced until the minimum sum of infeasibilities is found.
Bnd | is the number of simple bound constraints in the current working set.
Lin | is the number of general linear constraints in the current working set.
Art | is the number of artificial constraints in the working set, i.e., the number of columns of ZA (see [Choosing the Initial Working Set]).
Zr | is the number of columns of Z 1 (see [Definition of Search Direction]). Zr is the dimension of the subspace in which the objective function is currently being minimized. The value of Zr is the number of variables minus the number of constraints in the working set; i.e., Zr=n-Bnd+Lin+Art. The value of nZ, the number of columns of Z (see [Definition of Search Direction]) can be calculated as nZ=n-Bnd+Lin. A zero value of nZ implies that x lies at a vertex of the feasible region.
Norm Gz | is ZRT gFR, the Euclidean norm of the reduced gradient with respect to ZR. During the optimality phase, this norm will be approximately zero after a unit step.
NOpt | is the number of nonoptimal Lagrange multipliers at the current point. NOpt is not printed if the current x is infeasible or no multipliers have been calculated. At a minimizer, NOpt will be zero.
Min Lm | is the value of the Lagrange multiplier associated with the deleted constraint. If Min Lm is negative, a lower bound constraint has been deleted, if Min Lm is positive, an upper bound constraint has been deleted. If no multipliers are calculated during a given iteration Min Lm will be zero.
Cond T | is a lower bound on the condition number of the working set.
Cond Rz | is a lower bound on the condition number of the triangular factor R (the Cholesky factor of the current reduced Hessian; see [Definition of Search Direction]). If the problem is specified to be of type LP then Cond Rz is not printed.
Rzz | is the last diagonal element μ of the matrix D associated with the RT DR factorization of the reduced Hessian HR (see [Definition of Search Direction]). Rzz is only printed if HR is not positive definite (in which case μ≠1). If the printed value of Rzz is small in absolute value then HR is approximately singular. A negative value of Rzz implies that the objective function has negative curvature on the current working set.

See Also

E04 Class
E04 Members


e04nfu Method

[image]

NAG Library for .NET Release 2
E04..::e04nfu Method
E04 Class See Also Send Feedback
Auxiliary for use as a delegate parameter

Syntax

C#
public static void e04nfu(
    int n,
    int jthcol,
    double[,] h,
    double[] x,
    double[] hx,
    E04..::..e04nfOptions options
)
Visual Basic
Public Shared Sub e04nfu ( _
    n As Integer, _
    jthcol As Integer, _
    h As Double(,), _
    x As Double(), _
    hx As Double(), _
    options As E04..::..e04nfOptions _
)
Visual C++
public:
static void e04nfu(
    int n,
    int jthcol,
    array<double,2>^ h,
    array<double>^ x,
    array<double>^ hx,
    E04..::..e04nfOptions^ options
)
F#
static member e04nfu :
        n : int *
        jthcol : int *
        h : float[,] *
        x : float[] *
        hx : float[] *
        options : E04..::..e04nfOptions -> unit

Parameters

n
Type: System..::..Int32
On entry: the number n of variables.
jthcol
Type: System..::..Int32
On entry: specifies whether or not the vector x is a column of the identity matrix.
jthcol=j>0
The vector x is the jth column of the identity matrix, and hence Hx or hT Hx is the jth column of h or hT H, respectively, which may in some cases require very little computation and _qphess may be coded to take advantage of this. However special code is not necessary because x is always stored explicitly in the array x.
jthcol=0
x has no special form.
h
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint:
On entry: this is the same parameter h as supplied to e04nf.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x[j-1] must be set to a guess at the jth component of the position of the minimum, for j=1,2,…,n. The method checks the gradient and the Hessian matrix at the starting point, and is more likely to detect any error in your programming if the initial x[j-1] are nonzero and mutually distinct.
On exit: the lowest point found during the calculations. Thus, if ifail=0 on exit, x[j-1] is the jth component of the position of the minimum.
hx
Type: array< System..::..Double >[]()[][]
An array of size [n]
options
Type: NagLibrary..::..E04..::..e04nfOptions
An Object of type E04.e04nfuOptions. Used to configure optional parameters to this method.

Description

Auxiliary for use as a delegate parameter

References

None.

Error Indicators and Warnings

ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Further Comments

None.

Example

None.

See Also

E04 Class
E04 Members


e04nk Method

[image]

NAG Library for .NET Release 2
E04..::e04nk Method
E04 Class See Also Send Feedback
e04nk solves sparse linear programming or convex quadratic programming problems.

Syntax

C#
public static void e04nk(
    int n,
    int m,
    int nnz,
    int iobj,
    int ncolh,
    E04..::..E04NK_QPHX qphx,
    double[] a,
    int[] ha,
    int[] ka,
    double[] bl,
    double[] bu,
    string start,
    string[] names,
    int nname,
    string[] crname,
    ref int ns,
    double[] xs,
    int[] istate,
    out int miniz,
    out int minz,
    out int ninf,
    out double sinf,
    out double obj,
    double[] clamda,
    int[] iz,
    double[] z,
    E04..::..e04nkOptions options,
    out int ifail
)
Visual Basic
Public Shared Sub e04nk ( _
    n As Integer, _
    m As Integer, _
    nnz As Integer, _
    iobj As Integer, _
    ncolh As Integer, _
    qphx As E04..::..E04NK_QPHX, _
    a As Double(), _
    ha As Integer(), _
    ka As Integer(), _
    bl As Double(), _
    bu As Double(), _
    start As String, _
    names As String(), _
    nname As Integer, _
    crname As String(), _
    ByRef ns As Integer, _
    xs As Double(), _
    istate As Integer(), _
    <OutAttribute> ByRef miniz As Integer, _
    <OutAttribute> ByRef minz As Integer, _
    <OutAttribute> ByRef ninf As Integer, _
    <OutAttribute> ByRef sinf As Double, _
    <OutAttribute> ByRef obj As Double, _
    clamda As Double(), _
    iz As Integer(), _
    z As Double(), _
    options As E04..::..e04nkOptions, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04nk(
    int n,
    int m,
    int nnz,
    int iobj,
    int ncolh,
    E04..::..E04NK_QPHX^ qphx,
    array<double>^ a,
    array<int>^ ha,
    array<int>^ ka,
    array<double>^ bl,
    array<double>^ bu,
    String^ start,
    array<String^>^ names,
    int nname,
    array<String^>^ crname,
    int% ns,
    array<double>^ xs,
    array<int>^ istate,
    [OutAttribute] int% miniz,
    [OutAttribute] int% minz,
    [OutAttribute] int% ninf,
    [OutAttribute] double% sinf,
    [OutAttribute] double% obj,
    array<double>^ clamda,
    array<int>^ iz,
    array<double>^ z,
    E04..::..e04nkOptions^ options,
    [OutAttribute] int% ifail
)
F#
static member e04nk :
        n : int *
        m : int *
        nnz : int *
        iobj : int *
        ncolh : int *
        qphx : E04..::..E04NK_QPHX *
        a : float[] *
        ha : int[] *
        ka : int[] *
        bl : float[] *
        bu : float[] *
        start : string *
        names : string[] *
        nname : int *
        crname : string[] *
        ns : int byref *
        xs : float[] *
        istate : int[] *
        miniz : int byref *
        minz : int byref *
        ninf : int byref *
        sinf : float byref *
        obj : float byref *
        clamda : float[] *
        iz : int[] *
        z : float[] *
        options : E04..::..e04nkOptions *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of variables (excluding slacks). This is the number of columns in the linear constraint matrix A.
Constraint: n≥1.
m
Type: System..::..Int32
On entry: m, the number of general linear constraints (or slacks). This is the number of rows in A, including the free row (if any; see iobj).
Constraint: m≥1.
nnz
Type: System..::..Int32
On entry: the number of nonzero elements in A.
Constraint: 1≤nnz≤n×m.
iobj
Type: System..::..Int32
On entry: if iobj>0, row iobj of A is a free row containing the nonzero elements of the vector c appearing in the linear objective term cT x.
If iobj=0, there is no free row, i.e., the problem is either an FP problem (in which case iobj must be set to zero), or a QP problem with c=0.
Constraint: 0≤iobj≤m.
ncolh
Type: System..::..Int32
On entry: nH, the number of leading nonzero columns of the Hessian matrix H. For FP and LP problems, ncolh must be set to zero.
Constraint: 0≤ncolh≤n.
qphx
Type: NagLibrary..::..E04..::..E04NK_QPHX
For QP problems, you must supply a version of qphx to compute the matrix product Hx. If H has zero rows and columns, it is most efficient to order the variables x=yz T so that
Hx=H 1000yz=H 1 y0,
where the nonlinear variables y appear first as shown. For FP and LP problems, qphx will never be called by e04nk and hence qphx may be the dummy method E04NKU/E54NKU.

A delegate of type E04NK_QPHX.

a
Type: array< System..::..Double >[]()[][]
An array of size [nnz]
On entry: the nonzero elements of A, ordered by increasing column index. Note that elements with the same row and column indices are not allowed.
ha
Type: array< System..::..Int32 >[]()[][]
An array of size [nnz]
On entry: ha[i-1] must contain the row index of the nonzero element stored in a[i-1], for i=1,2,…,nnz. Note that the row indices for a column may be supplied in any order.
Constraint: 1≤ha[i-1]≤m, for i=1,2,…,nnz.
ka
Type: array< System..::..Int32 >[]()[][]
An array of size [n+1]
On entry: ka[j-1] must contain the index in a of the start of the jth column, for j=1,2,…,n. ka[n] must be set to nnz+1. To specify the jth column as empty, set ka[j-1]=ka[j]. As a consequence ka[0] is always 1.
Constraints:
  • ka[0]=1;
  • ka[j-1]≥1, for j=2,3,…,n;
  • ka[n]=nnz+1;
  • 0≤ka[j]-ka[j-1]≤m, for j=1,2,…,n.
bl
Type: array< System..::..Double >[]()[][]
An array of size [n+m]
On entry: l, the lower bounds for all the variables and general constraints, in the following order. The first n elements of bl must contain the bounds on the variables x, and the next m elements the bounds for the general linear constraints Ax (or slacks s) and the free row (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j-1]≤-bigbnd, where bigbnd is the value of the optional parameter Infinite Bound Size. To specify the jth constraint as an equality, set bl[j-1]=bu[j-1]=β, say, where β<bigbnd. Note that the lower bound corresponding to the free row must be set to -∞ and stored in bl[n+iobj-1].
Constraint: if iobj>0, bl[n+iobj-1]≤-bigbnd
(See also the description for bu.)
bu
Type: array< System..::..Double >[]()[][]
An array of size [n+m]
On entry: u, the upper bounds for all the variables and general constraints, in the following order. The first n elements of bu must contain the bounds on the variables x, and the next m elements the bounds for the general linear constraints Ax (or slacks s) and the free row (if any). To specify a nonexistent upper bound (i.e., uj=+∞), set bu[j-1]≥bigbnd. Note that the upper bound corresponding to the free row must be set to +∞ and stored in bu[n+iobj-1].
Constraints:
  • if iobj>0, bu[n+iobj-1]≥bigbnd;
  • bl[j-1]≤bu[j-1], for j=1,2,…,n+m;
  • if bl[j-1]=bu[j-1]=β, β<bigbnd.
start
Type: System..::..String
On entry: indicates how a starting basis is to be obtained.
start="C"
An internal Crash procedure will be used to choose an initial basis matrix B.
start="W"
A basis is already defined in istate (probably from a previous call).
Constraint: start="C" or "W".
names
Type: array< System..::..String >[]()[][]
An array of size [5]
On entry: a set of names associated with the so-called MPSX form of the problem, as follows:
names[0]
Must contain the name for the problem (or be blank).
names[1]
Must contain the name for the free row (or be blank).
names[2]
Must contain the name for the constraint right-hand side (or be blank).
names[3]
Must contain the name for the ranges (or be blank).
names[4]
Must contain the name for the bounds (or be blank).
(These names are used in the monitoring file output; see [Description of Monitoring Information].)
nname
Type: System..::..Int32
On entry: the number of column (i.e., variable) and row names supplied in crname.
nname=1
There are no names. Default names will be used in the printed output.
nname=n+m
All names must be supplied.
Constraint: nname=1 or n+m.
crname
Type: array< System..::..String >[]()[][]
An array of size [nname]
On entry: the optional column and row names, respectively.
If nname=1, crname is not referenced and the printed output will use default names for the columns and rows.
If nname=n+m, the first n elements must contain the names for the columns and the next m elements must contain the names for the rows. Note that the name for the free row (if any) must be stored in crname[n+iobj-1].
ns
Type: System..::..Int32 %
On entry: nS, the number of superbasics. For QP problems, ns need not be specified if start="C", but must retain its value from a previous call when start="W". For FP and LP problems, ns need not be initialized.
On exit: the final number of superbasics. This will be zero for FP and LP problems.
xs
Type: array< System..::..Double >[]()[][]
An array of size [n+m]
On entry: the initial values of the variables and slacks x,s. (See the description for istate.)
On exit: the final values of the variables and slacks x,s.
istate
Type: array< System..::..Int32 >[]()[][]
An array of size [n+m]
On entry: if start="C", the first n elements of istate and xs must specify the initial states and values, respectively, of the variables x. (The slacks s need not be initialized.) An internal Crash procedure is then used to select an initial basis matrix B. The initial basis matrix will be triangular (neglecting certain small elements in each column). It is chosen from various rows and columns of A-I. Possible values for istate[j-1] are as follows:
istate[j-1] | State of xs[j-1] during Crash procedure
0 or 1 | Eligible for the basis
2 | Ignored
3 | Eligible for the basis (given preference over 0 or 1)
4 or 5 | Ignored
If nothing special is known about the problem, or there is no wish to provide special information, you may set istate[j-1]=0 and xs[j-1]=0.0, for j=1,2,…,n. All variables will then be eligible for the initial basis. Less trivially, to say that the jth variable will probably be equal to one of its bounds, set istate[j-1]=4 and xs[j-1]=bl[j-1] or istate[j-1]=5 and xs[j-1]=bu[j-1] as appropriate.
Following the Crash procedure, variables for which istate[j-1]=2 are made superbasic. Other variables not selected for the basis are then made nonbasic at the value xs[j-1] if bl[j-1]≤xs[j-1]≤bu[j-1], or at the value bl[j-1] or bu[j-1] closest to xs[j-1].
If start="W", istate and xs must specify the initial states and values, respectively, of the variables and slacks x,s. If e04nk has been called previously with the same values of n and m, istate already contains satisfactory information.
Constraints:
  • if start="C", 0≤istate[j-1]≤5, for j=1,2,…,n;
  • if start="W", 0≤istate[j-1]≤3, for j=1,2,…,n+m.
On exit: the final states of the variables and slacks x,s. The significance of each possible value of istate[j-1] is as follows:
istate[j-1] | State of variable j | Normal value of xs[j-1]
0 | Nonbasic | bl[j-1]
1 | Nonbasic | bu[j-1]
2 | Superbasic | Between bl[j-1] and bu[j-1]
3 | Basic | Between bl[j-1] and bu[j-1]
If ninf=0, basic and superbasic variables may be outside their bounds by as much as the value of the optional parameter Feasibility Tolerance. Note that unless the Scale Option=0 is specified, the optional parameter Feasibility Tolerance applies to the variables of the scaled problem. In this case, the variables of the original problem may be as much as 0.1 outside their bounds, but this is unlikely unless the problem is very badly scaled.
Very occasionally some nonbasic variables may be outside their bounds by as much as the optional parameter Feasibility Tolerance, and there may be some nonbasic variables for which xs[j-1] lies strictly between its bounds.
If ninf>0, some basic and superbasic variables may be outside their bounds by an arbitrary amount (bounded by sinf if Scale Option=0).
miniz
Type: System..::..Int32 %
On exit: the minimum value of _leniz required to start solving the problem. If ifail=12, e04nk may be called again with _leniz suitably larger than miniz. (The bigger the better, since it is not certain how much workspace the basis factors need.)
minz
Type: System..::..Int32 %
On exit: the minimum value of _lenz required to start solving the problem. If ifail=13, e04nk may be called again with _lenz suitably larger than minz. (The bigger the better, since it is not certain how much workspace the basis factors need.)
ninf
Type: System..::..Int32 %
On exit: the number of infeasibilities. This will be zero if ifail=0 or 1.
sinf
Type: System..::..Double %
On exit: the sum of infeasibilities. This will be zero if ninf=0. (Note that e04nk does not attempt to compute the minimum value of sinf if ifail=3.)
obj
Type: System..::..Double %
On exit: the value of the objective function.
If ninf=0, obj includes the quadratic objective term 12 xT Hx (if any).
If ninf>0, obj is just the linear objective term cT x (if any).
For FP problems, obj is set to zero.
clamda
Type: array< System..::..Double >[]()[][]
An array of size [n+m]
On exit: a set of Lagrange multipliers for the bounds on the variables and the general constraints. More precisely, the first n elements contain the multipliers (reduced costs) for the bounds on the variables, and the next m elements contain the multipliers (shadow prices) for the general linear constraints.
iz
Type: array< System..::..Int32 >[]()[][]
An array of size [dim1]
Note: dim1 must satisfy the constraint: _leniz≥1
z
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: dim1 must satisfy the constraint: _lenz≥1
the dimension of the array z.
On entry: the dimension of the array z as declared in the (sub)program from which e04nk is called.
Constraint: _lenz≥1.
The amounts of workspace provided and required (i.e., miniz and minz) are (by default for e04nk) output. Since the minimum values of _leniz and _lenz required to start solving the problem are returned in miniz and minz, respectively, you may prefer to obtain appropriate values from the output of a preliminary run with the length of z and iz set to 1. (e04nk will then terminate with ifail=12.)
options
Type: NagLibrary..::..E04..::..e04nkOptions
An Object of type E04.e04nkOptions. Used to configure optional parameters to this method.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04nk is designed to solve a class of quadratic programming problems that are assumed to be stated in the following general form:
minimize x∈Rn f x  subject to  l≤xAx≤u, (1)
where x is a set of variables, A is an m by n matrix and the objective function f x may be specified in a variety of ways depending upon the particular problem to be solved. The optional parameter Maximize may be used to specify an alternative problem in which f x is maximized. The possible forms for f x are listed in Table 1, in which the prefixes FP, LP and QP stand for ‘feasible point’, ‘linear programming’ and ‘quadratic programming’ respectively, c is an n-element vector and H is the n by n second-derivative matrix ∇2 f x (the Hessian matrix).
Problem type | Objective function f x | Hessian matrix H
FP | Not applicable | Not applicable
LP | cT x | Not applicable
QP | cT x+12 xT Hx | Symmetric positive semidefinite
Table 1
For LP and QP problems, the unique global minimum value of f x is found. For FP problems, f x is omitted and the method attempts to find a feasible point for the set of constraints. For QP problems, you must also provide a method that computes Hx for any given vector x. (H need not be stored explicitly.) If H is the zero matrix, the method will still solve the resulting LP problem; however, this can be accomplished more efficiently by setting ncolh=0 (see [Parameters]).
The defining feature of a convex QP problem is that the matrix H must be positive semidefinite, i.e., it must satisfy xT Hx≥0 for all x. Otherwise, f x is said to be nonconvex and it may be more appropriate to call e04ug instead.
e04nk is intended to solve large-scale linear and quadratic programming problems in which the constraint matrix A is sparse (i.e., when the number of zero elements is sufficiently large that it is worthwhile using algorithms which avoid computations and storage involving zero elements). The method also takes advantage of sparsity in c. (Sparsity in H can be exploited in the method that computes Hx.) For problems in which A can be treated as a dense matrix, it is usually more efficient to use e04mf, e04nc or e04nf.
The upper and lower bounds on the m elements of Ax are said to define the general constraints of the problem. Internally, e04nk converts the general constraints to equalities by introducing a set of slack variables s, where s=s 1,s 2,…,sm T. For example, the linear constraint 5≤2 x 1+3 x 2≤+∞ is replaced by 2 x 1+3 x 2-s 1=0, together with the bounded slack 5≤s 1≤+∞. The problem defined by (1) can therefore be re-written in the following equivalent form:
minimize x∈Rn,s∈Rm f x  subject to  Ax-s=0,  l≤xs≤u.
Since the slack variables s are subject to the same upper and lower bounds as the elements of Ax, the bounds on Ax and x can simply be thought of as bounds on the combined vector x,s. (In order to indicate their special role in QP problems, the original variables x are sometimes known as ‘column variables’, and the slack variables s are known as ‘row variables’.)
Each LP or QP problem is solved using an active-set method. This is an iterative procedure with two phases: a feasibility phase, in which the sum of infeasibilities is minimized to find a feasible point; and an optimality phase, in which f x is minimized by constructing a sequence of iterations that lies within the feasible region.
A constraint is said to be active or binding at x if the associated element of either x or Ax is equal to one of its upper or lower bounds. Since an active constraint in Ax has its associated slack variable at a bound, the status of both simple and general upper and lower bounds can be conveniently described in terms of the status of the variables x,s. A variable is said to be nonbasic if it is temporarily fixed at its upper or lower bound. It follows that regarding a general constraint as being active is equivalent to thinking of its associated slack as being nonbasic.
At each iteration of an active-set method, the constraints Ax-s=0 are (conceptually) partitioned into the form
B xB+S xS+N xN=0,
where xN consists of the nonbasic elements of x,s and the basis matrix B is square and nonsingular. The elements of xB and xS are called the basic and superbasic variables respectively; with xN they are a permutation of the elements of x and s. At a QP solution, the basic and superbasic variables will lie somewhere between their upper or lower bounds, while the nonbasic variables will be equal to one of their bounds. At each iteration, xS is regarded as a set of independent variables that are free to move in any desired direction, namely one that will improve the value of the objective function (or sum of infeasibilities). The basic variables are then adjusted in order to ensure that x,s continues to satisfy Ax-s=0. The number of superbasic variables (nS say) therefore indicates the number of degrees of freedom remaining after the constraints have been satisfied. In broad terms, nS is a measure of how nonlinear the problem is. In particular, nS will always be zero for FP and LP problems.
If it appears that no improvement can be made with the current definition of B, S and N, a nonbasic variable is selected to be added to S, and the process is repeated with the value of nS increased by one. At all stages, if a basic or superbasic variable encounters one of its bounds, the variable is made nonbasic and the value of nS is decreased by one.
Associated with each of the m equality constraints Ax-s=0 is a dual variable πi. Similarly, each variable in x,s has an associated reduced gradient dj (also known as a reduced cost). The reduced gradients for the variables x are the quantities g-AT π, where g is the gradient of the QP objective function; and the reduced gradients for the slack variables s are the dual variables π. The QP subproblem is optimal if dj≥0 for all nonbasic variables at their lower bounds, dj≤0 for all nonbasic variables at their upper bounds and dj=0 for all superbasic variables. In practice, an approximate QP solution is found by slightly relaxing these conditions on dj (see the description of the optional parameter Optimality Tolerance).
The process of computing and comparing reduced gradients is known as pricing (a term first introduced in the context of the simplex method for linear programming). To ‘price’ a nonbasic variable xj means that the reduced gradient dj associated with the relevant active upper or lower bound on xj is computed via the formula dj=gj-aT π, where aj is the jth column of A-I. (The variable selected by such a process and the corresponding value of dj (i.e., its reduced gradient) are the quantities +S and dj in the monitoring file output; see [Description of Monitoring Information].) If A has significantly more columns than rows (i.e., n≫m), pricing can be computationally expensive. In this case, a strategy known as partial pricing can be used to compute and compare only a subset of the dj's.
e04nk is based on SQOPT, which is part of the SNOPT package described in Gill et al. (2002), which in turn utilizes methods from the MINOS package (see Murtagh and Saunders (1995)). It uses stable numerical methods throughout and includes a reliable basis package (for maintaining sparse LU factors of the basis matrix B), a practical anti-degeneracy procedure, efficient handling of linear constraints and bounds on the variables (by an active-set strategy), as well as automatic scaling of the constraints. Further details can be found in [Algorithmic Details].

References

Fourer R (1982) Solving staircase linear programs by the simplex method Math. Programming 23 274–313
Gill P E and Murray W (1978) Numerically stable methods for quadratic programming Math. Programming 14 349–372
Gill P E, Murray W and Saunders M A (2002) SNOPT: An SQP Algorithm for Large-scale Constrained Optimization 12 979–1006 SIAM J. Optim.
Gill P E, Murray W, Saunders M A and Wright M H (1987) Maintaining LU factors of a general sparse matrix Linear Algebra and its Applics. 88/89 239–270
Gill P E, Murray W, Saunders M A and Wright M H (1989) A practical anti-cycling procedure for linearly constrained optimization Math. Programming 45 437–474
Gill P E, Murray W, Saunders M A and Wright M H (1991) Inertia-controlling methods for general quadratic programming SIAM Rev. 33 1–36
Hall J A J and McKinnon K I M (1996) The simplest examples where the simplex method cycles and conditions where EXPAND fails to prevent cycling Report MS 96–100 Department of Mathematics and Statistics, University of Edinburgh
Murtagh B A and Saunders M A (1995) MINOS 5.4 users' guide Report SOL 83-20R Department of Operations Research, Stanford University

Error Indicators and Warnings

Note: e04nk may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LENIZ, LENZ) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
Weak solution found. The final x is not unique, although x gives the global minimum value of the objective function.
ifail=2
The problem is unbounded (or badly scaled). The objective function is not bounded below in the feasible region.
ifail=3
The problem is infeasible. The general constraints cannot all be satisfied simultaneously to within the value of the optional parameter Feasibility Tolerance (default value=max 10-6,ε, where ε is the machine precision).
ifail=4
Too many iterations. The value of the optional parameter Iteration Limit (default value=max 50,5 n+m) is too small.
ifail=5
The reduced Hessian matrix ZT HZ (see [Definition of the Working Set and Search Direction]) exceeds its assigned dimension. The value of the optional parameter Superbasics Limit (default value=min nH+1,n) is too small.
ifail=6
The Hessian matrix H appears to be indefinite. This sometimes occurs because the values of the optional parameters LU Factor Tolerance (default value=100.0) and LU Update Tolerance (default value=10.0) are too large. Check also that qphx has been coded correctly and that all relevant elements of Hx have been assigned their correct values.
ifail=7
An input parameter is invalid.
ifail=8
Numerical error in trying to satisfy the general constraints. The basis is very ill-conditioned.
ifail=9
Not enough integer workspace for the basis factors. Increase _leniz and rerun e04nk.
ifail=10
Not enough real workspace for the basis factors. Increase _lenz and rerun e04nk.
ifail=11
The basis is singular after 15 attempts to factorize it (adding slacks where necessary). Either the problem is badly scaled or the value of the optional parameter LU Factor Tolerance (default value=100.0) is too large.
ifail=12
Not enough integer workspace to start solving the problem. Increase _leniz to at least miniz and rerun e04nk.
ifail=13
Not enough real workspace to start solving the problem. Increase _lenz to at least minz and rerun e04nk.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

e04nk implements a numerically stable active-set strategy and returns solutions that are as accurate as the condition of the problem warrants on the machine.

Parallelism and Performance

None.

Further Comments

This section contains a description of the printed output.

Description of the Printed Output

This section describes the intermediate printout and final printout produced by e04nk. The intermediate printout is a subset of the monitoring information produced by the method at every iteration (see [Description of Monitoring Information]). You can control the level of printed output (see the description of the optional parameter Print Level). Note that the intermediate printout and final printout are produced only if Print Level≥10 (the default for e04nk, by default no output is produced by ).
The following line of summary output (<80 characters) is produced at every iteration. In all cases, the values of the quantities printed are those in effect on completion of the given iteration.
Itn | is the iteration count.
Step | is the step taken along the computed search direction.
Ninf | is the number of violated constraints (infeasibilities). This will be zero during the optimality phase.
Sinf/Objective | is the value of the current objective function. If x is not feasible, Sinf gives the sum of the magnitudes of constraint violations. If x is feasible, Objective is the value of the objective function. The output line for the final iteration of the feasibility phase (i.e., the first iteration for which Ninf is zero) will give the value of the true objective at the first feasible point. During the optimality phase, the value of the objective function will be nonincreasing. During the feasibility phase, the number of constraint infeasibilities will not increase until either a feasible point is found, or the optimality of the multipliers implies that no feasible point exists.
Norm rg | is dS, the Euclidean norm of the reduced gradient (see [Main Iteration]). During the optimality phase, this norm will be approximately zero after a unit step. For FP and LP problems, Norm rg is not printed.
The final printout includes a listing of the status of every variable and constraint.
The following describes the printout for each variable. A full stop (.) is printed for any numerical value that is zero.
Variable | gives the name of the variable. If nname=1, a default name is assigned to the jth variable, for j=1,2,…,n. If nname=n+m, the name supplied in crname[j-1] is assigned to the jth variable.
State gives the state of the variable (LL if nonbasic on its lower bound, UL if nonbasic on its upper bound, EQ if nonbasic and fixed, FR if nonbasic and strictly between its bounds, BS if basic and SBS if superbasic).
A key is sometimes printed before State. Note that unless the optional parameter Scale Option=0 (default value=2) is specified, the tests for assigning a key are applied to the variables of the scaled problem.
A | Alternative optimum possible. The variable is nonbasic, but its reduced gradient is essentially zero. This means that if the variable were allowed to start moving away from its bound, there would be no change in the value of the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case, the values of the Lagrange multipliers might also change.
D | Degenerate. The variable is basic or superbasic, but it is equal (or very close) to one of its bounds.
I | Infeasible. The variable is basic or superbasic and is currently violating one of its bounds by more than the value of the Feasibility Tolerance.
N | Not precisely optimal. The variable is nonbasic or superbasic. If the value of the reduced gradient for the variable exceeds the value of the optional parameter Optimality Tolerance, the solution would not be declared optimal because the reduced gradient for the variable would not be considered negligible.
Value | is the value of the variable at the final iteration.
Lower Bound | is the lower bound specified for the variable. None indicates that bl[j-1]≤-bigbnd.
Upper Bound | is the upper bound specified for the variable. None indicates that bu[j-1]≥bigbnd.
Lagr Mult | is the Lagrange multiplier for the associated bound. This will be zero if State is FR. If x is optimal, the multiplier should be non-negative if State is LL, non-positive if State is UL and zero if State is BS or SBS.
Residual | is the difference between the variable Value and the nearer of its (finite) bounds bl[j-1] and bu[j-1]. A blank entry indicates that the associated variable is not bounded (i.e., bl[j-1]≤-bigbnd and bu[j-1]≥bigbnd).
The meaning of the printout for linear constraints is the same as that given above for variables, with ‘variable’ replaced by ‘constraint’, n replaced by m, crname[j-1] replaced by crname[n+j-1], bl[j-1] and bu[j-1] are replaced by bl[n+j-1] and bu[n+j-1] respectively, and with the following change in the heading:
Constrnt gives the name of the linear constraint.
Note that movement off a constraint (as opposed to a variable moving away from its bound) can be interpreted as allowing the entry in the Residual column to become positive.
Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.

Example

This example minimizes the quadratic function f x=cT x+12 xT Hx, where
c=-200.0,-2000.0,-2000.0,-2000.0,-2000.0,400.0,400.0 T
H=2000000020000000220000022000000020000000220000022
subject to the bounds
00 0≤x 1≤0 20000 0≤x 2≤2500400≤x 3≤0 800100≤x 4≤0 70000 0≤x 5≤150000 0≤x 6≤150000 0≤x 7≤1500
and to the linear constraints
1500≤0.00 x 1+0.00 x 2+0.00 x 3+0.00 x 4+0.00 x 5+0.00 x 6+0.00 x 7=20001500≤0.15 x 1+0.04 x 2+0.02 x 3+0.04 x 4+0.02 x 5+0.01 x 6+0.03 x 7≤00 601500≤0.03 x 1+0.05 x 2+0.08 x 3+0.02 x 4+0.06 x 5+0.01 x 6+0.03 x 7≤0 1001500≤0.02 x 1+0.04 x 2+0.01 x 3+0.02 x 4+0.02 x 5+0.01 x 6+0.03 x 7≤00 401500≤0.02 x 1+0.03 x 2+0.01 x 3+0.02 x 4+0.01 x 5+0.01 x 6+0.03 x 7≤00 301500≤0.70 x 1+0.75 x 2+0.80 x 3+0.75 x 4+0.80 x 5+0.97 x 6+0.03 x 7≤20000 250≤0.02 x 1+0.06 x 2+0.08 x 3+0.12 x 4+0.02 x 5+0.01 x 6+0.97 x 7≤0 300
The initial point, which is infeasible, is
x 0=0.0,0.0,0.0,0.0,0.0,0.0,0.0 T.
The optimal solution (to five figures) is
x*=0.0,349.40,648.85,172.85,407.52,271.36,150.02 T.
One bound constraint and four linear constraints are active at the solution. Note that the Hessian matrix H is positive semidefinite.

Example program (C#): e04nke.cs

Example program data: e04nke.d

Example program results: e04nke.r

Algorithmic Details

This section contains a detailed description of the method used by e04nk.

Overview

e04nk is based on an inertia-controlling method that maintains a Cholesky factorization of the reduced Hessian (see below). The method is similar to that of Gill and Murray (1978), and is described in detail by Gill et al. (1991). Here we briefly summarise the main features of the method. Where possible, explicit reference is made to the names of variables that are parameters of the method or appear in the printed output.
The method used has two distinct phases: finding an initial feasible point by minimizing the sum of infeasibilities (the feasibility phase), and minimizing the quadratic objective function within the feasible region (the optimality phase). The computations in both phases are performed by the same methods. The two-phase nature of the algorithm is reflected by changing the function being minimized from the sum of infeasibilities (the printed quantity Sinf; see [Description of Monitoring Information]) to the quadratic objective function (the printed quantity Objective; see [Description of Monitoring Information]).
In general, an iterative process is required to solve a quadratic program. Given an iterate x,s in both the original variables x and the slack variables s, a new iterate x-,s- is defined by
x-s-=xs+αp, (2)
where the step length α is a non-negative scalar (the printed quantity Step; see [Description of Monitoring Information]), and p is called the search direction. (For simplicity, we shall consider a typical iteration and avoid reference to the index of the iteration.) Once an iterate is feasible (i.e., satisfies the constraints), all subsequent iterates remain feasible.

Definition of the Working Set and Search Direction

At each iterate x,s, a working set of constraints is defined to be a linearly independent subset of the constraints that are satisfied ‘exactly’ (to within the value of the optional parameter Feasibility Tolerance). The working set is the current prediction of the constraints that hold with equality at a solution of the LP or QP problem. Let mW denote the number of constraints in the working set (including bounds), and let W denote the associated mW by n+m working set matrix consisting of the mW gradients of the working set constraints.
The search direction is defined so that constraints in the working set remain unaltered for any value of the step length. It follows that p must satisfy the identity
Wp=0. (3)
This characterisation allows p to be computed using any n by nZ full-rank matrix Z that spans the null space of W. (Thus, nZ=n-mW and WZ=0.) The null space matrix Z is defined from a sparse LU factorization of part of W (see (6) and (7)). The direction p will satisfy (3) if
p=Z pZ, (4)
where pZ is any nZ-vector.
The working set contains the constraints Ax-s=0 and a subset of the upper and lower bounds on the variables x,s. Since the gradient of a bound constraint xj≥lj or xj≤uj is a vector of all zeros except for ±1 in position j, it follows that the working set matrix contains the rows of A-I and the unit rows associated with the upper and lower bounds in the working set.
The working set matrix W can be represented in terms of a certain column partition of the matrix A-I by (conceptually) partitioning the constraints Ax-s=0 so that
B xB+S xS+N xN=0, (5)
where B is a square nonsingular basis and xB, xS and xN are the basic, superbasic and nonbasic variables respectively. The nonbasic variables are equal to their upper or lower bounds at x,s, and the superbasic variables are independent variables that are chosen to improve the value of the current objective function. The number of superbasic variables is nS (the printed quantity Ns; see [Description of Monitoring Information]). Given values of xN and xS, the basic variables xB are adjusted so that x,s satisfies (5).
If P is a permutation matrix such that A-I P=BSN, then W satisfies
WP=BSN00IN, (6)
where IN is the identity matrix with the same number of columns as N.
The null space matrix Z is defined from a sparse LU factorization of part of W. In particular, Z is maintained in ‘reduced gradient’ form, using the LUSOL package (see Gill et al. (1991)) to maintain sparse LU factors of the basis matrix B that alters as the working set W changes. Given the permutation P, the null space basis is given by
Z=P-B-1 SI0. (7)
This matrix is used only as an operator, i.e., it is never computed explicitly. Products of the form Zv and ZT g are obtained by solving with B or BT. This choice of Z implies that nZ, the number of ‘degrees of freedom’ at x,s, is the same as nS, the number of superbasic variables.
Let gZ and HZ denote the reduced gradient and reduced Hessian of the objective function:
gZ=ZT g  and  HZ=ZT HZ, (8)
where g is the objective gradient at x,s. Roughly speaking, gZ and HZ describe the first and second derivatives of an nS-dimensional unconstrained problem for the calculation of pZ. (The condition estimator of HZ is the quantity Cond Hz in the monitoring file output; see [Description of Monitoring Information].)
At each iteration, an upper triangular factor R is available such that HZ=RT R. Normally, R is computed from RT R=ZT HZ at the start of the optimality phase and then updated as the QP working set changes. For efficiency, the dimension of R should not be excessive (say, nS≤1000). This is guaranteed if the number of nonlinear variables is ‘moderate’.
If the QP problem contains linear variables, H is positive semidefinite and R may be singular with at least one zero diagonal element. However, an inertia-controlling strategy is used to ensure that only the last diagonal element of R can be zero. (See Gill et al. (1991) for a discussion of a similar strategy for indefinite quadratic programming.)
If the initial R is singular, enough variables are fixed at their current value to give a nonsingular R. This is equivalent to including temporary bound constraints in the working set. Thereafter, R can become singular only when a constraint is deleted from the working set (in which case no further constraints are deleted until R becomes nonsingular).

Main Iteration

If the reduced gradient is zero, x,s is a constrained stationary point on the working set. During the feasibility phase, the reduced gradient will usually be zero only at a vertex (although it may be zero elsewhere in the presence of constraint dependencies). During the optimality phase, a zero reduced gradient implies that x minimizes the quadratic objective function when the constraints in the working set are treated as equalities. At a constrained stationary point, Lagrange multipliers λ are defined from the equations
WT λ=g x. (9)
A Lagrange multiplier λj corresponding to an inequality constraint in the working set is said to be optimal if λj≤σ when the associated constraint is at its upper bound, or if λj≥-σ when the associated constraint is at its lower bound, where σ depends on the value of the optional parameter Optimality Tolerance. If a multiplier is nonoptimal, the objective function (either the true objective or the sum of infeasibilities) can be reduced by continuing the minimization with the corresponding constraint excluded from the working set. (This step is sometimes referred to as ‘deleting’ a constraint from the working set.) If optimal multipliers occur during the feasibility phase but the sum of infeasibilities is nonzero, there is no feasible point and the method terminates immediately with ifail=3 (see [Error Indicators and Warnings]).
The special form (6) of the working set allows the multiplier vector λ, the solution of (9), to be written in terms of the vector
d=g0-A-I T π=g-AT ππ, (10)
where π satisfies the equations BT π=gB, and gB denotes the basic elements of g. The elements of π are the Lagrange multipliers λj associated with the equality constraints Ax-s=0. The vector dN of nonbasic elements of d consists of the Lagrange multipliers λj associated with the upper and lower bound constraints in the working set. The vector dS of superbasic elements of d is the reduced gradient gZ in (8). The vector dB of basic elements of d is zero, by construction. (The Euclidean norm of dS and the final values of dS, g and π are the quantities Norm rg, Reduced Gradnt, Obj Gradient and Dual Activity in the monitoring file output; see [Description of Monitoring Information].)
If the reduced gradient is not zero, Lagrange multipliers need not be computed and the search direction is given by p=Z pZ (see (7) and (11)). The step length is chosen to maintain feasibility with respect to the satisfied constraints.
There are two possible choices for pZ, depending on whether or not HZ is singular. If HZ is nonsingular, R is nonsingular and pZ in (4) is computed from the equations
RT R pZ=-gZ, (11)
where gZ is the reduced gradient at x. In this case, x,s+p is the minimizer of the objective function subject to the working set constraints being treated as equalities. If x,s+p is feasible, α is defined to be unity. In this case, the reduced gradient at x-,s- will be zero, and Lagrange multipliers are computed at the next iteration. Otherwise, α is set to αm, the step to the ‘nearest’ constraint along p. This constraint is then added to the working set at the next iteration.
If HZ is singular, then R must also be singular, and an inertia-controlling strategy is used to ensure that only the last diagonal element of R is zero. (See Gill et al. (1991) for a discussion of a similar strategy for indefinite quadratic programming.) In this case, pZ satisfies
pZT HZpZ=0  and  gZT pZ≤0, (12)
which allows the objective function to be reduced by any step of the form x,s+αp, where α>0. The vector p=Z pZ is a direction of unbounded descent for the QP problem in the sense that the QP objective is linear and decreases without bound along p. If no finite step of the form x,s+αp (where α>0) reaches a constraint not in the working set, the QP problem is unbounded and the method terminates immediately with ifail=2 (see [Error Indicators and Warnings]). Otherwise, α is defined as the maximum feasible step along p and a constraint active at x,s+αp is added to the working set for the next iteration.

Miscellaneous

If the basis matrix is not chosen carefully, the condition of the null space matrix Z in (7) could be arbitrarily high. To guard against this, the method implements a ‘basis repair’ feature in which the LUSOL package (see Gill et al. (1991)) is used to compute the rectangular factorization
BS T=LU, (13)
returning just the permutation P that makes PL PT unit lower triangular. The pivot tolerance is set to require PL PT ij≤2, and the permutation is used to define P in (6). It can be shown that Z is likely to be little more than unity. Hence, Z should be well-conditioned regardless of the condition of W. This feature is applied at the beginning of the optimality phase if a potential B-S ordering is known.
The EXPAND procedure (see Gill et al. (1989)) is used to reduce the possibility of cycling at a point where the active constraints are nearly linearly dependent. Although there is no absolute guarantee that cycling will not occur, the probability of cycling is extremely small (see Hall and McKinnon (1996)). The main feature of EXPAND is that the feasibility tolerance is increased at the start of every iteration. This allows a positive step to be taken at every iteration, perhaps at the expense of violating the bounds on x,s by a small amount.
Suppose that the value of the optional parameter Feasibility Tolerance is δ. Over a period of K iterations (where K is the value of the optional parameter Expand Frequency), the feasibility tolerance actually used by the method (i.e., the working feasibility tolerance) increases from 0.5 δ to δ (in steps of 0.5 δ/K).
At certain stages the following ‘resetting procedure’ is used to remove small constraint infeasibilities. First, all nonbasic variables are moved exactly onto their bounds. A count is kept of the number of nontrivial adjustments made. If the count is nonzero, the basic variables are recomputed. Finally, the working feasibility tolerance is reinitialized to 0.5 δ.
If a problem requires more than K iterations, the resetting procedure is invoked and a new cycle of iterations is started. (The decision to resume the feasibility phase or optimality phase is based on comparing any constraint infeasibilities with δ.)
The resetting procedure is also invoked when the method reaches an apparently optimal, infeasible or unbounded solution, unless this situation has already occurred twice. If any nontrivial adjustments are made, iterations are continued.
The EXPAND procedure not only allows a positive step to be taken at every iteration, but also provides a potential choice of constraints to be added to the working set. All constraints at a distance α (where α≤αm) along p from the current point are then viewed as acceptable candidates for inclusion in the working set. The constraint whose normal makes the largest angle with the search direction is added to the working set. This strategy helps keep the basis matrix B well-conditioned.

Description of Monitoring Information

This section describes the intermediate printout and final printout which constitutes the monitoring information produced by e04nk. (See also the description of the optional parameters Monitoring File and Print Level.) You can control the level of printed output.
When Print Level=5 or ≥10 and Monitoring File≥0, the following line of intermediate printout (<120 characters) is produced at every iteration on the unit number specified by optional parameter Monitoring File. Unless stated otherwise, the values of the quantities printed are those in effect on completion of the given iteration.
Itn | is the iteration count.
pp | is the partial price indicator. The variable selected by the last pricing operation came from the ppth partition of A and -I. Note that pp is reset to zero whenever the basis is refactorized.
dj | is the value of the reduced gradient (or reduced cost) for the variable selected by the pricing operation at the start of the current iteration.
+S | is the variable selected by the pricing operation to be added to the superbasic set.
-S | is the variable chosen to leave the superbasic set.
-BS | is the variable removed from the basis (if any) to become nonbasic.
Step | is the value of the step length α taken along the current search direction p. The variables x have just been changed to x+αp. If a variable is made superbasic during the current iteration (i.e., +S is positive), Step will be the step to the nearest bound. During the optimality phase, the step can be greater than unity only if the reduced Hessian is not positive definite.
Pivot | is the rth element of a vector y satisfying By=aq whenever aq (the qth column of the constraint matrix A-I) replaces the rth column of the basis matrix B. Wherever possible, Step is chosen so as to avoid extremely small values of Pivot (since they may cause the basis to be nearly singular). In extreme cases, it may be necessary to increase the value of the optional parameter Pivot Tolerance to exclude very small elements of y from consideration during the computation of Step.
Ninf | is the number of violated constraints (infeasibilities). This will be zero during the optimality phase.
Sinf/Objective | is the value of the current objective function. If x is not feasible, Sinf gives the sum of the magnitudes of constraint violations. If x is feasible, Objective is the value of the objective function. The output line for the final iteration of the feasibility phase (i.e., the first iteration for which Ninf is zero) will give the value of the true objective at the first feasible point. During the optimality phase, the value of the objective function will be nonincreasing. During the feasibility phase, the number of constraint infeasibilities will not increase until either a feasible point is found, or the optimality of the multipliers implies that no feasible point exists.
L | is the number of nonzeros in the basis factor L. Immediately after a basis factorization B=LU, this entry contains lenL. Further nonzeros are added to L when various columns of B are later replaced. (Thus, L increases monotonically.)
U | is the number of nonzeros in the basis factor U. Immediately after a basis factorization B=LU, this entry contains lenU. As columns of B are replaced, the matrix U is maintained explicitly (in sparse form). The value of U may fluctuate up or down; in general, it will tend to increase.
Ncp | is the number of compressions required to recover workspace in the data structure for U. This includes the number of compressions needed during the previous basis factorization. Normally, Ncp should increase very slowly. If it does not, increase _leniz and _lenz by at least L+U and rerun e04nk (possibly using start="W"; see [Parameters]).
Norm rg | is dS, the Euclidean norm of the reduced gradient (see [Main Iteration]). During the optimality phase, this norm will be approximately zero after a unit step. For FP and LP problems, Norm rg is not printed.
Ns | is the current number of superbasic variables. For FP and LP problems, Ns is not printed.
Cond Hz | is a lower bound on the condition number of the reduced Hessian (see [Definition of the Working Set and Search Direction]). The larger this number, the more difficult the problem. For FP and LP problems, Cond Hz is not printed.
When Print Level≥20 and Monitoring File≥0, the following lines of intermediate printout (<120 characters) are produced on the unit number specified by optional parameter Monitoring File whenever the matrix B or BS=BS T is factorized. Gaussian elimination is used to compute an LU factorization of B or BS, where PL PT is a lower triangular matrix and PUQ is an upper triangular matrix for some permutation matrices P and Q. The factorization is stabilized in the manner described under the optional parameter LU Factor Tolerance (default value=100.0).
Factorize | is the factorization count.
Demand is a code giving the reason for the present factorization as follows:
Code | Meaning
01 0 | First LU factorization.
01 1 | The number of updates reached the value of the optional parameter Factorization Frequency.
01 2 | The number of nonzeros in the updated factors has increased significantly.
01 7 | Not enough storage to update factors.
0 10 | Row residuals too large (see the description for the optional parameter Check Frequency).
0 11 | Ill-conditioning has caused inconsistent results.
Iteration | is the iteration count.
Nonlinear | is the number of nonlinear variables in the current basis B (not printed if BS is factorized).
Linear | is the number of linear variables in B (not printed if BS is factorized).
Slacks | is the number of slack variables in B (not printed if BS is factorized).
Elems | is the number of nonzeros in B (not printed if BS is factorized).
Density | is the percentage nonzero density of B (not printed if BS is factorized). More precisely, Density=100×Elems/Nonlinear+Linear+Slacks 2.
Compressns | is the number of times the data structure holding the partially factorized matrix needed to be compressed, in order to recover unused workspace. Ideally, it should be zero. If it is more than 3 or 4, increase _leniz and _lenz and rerun e04nk (possibly using start="W"; see [Parameters]).
Merit | is the average Markowitz merit count for the elements chosen to be the diagonals of PUQ. Each merit count is defined to be c-1r-1, where c and r are the number of nonzeros in the column and row containing the element at the time it is selected to be the next diagonal. Merit is the average of m such quantities. It gives an indication of how much work was required to preserve sparsity during the factorization.
lenL | is the number of nonzeros in L.
lenU | is the number of nonzeros in U.
Increase | is the percentage increase in the number of nonzeros in L and U relative to the number of nonzeros in B. More precisely, Increase=100×lenL+lenU-Elems/Elems.
m | is the number of rows in the problem. Note that m=Ut+Lt+bp.
Ut | is the number of triangular rows of B at the top of U.
d1 | is the number of columns remaining when the density of the basis matrix being factorized reached 0.3.
Lmax | is the maximum subdiagonal element in the columns of L. This will not exceed the value of the optional parameter LU Factor Tolerance.
Bmax | is the maximum nonzero element in B (not printed if BS is factorized).
BSmax | is the maximum nonzero element in BS (not printed if B is factorized).
Umax is the maximum nonzero element in U, excluding elements of B that remain in U unchanged. (For example, if a slack variable is in the basis, the corresponding row of B will become a row of U without modification. Elements in such rows will not contribute to Umax. If the basis is strictly triangular then none of the elements of B will contribute and Umax will be zero.)
Ideally, Umax should not be significantly larger than Bmax. If it is several orders of magnitude larger, it may be advisable to reset the optional parameter LU Factor Tolerance to some value nearer unity.
Umax is not printed if BS is factorized.
Umin | is the magnitude of the smallest diagonal element of PUQ (not printed if BS is factorized).
Growth is the value of the ratio Umax/Bmax, which should not be too large.
Providing Lmax is not large (say, <10.0), the ratio max Bmax,Umax/Umin is an estimate of the condition number of B. If this number is extremely large, the basis is nearly singular and some numerical difficulties might occur. (However, an effort is made to avoid near-singularity by using slacks to replace columns of B that would have made Umin extremely small and the modified basis is refactorized.)
Growth is not printed if BS is factorized.
Lt | is the number of triangular columns of B at the left of L.
bp | is the size of the ‘bump’ or block to be factorized nontrivially after the triangular rows and columns of B have been removed.
d2 | is the number of columns remaining when the density of the basis matrix being factorized has reached 0.6.
When Print Level≥20 and Monitoring File≥0, the following lines of intermediate printout (<80 characters) are produced on the unit number specified by optional parameter Monitoring File whenever start="C" (see [Parameters]). They refer to the number of columns selected by the Crash procedure during each of several passes through A, whilst searching for a triangular basis matrix.
Slacks | is the number of slacks selected initially.
Free cols | is the number of free columns in the basis, including those whose bounds are rather far apart.
Preferred | is the number of ‘preferred’ columns in the basis (i.e., istate[j-1]=3 for some j≤n). It will be a subset of the columns for which istate[j-1]=3 was specified.
Unit | is the number of unit columns in the basis.
Double | is the number of double columns in the basis.
Triangle | is the number of triangular columns in the basis.
Pad | is the number of slacks used to pad the basis (to make it a nonsingular triangle).
When Print Level≥20 and Monitoring File≥0, the following lines of intermediate printout (<80 characters) are produced on the unit number specified by optional parameter Monitoring File. They refer to the elements of the names array (see [Parameters]).
Name | gives the name for the problem (blank if problem unnamed).
Status | gives the exit status for the problem (i.e., Optimal soln, Weak soln, Unbounded, Infeasible, Excess itns, Error condn or Feasble soln) followed by details of the direction of the optimization (i.e., (Min) or (Max)).
Objective | gives the name of the free row for the problem (blank if objective unnamed).
RHS | gives the name of the constraint right-hand side for the problem (blank if objective unnamed).
Ranges | gives the name of the ranges for the problem (blank if objective unnamed).
Bounds | gives the name of the bounds for the problem (blank if objective unnamed).
When Print Level=1 or ≥10 and Monitoring File≥0, the following lines of final printout (<120 characters) are produced on the unit number specified by optional parameter Monitoring File.
Let aj denote the jth column of A, for j=1,2,…,n. The following describes the printout for each column (or variable). A full stop (.) is printed for any numerical value that is zero.
Number | is the column number j. (This is used internally to refer to xj in the intermediate output.)
Column | gives the name of xj.
State gives the state of the variable (LL if nonbasic on its lower bound, UL if nonbasic on its upper bound, EQ if nonbasic and fixed, FR if nonbasic and strictly between its bounds, BS if basic and SBS if superbasic).
A key is sometimes printed before State. Note that unless the optional parameter Scale Option=0 is specified, the tests for assigning a key are applied to the variables of the scaled problem.
A | Alternative optimum possible. The variable is nonbasic, but its reduced gradient is essentially zero. This means that if the variable were allowed to start moving away from its bound, there would be no change in the value of the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case, the values of the Lagrange multipliers might also change.
D | Degenerate. The variable is basic or superbasic, but it is equal (or very close) to one of its bounds.
I | Infeasible. The variable is basic or superbasic and is currently violating one of its bounds by more than the value of the Feasibility Tolerance.
N | Not precisely optimal. The variable is nonbasic or superbasic. If the value of the reduced gradient for the variable exceeds the value of the optional parameter Optimality Tolerance, the solution would not be declared optimal because the reduced gradient for the variable would not be considered negligible.
Activity | is the value of xj at the final iterate.
Obj Gradient | is the value of gj at the final iterate. For FP problems, gj is set to zero.
Lower Bound | is the lower bound specified for the variable. None indicates that bl[j-1]≤-bigbnd.
Upper Bound | is the upper bound specified for the variable. None indicates that bu[j-1]≥bigbnd.
Reduced Gradnt | is the value of dj at the final iterate (see [Main Iteration]). For FP problems, dj is set to zero.
m + j | is the value of m+j.
Let vi denote the ith row of A, for i=1,2,…,m. The following describes the printout for each row (or constraint). A full stop (.) is printed for any numerical value that is zero.
Number | is the value of n+i. (This is used internally to refer to si in the intermediate output.)
Row | gives the name of νi.
State gives the state of vi (LL if active on its lower bound, UL if active on its upper bound, EQ if active and fixed, BS if inactive when si is basic and SBS if inactive when si is superbasic).
A key is sometimes printed before State. Note that unless the optional parameter Scale Option=0 is specified, the tests for assigning a key are applied to the variables of the scaled problem.
A | Alternative optimum possible. The variable is nonbasic, but its reduced gradient is essentially zero. This means that if the variable were allowed to start moving away from its bound, there would be no change in the value of the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case, the values of the Lagrange multipliers might also change.
D | Degenerate. The variable is basic or superbasic, but it is equal (or very close) to one of its bounds.
I | Infeasible. The variable is basic or superbasic and is currently violating one of its bounds by more than the value of the Feasibility Tolerance.
N | Not precisely optimal. The variable is nonbasic or superbasic. If the value of the reduced gradient for the variable exceeds the value of the optional parameter Optimality Tolerance, the solution would not be declared optimal because the reduced gradient for the variable would not be considered negligible.
Activity | is the value of vi at the final iterate.
Slack Activity | is the value by which the row differs from its nearest bound. (For the free row (if any), it is set to Activity.)
Lower Bound | is the lower bound specified for the variable. None indicates that bl[j-1]≤-bigbnd.
Upper Bound | is the upper bound specified for the variable. None indicates that bu[j-1]≥bigbnd.
Dual Activity | is the value of the dual variable πi (the Lagrange multiplier for νi; see [Main Iteration]). For FP problems, πi is set to zero.
i | gives the index i of the ith row.
Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.

See Also

E04 Class
E04 Members


e04nku Method

[image]

NAG Library for .NET Release 2
E04..::e04nku Method
E04 Class See Also Send Feedback
Auxiliary for use as a delegate parameter

Syntax

C#
public static void e04nku(
    int nstate,
    int ncolh,
    double[] x,
    double[] hx
)
Visual Basic
Public Shared Sub e04nku ( _
    nstate As Integer, _
    ncolh As Integer, _
    x As Double(), _
    hx As Double() _
)
Visual C++
public:
static void e04nku(
    int nstate,
    int ncolh,
    array<double>^ x,
    array<double>^ hx
)
F#
static member e04nku :
        nstate : int *
        ncolh : int *
        x : float[] *
        hx : float[] -> unit

Parameters

nstate
Type: System..::..Int32
On entry: if nstate=1, then e04nk is calling _qphx for the first time on a sub-problem. This parameter setting allows you to save computation time if certain data must be read or calculated only once.
If nstate≥2, then e04nk is calling _qphx for the last time. This parameter setting allows you to perform some additional computation on the final sub-problem solution. In general, the last call to _qphx is made with nstate=2+_ifail (see [Error Indicators and Warnings]).
Otherwise, nstate=0.
ncolh
Type: System..::..Int32
On entry: this is the same parameter ncolh as supplied to e04nk.
x
Type: array< System..::..Double >[]()[][]
An array of size [ncolh]
On entry: an initial estimate of the solution.
On exit: the point at which e04nk terminated. If ifail=0, 1 or 4, x contains an estimate of the solution.
hx
Type: array< System..::..Double >[]()[][]
An array of size [ncolh]

Description

Auxiliary for use as a delegate parameter

References

None.

Error Indicators and Warnings

None.

Accuracy

Not applicable.

Further Comments

None.

Example

None.

See Also

E04 Class
E04 Members


e04nq Method

[image]

NAG Library for .NET Release 2
E04..::e04nq Method
E04 Class See Also Send Feedback
e04nq solves sparse linear programming or convex quadratic programming problems. The initialization method (E04NPF not in this release) must have been called before calling e04nq.

Syntax

C#
public static void e04nq(
    string start,
    E04..::..E04NQ_QPHX qphx,
    int m,
    int n,
    int ne,
    int nname,
    int lenc,
    int ncolh,
    int iobj,
    double objadd,
    string prob,
    double[] acol,
    int[] inda,
    int[] loca,
    double[] bl,
    double[] bu,
    double[] c,
    string[] names,
    int[] helast,
    int[] hs,
    double[] x,
    double[] pi,
    double[] rc,
    ref int ns,
    out int ninf,
    out double sinf,
    out double obj,
    E04..::..e04nqOptions options,
    out int ifail
)
Visual Basic
Public Shared Sub e04nq ( _
    start As String, _
    qphx As E04..::..E04NQ_QPHX, _
    m As Integer, _
    n As Integer, _
    ne As Integer, _
    nname As Integer, _
    lenc As Integer, _
    ncolh As Integer, _
    iobj As Integer, _
    objadd As Double, _
    prob As String, _
    acol As Double(), _
    inda As Integer(), _
    loca As Integer(), _
    bl As Double(), _
    bu As Double(), _
    c As Double(), _
    names As String(), _
    helast As Integer(), _
    hs As Integer(), _
    x As Double(), _
    pi As Double(), _
    rc As Double(), _
    ByRef ns As Integer, _
    <OutAttribute> ByRef ninf As Integer, _
    <OutAttribute> ByRef sinf As Double, _
    <OutAttribute> ByRef obj As Double, _
    options As E04..::..e04nqOptions, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04nq(
    String^ start,
    E04..::..E04NQ_QPHX^ qphx,
    int m,
    int n,
    int ne,
    int nname,
    int lenc,
    int ncolh,
    int iobj,
    double objadd,
    String^ prob,
    array<double>^ acol,
    array<int>^ inda,
    array<int>^ loca,
    array<double>^ bl,
    array<double>^ bu,
    array<double>^ c,
    array<String^>^ names,
    array<int>^ helast,
    array<int>^ hs,
    array<double>^ x,
    array<double>^ pi,
    array<double>^ rc,
    int% ns,
    [OutAttribute] int% ninf,
    [OutAttribute] double% sinf,
    [OutAttribute] double% obj,
    E04..::..e04nqOptions^ options,
    [OutAttribute] int% ifail
)
F#
static member e04nq :
        start : string *
        qphx : E04..::..E04NQ_QPHX *
        m : int *
        n : int *
        ne : int *
        nname : int *
        lenc : int *
        ncolh : int *
        iobj : int *
        objadd : float *
        prob : string *
        acol : float[] *
        inda : int[] *
        loca : int[] *
        bl : float[] *
        bu : float[] *
        c : float[] *
        names : string[] *
        helast : int[] *
        hs : int[] *
        x : float[] *
        pi : float[] *
        rc : float[] *
        ns : int byref *
        ninf : int byref *
        sinf : float byref *
        obj : float byref *
        options : E04..::..e04nqOptions *
        ifail : int byref -> unit

Parameters

start
Type: System..::..String
On entry: indicates how a starting basis (and certain other items) will be obtained.
start="C"
Requests that an internal Crash procedure be used to choose an initial basis, unless a Basis file is provided via optional parameters Old Basis File, Insert File or Load File.
start="B"
Is the same as start="C" but is more meaningful when a Basis file is given.
start="W"
Means that a basis is already defined in hs and a start point is already defined in x (probably from an earlier call).
Constraint: start="B", "C" or "W".
qphx
Type: NagLibrary..::..E04..::..E04NQ_QPHX
For QP problems, you must supply a version of qphx to compute the matrix product Hx for a given vector x. If H has rows and columns of zeros, it is most efficient to order x so that the nonlinear variables appear first. For example, if x=y,z T and only y enters the objective quadratically then
Hx=H 1000yz=H 1 y0. (2)
In this case, ncolh should be the dimension of y, and qphx should compute H 1 y. For FP and LP problems, qphx will never be called by e04nq and hence qphx may be the dummy method E04NSH.

A delegate of type E04NQ_QPHX.

m
Type: System..::..Int32
On entry: m, the number of general linear constraints (or slacks). This is the number of rows in the linear constraint matrix A, including the free row (if any; see iobj). Note that A must have at least one row. If your problem has no constraints, or only upper or lower bounds on the variables, then you must include a dummy row with sufficiently wide upper and lower bounds (see also acol, inda and loca).
Constraint: m≥1.
n
Type: System..::..Int32
On entry: n, the number of variables (excluding slacks). This is the number of columns in the linear constraint matrix A.
Constraint: n≥1.
ne
Type: System..::..Int32
On entry: the number of nonzero elements in A.
Constraint: 1≤ne≤n×m.
nname
Type: System..::..Int32
On entry: the number of column (i.e., variable) and row names supplied in the array names.
nname=1
There are no names. Default names will be used in the printed output.
nname=n+m
All names must be supplied.
Constraint: nname=1 or n+m.
lenc
Type: System..::..Int32
On entry: the number of elements in the constant objective vector c.
If lenc>0, the first lenc elements of x belong to variables corresponding to the constant objective term c.
Constraint: 0≤lenc≤n.
ncolh
Type: System..::..Int32
On entry: nH, the number of leading nonzero columns of the Hessian matrix H. For FP and LP problems, ncolh must be set to zero.
The first ncolh elements of x belong to variables corresponding to the nonzero block of the QP Hessian.
Constraint: 0≤ncolh≤n.
iobj
Type: System..::..Int32
On entry: if iobj>0, row iobj of A is a free row containing the nonzero elements of the vector c appearing in the linear objective term cT x.
If iobj=0, there is no free row, and the linear objective vector should be supplied in array c.
Constraint: 0≤iobj≤m.
objadd
Type: System..::..Double
On entry: the constant q, to be added to the objective for printing purposes. Typically objadd=0.0E0.
prob
Type: System..::..String
On entry: the name for the problem. It is used in the printed solution and in some methods that output Basis files. A blank name may be used.
acol
Type: array< System..::..Double >[]()[][]
An array of size [ne]
On entry: the nonzero elements of A, ordered by increasing column index. Note that all elements must be assigned a value in the calling program.
inda
Type: array< System..::..Int32 >[]()[][]
An array of size [ne]
On entry: inda[i-1] must contain the row index of the nonzero element stored in acol[i-1], for i=1,2,…,ne. Thus a pair of values acol[i-1],inda[i-1] contains a matrix element and its corresponding row index.
Note that the row indices for a column may be supplied in any order.
Constraint: 1≤inda[i-1]≤m, for i=1,2,…,ne.
loca
Type: array< System..::..Int32 >[]()[][]
An array of size [n+1]
On entry: loca[j-1] must contain the index in acol and inda of the start of the jth column, for j=1,2,…,n. Thus for j=1:n, the entries of column j are held in acol[k-1:l-1] and their corresponding row indices are in inda[k-1:l-1], where k=loca[j-1] and l=loca[j]-1. To specify the jth column as empty, set loca[j-1]=loca[j]. Note that the first and last elements of loca must be loca[0]=1 and loca[n]=ne+1. If your problem has no constraints, or just bounds on the variables, you may include a dummy ‘free’ row with a single (zero) element by setting ne=1, acol[0]=0.0, inda[0]=1, loca[0]=1, and loca[j-1]=2, for j=2:n+1. This row is made ‘free’ by setting its bounds to be bl[n]=-bigbnd and bu[n]=bigbnd, where bigbnd is the value of the optional parameter Infinite Bound Size.
Constraints:
  • loca[0]=1;
  • loca[j-1]≥1, for j=2,3,…,n;
  • loca[n]=ne+1;
  • 0≤loca[j]-loca[j-1]≤m, for j=1,2,…,n.
bl
Type: array< System..::..Double >[]()[][]
An array of size [n+m]
On entry: l, the lower bounds for all the variables and general constraints, in the following order. The first n elements of bl must contain the bounds on the variables x, and the next m elements the bounds for the general linear constraints Ax (which, equivalently, are the bounds for the slacks, s) and the free row (if any). To fix the jth variable, set bl[j-1]=bu[j-1]=β, say, where β<bigbnd. To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j-1]≤-bigbnd. Here, bigbnd is the value of the optional parameter Infinite Bound Size. To specify the jth constraint as an equality, set bl[n+j-1]=bu[n+j-1]=β, say, where β<bigbnd. Note that the lower bound corresponding to the free row must be set to -∞ and stored in bl[n+iobj-1].
Constraint: if iobj>0, bl[n+iobj-1]≤-bigbnd
(See also the description for bu.)
bu
Type: array< System..::..Double >[]()[][]
An array of size [n+m]
On entry: u, the upper bounds for all the variables and general constraints, in the following order. The first n elements of bu must contain the bounds on the variables x, and the next m elements the bounds for the general linear constraints Ax (which, equivalently, are the bounds for the slacks, s) and the free row (if any). To specify a nonexistent upper bound (i.e., uj=+∞), set bu[j-1]≥bigbnd. Note that the upper bound corresponding to the free row must be set to +∞ and stored in bu[n+iobj-1].
Constraints:
  • if iobj>0, bu[n+iobj-1]≥bigbnd;
  • otherwise bl[i-1]≤bu[i-1].
c
Type: array< System..::..Double >[]()[][]
An array of size [max 1,lenc]
Note: the dimension of the array c must be at least max 1,lenc if iobj≠0, and at least 1 otherwise.
On entry: contains the explicit objective vector c (if any). If the problem is of type FP, or if lenc=0, then c is not referenced. (In that case, c may be dimensioned (1), or it could be any convenient array.)
names
Type: array< System..::..String >[]()[][]
An array of size [nname]
On entry: the optional column and row names, respectively.
If nname=1, names is not referenced and the printed output will use default names for the columns and rows.
If nname=n+m, the first n elements must contain the names for the columns and the next m elements must contain the names for the rows. Note that the name for the free row (if any) must be stored in names[n+iobj-1].
helast
Type: array< System..::..Int32 >[]()[][]
An array of size [n+m]
On entry: defines which variables are to be treated as being elastic in elastic mode. The allowed values of helast are:
helast[j-1] | Status in elastic mode
0 | Variable j is non-elastic and cannot be infeasible
1 | Variable j can violate its lower bound
2 | Variable j can violate its upper bound
3 | Variable j can violate either its lower or upper bound
helast need not be assigned if optional parameter Elastic Mode=0.
Constraint: if Elastic Mode≠0, helast[j-1]=0,1,2,3, for j=1,2,…,n+m.
hs
Type: array< System..::..Int32 >[]()[][]
An array of size [n+m]
On entry: if start="C" or "B", and a Basis file of some sort is to be input (see the description of the optional parameters Old Basis File, Insert File or Load File), then hs and x need not be set at all.
If start="C" or "B" and there is no Basis file, the first n elements of hs and x must specify the initial states and values, respectively, of the variables x. (The slacks s need not be initialized.) An internal Crash procedure is then used to select an initial basis matrix B. The initial basis matrix will be triangular (neglecting certain small elements in each column). It is chosen from various rows and columns of A-I. Possible values for hs[j-1] are as follows:
hs[j-1] | State of x[j-1] during Crash procedure
0 or 1 | Eligible for the basis
2 | Ignored
3 | Eligible for the basis (given preference over 0 or 1)
4 or 5 | Ignored
If nothing special is known about the problem, or there is no wish to provide special information, you may set hs[j-1]=0 and x[j-1]=0.0, for j=1,2,…,n. All variables will then be eligible for the initial basis. Less trivially, to say that the jth variable will probably be equal to one of its bounds, set hs[j-1]=4 and x[j-1]=bl[j-1] or hs[j-1]=5 and x[j-1]=bu[j-1] as appropriate.
Following the Crash procedure, variables for which hs[j-1]=2 are made superbasic. Other variables not selected for the basis are then made nonbasic at the value x[j-1] if bl[j-1]≤x[j-1]≤bu[j-1], or at the value bl[j-1] or bu[j-1] closest to x[j-1].
If start="W", hs and x must specify the initial states and values, respectively, of the variables and slacks x,s. If e04nq has been called previously with the same values of n and m, hs already contains satisfactory information.
Constraints:
  • if start="C" or "B", 0≤hs[j-1]≤5, for j=1,2,…,n;
  • if start="W", 0≤hs[j-1]≤3, for j=1,2,…,n+m.
On exit: the final states of the variables and slacks x,s. The significance of each possible value of hs[j-1] is as follows:
hs[j-1] | State of variable j | Normal value of x[j-1]
0 | Nonbasic | bl[j-1]
1 | Nonbasic | bu[j-1]
2 | Superbasic | Between bl[j-1] and bu[j-1]
3 | Basic | Between bl[j-1] and bu[j-1]
If ninf=0, basic and superbasic variables may be outside their bounds by as much as the value of the optional parameter Feasibility Tolerance. Note that unless the optional parameter Scale Option=0 is specified, the optional parameter Feasibility Tolerance applies to the variables of the scaled problem. In this case, the variables of the original problem may be as much as 0.1 outside their bounds, but this is unlikely unless the problem is very badly scaled.
Very occasionally some nonbasic variables may be outside their bounds by as much as the optional parameter Feasibility Tolerance, and there may be some nonbasic variables for which x[j-1] lies strictly between its bounds.
If ninf>0, some basic and superbasic variables may be outside their bounds by an arbitrary amount (bounded by sinf if Scale Option=0).
x
Type: array< System..::..Double >[]()[][]
An array of size [n+m]
On entry: the initial values of the variables x, and, if start="W", the slacks s, i.e., x,s. (See the description for parameter hs.)
On exit: the final values of the variables and slacks x,s.
pi
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: contains the dual variables π (a set of Lagrange multipliers (shadow prices) for the general constraints).
rc
Type: array< System..::..Double >[]()[][]
An array of size [n+m]
On exit: contains the reduced costs, g-A-I T π. The vector g is the gradient of the objective if x is feasible, otherwise it is the gradient of the Phase 1 objective. In the former case, g i=0, for i=n+1:m, hence rc[n+1:m-1]=π.
ns
Type: System..::..Int32 %
On entry: nS, the number of superbasics. For QP problems, ns need not be specified if start="C", but must retain its value from a previous call when start="W". For FP and LP problems, ns need not be initialized.
On exit: the final number of superbasics. This will be zero for FP and LP problems.
ninf
Type: System..::..Int32 %
On exit: the number of infeasibilities.
sinf
Type: System..::..Double %
On exit: the sum of the scaled infeasibilities. This will be zero if ninf=0, and is most meaningful when Scale Option=0.
obj
Type: System..::..Double %
On exit: the value of the objective function.
If ninf=0, obj includes the quadratic objective term 12 xT Hx (if any).
If ninf>0, obj is just the linear objective term cT x (if any).
For FP problems, obj is set to zero.
Note that obj does not include contributions from the constant term objadd or the objective row, if any.
options
Type: NagLibrary..::..E04..::..e04nqOptions
An Object of type E04.e04nqOptions. Used to configure optional parameters to this method.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04nq is designed to solve large-scale linear or quadratic programming problems of the form:
minimize x∈Rn f x  subject to ​l≤xAx≤u, (1)
where x is an n-vector of variables, l and u are constant lower and upper bounds, A is an m by n sparse matrix and f x is a linear or quadratic objective function that may be specified in a variety of ways, depending upon the particular problem being solved. The optional parameter Maximize may be used to specify a problem in which f x is maximized instead of minimized.
Upper and lower bounds are specified for all variables and constraints. This form allows full generality in specifying various types of constraint. In particular, the jth constraint may be defined as an equality by setting lj=uj. If certain bounds are not present, the associated elements of l or u may be set to special values that are treated as -∞ or +∞.
The possible forms for the function f x are summarised in Table 1. The most general form for f x is
f x=q+cT x+12 xT Hx=q+∑j=1 n cjxj+12∑i=1 n∑j=1 n xiH ijxj
where q is a constant, c is a constant n-vector and H is a constant symmetric n by n matrix with elements H ij. In this form, f is a quadratic function of x and (1) is known as a quadratic program (QP). e04nq is suitable for all convex quadratic programs. The defining feature of a convex QP is that the matrix H must be positive semidefinite, i.e., it must satisfy xT Hx≥0 for all x. If not, f x is nonconvex and e04nq will terminate with the error indicator ifail=11. If f x is nonconvex it may be more appropriate to call e04vh instead.
Problem type | Objective function f x | Hessian matrix H
FP | Not applicable | q=c=H=0
LP | q+cT x | H=0
QP | q+cT x+12 xT Hx | Symmetric positive semidefinite
Table 1
Choices for the objective function f x
If H=0, then f x=q+cT x and the problem is known as a linear program (LP). In this case, rather than defining an H with zero elements, you can define H to have no columns by setting ncolh=0 (see [Parameters]).
If H=0, q=0, and c=0, there is no objective function and the problem is a feasible point problem (FP), which is equivalent to finding a point that satisfies the constraints on x. In the situation where no feasible point exists, several options are available for finding a point that minimizes the constraint violations (see the description of the optional parameter Elastic Mode).
e04nq is suitable for large LPs and QPs in which the matrix A is sparse, i.e., when the number of zero elements is sufficiently large that it is worthwhile using algorithms which avoid computations and storage involving zero elements. The matrix A is input to e04nq by means of the three array parameters acol, inda and loca. This allows you to specify the pattern of nonzero elements in A.
e04nq exploits structure in H by requiring H to be defined implicitly in a method that computes the product Hx for any given vector x. In many cases, the product Hx can be computed very efficiently for any given x, e.g., H may be a sparse matrix, or a sum of matrices of rank-one.
For problems in which A can be treated as a dense matrix, it is usually more efficient to use e04mf, e04nc or e04nf.
There is considerable flexibility allowed in the definition of f x in Table 1. The vector c defining the linear term cT x can be input in three ways: as a sparse row of A; as an explicit dense vector c; or as both a sparse row and an explicit vector (in which case, cT x will be the sum of two linear terms). When stored in A, c is the iobjth row of A, which is known as the objective row. The objective row must always be a free row of A in the sense that its lower and upper bounds must be -∞ and +∞. Storing c as part of A is recommended if c is a sparse vector. Storing c as an explicit vector is recommended for a sequence of problems, each with a different objective (see parameters c and lenc).
The upper and lower bounds on the m elements of Ax are said to define the general constraints of the problem. Internally, e04nq converts the general constraints to equalities by introducing a set of slack variables s, where s=s 1,s 2,…,sm T. For example, the linear constraint 5≤2 x 1+3 x 2≤+∞ is replaced by 2 x 1+3 x 2-s 1=0, together with the bounded slack 5≤s 1≤+∞. The problem defined by (1) can therefore be re-written in the following equivalent form:
minimize x∈Rn,s∈Rm f x subject to ​Ax-s=0,  l≤xs≤u.
Since the slack variables s are subject to the same upper and lower bounds as the elements of Ax, the bounds on x and Ax can simply be thought of as bounds on the combined vector x,s. (In order to indicate their special role in QP problems, the original variables x are sometimes known as ‘column variables’, and the slack variables s are known as ‘row variables’.)
Each LP or QP problem is solved using a two-phase iterative procedure (in which the general constraints are satisfied throughout): a feasibility phase (Phase 1), in which the sum of infeasibilities with respect to the bounds on x and s is minimized to find a feasible point that satisfies all constraints within a specified feasibility tolerance; and an optimality phase (Phase 2), in which f x is minimized (or maximized) by constructing a sequence of iterates that lies within the feasible region.
Phase 1 involves solving a linear program of the form
Phase 1 |
 | minimize x,s,v,w∑j=1n+m vj+wj
 | subject to ​Ax-s=0, l≤xs-v+w≤u, v≥0, w≥0
which is equivalent to minimizing the sum of the constraint violations. If the constraints are feasible (i.e., at least one feasible point exists), eventually a point will be found at which both v and w are zero. Then the associated value of x,s satisfies the original constraints and is used as the starting point for the Phase 2 iterations for minimizing f x.
If the constraints are infeasible (i.e., v≠0 or w≠0 at the end of Phase 1), no solution exists for (1) and you have the option of either terminating or continuing in so-called elastic mode (see the discussion of the optional parameter Elastic Mode). In elastic mode, a ‘relaxed’ or ‘perturbed’ problem is solved in which f x is minimized while allowing some of the bounds to become ‘elastic’, i.e., to change from their specified values. Variables subject to elastic bounds are known as elastic variables. An elastic variable is free to violate one or both of its original upper or lower bounds. You are able to assign which bounds will become elastic if elastic mode is ever started (see the parameter helast in [Parameters]).
To make the relaxed problem meaningful, e04nq minimizes f x while (in some sense) finding the ‘smallest’ violation of the elastic variables. In the situation where all the variables are elastic, the relaxed problem has the form
Phase 2 (γ) |
 | minimize x,s,v,w f x+γ∑j=1n+m vj+wj
 | subject to ​Ax-s=0, l≤xs-v+w≤u, v≥0, w≥0,
where γ is a non-negative parameter known as the elastic weight (see the description of the optional parameter Elastic Weight), and f x+γ∑j vj+wj is called the composite objective. In the more general situation where only a subset of the bounds are elastic, the v's and w's for the non-elastic bounds are fixed at zero.
The elastic weight can be chosen to make the composite objective behave like the original objective f x, the sum of infeasibilities, or anything in-between. If γ=0, e04nq will attempt to minimize f subject to the (true) upper and lower bounds on the non-elastic variables (and declare the problem infeasible if the non-elastic variables cannot be made feasible).
At the other extreme, choosing γ sufficiently large will have the effect of minimizing the sum of the violations of the elastic variables subject to the original constraints on the non-elastic variables. Choosing a large value of the elastic weight is useful for defining a ‘least-infeasible’ point for an infeasible problem.
In Phase 1 and elastic mode, all calculations involving v and w are done implicitly in the sense that an elastic variable xj is allowed to violate its lower bound (say) and an explicit value of v can be recovered as vj=lj-xj.
A constraint is said to be active or binding at x if the associated element of either x or Ax is equal to one of its upper or lower bounds. Since an active constraint in Ax has its associated slack variable at a bound, the status of both simple and general upper and lower bounds can be conveniently described in terms of the status of the variables x,s. A variable is said to be nonbasic if it is temporarily fixed at its upper or lower bound. It follows that regarding a general constraint as being active is equivalent to thinking of its associated slack as being nonbasic.
At each iteration of an active-set method, the constraints Ax-s=0 are (conceptually) partitioned into the form
B xB+S xS+N xN=0,
where xN consists of the nonbasic elements of x,s and the basis matrix B is square and nonsingular. The elements of xB and xS are called the basic and superbasic variables respectively; with xN they are a permutation of the elements of x and s. At a QP solution, the basic and superbasic variables will lie somewhere between their upper or lower bounds, while the nonbasic variables will be equal to one of their bounds. At each iteration, xS is regarded as a set of independent variables that are free to move in any desired direction, namely one that will improve the value of the objective function (or sum of infeasibilities). The basic variables are then adjusted in order to ensure that x,s continues to satisfy Ax-s=0. The number of superbasic variables (nS say) therefore indicates the number of degrees of freedom remaining after the constraints have been satisfied. In broad terms, nS is a measure of how nonlinear the problem is. In particular, nS will always be zero for FP and LP problems.
If it appears that no improvement can be made with the current definition of B, S and N, a nonbasic variable is selected to be added to S, and the process is repeated with the value of nS increased by one. At all stages, if a basic or superbasic variable encounters one of its bounds, the variable is made nonbasic and the value of nS is decreased by one.
Associated with each of the m equality constraints Ax-s=0 is a dual variable πi. Similarly, each variable in x,s has an associated reduced gradient dj (also known as a reduced cost). The reduced gradients for the variables x are the quantities g-AT π, where g is the gradient of the QP objective function, and the reduced gradients for the slack variables s are the dual variables π. The QP subproblem is optimal if dj≥0 for all nonbasic variables at their lower bounds, dj≤0 for all nonbasic variables at their upper bounds and dj=0 for all superbasic variables. In practice, an approximate QP solution is found by slightly relaxing these conditions on dj (see the description of the optional parameter Optimality Tolerance).
The process of computing and comparing reduced gradients is known as pricing (a term first introduced in the context of the simplex method for linear programming). To ‘price’ a nonbasic variable xj means that the reduced gradient dj associated with the relevant active upper or lower bound on xj is computed via the formula dj=gj-ajT π, where aj is the jth column of A-I. (The variable selected by such a process and the corresponding value of dj (i.e., its reduced gradient) are the quantities +SBS and dj in the monitoring file output; see [Description of the Printed Output].) If A has significantly more columns than rows (i.e., n≫m), pricing can be computationally expensive. In this case, a strategy known as partial pricing can be used to compute and compare only a subset of the djs.
e04nq is based on SQOPT, which is part of the SNOPT package described in Gill et al. (2005a). It uses stable numerical methods throughout and includes a reliable basis package (for maintaining sparse LU factors of the basis matrix B), a practical anti-degeneracy procedure, efficient handling of linear constraints and bounds on the variables (by an active-set strategy), as well as automatic scaling of the constraints. Further details can be found in [Algorithmic Details].

References

Fourer R (1982) Solving staircase linear programs by the simplex method Math. Programming 23 274–313
Gill P E and Murray W (1978) Numerically stable methods for quadratic programming Math. Programming 14 349–372
Gill P E, Murray W and Saunders M A (1995) User's guide for QPOPT 1.0: a Fortran package for quadratic programming Report SOL 95-4 Department of Operations Research, Stanford University
Gill P E, Murray W and Saunders M A (2005a) Users' guide for SQOPT 7: a Fortran package for large-scale linear and quadratic programming Report NA 05-1 Department of Mathematics, University of California, San Diego http://www.ccom.ucsd.edu/~peg/papers/sqdoc7.pdf
Gill P E, Murray W and Saunders M A (2005b) Users' guide for SNOPT 7.1: a Fortran package for large-scale linear nonlinear programming Report NA 05-2 Department of Mathematics, University of California, San Diego http://www.ccom.ucsd.edu/~peg/papers/sndoc7.pdf
Gill P E, Murray W, Saunders M A and Wright M H (1987) Maintaining LU factors of a general sparse matrix Linear Algebra and its Applics. 88/89 239–270
Gill P E, Murray W, Saunders M A and Wright M H (1989) A practical anti-cycling procedure for linearly constrained optimization Math. Programming 45 437–474
Gill P E, Murray W, Saunders M A and Wright M H (1991) Inertia-controlling methods for general quadratic programming SIAM Rev. 33 1–36
Hall J A J and McKinnon K I M (1996) The simplest examples where the simplex method cycles and conditions where EXPAND fails to prevent cycling Report MS 96–100 Department of Mathematics and Statistics, University of Edinburgh

Error Indicators and Warnings

Note: e04nq may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail=1
The initialization method (E04NPF not in this release) has not been called or at least one of lencw, leniw and lenrw is less than 600.
ifail=2
An input parameter is invalid.
ifail=3
The requested accuracy could not be achieved.
ifail=4
Weak QP solution found. The final x is not unique.
This exit will occur when the following are true:
(i) | the problem is feasible;
(ii) | the reduced gradient is negligible;
(iii) | the Lagrange multipliers are optimal; and
(iv) | the reduced Hessian is singular or there are some very small multipliers.
This exit cannot occur if H is positive definite (i.e., f x is strictly convex).
ifail=5
The problem is infeasible. The general constraints cannot all be satisfied simultaneously to within the value of the optional parameter Feasibility Tolerance.
Feasibility is measured with respect to the upper and lower bounds on the variables and slacks. The message tells us that among all the points satisfying the general constraints Ax-s=0, there is apparently no point that satisfies the bounds on x and s. Violations as small as the Feasibility Tolerance are ignored, but at least one component of x or s violates a bound by more than the tolerance.
Note: although the objective function is the sum of infeasibilities (when ninf>0), this sum will not necessarily have been minimized when Elastic Mode=1.
If Elastic Mode≠0, e04nq will optimize the QP objective and the sum of infeasibilities, suitably weighted using the optional parameter Elastic Mode. The method will tend to determine a ‘good’ infeasible point if the elastic weight is sufficiently large.
ifail=6
The problem is unbounded (or badly scaled). For a minimization problem, the objective function is not bounded below in the feasible region.
For linear problems, unboundedness is detected by the simplex method when a nonbasic variable can be increased or decreased by an arbitrary amount without causing a basic variable to violate a bound. Consider adding an upper or lower bound to the variable. Also, examine the constraints that have nonzeros in the associated column, to see if they have been formulated as intended.
Very rarely, the scaling of the problem could be so poor that numerical error will give an erroneous indication of unboundedness. Consider using the optional parameter Scale Option.
ifail=7
Too many iterations. The value of the optional parameter Iterations Limit is too small.
The Iterations limit was exceeded before the required solution could be found. Check the iteration log to be sure that progress was being made. If so, restart the run using a Basis file that was saved at the end of the run.
ifail=8
The value of the optional parameter Superbasics Limit is too small. The current set of basic and superbasic variables have been optimized as much as possible and a pricing operation is necessary to continue, but there are already Superbasics Limit superbasics (and no room for any more).
In general, raise the Superbasics Limit s by a reasonable amount, bearing in mind the storage needed for reduced Hessian (see [Definition of the Working Set and Search Direction]). (The Reduced Hessian Dimension h will also increase to s unless specified otherwise, and the associated storage will be about 12 s 2 words.) In some cases you may have to set h<s to conserve storage, but beware that the rate of convergence will probably fall off severely.
ifail=9
The basis is singular after several attempts to factorize it (adding slacks where necessary). Either the problem is badly scaled or the value of the optional parameter LU Factor Tolerance is too large.
ifail=10
Numerical error in trying to satisfy the general constraints. The basis is very ill-conditioned.
An LU factorization of the basis has just been obtained and used to recompute the basic variables xB, given the present values of the superbasic and nonbasic variables. However, a row check has revealed that the resulting solution does not satisfy the current constraints Ax-s=0 sufficiently well.
This probably means that the current basis is very ill-conditioned. Request the Scale Option if there are any linear constraints and variables.
For certain highly structured basis matrices (notably those with band structure), a systematic growth may occur in the factor U. Consult the description of Umax, Umin and Growth in [Description of Monitoring Information], and set the optional parameter LU Factor Tolerance to 2.0 (or possibly even smaller, but not less than 1.0).
ifail=11
An indefinite matrix was detected during the computation of the reduced Hessian factor R (see [Definition of the Working Set and Search Direction]). This may be caused by H being indefinite. Check also that qphx has been coded correctly and that all relevant elements of Hx have been assigned their correct values. If qphx is coded correctly and H is positive semidefinite, the failure may be caused by ill conditioning. Try reducing the values of the optional parameters LU Factor Tolerance and LU Update Tolerance. If there are very large values in H, check the scaling of the variables and constraints.
ifail=12
Internal memory allocation failed when attempting to obtain the required workspace. Please contact NAG.
ifail=13
Internal memory allocation was insufficient. Please contact NAG.
ifail=14
An error has occurred in the basis package, perhaps indicating incorrect setup of arrays inda and loca. Set the optional parameter Print File and examine the output carefully for further information.
ifail=15
An unexpected error has occurred. Set the optional parameter Print File and examine the output carefully for further information.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

e04nq implements a numerically stable active-set strategy and returns solutions that are as accurate as the condition of the problem warrants on the machine.

Parallelism and Performance

None.

Further Comments

This section contains a description of the printed output.

Description of the Printed Output

If Print Level>0, one line of information is output to the Print File every kth iteration, where k is the specified Print Frequency. A heading is printed before the first such line following a basis factorization. The heading contains the items described below. In this description, a pricing operation is defined to be the process by which one or more nonbasic variables are selected to become superbasic (in addition to those already in the superbasic set). The variable selected will be denoted by jq. If the problem is purely linear, variable jq will usually become basic immediately (unless it should happen to reach its opposite bound and return to the nonbasic set).
If optional parameter Partial Price is in effect, variable jq is selected from App or Ipp, the ppth segments of the constraint matrix A-I.
Label | Description
Itn | is the iteration count.
pp | is the partial-price indicator. The variable selected by the last pricing operation came from the ppth partition of A and -I. Note that pp is reset to zero whenever the basis is refactorized.
dj is the value of the reduced gradient (or reduced cost) for the variable selected by the pricing operation at the start of the current iteration.
Algebraically, dj is dj=gj-πT aj, for j=jq, where gj is the gradient of the current objective function, π is the vector of dual variables, and aj is the jth column of the constraint matrix A-I.
Note that dj is the norm of the reduced-gradient vector at the start of the iteration, just after the pricing operation.
+SBS | is the variable jq selected by the pricing operation to be added to the superbasic set.
-SBS | is the variable chosen to leave the superbasic set. It has become basic if the entry under -B is nonzero, otherwise it becomes nonbasic.
-BS | is the variable removed from the basis to become nonbasic.
Step | is the value of the step length α taken along the current search direction p. The variables x have just been changed to x+αp. If a variable is made superbasic during the current iteration (i.e., +SBS is positive), Step will be the step to the nearest bound. During the optimality phase, the step can be greater than unity only if the reduced Hessian is not positive definite.
Pivot | is the rth element of a vector y satisfying By=aq whenever aq (the qth column of the constraint matrix A-I replaces the rth column of the basis matrix B. Wherever possible, Step is chosen so as to avoid extremely small values of Pivot (since they may cause the basis to be nearly singular). In extreme cases, it may be necessary to increase the value of the optional parameter Pivot Tolerance to exclude very small elements of y from consideration during the computation of Step.
nInf | is the number of violated constraints (infeasibilities) before the present iteration. This number will not increase unless iterations are in elastic mode.
sInf | is the sum of infeasibilities before the present iteration. It will usually decrease at each nonzero step, but if nInf decreases by 2 or more, sInf may occasionally increase. However, in elastic mode it will decrease monotonically.
Objective | is the value of the current objective function after the present iteration. Note, if Elastic Mode is 2, the heading is Composite Obj.
L+U | L is the number of nonzeros in the basis factor L. Immediately after a basis factorization B=LU, L contains lenL (see [Description of Monitoring Information]). Further nonzeros are added to L when various columns of B are later replaced. (Thus, L increases monotonically.) U is the number of nonzeros in the basis factor U. Immediately after a basis factorization B=LU, U contains lenU (see [Description of Monitoring Information]). As columns of B are replaced, the matrix U is maintained explicitly (in sparse form). The value of U may fluctuate up or down; in general, it will tend to increase.
ncp | is the number of compressions required to recover workspace in the data structure for U. This includes the number of compressions needed during the previous basis factorization. Normally, ncp should increase very slowly.
The following will be output if the problem is QP or if the superbasic set is non-empty.
Label | Description
rgNorm | is the largest reduced-gradient among the superbasic variables after the current iteration. During the optimality phase, this will be approximately zero after a unit step.
nS | is the current number of superbasic variables.
condHz | is a lower bound on the condition number of the reduced Hessian (see [Definition of the Working Set and Search Direction]). The larger this number, the more difficult the problem. Attention should be given to the scaling of the variables and the constraints to guard against high values of condHz.

Example

This example minimizes the quadratic function f x=cT x+12 xT Hx, where
c=-200.0,-2000.0,-2000.0,-2000.0,-2000.0,400.0,400.0 T
H=2000000020000000220000022000000020000000220000022
subject to the bounds
00 0≤x 1≤0 20000 0≤x 2≤2500400≤x 3≤0 800100≤x 4≤0 70000 0≤x 5≤150000 0≤x 6≤150000 0≤x 7≤1500
and to the linear constraints
x 1+x 2+x 3+x 4+x 5+x 6+x 7=20000.15 x 1+0.04 x 2+0.02 x 3+0.04 x 4+0.02 x 5+0.01 x 6+0.03 x 7≤600.03 x 1+0.05 x 2+0.08 x 3+0.02 x 4+0.06 x 5+0.01 x 6+0.03 x 7≤1000.02 x 1+0.04 x 2+0.01 x 3+0.02 x 4+0.02 x 5≤400.02 x 1+0.03 x 2+0.01 x 5≤301500≤0.70 x 1+0.75 x 2+0.80 x 3+0.75 x 4+0.80 x 5+0.97 x 6250≤0.02 x 1+0.06 x 2+0.08 x 3+0.12 x 4+0.02 x 5+0.01 x 6+0.97 x 7≤300
The initial point, which is infeasible, is
x 0=0.0,0.0,0.0,0.0,0.0,0.0,0.0 T.
The optimal solution (to five figures) is
x*=0.0,349.40,648.85,172.85,407.52,271.36,150.02 T.
One bound constraint and four linear constraints are active at the solution. Note that the Hessian matrix H is positive semidefinite.

Example program (C#): e04nqe.cs

Example program data: e04nqe.d

Example program results: e04nqe.r

Algorithmic Details

This section contains a detailed description of the method used by e04nq.

Overview

e04nq is based on an inertia-controlling method that maintains a Cholesky factorization of the reduced Hessian (see below). The method is similar to that of Gill and Murray (1978), and is described in detail by Gill et al. (1991). Here we briefly summarise the main features of the method. Where possible, explicit reference is made to the names of variables that are parameters of the method or appear in the printed output.
The method used has two distinct phases: finding an initial feasible point by minimizing the sum of infeasibilities (the feasibility phase), and minimizing the quadratic objective function within the feasible region (the optimality phase). The computations in both phases are performed by the same methods. The two-phase nature of the algorithm is reflected by changing the function being minimized from the sum of infeasibilities (the printed quantity sInf; see [Description of the Printed Output]) to the quadratic objective function (the printed quantity Objective; see [Description of the Printed Output]).
In general, an iterative process is required to solve a quadratic program. Given an iterate x,s in both the original variables x and the slack variables s, a new iterate x-,s- is defined by
x-s-=xs+αp, (3)
where the step length α is a non-negative scalar (the printed quantity Step; see [Description of Monitoring Information]), and p is called the search direction. (For simplicity, we shall consider a typical iteration and avoid reference to the index of the iteration.) Once an iterate is feasible (i.e., satisfies the constraints), all subsequent iterates remain feasible.

Definition of the Working Set and Search Direction

At each iterate x,s, a working set of constraints is defined to be a linearly independent subset of the constraints that are satisfied ‘exactly’ (to within the value of the optional parameter Feasibility Tolerance). The working set is the current prediction of the constraints that hold with equality at a solution of the LP or QP problem. Let mW denote the number of constraints in the working set (including bounds), and let W denote the associated mW by n+m working set matrix consisting of the mW gradients of the working set constraints.
The search direction is defined so that constraints in the working set remain unaltered for any value of the step length. It follows that p must satisfy the identity
Wp=0. (4)
This characterisation allows p to be computed using any n by nZ full-rank matrix Z that spans the null space of W. (Thus, nZ=n-mW and WZ=0.) The null space matrix Z is defined from a sparse LU factorization of part of W (see (7) and (8)). The direction p will satisfy (4) if
p=Z pZ, (5)
where pZ is any nZ-vector.
The working set contains the constraints Ax-s=0 and a subset of the upper and lower bounds on the variables x,s. Since the gradient of a bound constraint xj≥lj or xj≤uj is a vector of all zeros except for ±1 in position j, it follows that the working set matrix contains the rows of A-I and the unit rows associated with the upper and lower bounds in the working set.
The working set matrix W can be represented in terms of a certain column partition of the matrix A-I by (conceptually) partitioning the constraints Ax-s=0 so that
B xB+S xS+N xN=0, (6)
where B is a square nonsingular basis and xB, xS and xN are the basic, superbasic and nonbasic variables respectively. The nonbasic variables are equal to their upper or lower bounds at x,s, and the superbasic variables are independent variables that are chosen to improve the value of the current objective function. The number of superbasic variables is nS (the printed quantity nS; see [Description of the Printed Output]). Given values of xN and xS, the basic variables xB are adjusted so that x,s satisfies (6).
If P is a permutation matrix such that A-I P=BSN, then W satisfies
WP=BSN00IN, (7)
where IN is the identity matrix with the same number of columns as N.
The null space matrix Z is defined from a sparse LU factorization of part of W. In particular, Z is maintained in ‘reduced gradient’ form, using the LUSOL package (see Gill et al. (1991)) to maintain sparse LU factors of the basis matrix B as the BSN partition changes. Given the permutation P, the null space basis is given by
Z=P-B-1 SI0. (8)
This matrix is used only as an operator, i.e., it is never computed explicitly. Products of the form Zv and ZT g are obtained by solving with B or BT. This choice of Z implies that nZ, the number of ‘degrees of freedom’ at x,s, is the same as nS, the number of superbasic variables.
Let gZ and HZ denote the reduced gradient and reduced Hessian of the objective function:
gZ=ZT g  and  HZ=ZT HZ, (9)
where g is the objective gradient at x,s. Roughly speaking, gZ and HZ describe the first and second derivatives of an nS-dimensional unconstrained problem for the calculation of pZ. (The condition estimator of HZ is the quantity condHz in the monitoring file output; see [Description of the Printed Output].)
At each iteration, an upper triangular factor R is available such that HZ=RT R. Normally, R is computed from RT R=ZT HZ at the start of the optimality phase and then updated as the QP working set changes. For efficiency, the dimension of R should not be excessive (say, nS≤1000). This is guaranteed if the number of nonlinear variables is ‘moderate’.
If the QP problem contains linear variables, H is positive semidefinite and R may be singular with at least one zero diagonal element. However, an inertia-controlling strategy is used to ensure that only the last diagonal element of R can be zero. (See Gill et al. (1991) for a discussion of a similar strategy for indefinite quadratic programming.)
If the initial R is singular, enough variables are fixed at their current value to give a nonsingular R. This is equivalent to including temporary bound constraints in the working set. Thereafter, R can become singular only when a constraint is deleted from the working set (in which case no further constraints are deleted until R becomes nonsingular).

Main Iteration

If the reduced gradient is zero, x,s is a constrained stationary point on the working set. During the feasibility phase, the reduced gradient will usually be zero only at a vertex (although it may be zero elsewhere in the presence of constraint dependencies). During the optimality phase, a zero reduced gradient implies that x minimizes the quadratic objective function when the constraints in the working set are treated as equalities. At a constrained stationary point, Lagrange multipliers λ are defined from the equations
WT λ=g x. (10)
A Lagrange multiplier, λj, corresponding to an inequality constraint in the working set is said to be optimal if λj≤σ when the associated constraint is at its upper bound, or if λj≥-σ when the associated constraint is at its lower bound, where σ depends on the value of the optional parameter Optimality Tolerance. If a multiplier is nonoptimal, the objective function (either the true objective or the sum of infeasibilities) can be reduced by continuing the minimization with the corresponding constraint excluded from the working set. (This step is sometimes referred to as ‘deleting’ a constraint from the working set.) If optimal multipliers occur during the feasibility phase but the sum of infeasibilities is nonzero, there is no feasible point and the method terminates immediately with ifail=3.
The special form (7) of the working set allows the multiplier vector λ, the solution of (10), to be written in terms of the vector
d=g0-AT-I π=g-AT ππ, (11)
where π satisfies the equations BT π=gB, and gB denotes the basic elements of g. The elements of π are the Lagrange multipliers λj associated with the equality constraints Ax-s=0. The vector dN of nonbasic elements of d consists of the Lagrange multipliers λj associated with the upper and lower bound constraints in the working set. The vector dS of superbasic elements of d is the reduced gradient gZ in (9). The vector dB of basic elements of d is zero, by construction. (The Euclidean norm of dS and the final values of dS, g and π are the quantities rgNorm, Reduced Gradnt, Obj Gradient and Dual Activity in the monitoring file output; see [Description of Monitoring Information].)
If the reduced gradient is not zero, Lagrange multipliers need not be computed and the search direction is given by p=Z pZ (see (8) and (12)). The step length is chosen to maintain feasibility with respect to the satisfied constraints.
There are two possible choices for pZ, depending on whether or not HZ is singular. If HZ is nonsingular, R is nonsingular and pZ in (5) is computed from the equations
RT R pZ=-gZ, (12)
where gZ is the reduced gradient at x. In this case, x,s+p is the minimizer of the objective function subject to the working set constraints being treated as equalities. If x,s+p is feasible, α is defined to be unity. In this case, the reduced gradient at x-,s- will be zero, and Lagrange multipliers are computed at the next iteration. Otherwise, α is set to αN, the step to the ‘nearest’ constraint along p. This constraint is then added to the working set at the next iteration.
If HZ is singular, then R must also be singular, and an inertia-controlling strategy is used to ensure that only the last diagonal element of R is zero. (See Gill et al. (1991) for a discussion of a similar strategy for indefinite quadratic programming.) In this case, pZ satisfies
pZT HZpZ=0  and  gZT pZ≤0, (13)
which allows the objective function to be reduced by any step of the form x,s+αp, where α>0. The vector p=Z pZ is a direction of unbounded descent for the QP problem in the sense that the QP objective is linear and decreases without bound along p. If no finite step of the form x,s+αp (where α>0) reaches a constraint not in the working set, the QP problem is unbounded and the method terminates immediately with ifail=6. Otherwise, α is defined as the maximum feasible step along p and a constraint active at x,s+αp is added to the working set for the next iteration.
e04nq makes explicit allowance for infeasible constraints. Infeasible linear constraints are detected first by solving a problem of the form
minimize x,v,w eT v+w  subject to ​l≤xGx-v+w≤u,  v≥0,  w≥0, (14)
where eT=1,1,…,1. This is equivalent to minimizing the sum of the general linear constraint violations subject to the simple bounds. (In the linear programming literature, the approach is often called elastic programming.)

Miscellaneous

If the basis matrix is not chosen carefully, the condition of the null space matrix Z in (8) could be arbitrarily high. To guard against this, the method implements a ‘basis repair’ feature in which the LUSOL package (see Gill et al. (1991)) is used to compute the rectangular factorization
BS T=LU, (15)
returning just the permutation P that makes PL PT unit lower triangular. The pivot tolerance is set to require PL PT ij≤2, and the permutation is used to define P in (7). It can be shown that Z is likely to be little more than unity. Hence, Z should be well-conditioned regardless of the condition of W. This feature is applied at the beginning of the optimality phase if a potential B-S ordering is known.
The EXPAND procedure (see Gill et al. (1989)) is used to reduce the possibility of cycling at a point where the active constraints are nearly linearly dependent. Although there is no absolute guarantee that cycling will not occur, the probability of cycling is extremely small (see Hall and McKinnon (1996)). The main feature of EXPAND is that the feasibility tolerance is increased at the start of every iteration. This allows a positive step to be taken at every iteration, perhaps at the expense of violating the bounds on x,s by a small amount.
Suppose that the value of the optional parameter Feasibility Tolerance is δ. Over a period of K iterations (where K is the value of the optional parameter Expand Frequency), the feasibility tolerance actually used by the method (i.e., the working feasibility tolerance) increases from 0.5 δ to δ (in steps of 0.5 δ/K).
At certain stages the following ‘resetting procedure’ is used to remove small constraint infeasibilities. First, all nonbasic variables are moved exactly onto their bounds. A count is kept of the number of nontrivial adjustments made. If the count is nonzero, the basic variables are recomputed. Finally, the working feasibility tolerance is reinitialized to 0.5 δ.
If a problem requires more than K iterations, the resetting procedure is invoked and a new cycle of iterations is started. (The decision to resume the feasibility phase or optimality phase is based on comparing any constraint infeasibilities with δ.)
The resetting procedure is also invoked when the method reaches an apparently optimal, infeasible or unbounded solution, unless this situation has already occurred twice. If any nontrivial adjustments are made, iterations are continued.
The EXPAND procedure not only allows a positive step to be taken at every iteration, but also provides a potential choice of constraints to be added to the working set. All constraints at a distance α (where α≤αN) along p from the current point are then viewed as acceptable candidates for inclusion in the working set. The constraint whose normal makes the largest angle with the search direction is added to the working set. This strategy helps keep the basis matrix B well-conditioned.

Description of Monitoring Information

This section describes the intermediate printout and final printout which constitutes the monitoring information produced by e04nq. (See also the description of the optional parameters Print File and Print Level.) You can control the level of printed output.

Crash Statistics

When Print Level≥10, Print File>0 and System Information Yes has been specified, the following lines of intermediate printout (less than 120 characters) are produced on the unit number specified by optional parameter Print File whenever start="C" (see [Parameters]). They refer to the number of columns selected by the Crash procedure during each of several passes through A, whilst searching for a triangular basis matrix.
Label | Description
Slacks | is the number of slacks selected initially.
Free cols | is the number of free columns in the basis, including those whose bounds are rather far apart.
Preferred | is the number of ‘preferred’ columns in the basis (i.e., hs[j-1]=3 for some j≤n). It will be a subset of the columns for which hs[j-1]=3 was specified.
Unit | is the number of unit columns in the basis.
Double | is the number of double columns in the basis.
Triangle | is the number of triangular columns in the basis.
Pad | is the number of slacks used to pad the basis (to make it a nonsingular triangle).

Basis Factorization Statistics

When Print Level≥10 and Print File>0, the first seven items of intermediate printout in the list below are produced on the unit number specified by optional parameter Print File whenever the matrix B or BS=BS T is factorized. Gaussian elimination is used to compute an LU factorization of B or BS, where PL PT is a lower triangular matrix and PUQ is an upper triangular matrix for some permutation matrices P and Q. The factorization is stabilized in the manner described under the optional parameter LU Factor Tolerance. In addition, if System Information Yes has been specified, the entries from Elems onwards are also output.
Label | Description
Factor | the number of factorizations since the start of the run.
Demand a code giving the reason for the present factorization, as follows:
Code | Meaning
0 | First LU factorization.
1 | The number of updates reached the Factorization Frequency.
2 | The nonzeros in the updated factors have increased significantly.
7 | Not enough storage to update factors.
10 | Row residuals are too large (see the description of the optional parameter Check Frequency).
11 | Ill-conditioning has caused inconsistent results.
Itn | is the current minor iteration number.
Nonlin | is the number of nonlinear variables in the current basis B.
Linear | is the number of linear variables in B.
Slacks | is the number of slack variables in B.
B, BR, BS or BT factorize is the type of LU factorization.
B | periodic factorization of the basis B.
BR | more careful rank-revealing factorization of B using threshold rook pivoting. This occurs mainly at the start, if the first basis factors seem singular or ill-conditioned. Followed by a normal B factorize.
BS | BS is factorized to choose a well-conditioned B from the current B S. Followed by a normal B factorize.
BT | same as BS except the current B is tried first and accepted if it appears to be not much more ill-conditioned than after the previous BS factorize.
m | is the number of rows in B or BS.
n | is the number of columns in B or BS. Preceded by ‘=’ or ‘>’ respectively.
Elems | is the number of nonzero elements in B or BS.
Amax | is the largest nonzero in B or BS.
Density | is the percentage nonzero density of B or BS.
Merit/MerRP/MerCP | Merit is the average Markowitz merit count for the elements chosen to be the diagonals of PUQ. Each merit count is defined to be c-1r-1 where c and r are the number of nonzeros in the column and row containing the element at the time it is selected to be the next diagonal. Merit is the average of n such quantities. It gives an indication of how much work was required to preserve sparsity during the factorization. If LU Complete Pivoting or LU Rook Pivoting has been selected, this heading is changed to MerCP, respectively MerRP.
lenL | is the number of nonzeros in L.
L+U | is the number of nonzeros representing the basis factors L and U. Immediately after a basis factorization B=LU, this is lenL+lenU, the number of subdiagonal elements in the columns of a lower triangular matrix and the number of diagonal and superdiagonal elements in the rows of an upper-triangular matrix. Further nonzeros are added to L when various columns of B are later replaced. As columns of B are replaced, the matrix U is maintained explicitly (in sparse form). The value of L will steadily increase, whereas the value of U may fluctuate up or down. Thus the value of L+U may fluctuate up or down (in general, it will tend to increase).
Cmpressns | is the number of times the data structure holding the partially factored matrix needed to be compressed to recover unused storage. Ideally this number should be zero. If it is more than 3 or 4, the amount of workspace available to e04nq should be increased for efficiency.
Incres | is the percentage increase in the number of nonzeros in L and U relative to the number of nonzeros in B or BS.
Utri | is the number of triangular rows of B or BS at the top of U.
lenU | the number of nonzeros in U, including its diagonals.
Ltol | is the largest subdiagonal element allowed in L. This is the specified LU Factor Tolerance or a smaller value that is currently being used for greater stability.
Umax | the maximum nonzero element in U.
Ugrwth is the ratio Umax/Amax, which ideally should not be substantially larger than 10.0 or 100.0. If it is orders of magnitude larger, it may be advisable to reduce the LU Factor Tolerance to 5.0, 4.0, 3.0 or 2.0, say (but bigger than 1.0).
As long as Lmax is not large (say 5.0 or less), max Amax,Umax/DUmin gives an estimate of the condition number B. If this is extremely large, the basis is nearly singular. Slacks are used to replace suspect columns of B and the modified basis is refactored.
Ltri | is the number of triangular columns of B or BS at the left of L.
dense1 | is the number of columns remaining when the density of the basis matrix being factorized reached 0.3.
Lmax | is the actual maximum subdiagonal element in L (bounded by Ltol).
Akmax | is the largest nonzero generated at any stage of the LU factorization. (Values much larger than Amax indicate instability.) Akmax is not printed if LU Partial Pivoting is selected.
Agrwth | is the ratio Akmax/Amax. Values much larger than 100 (say) indicate instability. Agrwth is not printed if LU Partial Pivoting is selected.
bump | is the size of the block to be factorized nontrivially after the triangular rows and columns of B or BS have been removed.
dense2 | is the number of columns remaining when the density of the basis matrix being factorized reached 0.6. (The Markowitz pivot strategy searches fewer columns at that stage.)
DUmax | is the largest diagonal of PUQ.
DUmin | is the smallest diagonal of PUQ.
condU | the ratio DUmax/DUmin, which estimates the condition number of U (and of B if Ltol is less than 5.0, say).

Basis Map

When Print Level≥10 and Print File>0, the following lines of intermediate printout (less than 80 characters) are produced on the unit number specified by optional parameter Print File. They refer to the elements of the names array (see [Parameters]).
Label | Description
Name | gives the name for the problem (blank if problem unnamed).
Infeasibilities | gives the number of infeasibilities. Printed only if the final point is infeasible.
Objective Value | gives the objective value at the final point (or the value of the sum of infeasibilities). Printed only if the final point is feasible.
Status | gives the exit status for the problem (i.e., Optimal soln, Weak soln, Unbounded, Infeasible, Excess itns, Error condn or Feasble soln) followed by details of the direction of the optimization (i.e., (Min) or (Max)).
Iteration | gives the iteration number when the file was created.
Superbasics | gives the number of superbasic variables.
Objective | gives the name of the free row for the problem (blank if objective unnamed).
RHS | gives the name of the constraint right-hand side for the problem (blank if objective unnamed).
Ranges | gives the name of the ranges for the problem (blank if objective unnamed).
Bounds | gives the name of the bounds for the problem (blank if objective unnamed).

Solution Output

At the end of a run, the final solution will be output to the Print file. Some header information appears first to identify the problem and the final state of the optimization procedure. A ROWS section and a COLUMNS section then follow, giving one line of information for each row and column.

The ROWS section

General constraints take the form l≤Ax≤u. The ith constraint is therefore of the form
α≤νi x≤β,
where νi is the ith row of A.
Internally, the constraints take the form Ax-s=0, where s is the set of slack variables (which happen to satisfy the bounds l≤s≤u). For the ith constraint, the slack variable si is directly available, and it is sometimes convenient to refer to its state. It should satisfy α≤si≤β. A fullstop (.) is printed for any numerical value that is exactly zero.
Label | Description
Number | is the value of n+i. (This is used internally to refer to si in the intermediate output.)
Row | gives the name of νi.
State the state of νi (the state of si relative to the bounds α and β). The various states possible are as follows:
LL | si is nonbasic at its lower limit, α.
UL | si is nonbasic at its upper limit, β.
EQ | si is nonbasic and fixed at the value α=β.
FR | si is nonbasic and currently zero, even though it is free to take any value between its bounds α and β.
BS | si is basic.
SBS | si is superbasic.
A key is sometimes printed before State. Note that unless the optional parameter Scale Option=0 is specified, the tests for assigning a key are applied to the variables of the scaled problem.
A | Alternative optimum possible. The variable is nonbasic, but its reduced gradient is essentially zero. This means that if the variable were allowed to start moving away from its bound, there would be no change in the value of the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case, the values of the Lagrange multipliers might also change.
D | Degenerate. The variable is basic or superbasic, but it is equal (or very close) to one of its bounds.
I | Infeasible. The variable is basic or superbasic and is currently violating one of its bounds by more than the value of the Feasibility Tolerance.
N | Not precisely optimal. If the slack is superbasic, the dual variable πi is not sufficiently small, as measured by the Optimality Tolerance. If the slack is nonbasic, πi is not sufficiently positive or negative. If a loose Optimality Tolerance has been used, or if iterations were terminated before optimality, this key might be helpful in deciding whether or not to restart the run.
Activity | is the value of νi x at the final iterate.
Slack Activity | is the value by which the row differs from its nearest bound. (For the free row (if any), it is set to Activity.)
Lower Limit | is α, the lower bound specified for the variable si. None indicates that bl[j-1]≤-infbnd.
Upper Limit | is β, the upper bound specified for the variable si. None indicates that bu[j-1]≥infbnd.
Dual Activity | is the value of the dual variable πi (the Lagrange multiplier for νi; see [Main Iteration]). For FP problems, πi is set to zero.
i | gives the index i of the ith row.

The COLUMNS Section

Let the jth component of x be the variable xj and assume that it satisfies the bounds α≤xj≤β. A fullstop (.) is printed for any numerical value that is exactly zero.
Label | Description
Number | is the column number j. (This is used internally to refer to xj in the intermediate output.)
Column | gives the name of xj.
State the state of xj relative to the bounds α and β. The various states possible are as follows:
LL | xj is nonbasic at its lower limit, α.
UL | xj is nonbasic at its upper limit, β.
EQ | xj is nonbasic and fixed at the value α=β.
FR | xj is nonbasic and currently zero, even though it is free to take any value between its bounds α and β.
BS | xj is basic.
SBS | xj is superbasic.
A key is sometimes printed before State. Note that unless the optional parameter Scale Option=0 is specified, the tests for assigning a key are applied to the variables of the scaled problem.
A | Alternative optimum possible. The variable is nonbasic, but its reduced gradient is essentially zero. This means that if the variable were allowed to start moving away from its bound, there would be no change in the value of the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case, the values of the Lagrange multipliers might also change.
D | Degenerate. The variable is basic or superbasic, but it is equal (or very close) to one of its bounds.
I | Infeasible. The variable is basic or superbasic and is currently violating one of its bounds by more than the value of the Feasibility Tolerance.
N | Not precisely optimal. If the slack is superbasic, the dual variable πi is not sufficiently small, as measured by the Optimality Tolerance. If the slack is nonbasic, πi is not sufficiently positive or negative. If a loose Optimality Tolerance has been used, or if iterations were terminated before optimality, this key might be helpful in deciding whether or not to restart the run.
Activity | is the value of xj at the final iterate.
Obj Gradient | is the value of gj at the final iterate. For FP problems, gj is set to zero.
Lower Limit | is the lower bound specified for the variable. None indicates that bl[j-1]≤-infbnd.
Upper Limit | is the upper bound specified for the variable. None indicates that bu[j-1]≥infbnd.
Reduced Gradnt | is the value of dj at the final iterate (see [Main Iteration]). For FP problems, dj is set to zero.
m + j | is the value of m+j.
Note: if two problems are the same except that one minimizes f x and the other maximizes -f x, their solutions will be the same but the signs of the dual variables πi and the reduced gradients dj will be reversed.

The Solution File

If a positive Solution File is specified, the information contained in a printed solution may also be output to the relevant file (which may be the Print file if so desired). Infinite Upper and Lower limits appear as ±1020 rather than None. Other real values are output with format 1pe16.6. The maximum line length is 111 characters, including what would be the carriage-control character if the file were printed.
A Solution file is intended to be read from disk by a self-contained program that extracts and saves certain values as required for possible further computation. Typically the first 14 lines would be ignored. Each subsequent line may be read using adapted to suit the occasion. The end of the ROWS section is marked by a line that starts with a 1 and is otherwise blank. If this and the next 4 lines are skipped, the COLUMNS section (see [The COLUMNS Section]) can then be read under the same format. (There should be no need to use any BACKSPACE statements.)

The Summary File

If Summary File f is specified with f>0, certain brief information will be output to unit f. When e04nq is run interactively, unit f will usually be the terminal. For batch jobs a disk file should be used, to retain a concise log of each run if desired. (A Summary File is more easily perused than the associated Print file).
A Summary file (like the Print file) is not rewound after a problem has been processed. The maximum line length is 72 characters, including a carriage-control character in column 1.
The following information is included:
1. | The optional parameters supplied via the option setting methods, if any;
2. | The Basis file loaded, if any;
3. | The status of the solution after each basis factorization (whether feasible; the objective value; the number of function calls so far);
4. | The same information every kth iteration, where k is the specified Summary Frequency;
5. | Warnings and error messages;
6. | The exit condition and a summary of the final solution.
Item 4. is preceded by a blank line, but item 5. is not.
The meaning of the printout for linear constraints is the same as that given above for variables, with ‘variable’ replaced by ‘constraint’, n replaced by m, names[j-1] replaced by names[n+j-1], bl[j-1] and bu[j-1] are replaced by bl[n+j-1] and bu[n+j-1] respectively, and with the following change in the heading:
Constrnt gives the name of the linear constraint.
Note that movement off a constraint (as opposed to a variable moving away from its bound) can be interpreted as allowing the entry in the Residual column to become positive.
Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.

See Also

E04 Class
E04 Members


e04nsh Method

[image]

NAG Library for .NET Release 2
E04..::e04nsh Method
E04 Class See Also Send Feedback
Auxiliary for use as a delegate parameter

Syntax

C#
public static void e04nsh(
    int ncolh,
    double[] x,
    double[] hx,
    int nstate
)
Visual Basic
Public Shared Sub e04nsh ( _
    ncolh As Integer, _
    x As Double(), _
    hx As Double(), _
    nstate As Integer _
)
Visual C++
public:
static void e04nsh(
    int ncolh,
    array<double>^ x,
    array<double>^ hx,
    int nstate
)
F#
static member e04nsh :
        ncolh : int *
        x : float[] *
        hx : float[] *
        nstate : int -> unit

Parameters

ncolh
Type: System..::..Int32
On entry: this is the same parameter _ncolh as supplied to e04ns.
x
Type: array< System..::..Double >[]()[][]
An array of size [ncolh]
On entry: an initial estimate of the solution.
On exit: the point at which e04ns terminated. If ifail=0, 1 or 4, x contains an estimate of the solution.
hx
Type: array< System..::..Double >[]()[][]
An array of size [ncolh]
On exit: the product Hx. If ncolh is less than the input parameter _n, Hx is really the product H 1 y in eqnqphx.
nstate
Type: System..::..Int32
On entry: allows you to save computation time if certain data must be read or calculated only once. To preserve this data for a subsequent calculation place it in one of cuser, ruser or iuser .
nstate=1
e04ns is calling _qphx for the first time.
nstate=0
There is nothing special about the current call of _qphx.
nstate≥2
e04ns is calling _qphx for the last time. This parameter setting allows you to perform some additional computation on the final solution.
nstate=2
The current x is optimal.
nstate=3
The problem appears to be infeasible.
nstate=4
The problem appears to be unbounded.
nstate=5
The iterations limit was reached.

Description

Auxiliary for use as a delegate parameter

References

None.

Error Indicators and Warnings

None.

Accuracy

Not applicable.

Further Comments

None.

Example

None.

See Also

E04 Class
E04 Members


e04pc Method

[image]

NAG Library for .NET Release 2
E04..::e04pc Method
E04 Class See Also Send Feedback
e04pc solves a linear least squares problem subject to fixed lower and upper bounds on the variables.

Syntax

C#
public static void e04pc(
    int itype,
    int m,
    int n,
    double[,] a,
    double[] b,
    double[] bl,
    double[] bu,
    double tol,
    double[] x,
    out double rnorm,
    out int nfree,
    double[] w,
    int[] indx,
    out int ifail
)
Visual Basic
Public Shared Sub e04pc ( _
    itype As Integer, _
    m As Integer, _
    n As Integer, _
    a As Double(,), _
    b As Double(), _
    bl As Double(), _
    bu As Double(), _
    tol As Double, _
    x As Double(), _
    <OutAttribute> ByRef rnorm As Double, _
    <OutAttribute> ByRef nfree As Integer, _
    w As Double(), _
    indx As Integer(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04pc(
    int itype,
    int m,
    int n,
    array<double,2>^ a,
    array<double>^ b,
    array<double>^ bl,
    array<double>^ bu,
    double tol,
    array<double>^ x,
    [OutAttribute] double% rnorm,
    [OutAttribute] int% nfree,
    array<double>^ w,
    array<int>^ indx,
    [OutAttribute] int% ifail
)
F#
static member e04pc :
        itype : int *
        m : int *
        n : int *
        a : float[,] *
        b : float[] *
        bl : float[] *
        bu : float[] *
        tol : float *
        x : float[] *
        rnorm : float byref *
        nfree : int byref *
        w : float[] *
        indx : int[] *
        ifail : int byref -> unit

Parameters

itype
Type: System..::..Int32
On entry: provides the choice of returning a regularized solution if the matrix is not of full rank.
itype=0
Specifies that a regularized solution is to be computed.
itype=1
Specifies that no regularization is to take place.
Suggested value: unless there is a definite need for a minimal length solution we recommend that itype=1 is used.
Constraint: itype=0 or 1.
m
Type: System..::..Int32
On entry: m, the number of linear equations.
Constraint: m≥0.
n
Type: System..::..Int32
On entry: n, the number of variables.
Constraint: n≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥m
Note: the second dimension of the array a must be at least n.
On entry: the m by n matrix A.
On exit: if itype=1, a contains the product matrix Q⁢A, where Q is an m by m orthogonal matrix generated by e04pc; otherwise a is unchanged.
b
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: the right-hand side vector b.
On exit: if itype=1, the product of Q times the original vector b, where Q is as described in parameter a; otherwise b is unchanged.
bl
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: bl[i-1] and bu[i-1] must specify the lower and upper bounds, li and ui respectively, to be imposed on the solution vector xi.
Constraint: bl[i-1]≤bu[i-1], for i=1,2,…,n.
bu
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: bl[i-1] and bu[i-1] must specify the lower and upper bounds, li and ui respectively, to be imposed on the solution vector xi.
Constraint: bl[i-1]≤bu[i-1], for i=1,2,…,n.
tol
Type: System..::..Double
On entry: tol specifies a parameter used to determine the relative linear dependence of a column vector for a variable moved from its initial value. It determines the computational rank of the matrix. Increasing its value from machine precision will increase the likelihood of additional elements of x being set to zero. It may be worth experimenting with increasing values of tol to determine whether the nature of the solution, x, changes significantly. In practice a value of machine precision is recommended (see x02aj).
If on entry tol<machine precision, then machine precision is used.
Suggested value: tol=0.0
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the solution vector x.
rnorm
Type: System..::..Double %
On exit: the Euclidean norm of the residual vector b-Ax.
nfree
Type: System..::..Int32 %
On exit: indicates the number of components of the solution vector that are not at one of the constraints.
w
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: contains the dual solution vector. The magnitude of w[i-1] gives a measure of the improvement in the objective value if the corresponding bound were to be relaxed so that xi could take different values.
A value of w[i-1] equal to the special value -999.0 is indicative of the matrix A not having full rank. It is only likely to occur when itype=1. However a matrix may have less than full rank without w[i-1] being set to -999.0. If itype=1 then the values contained in w (other than those set to -999.0) may be unreliable; the corresponding values in indx may likewise be unreliable. If you have any doubts set itype=0. Otherwise the values of w[i-1] have the following meaning:
w[i-1]=0
if xi is unconstrained.
w[i-1]<0
if xi is constrained by its lower bound.
w[i-1]>0
if xi is constrained by its upper bound.
w[i-1]
may be any value if li=ui.
indx
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On exit: the contents of this array describe the components of the solution vector as follows:
indx[i-1], for i=1,2,…,nfree
These elements of the solution have not hit a constraint; i.e., w[i-1]=0.
indx[i-1], for i=nfree+1,…,k
These elements of the solution have been constrained by either the lower or upper bound.
indx[i-1], for i=k+1,…,n
These elements of the solution are fixed by the bounds; i.e., bl[i-1]=bu[i-1].
Here k is determined from nfree and the number of fixed components. (Often the latter will be 0, so k will be n-nfree.)
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Given an m by n matrix A, an n-vector l of lower bounds, an n-vector u of upper bounds, and an m-vector b, e04pc computes an n-vector x that solves the least squares problem Ax=b subject to xi satisfying li≤xi≤ui.
A facility is provided to return a ‘regularized’ solution, which will closely approximate a minimal length solution whenever A is not of full rank. A minimal length solution is the solution to the problem which has the smallest Euclidean norm.
The algorithm works by applying orthogonal transformations to the matrix and to the right hand side to obtain within the matrix an upper triangular matrix R. In general the elements of x corresponding to the columns of R will be the candidate non-zero solutions. If a diagonal element of R is small compared to the other members of R then this is undesirable. R will be nearly singular and the equations for x thus ill-conditioned. You may specify the tolerance used to determine the relative linear dependence of a column vector for a variable moved from its initial value.

References

Lawson C L and Hanson R J (1974) Solving Least Squares Problems Prentice–Hall

Error Indicators and Warnings

Note: e04pc may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
One of the following input errors has occurred:
  • lda<m,
  • m<0,
  • n<0,
  • li>ui for at least one value of i.
ifail=2
The routine failed to converge in 3 n iterations. This is not expected. Please contact NAG.
ifail=-9000
An error occured, see message report.
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Orthogonal rotations are used.

Parallelism and Performance

None.

Further Comments

If either m or n is zero on entry then e04pc sets ifail=0 and simply returns without setting any other output parameters.

Example

The example minimizes Ax-b 2 where
A=0.050.050.25-0.250.250.250.05-0.050.350.351.75-1.751.751.750.35-0.350.30-0.300.300.300.40-0.400.400.40
and
b=1.02.03.04.05.06.0 T
subject to 1≤x≤5.

Example program (C#): e04pce.cs

Example program data: e04pce.d

Example program results: e04pce.r

See Also

E04 Class
E04 Members


e04uc Method

[image]

NAG Library for .NET Release 2
E04..::e04uc Method
E04 Class See Also Send Feedback
e04uc is designed to minimize an arbitrary smooth function subject to constraints (which may include simple bounds on the variables, linear constraints and smooth nonlinear constraints) using a sequential quadratic programming (SQP) method. As many first derivatives as possible should be supplied by you; any unspecified derivatives are approximated by finite differences. It is not intended for large sparse problems.
e04uc may also be used for unconstrained, bound-constrained and linearly constrained optimization.
e04uc uses forward communication for evaluating the objective function, the nonlinear constraint functions, and any of their derivatives.

Syntax

C#
public static void e04uc(
    int n,
    int nclin,
    int ncnln,
    double[,] a,
    double[] bl,
    double[] bu,
    E04..::..E04UC_CONFUN confun,
    E04..::..E04UC_OBJFUN objfun,
    out int iter,
    int[] istate,
    double[] c,
    double[,] cjac,
    double[] clamda,
    out double objf,
    double[] objgrd,
    double[,] r,
    double[] x,
    E04..::..e04ucOptions options,
    out int ifail
)
Visual Basic
Public Shared Sub e04uc ( _
    n As Integer, _
    nclin As Integer, _
    ncnln As Integer, _
    a As Double(,), _
    bl As Double(), _
    bu As Double(), _
    confun As E04..::..E04UC_CONFUN, _
    objfun As E04..::..E04UC_OBJFUN, _
    <OutAttribute> ByRef iter As Integer, _
    istate As Integer(), _
    c As Double(), _
    cjac As Double(,), _
    clamda As Double(), _
    <OutAttribute> ByRef objf As Double, _
    objgrd As Double(), _
    r As Double(,), _
    x As Double(), _
    options As E04..::..e04ucOptions, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04uc(
    int n,
    int nclin,
    int ncnln,
    array<double,2>^ a,
    array<double>^ bl,
    array<double>^ bu,
    E04..::..E04UC_CONFUN^ confun,
    E04..::..E04UC_OBJFUN^ objfun,
    [OutAttribute] int% iter,
    array<int>^ istate,
    array<double>^ c,
    array<double,2>^ cjac,
    array<double>^ clamda,
    [OutAttribute] double% objf,
    array<double>^ objgrd,
    array<double,2>^ r,
    array<double>^ x,
    E04..::..e04ucOptions^ options,
    [OutAttribute] int% ifail
)
F#
static member e04uc :
        n : int *
        nclin : int *
        ncnln : int *
        a : float[,] *
        bl : float[] *
        bu : float[] *
        confun : E04..::..E04UC_CONFUN *
        objfun : E04..::..E04UC_OBJFUN *
        iter : int byref *
        istate : int[] *
        c : float[] *
        cjac : float[,] *
        clamda : float[] *
        objf : float byref *
        objgrd : float[] *
        r : float[,] *
        x : float[] *
        options : E04..::..e04ucOptions *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of variables.
Constraint: n>0.
nclin
Type: System..::..Int32
On entry: nL, the number of general linear constraints.
Constraint: nclin≥0.
ncnln
Type: System..::..Int32
On entry: nN, the number of nonlinear constraints.
Constraint: ncnln≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,nclin
Note: the second dimension of the array a must be at least n if nclin>0, and at least 1 otherwise.
On entry: the ith row of a contains the ith row of the matrix AL of general linear constraints in (1). That is, the ith row contains the coefficients of the ith general linear constraint, for i=1,2,…,nclin.
If nclin=0, the array a is not referenced.
bl
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin+ncnln]
On entry: bl must contain the lower bounds and bu the upper bounds for all the constraints in the following order. The first n elements of each array must contain the bounds on the variables, the next nL elements the bounds for the general linear constraints (if any) and the next nN elements the bounds for the general nonlinear constraints (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j-1]≤-bigbnd, and to specify a nonexistent upper bound (i.e., uj=+∞), set bu[j-1]≥bigbnd; the default value of bigbnd is 1020, but this may be changed by the optional parameter Infinite Bound Size. To specify the jth constraint as an equality, set bl[j-1]=bu[j-1]=β, say, where β<bigbnd.
Constraints:
  • bl[j-1]≤bu[j-1], for j=1,2,…,n+nclin+ncnln;
  • if bl[j-1]=bu[j-1]=β, β<bigbnd.
bu
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin+ncnln]
On entry: bl must contain the lower bounds and bu the upper bounds for all the constraints in the following order. The first n elements of each array must contain the bounds on the variables, the next nL elements the bounds for the general linear constraints (if any) and the next nN elements the bounds for the general nonlinear constraints (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j-1]≤-bigbnd, and to specify a nonexistent upper bound (i.e., uj=+∞), set bu[j-1]≥bigbnd; the default value of bigbnd is 1020, but this may be changed by the optional parameter Infinite Bound Size. To specify the jth constraint as an equality, set bl[j-1]=bu[j-1]=β, say, where β<bigbnd.
Constraints:
  • bl[j-1]≤bu[j-1], for j=1,2,…,n+nclin+ncnln;
  • if bl[j-1]=bu[j-1]=β, β<bigbnd.
confun
Type: NagLibrary..::..E04..::..E04UC_CONFUN
confun must calculate the vector c x of nonlinear constraint functions and (optionally) its Jacobian (=∂c∂x) for a specified n-element vector x. If there are no nonlinear constraints (i.e., ncnln=0), confun will never be called by e04uc and confun may be the dummy method E04UDM. (E04UDM is included in the NAG Library.) If there are nonlinear constraints, the first call to confun will occur before the first call to objfun.

A delegate of type E04UC_CONFUN.

confun should be tested separately before being used in conjunction with e04uc. See also the description of the optional parameter Verify.
objfun
Type: NagLibrary..::..E04..::..E04UC_OBJFUN
objfun must calculate the objective function F x and (optionally) its gradient g x=∂F∂x for a specified n-vector x.

A delegate of type E04UC_OBJFUN.

objfun should be tested separately before being used in conjunction with e04uc. See also the description of the optional parameter Verify.
iter
Type: System..::..Int32 %
On exit: the number of major iterations performed.
istate
Type: array< System..::..Int32 >[]()[][]
An array of size [n+nclin+ncnln]
On entry: need not be set if the (default) optional parameter Cold Start is used.
If the optional parameter Warm Start has been chosen, the elements of istate corresponding to the bounds and linear constraints define the initial working set for the procedure that finds a feasible point for the linear constraints and bounds. The active set at the conclusion of this procedure and the elements of istate corresponding to nonlinear constraints then define the initial working set for the first QP subproblem. More precisely, the first n elements of istate refer to the upper and lower bounds on the variables, the next nL elements refer to the upper and lower bounds on AL x, and the next nN elements refer to the upper and lower bounds on c x. Possible values for istate[j-1] are as follows:
istate[j-1] | Meaning
0 | The corresponding constraint is not in the initial QP working set.
1 | This inequality constraint should be in the working set at its lower bound.
2 | This inequality constraint should be in the working set at its upper bound.
3 | This equality constraint should be in the initial working set. This value must not be specified unless bl[j-1]=bu[j-1].
The values -2, -1 and 4 are also acceptable but will be modified by the method. If e04uc has been called previously with the same values of n, nclin and ncnln, istate already contains satisfactory information. The method also adjusts (if necessary) the values supplied in x to be consistent with istate.
Constraint: -2≤istate[j-1]≤4, for j=1,2,…,n+nclin+ncnln.
On exit: the status of the constraints in the QP working set at the point returned in x. The significance of each possible value of istate[j-1] is as follows:
istate[j-1] | Meaning
-2 | This constraint violates its lower bound by more than the appropriate feasibility tolerance (see the optional parameters Linear Feasibility Tolerance and Nonlinear Feasibility Tolerance). This value can occur only when no feasible point can be found for a QP subproblem.
-1 | This constraint violates its upper bound by more than the appropriate feasibility tolerance (see the optional parameters Linear Feasibility Tolerance and Nonlinear Feasibility Tolerance). This value can occur only when no feasible point can be found for a QP subproblem.
-0 | The constraint is satisfied to within the feasibility tolerance, but is not in the QP working set.
-1 | This inequality constraint is included in the QP working set at its lower bound.
-2 | This inequality constraint is included in the QP working set at its upper bound.
-3 | This constraint is included in the QP working set as an equality. This value of istate can occur only when bl[j-1]=bu[j-1].
c
Type: array< System..::..Double >[]()[][]
An array of size [max 1,ncnln]
On exit: if ncnln>0, c[i-1] contains the value of the ith nonlinear constraint function ci at the final iterate, for i=1,2,…,ncnln.
If ncnln=0, the array c is not referenced.
cjac
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,ncnln
Note: the second dimension of the array cjac must be at least n if ncnln>0, and at least 1 otherwise.
On entry: in general, cjac need not be initialized before the call to e04uc. However, if Derivative Level=2 or 3, you may optionally set the constant elements of cjac (see parameter nstate in the description of confun). Such constant elements need not be re-assigned on subsequent calls to confun.
On exit: if ncnln>0, cjac contains the Jacobian matrix of the nonlinear constraint functions at the final iterate, i.e., cjac[i-1,j-1] contains the partial derivative of the ith constraint function with respect to the jth variable, for i=1,2,…,ncnln and j=1,2,…,n. (See the discussion of parameter cjac under confun.)
If ncnln=0, the array cjac is not referenced.
clamda
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin+ncnln]
On entry: need not be set if the (default) optional parameter Cold Start is used.
If the optional parameter Warm Start has been chosen, clamda[j-1] must contain a multiplier estimate for each nonlinear constraint with a sign that matches the status of the constraint specified by the istate array, for j=n+nclin+1,…,n+nclin+ncnln. The remaining elements need not be set. Note that if the jth constraint is defined as ‘inactive’ by the initial value of istate array (i.e., istate[j-1]=0), clamda[j-1] should be zero; if the jth constraint is an inequality active at its lower bound (i.e., istate[j-1]=1), clamda[j-1] should be non-negative; if the jth constraint is an inequality active at its upper bound (i.e., istate[j-1]=2), clamda[j-1] should be non-positive. If necessary, the method will modify clamda to match these rules.
On exit: the values of the QP multipliers from the last QP subproblem. clamda[j-1] should be non-negative if istate[j-1]=1 and non-positive if istate[j-1]=2.
objf
Type: System..::..Double %
On exit: the value of the objective function at the final iterate.
objgrd
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the gradient of the objective function at the final iterate (or its finite difference approximation).
r
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: need not be initialized if the (default) optional parameter Cold Start is used.
If the optional parameter Warm Start has been chosen, r must contain the upper triangular Cholesky factor R of the initial approximation of the Hessian of the Lagrangian function, with the variables in the natural order. Elements not in the upper triangular part of r are assumed to be zero and need not be assigned.
On exit: if Hessian=NO, r contains the upper triangular Cholesky factor R of QT H~Q, an estimate of the transformed and reordered Hessian of the Lagrangian at x (see (6) in [Overview]). If Hessian=YES, r contains the upper triangular Cholesky factor R of H, the approximate (untransformed) Hessian of the Lagrangian, with the variables in the natural order.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: an initial estimate of the solution.
On exit: the final estimate of the solution.
options
Type: NagLibrary..::..E04..::..e04ucOptions
An Object of type E04.e04ucOptions. Used to configure optional parameters to this method.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04uc is designed to solve the nonlinear programming problem – the minimization of a smooth nonlinear function subject to a set of constraints on the variables. The problem is assumed to be stated in the following form:
minimize x∈Rn F x  subject to  l≤xAL xc x≤u, (1)
where F x (the objective function) is a nonlinear function, AL is an nL by n constant matrix, and c x is an nN element vector of nonlinear constraint functions. (The matrix AL and the vector c x may be empty.) The objective function and the constraint functions are assumed to be smooth, i.e., at least twice-continuously differentiable. (The method of e04uc will usually solve (1) if there are only isolated discontinuities away from the solution.)
Note that although the bounds on the variables could be included in the definition of the linear constraints, we prefer to distinguish between them for reasons of computational efficiency. For the same reason, the linear constraints should not be included in the definition of the nonlinear constraints. Upper and lower bounds are specified for all the variables and for all the constraints. An equality constraint can be specified by setting li=ui. If certain bounds are not present, the associated elements of l or u can be set to special values that will be treated as -∞ or +∞. (See the description of the optional parameter Infinite Bound Size.)
If there are no nonlinear constraints in (1) and F is linear or quadratic, then it will generally be more efficient to use one of e04mf, e04nc or e04nf, or e04nk if the problem is large and sparse. If the problem is large and sparse and does have nonlinear constraints, then e04ug should be used, since e04uc treats all matrices as dense.
You must supply an initial estimate of the solution to (1), together with methods that define F x, c x and as many first partial derivatives as possible; unspecified derivatives are approximated by finite differences.
The objective function is defined by objfun, and the nonlinear constraints are defined by confun. On every call, these methods must return appropriate values of the objective and nonlinear constraints. You should also provide the available partial derivatives. Any unspecified derivatives are approximated by finite differences; see [Description of the Optional Parameters] for a discussion of the optional parameter Derivative Level. Note that if there are any nonlinear constraints then the first call to confun will precede the first call to objfun.
For maximum reliability, it is preferable for you to provide all partial derivatives (see Chapter 8 of Gill et al. (1981), for a detailed discussion). If all gradients cannot be provided, it is similarly advisable to provide as many as possible. While developing objfun and confun, the optional parameter Verify should be used to check the calculation of any known gradients.
The method used by e04uc is described in detail in [Algorithmic Details].
e04uf is an alternative method which uses exactly the same method, but uses reverse communication for evaluating the objective and constraint functions.

References

Dennis J E Jr and Moré J J (1977) Quasi-Newton methods, motivation and theory SIAM Rev. 19 46–89
Dennis J E Jr and Schnabel R B (1981) A new derivation of symmetric positive-definite secant updates nonlinear programming (eds O L Mangasarian, R R Meyer and S M Robinson) 4 167–199 Academic Press
Dennis J E Jr and Schnabel R B (1983) Numerical Methods for Unconstrained Optimization and Nonlinear Equations Prentice–Hall
Fletcher R (1987) Practical Methods of Optimization (2nd Edition) Wiley
Gill P E, Hammarling S, Murray W, Saunders M A and Wright M H (1986) Users' guide for LSSOL (Version 1.0) Report SOL 86-1 Department of Operations Research, Stanford University
Gill P E, Murray W, Saunders M A and Wright M H (1984a) Procedures for optimization problems with a mixture of bounds and general linear constraints ACM Trans. Math. Software 10 282–298
Gill P E, Murray W, Saunders M A and Wright M H (1984b) Users' guide for SOL/QPSOL version 3.2 Report SOL 84–5 Department of Operations Research, Stanford University
Gill P E, Murray W, Saunders M A and Wright M H (1986a) Some theoretical properties of an augmented Lagrangian merit function Report SOL 86–6R Department of Operations Research, Stanford University
Gill P E, Murray W, Saunders M A and Wright M H (1986b) Users' guide for NPSOL (Version 4.0): a Fortran package for nonlinear programming Report SOL 86-2 Department of Operations Research, Stanford University
Gill P E, Murray W and Wright M H (1981) Practical Optimization Academic Press
Hock W and Schittkowski K (1981) Test Examples for Nonlinear Programming Codes. Lecture Notes in Economics and Mathematical Systems 187 Springer–Verlag
Powell M J D (1974) Introduction to constrained optimization Numerical Methods for Constrained Optimization (eds P E Gill and W Murray) 1–28 Academic Press
Powell M J D (1983) Variable metric methods in constrained optimization Mathematical Programming: the State of the Art (eds A Bachem, M Grötschel and B Korte) 288–311 Springer–Verlag

Error Indicators and Warnings

Note: e04uc may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA, LDCJ, LDR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail<0
A negative value of ifail indicates an exit from e04uc because you set mode<0 in objfun or confun. The value of ifail will be the same as your setting of mode.
ifail=1
The final iterate x satisfies the first-order Kuhn–Tucker conditions (see [Overview]) to the accuracy requested, but the sequence of iterates has not yet converged. e04uc was terminated because no further improvement could be made in the merit function (see [Description of the Printed Output]).
This value of ifail may occur in several circumstances. The most common situation is that you ask for a solution with accuracy that is not attainable with the given precision of the problem (as specified by the optional parameter Function Precision (default value=ε 0.9, where ε is the machine precision)). This condition will also occur if, by chance, an iterate is an ‘exact’ Kuhn–Tucker point, but the change in the variables was significant at the previous iteration. (This situation often happens when minimizing very simple functions, such as quadratics.)
If the four conditions listed in [Parameters] for ifail=0 are satisfied, x is likely to be a solution of (1) even if ifail=1.
ifail=2
e04uc has terminated without finding a feasible point for the linear constraints and bounds, which means that either no feasible point exists for the given value of the optional parameter Linear Feasibility Tolerance (default value=ε, where ε is the machine precision), or no feasible point could be found in the number of iterations specified by the optional parameter Minor Iteration Limit (default value=max 50,3 n+nL+nN). You should check that there are no constraint redundancies. If the data for the constraints are accurate only to an absolute precision σ, you should ensure that the value of the optional parameter Linear Feasibility Tolerance is greater than σ. For example, if all elements of AL are of order unity and are accurate to only three decimal places, Linear Feasibility Tolerance should be at least 10-3.
ifail=3
No feasible point could be found for the nonlinear constraints. The problem may have no feasible solution. This means that there has been a sequence of QP subproblems for which no feasible point could be found (indicated by I at the end of each line of intermediate printout produced by the major iterations; see [Description of the Printed Output]). This behaviour will occur if there is no feasible point for the nonlinear constraints. (However, there is no general test that can determine whether a feasible point exists for a set of nonlinear constraints.) If the infeasible subproblems occur from the very first major iteration, it is highly likely that no feasible point exists. If infeasibilities occur when earlier subproblems have been feasible, small constraint inconsistencies may be present. You should check the validity of constraints with negative values of istate. If you are convinced that a feasible point does exist, e04uc should be restarted at a different starting point.
ifail=4
The limiting number of iterations (as determined by the optional parameter Major Iteration Limit (default value=max 50,3 n+nL+10 nN)) has been reached.
If the algorithm appears to be making satisfactory progress, then Major Iteration Limit may be too small. If so, either increase its value and rerun e04uc or, alternatively, rerun e04uc using the optional parameter Warm Start. If the algorithm seems to be making little or no progress however, then you should check for incorrect gradients or ill-conditioning as described under ifail=6.
Note that ill-conditioning in the working set is sometimes resolved automatically by the algorithm, in which case performing additional iterations may be helpful. However, ill-conditioning in the Hessian approximation tends to persist once it has begun, so that allowing additional iterations without altering R is usually inadvisable. If the quasi-Newton update of the Hessian approximation was reset during the latter major iterations (i.e., an R occurs at the end of each line of intermediate printout; see [Description of the Printed Output]), it may be worthwhile to try a Warm Start at the final point as suggested above.
ifail=5
Not used by this method.
ifail=6
x does not satisfy the first-order Kuhn–Tucker conditions (see [Overview]) and no improved point for the merit function (see [Description of the Printed Output]) could be found during the final linesearch.
This sometimes occurs because an overly stringent accuracy has been requested, i.e., the value of the optional parameter Optimality Tolerance (default value=εR 0.8, where εr is the value of the optional parameter Function Precision (default value=ε 0.9, where ε is the machine precision)) is too small. In this case you should apply the four tests outlined in the description of the parameter ifail to determine whether or not the final solution is acceptable (see Gill et al. (1981), for a discussion of the attainable accuracy).
If many iterations have occurred in which essentially no progress has been made and e04uc has failed completely to move from the initial point then user-supplied delegates objfun and/or confun may be incorrect. You should refer to comments under ifail=7 and check the gradients using the optional parameter Verify (default value=0). Unfortunately, there may be small errors in the objective and constraint gradients that cannot be detected by the verification process. Finite difference approximations to first derivatives are catastrophically affected by even small inaccuracies. An indication of this situation is a dramatic alteration in the iterates if the finite difference interval is altered. One might also suspect this type of error if a switch is made to central differences even when Norm Gz and Violtn (see [Description of the Printed Output]) are large.
Another possibility is that the search direction has become inaccurate because of ill-conditioning in the Hessian approximation or the matrix of constraints in the working set; either form of ill-conditioning tends to be reflected in large values of Mnr (the number of iterations required to solve each QP subproblem; see [Description of the Printed Output]).
If the condition estimate of the projected Hessian (Cond Hz; see [Description of the Printed Output]) is extremely large, it may be worthwhile rerunning e04uc from the final point with the optional parameter Warm Start. In this situation, istate and clamda should be left unaltered and R should be reset to the identity matrix.
If the matrix of constraints in the working set is ill-conditioned (i.e., Cond T is extremely large; see [Description of Monitoring Information]), it may be helpful to run e04uc with a relaxed value of the Feasibility Tolerance (default value=ε, where ε is the machine precision). (Constraint dependencies are often indicated by wide variations in size in the diagonal elements of the matrix T, whose diagonals will be printed if Major Print Level≥30).
ifail=7
The user-supplied derivatives of the objective function and/or nonlinear constraints appear to be incorrect.
Large errors were found in the derivatives of the objective function and/or nonlinear constraints. This value of ifail will occur if the verification process indicated that at least one gradient or Jacobian element had no correct figures. You should refer to the printed output to determine which elements are suspected to be in error.
As a first-step, you should check that the code for the objective and constraint values is correct – for example, by computing the function at a point where the correct value is known. However, care should be taken that the chosen point fully tests the evaluation of the function. It is remarkable how often the values x=0 or x=1 are used to test function evaluation procedures, and how often the special properties of these numbers make the test meaningless.
Special care should be used in this test if computation of the objective function involves subsidiary data communicated in storage. Although the first evaluation of the function may be correct, subsequent calculations may be in error because some of the subsidiary data has accidentally been overwritten.
Gradient checking will be ineffective if the objective function uses information computed by the constraints, since they are not necessarily computed before each function evaluation.
Errors in programming the function may be quite subtle in that the function value is ‘almost’ correct. For example, the function may not be accurate to full precision because of the inaccurate calculation of a subsidiary quantity, or the limited accuracy of data upon which the function depends. A common error on machines where numerical calculations are usually performed in double precision is to include even one single precision constant in the calculation of the function; since some compilers do not convert such constants to double precision, half the correct figures may be lost by such a seemingly trivial error.
ifail=8
Not used by this method.
ifail=9
An input parameter is invalid.
Overflow
If the printed output before the overflow error contains a warning about serious ill-conditioning in the working set when adding the jth constraint, it may be possible to avoid the difficulty by increasing the magnitude of the optional parameter Linear Feasibility Tolerance and/or the optional parameter Nonlinear Feasibility Tolerance and rerunning the program. If the message recurs even after this change then the offending linearly dependent constraint (with index ‘j’) must be removed from the problem. If overflow occurs in one of the user-supplied subroutines (e.g., if the nonlinear functions involve exponentials or singularities), it may help to specify tighter bounds for some of the variables (i.e., reduce the gap between the appropriate lj and uj).
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

If ifail=0 on exit, then the vector returned in the array x is an estimate of the solution to an accuracy of approximately Optimality Tolerance (default value=ε 0.8, where ε is the machine precision).

Parallelism and Performance

None.

Further Comments

Description of the Printed Output

This section describes the intermediate printout and final printout produced by e04uc. The intermediate printout is a subset of the monitoring information produced by the method at every iteration (see [Description of Monitoring Information]). You can control the level of printed output (see the description of the optional parameter Major Print Level). Note that the intermediate printout and final printout are produced only if Major Print Level≥10 (the default for e04uc, by default no output is produced by ).
The following line of summary output (<80 characters) is produced at every major iteration. In all cases, the values of the quantities printed are those in effect on completion of the given iteration.
Maj | is the major iteration count.
Mnr is the number of minor iterations required by the feasibility and optimality phases of the QP subproblem. Generally, Mnr will be 1 in the later iterations, since theoretical analysis predicts that the correct active set will be identified near the solution (see [Algorithmic Details]).
Note that Mnr may be greater than the optional parameter Minor Iteration Limit if some iterations are required for the feasibility phase.
Step | is the step αk taken along the computed search direction. On reasonably well-behaved problems, the unit step (i.e., αk=1) will be taken as the solution is approached.
Merit Function is the value of the augmented Lagrangian merit function (12) at the current iterate. This function will decrease at each iteration unless it was necessary to increase the penalty parameters (see [The Merit Function]). As the solution is approached, Merit Function will converge to the value of the objective function at the solution.
If the QP subproblem does not have a feasible point (signified by I at the end of the current output line) then the merit function is a large multiple of the constraint violations, weighted by the penalty parameters. During a sequence of major iterations with infeasible subproblems, the sequence of Merit Function values will decrease monotonically until either a feasible subproblem is obtained or e04uc terminates with ifail=3 (no feasible point could be found for the nonlinear constraints).
If there are no nonlinear constraints present (i.e., ncnln=0) then this entry contains Objective, the value of the objective function F x. The objective function will decrease monotonically to its optimal value when there are no nonlinear constraints.
Norm Gz | is ZT gFR, the Euclidean norm of the projected gradient (see [Solution of the Quadratic Programming Subproblem]). Norm Gz will be approximately zero in the neighbourhood of a solution.
Violtn | is the Euclidean norm of the residuals of constraints that are violated or in the predicted active set (not printed if ncnln is zero). Violtn will be approximately zero in the neighbourhood of a solution.
Cond Hz | is a lower bound on the condition number of the projected Hessian approximation HZ (HZ=ZT HFR Z=RZT RZ; see (6)). The larger this number, the more difficult the problem.
M | is printed if the quasi-Newton update has been modified to ensure that the Hessian approximation is positive definite (see [The Quasi-Newton Update]).
I | is printed if the QP subproblem has no feasible point.
C | is printed if central differences have been used to compute the unspecified objective and constraint gradients. If the value of Step is zero then the switch to central differences was made because no lower point could be found in the linesearch. (In this case, the QP subproblem is resolved with the central difference gradient and Jacobian.) If the value of Step is nonzero then central differences were computed because Norm Gz and Violtn imply that x is close to a Kuhn–Tucker point (see [Overview] in e04uf).
L | is printed if the linesearch has produced a relative change in x greater than the value defined by the optional parameter Step Limit. If this output occurs frequently during later iterations of the run, optional parameter Step Limit should be set to a larger value.
R | is printed if the approximate Hessian has been refactorized. If the diagonal condition estimator of R indicates that the approximate Hessian is badly conditioned then the approximate Hessian is refactorized using column interchanges. If necessary, R is modified so that its diagonal condition estimator is bounded.
The final printout includes a listing of the status of every variable and constraint. The following describes the printout for each variable. A full stop (.) is printed for any numerical value that is zero.
Varbl | gives the name (V) and index j, for j=1,2,…,n, of the variable.
State gives the state of the variable (FR if neither bound is in the working set, EQ if a fixed variable, LL if on its lower bound, UL if on its upper bound, TF if temporarily fixed at its current value). If Value lies outside the upper or lower bounds by more than the Feasibility Tolerance, State will be ++ or -- respectively. (The latter situation can occur only when there is no feasible point for the bounds and linear constraints.)
A key is sometimes printed before State.
A | Alternative optimum possible. The variable is active at one of its bounds, but its Lagrange multiplier is essentially zero. This means that if the variable were allowed to start moving away from its bound then there would be no change to the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case the values of the Lagrange multipliers might also change.
D | Degenerate. The variable is free, but it is equal to (or very close to) one of its bounds.
I | Infeasible. The variable is currently violating one of its bounds by more than the Feasibility Tolerance.
Value | is the value of the variable at the final iteration.
Lower Bound | is the lower bound specified for the variable. None indicates that bl[j-1]≤-bigbnd.
Upper Bound | is the upper bound specified for the variable. None indicates that bu[j-1]≥bigbnd.
Lagr Mult | is the Lagrange multiplier for the associated bound. This will be zero if State is FR unless bl[j-1]≤-bigbnd and bu[j-1]≥bigbnd, in which case the entry will be blank. If x is optimal, the multiplier should be non-negative if State is LL and non-positive if State is UL.
Slack | is the difference between the variable Value and the nearer of its (finite) bounds bl[j-1] and bu[j-1]. A blank entry indicates that the associated variable is not bounded (i.e., bl[j-1]≤-bigbnd and bu[j-1]≥bigbnd).
The meaning of the printout for linear and nonlinear constraints is the same as that given above for variables, with ‘variable’ replaced by ‘constraint’, bl[j-1] and bu[j-1] are replaced by bl[n+j-1] and bu[n+j-1] respectively, and with the following changes in the heading:
L Con | gives the name (L) and index j, for j=1,2,…,nL, of the linear constraint.
N Con | gives the name (N) and index (j-nL), for j=nL+1,…,nL+nN, of the nonlinear constraint.
Note that movement off a constraint (as opposed to a variable moving away from its bound) can be interpreted as allowing the entry in the Slack column to become positive.
Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.

Example

This is based on Problem 71 in Hock and Schittkowski (1981) and involves the minimization of the nonlinear function
F x=x 1x 4 x 1+x 2+x 3+x 3
subject to the bounds
1≤x 1≤51≤x 2≤51≤x 3≤51≤x 4≤5
to the general linear constraint
x 1+x 2+x 3+x 4≤20,
and to the nonlinear constraints
x 12+x 22+x 32+x 42≤40,x 1x 2x 3x 4≥25.
The initial point, which is infeasible, is
x 0=1,5,5,1 T,
and F x 0=16.
The optimal solution (to five figures) is
x*=1.0,4.7430,3.8211,1.3794 T,
and F x*=17.014. One bound constraint and both nonlinear constraints are active at the solution.

Example program (C#): e04uce.cs

Example program data: e04uce.d

Example program results: e04uce.r

Algorithmic Details

This section contains a detailed description of the method used by e04uc.

Overview

e04uc is essentially identical to the method NPSOL described in Gill et al. (1986b).
At a solution of (1), some of the constraints will be active, i.e., satisfied exactly. An active simple bound constraint implies that the corresponding variable is fixed at its bound, and hence the variables are partitioned into fixed and free variables. Let C denote the m by n matrix of gradients of the active general linear and nonlinear constraints. The number of fixed variables will be denoted by nFX, with nFR nFR=n-nFX the number of free variables. The subscripts ‘FX’ and ‘FR’ on a vector or matrix will denote the vector or matrix composed of the elements corresponding to fixed or free variables.
A point x is a first-order Kuhn–Tucker point for (1) (see Powell (1974)) if the following conditions hold:
(i) | x is feasible;
(ii) there exist vectors ξ and λ (the Lagrange multiplier vectors for the bound and general constraints) such that
g=CT λ+ξ (2)
where g is the gradient of F evaluated at x, and ξj=0 if the jth variable is free.
(iii) | The Lagrange multiplier corresponding to an inequality constraint active at its lower bound must be non-negative, and non-positive for an inequality constraint active at its upper bound.
Let Z denote a matrix whose columns form a basis for the set of vectors orthogonal to the rows of CFR; i.e., CFR Z=0. An equivalent statement of the condition (2) in terms of Z is
ZT gFR=0.
The vector ZT gFR is termed the projected gradient of F at x. Certain additional conditions must be satisfied in order for a first-order Kuhn–Tucker point to be a solution of (1) (see Powell (1974)).
e04uc implements a sequential quadratic programming (SQP) method. For an overview of SQP methods, see, for example, Fletcher (1987), Gill et al. (1981) and Powell (1983).
The basic structure of e04uc involves major and minor iterations. The major iterations generate a sequence of iterates xk that converge to x*, a first-order Kuhn–Tucker point of (1). At a typical major iteration, the new iterate x- is defined by
x-=x+αp (3)
where x is the current iterate, the non-negative scalar α is the step length, and p is the search direction. (For simplicity, we shall always consider a typical iteration and avoid reference to the index of the iteration.) Also associated with each major iteration are estimates of the Lagrange multipliers and a prediction of the active set.
The search direction p in (3) is the solution of a quadratic programming subproblem of the form
minimizep gT p+12 pT Hp  subject to  l-≤pAL pAN p≤u-, (4)
where g is the gradient of F at x, the matrix H is a positive definite quasi-Newton approximation to the Hessian of the Lagrangian function (see [The Quasi-Newton Update]), and AN is the Jacobian matrix of c evaluated at x. (Finite difference estimates may be used for g and AN; see the optional parameter Derivative Level.) Let l in (1) be partitioned into three sections: lB, lL and lN, corresponding to the bound, linear and nonlinear constraints. The vector l- in (4) is similarly partitioned, and is defined as
l-B=lB-x,  l-L=lL-AL x,   and  l-N=lN-c,
where c is the vector of nonlinear constraints evaluated at x. The vector u- is defined in an analogous fashion.
The estimated Lagrange multipliers at each major iteration are the Lagrange multipliers from the subproblem (4) (and similarly for the predicted active set). (The numbers of bounds, general linear and nonlinear constraints in the QP active set are the quantities Bnd, Lin and Nln in the monitoring file output of e04uc; see [Description of Monitoring Information].) In e04uc, (4) is solved using e04nc. Since solving a quadratic program is itself an iterative procedure, the minor iterations of e04uc are the iterations of e04nc. (More details about solving the subproblem are given in [Solution of the Quadratic Programming Subproblem].)
Certain matrices associated with the QP subproblem are relevant in the major iterations. Let the subscripts ‘FX’ and ‘FR’ refer to the predicted fixed and free variables, and let C denote the m by n matrix of gradients of the general linear and nonlinear constraints in the predicted active set. First, we have available the TQ factorization of CFR:
CFRQFR=0T, (5)
where T is a nonsingular m by m reverse-triangular matrix (i.e., t ij=0 if i+j<m), and the nonsingular nFR by nFR matrix QFR is the product of orthogonal transformations (see Gill et al. (1984b)). Second, we have the upper triangular Cholesky factor R of the transformed and reordered Hessian matrix
RT R=HQ≡QT H~Q, (6)
where H~ is the Hessian H with rows and columns permuted so that the free variables are first, and Q is the n by n matrix
Q=QFRIFX (7)
with IFX the identity matrix of order nFX. If the columns of QFR are partitioned so that
QFR=ZY,
the nZ (nZ≡nFR-m) columns of Z form a basis for the null space of CFR. The matrix Z is used to compute the projected gradient ZT gFR at the current iterate. (The values Nz and Norm Gz printed by e04uc give nZ and ZT gFR; see [Description of Monitoring Information].)
A theoretical characteristic of SQP methods is that the predicted active set from the QP subproblem (4) is identical to the correct active set in a neighbourhood of x*. In e04uc, this feature is exploited by using the QP active set from the previous iteration as a prediction of the active set for the next QP subproblem, which leads in practice to optimality of the subproblems in only one iteration as the solution is approached. Separate treatment of bound and linear constraints in e04uc also saves computation in factorizing CFR and HQ.
Once p has been computed, the major iteration proceeds by determining a step length α that produces a ‘sufficient decrease’ in an augmented Lagrangian merit function (see [The Merit Function]). Finally, the approximation to the transformed Hessian matrix HQ is updated using a modified BFGS quasi-Newton update (see [The Quasi-Newton Update]) to incorporate new curvature information obtained in the move from x to x-.
On entry to e04uc, an iterative procedure from e04nc is executed, starting with the user-supplied initial point, to find a point that is feasible with respect to the bounds and linear constraints (using the tolerance specified by optional parameter Linear Feasibility Tolerance). If no feasible point exists for the bound and linear constraints, (1) has no solution and e04uc terminates. Otherwise, the problem functions will thereafter be evaluated only at points that are feasible with respect to the bounds and linear constraints. The only exception involves variables whose bounds differ by an amount comparable to the finite difference interval (see the discussion of optional parameter Difference Interval). In contrast to the bounds and linear constraints, it must be emphasized that the nonlinear constraints will not generally be satisfied until an optimal point is reached.
Facilities are provided to check whether the user-supplied gradients appear to be correct (see the description of the optional parameter Verify). In general, the check is provided at the first point that is feasible with respect to the linear constraints and bounds. However, you may request that the check be performed at the initial point.
In summary, the method of e04uc first determines a point that satisfies the bound and linear constraints. Thereafter, each iteration includes:
(a) | the solution of a quadratic programming subproblem;
(b) | a linesearch with an augmented Lagrangian merit function; and
(c) | a quasi-Newton update of the approximate Hessian of the Lagrangian function.
These three procedures are described in more detail in [Solution of the Quadratic Programming Subproblem] to [The Quasi-Newton Update].

Solution of the Quadratic Programming Subproblem

The search direction p is obtained by solving (4) using e04nc (see Gill et al. (1986)), which was specifically designed to be used within an SQP algorithm for nonlinear programming.
e04nc is based on a two-phase (primal) quadratic programming method. The two phases of the method are: finding an initial feasible point by minimizing the sum of infeasibilities (the feasibility phase), and minimizing the quadratic objective function within the feasible region (the optimality phase). The computations in both phases are performed by the same methods. The two-phase nature of the algorithm is reflected by changing the function being minimized from the sum of infeasibilities to the quadratic objective function.
In general, a quadratic program must be solved by iteration. Let p denote the current estimate of the solution of (4); the new iterate p- is defined by
p-=p+σd (8)
where, as in (3), σ is a non-negative step length and d is a search direction.
At the beginning of each iteration of e04nc, a working set is defined of constraints (general and bound) that are satisfied exactly. The vector d is then constructed so that the values of constraints in the working set remain unaltered for any move along d. For a bound constraint in the working set, this property is achieved by setting the corresponding element of d to zero, i.e., by fixing the variable at its bound. As before, the subscripts ‘FX’ and ‘FR’ denote selection of the elements associated with the fixed and free variables.
Let C denote the sub-matrix of rows of
ALAN
corresponding to general constraints in the working set. The general constraints in the working set will remain unaltered if
CFRdFR=0, (9)
which is equivalent to defining dFR as
dFR=Z dZ (10)
for some vector dZ, where Z is the matrix associated with the TQ factorization (5) of CFR.
The definition of dZ in (10) depends on whether the current p is feasible. If not, dZ is zero except for an element γ in the jth position, where j and γ are chosen so that the sum of infeasibilities is decreasing along d. (For further details, see Gill et al. (1986).) In the feasible case, dZ satisfies the equations
RZT RZdZ=-ZT qFR, (11)
where RZ is the Cholesky factor of ZT HFR Z and q is the gradient of the quadratic objective function q=g+Hp. (The vector ZT qFR is the projected gradient of the QP.) With (11), p+d is the minimizer of the quadratic objective function subject to treating the constraints in the working set as equalities.
If the QP projected gradient is zero, the current point is a constrained stationary point in the subspace defined by the working set. During the feasibility phase, the projected gradient will usually be zero only at a vertex (although it may vanish at non-vertices in the presence of constraint dependencies). During the optimality phase, a zero projected gradient implies that p minimizes the quadratic objective function when the constraints in the working set are treated as equalities. In either case, Lagrange multipliers are computed. Given a positive constant δ of the order of the machine precision, the Lagrange multiplier μj corresponding to an inequality constraint in the working set is said to be optimal if μj≤δ when the jth constraint is at its upper bound, or if μj≥-δ when the associated constraint is at its lower bound. If any multiplier is nonoptimal, the current objective function (either the true objective or the sum of infeasibilities) can be reduced by deleting the corresponding constraint from the working set.
If optimal multipliers occur during the feasibility phase and the sum of infeasibilities is nonzero, no feasible point exists. The QP algorithm will then continue iterating to determine the minimum sum of infeasibilities. At this point, the Lagrange multiplier μj will satisfy -1+δ≤μj≤δ for an inequality constraint at its upper bound, and -δ≤μj≤1+δ for an inequality at its lower bound. The Lagrange multiplier for an equality constraint will satisfy μj≤1+δ.
The choice of step length σ in the QP iteration (8) is based on remaining feasible with respect to the satisfied constraints. During the optimality phase, if p+d is feasible, σ will be taken as unity. (In this case, the projected gradient at p- will be zero.) Otherwise, σ is set to σM, the step to the ‘nearest’ constraint, which is added to the working set at the next iteration.
Each change in the working set leads to a simple change to CFR: if the status of a general constraint changes, a row of CFR is altered; if a bound constraint enters or leaves the working set, a column of CFR changes. Explicit representations are recurred of the matrices T, QFR and R, and of the vectors QT q and QT g.

The Merit Function

After computing the search direction as described in [Solution of the Quadratic Programming Subproblem], each major iteration proceeds by determining a step length α in (3) that produces a ‘sufficient decrease’ in the augmented Lagrangian merit function
L x,λ,s=F x-∑i λi ci x-si+12∑i ρi ci x-si 2, (12)
where x, λ and s vary during the linesearch. The summation terms in (12) involve only the nonlinear constraints. The vector λ is an estimate of the Lagrange multipliers for the nonlinear constraints of (1). The non-negative slack variables si allow nonlinear inequality constraints to be treated without introducing discontinuities. The solution of the QP subproblem (4) provides a vector triple that serves as a direction of search for the three sets of variables. The non-negative vector ρ of penalty parameters is initialized to zero at the beginning of the first major iteration. Thereafter, selected elements are increased whenever necessary to ensure descent for the merit function. Thus, the sequence of norms of ρ (the printed quantity Penalty; see [Description of Monitoring Information]) is generally nondecreasing, although each ρi may be reduced a limited number of times.
The merit function (12) and its global convergence properties are described in Gill et al. (1986a).

The Quasi-Newton Update

The matrix H in (4) is a positive definite quasi-Newton approximation to the Hessian of the Lagrangian function. (For a review of quasi-Newton methods, see Dennis and Schnabel (1983).) At the end of each major iteration, a new Hessian approximation H- is defined as a rank-two modification of H. In e04uc, the BFGS (Broyden–Fletcher–Goldfarb–Shanno) quasi-Newton update is used:
H-=H-1 sT Hs Hs sT H+1 yT s y yT, (13)
where s=x--x (the change in x).
In e04uc, H is required to be positive definite. If H is positive definite, H- defined by (13) will be positive definite if and only if yT s is positive (see Dennis and Moré (1977)). Ideally, y in (13) would be taken as yL, the change in gradient of the Lagrangian function
yL=g--A-NT μN-g+ANT μN, (14)
where μN denotes the QP multipliers associated with the nonlinear constraints of the original problem. If yLT s is not sufficiently positive, an attempt is made to perform the update with a vector y of the form
y=yL+∑i=1 mN ωi ai x^ci x^-ai x ci x,
where ωi≥0. If no such vector can be found, the update is performed with a scaled yL; in this case, M is printed to indicate that the update was modified.
Rather than modifying H itself, the Cholesky factor of the transformed Hessian HQ (6) is updated, where Q is the matrix from (5) associated with the active set of the QP subproblem. The update (13) is equivalent to the following update to HQ:
H-Q=HQ-1 sQT HQsQ HQsQ sQT HQ+1 yQT sQ yQ yQT, (15)
where yQ=QT y, and sQ=QT s. This update may be expressed as a rank-one update to R (see Dennis and Schnabel (1981)).

Description of Monitoring Information

This section describes the long line of output (>80 characters) which forms part of the monitoring information produced by e04uc. (See also the description of the optional parameters Major Print Level, Minor Print Level and Monitoring File.) You can control the level of printed output.
When Major Print Level≥5 and Monitoring File≥0, the following line of output is produced at every major iteration of e04uc on the unit number specified by Monitoring File. In all cases, the values of the quantities printed are those in effect on completion of the given iteration.
Maj | is the major iteration count.
Mnr is the number of minor iterations required by the feasibility and optimality phases of the QP subproblem. Generally, Mnr will be 1 in the later iterations, since theoretical analysis predicts that the correct active set will be identified near the solution (see [Algorithmic Details]).
Note that Mnr may be greater than the optional parameter Minor Iteration Limit if some iterations are required for the feasibility phase.
Step | is the step αk taken along the computed search direction. On reasonably well-behaved problems, the unit step (i.e., αk=1) will be taken as the solution is approached.
Nfun | is the cumulative number of evaluations of the objective function needed for the linesearch. Evaluations needed for the estimation of the gradients by finite differences are not included. Nfun is printed as a guide to the amount of work required for the linesearch.
Merit Function is the value of the augmented Lagrangian merit function (12) at the current iterate. This function will decrease at each iteration unless it was necessary to increase the penalty parameters (see [The Merit Function]). As the solution is approached, Merit Function will converge to the value of the objective function at the solution.
If the QP subproblem does not have a feasible point (signified by I at the end of the current output line) then the merit function is a large multiple of the constraint violations, weighted by the penalty parameters. During a sequence of major iterations with infeasible subproblems, the sequence of Merit Function values will decrease monotonically until either a feasible subproblem is obtained or e04uc terminates with ifail=3 (no feasible point could be found for the nonlinear constraints).
If there are no nonlinear constraints present (i.e., ncnln=0) then this entry contains Objective, the value of the objective function F x. The objective function will decrease monotonically to its optimal value when there are no nonlinear constraints.
Norm Gz | is ZT gFR, the Euclidean norm of the projected gradient (see [Solution of the Quadratic Programming Subproblem]). Norm Gz will be approximately zero in the neighbourhood of a solution.
Violtn | is the Euclidean norm of the residuals of constraints that are violated or in the predicted active set (not printed if ncnln is zero). Violtn will be approximately zero in the neighbourhood of a solution.
Nz | is the number of columns of Z (see [Solution of the Quadratic Programming Subproblem]). The value of Nz is the number of variables minus the number of constraints in the predicted active set; i.e., Nz=n-Bnd+Lin+Nln.
Bnd | is the number of simple bound constraints in the predicted active set.
Lin | is the number of general linear constraints in the predicted working set.
Nln | is the number of nonlinear constraints in the predicted active set (not printed if ncnln is zero).
Penalty | is the Euclidean norm of the vector of penalty parameters used in the augmented Lagrangian merit function (not printed if ncnln is zero).
Cond H | is a lower bound on the condition number of the Hessian approximation H.
Cond Hz | is a lower bound on the condition number of the projected Hessian approximation HZ (HZ=ZT HFR Z=RZT RZ; see (6)). The larger this number, the more difficult the problem.
Cond T | is a lower bound on the condition number of the matrix of predicted active constraints.
Conv is a three-letter indication of the status of the three convergence tests (16)–(18) defined in the description of the optional parameter Optimality Tolerance. Each letter is T if the test is satisfied and F otherwise. The three tests indicate whether:
(i) | the sequence of iterates has converged;
(ii) | the projected gradient (Norm Gz) is sufficiently small; and
(iii) | the norm of the residuals of constraints in the predicted active set (Violtn) is small enough.
If any of these indicators is F when e04uc terminates with ifail=0, you should check the solution carefully.
M | is printed if the quasi-Newton update has been modified to ensure that the Hessian approximation is positive definite (see [The Quasi-Newton Update]).
I | is printed if the QP subproblem has no feasible point.
C | is printed if central differences have been used to compute the unspecified objective and constraint gradients. If the value of Step is zero then the switch to central differences was made because no lower point could be found in the linesearch. (In this case, the QP subproblem is resolved with the central difference gradient and Jacobian.) If the value of Step is nonzero then central differences were computed because Norm Gz and Violtn imply that x is close to a Kuhn–Tucker point (see [Overview] in e04uf).
L | is printed if the linesearch has produced a relative change in x greater than the value defined by the optional parameter Step Limit. If this output occurs frequently during later iterations of the run, optional parameter Step Limit should be set to a larger value.
R | is printed if the approximate Hessian has been refactorized. If the diagonal condition estimator of R indicates that the approximate Hessian is badly conditioned then the approximate Hessian is refactorized using column interchanges. If necessary, R is modified so that its diagonal condition estimator is bounded.

See Also

E04 Class
E04 Members


e04udm Method

[image]

NAG Library for .NET Release 2
E04..::e04udm Method
E04 Class See Also Send Feedback
Auxiliary for use as a delegate parameter

Syntax

C#
public static void e04udm(
    ref int mode,
    int ncnln,
    int n,
    int[] needc,
    double[] x,
    double[] c,
    double[,] cjac,
    int nstate
)
Visual Basic
Public Shared Sub e04udm ( _
    ByRef mode As Integer, _
    ncnln As Integer, _
    n As Integer, _
    needc As Integer(), _
    x As Double(), _
    c As Double(), _
    cjac As Double(,), _
    nstate As Integer _
)
Visual C++
public:
static void e04udm(
    int% mode,
    int ncnln,
    int n,
    array<int>^ needc,
    array<double>^ x,
    array<double>^ c,
    array<double,2>^ cjac,
    int nstate
)
F#
static member e04udm :
        mode : int byref *
        ncnln : int *
        n : int *
        needc : int[] *
        x : float[] *
        c : float[] *
        cjac : float[,] *
        nstate : int -> unit

Parameters

mode
Type: System..::..Int32 %
On entry: indicates which values must be assigned during each call of _confun. Only the following values need be assigned, for each value of i such that needc[i-1]>0:
mode=0
c[i-1].
mode=1
All available elements in the ith row of cjac.
mode=2
c[i-1] and all available elements in the ith row of cjac.
On exit: may be set to a negative value if you wish to terminate the solution to the current problem. In this case e04ud will terminate with _ifail set to mode.
ncnln
Type: System..::..Int32
On entry: nN, the number of nonlinear constraints.
n
Type: System..::..Int32
On entry: n, the number of variables.
needc
Type: array< System..::..Int32 >[]()[][]
An array of size [ncnln]
On entry: the indices of the elements of c and/or cjac that must be evaluated by _confun. If needc[i-1]>0, the ith element of c and/or the available elements of the ith row of cjac (see parameter mode) must be evaluated at x.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x, the vector of variables at which the constraint functions and/or the available elements of the constraint Jacobian are to be evaluated.
c
Type: array< System..::..Double >[]()[][]
An array of size [ncnln]
On exit: if needc[i-1]>0 and mode=0 or 2, c[i-1] must contain the value of the ith constraint at x. The remaining elements of c, corresponding to the non-positive elements of needc, are ignored.
cjac
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint:
On entry: unless optparam_derivativelevel=2 or 3, the elements of cjac are set to special values which enable e04ud to detect whether they are changed by _confun.
On exit: if needc[i-1]>0 and mode=1 or 2, the ith row of cjac must contain the available elements of the vector ∇ci given by
∇ci=∂ci∂x 1,∂ci∂x 2,…,∂ci∂xn T,
where ∂ci∂xj is the partial derivative of the ith constraint with respect to the jth variable, evaluated at the point x. See also the parameter confun_nstate. The remaining rows of cjac, corresponding to non-positive elements of needc, are ignored.
If all elements of the constraint Jacobian are known (i.e., optparam_derivativelevel=2 or 3), any constant elements may be assigned to cjac one time only at the start of the optimization. An element of cjac that is not subsequently assigned in _confun will retain its initial value throughout. Constant elements may be loaded into cjac either before the call to e04ud or during the first call to _confun (signalled by the value confun_nstate=1). The ability to preload constants is useful when many Jacobian elements are identically zero, in which case cjac may be initialized to zero and nonzero elements may be reset by _confun.
Note that constant nonzero elements do affect the values of the constraints. Thus, if cjac[i-1,j-1] is set to a constant value, it need not be reset in subsequent calls to _confun, but the value cjac[i-1,j-1]×x[j-1] must nonetheless be added to c[i-1]. For example, if cjac[0,0]=2 and cjac[0,1]=-5 then the term 2×x[0]-5×x[1] must be included in the definition of c[0].
It must be emphasized that, if optparam_derivativelevel=0 or 1, unassigned elements of cjac are not treated as constant; they are estimated by finite differences, at nontrivial expense. If you do not supply a value for the optional parameter optparam_differenceinterval, an interval for each element of x is computed automatically at the start of the optimization. The automatic procedure can usually identify constant elements of cjac, which are then computed once only by finite differences.
nstate
Type: System..::..Int32
On entry: if nstate=1 then e04ud is calling _confun for the first time. This parameter setting allows you to save computation time if certain data must be read or calculated only once.

Description

Auxiliary for use as a delegate parameter

References

None.

Error Indicators and Warnings

None.

Accuracy

Not applicable.

Further Comments

None.

Example

None.

See Also

E04 Class
E04 Members


e04uf Method

[image]

NAG Library for .NET Release 2
E04..::e04uf Method
E04 Class See Also Send Feedback
e04uf is designed to minimize an arbitrary smooth function subject to constraints (which may include simple bounds on the variables, linear constraints and smooth nonlinear constraints) using a sequential quadratic programming (SQP) method. You should supply as many first derivatives as possible; any unspecified derivatives are approximated by finite differences. It is not intended for large sparse problems.
e04uf may also be used for unconstrained, bound-constrained and linearly constrained optimization.
e04uf uses reverse communication for evaluating the objective function, the nonlinear constraint functions and any of their derivatives.

Syntax

C#
public static void e04uf(
    ref int irevcm,
    int n,
    int nclin,
    int ncnln,
    double[,] a,
    double[] bl,
    double[] bu,
    ref int iter,
    int[] istate,
    double[] c,
    double[,] cjac,
    double[] clamda,
    ref double objf,
    double[] objgrd,
    double[,] r,
    double[] x,
    int[] needc,
    int[] iwork,
    double[] work,
    E04..::..e04ufOptions options,
    out int ifail
)
Visual Basic
Public Shared Sub e04uf ( _
    ByRef irevcm As Integer, _
    n As Integer, _
    nclin As Integer, _
    ncnln As Integer, _
    a As Double(,), _
    bl As Double(), _
    bu As Double(), _
    ByRef iter As Integer, _
    istate As Integer(), _
    c As Double(), _
    cjac As Double(,), _
    clamda As Double(), _
    ByRef objf As Double, _
    objgrd As Double(), _
    r As Double(,), _
    x As Double(), _
    needc As Integer(), _
    iwork As Integer(), _
    work As Double(), _
    options As E04..::..e04ufOptions, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04uf(
    int% irevcm,
    int n,
    int nclin,
    int ncnln,
    array<double,2>^ a,
    array<double>^ bl,
    array<double>^ bu,
    int% iter,
    array<int>^ istate,
    array<double>^ c,
    array<double,2>^ cjac,
    array<double>^ clamda,
    double% objf,
    array<double>^ objgrd,
    array<double,2>^ r,
    array<double>^ x,
    array<int>^ needc,
    array<int>^ iwork,
    array<double>^ work,
    E04..::..e04ufOptions^ options,
    [OutAttribute] int% ifail
)
F#
static member e04uf :
        irevcm : int byref *
        n : int *
        nclin : int *
        ncnln : int *
        a : float[,] *
        bl : float[] *
        bu : float[] *
        iter : int byref *
        istate : int[] *
        c : float[] *
        cjac : float[,] *
        clamda : float[] *
        objf : float byref *
        objgrd : float[] *
        r : float[,] *
        x : float[] *
        needc : int[] *
        iwork : int[] *
        work : float[] *
        options : E04..::..e04ufOptions *
        ifail : int byref -> unit

Parameters

irevcm
Type: System..::..Int32 %
On initial entry: must be set to 0.
On intermediate exit: specifies what values the calling program must assign to parameters of e04uf before re-entering the method.
irevcm=1
Set objf to the value of the objective function F x.
irevcm=2
Set objgrd[j-1] to the value ∂F∂xj if available, for j=1,2,…,n.
irevcm=3
Set objf and objgrd[j-1] as for irevcm=1 and irevcm=2.
irevcm=4
Set c[i-1] to the value of the constraint function ci x, for each i such that needc[i-1]>0.
irevcm=5
Set cjac[i-1,j-1] to the value ∂ci∂xj if available, for each i such that needc[i-1]>0 and j=1,2,…,n.
irevcm=6
Set c[i-1] and cjac[i-1,j-1] as for irevcm=4 and irevcm=5.
On intermediate re-entry: must remain unchanged, unless you wish to terminate the solution to the current problem. In this case irevcm may be set to a negative value and then e04uf will take a final exit with ifail set to this value of irevcm.
On final exit: irevcm=0.
Constraint: irevcm≤6.
n
Type: System..::..Int32
On initial entry: n, the number of variables.
Constraint: n>0.
nclin
Type: System..::..Int32
On initial entry: nL, the number of general linear constraints.
Constraint: nclin≥0.
ncnln
Type: System..::..Int32
On initial entry: nN, the number of nonlinear constraints.
Constraint: ncnln≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,nclin
Note: the second dimension of the array a must be at least n if nclin>0, and at least 1 otherwise.
On initial entry: the ith row of the matrix AL of general linear constraints in (1) must be stored in a[i-1,j-1], for i=1,2,…,nclin and j=1,2,…,n. That is, the ith row contains the coefficients of the ith general linear constraint, for i=1,2,…,nclin.
If nclin=0, the array a is not referenced.
bl
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin+ncnln]
On initial entry: bl must contain the lower bounds and bu the upper bounds, for all the constraints in the following order. The first n elements of each array must contain the bounds on the variables, the next nL elements the bounds for the general linear constraints (if any) and the next nN elements the bounds for the general nonlinear constraints (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j-1]≤-bigbnd, and to specify a nonexistent upper bound (i.e., uj=+∞), set bu[j-1]≥bigbnd; the default value of bigbnd is 1020, but this may be changed by the optional parameter Infinite Bound Size. To specify the jth constraint as an equality, set bl[j-1]=bu[j-1]=β, say, where β<bigbnd.
Constraints:
  • bl[j-1]≤bu[j-1], for j=1,2,…,n+nclin+ncnln;
  • if bl[j]=bu[j]=β, β<bigbnd.
bu
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin+ncnln]
On initial entry: bl must contain the lower bounds and bu the upper bounds, for all the constraints in the following order. The first n elements of each array must contain the bounds on the variables, the next nL elements the bounds for the general linear constraints (if any) and the next nN elements the bounds for the general nonlinear constraints (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j-1]≤-bigbnd, and to specify a nonexistent upper bound (i.e., uj=+∞), set bu[j-1]≥bigbnd; the default value of bigbnd is 1020, but this may be changed by the optional parameter Infinite Bound Size. To specify the jth constraint as an equality, set bl[j-1]=bu[j-1]=β, say, where β<bigbnd.
Constraints:
  • bl[j-1]≤bu[j-1], for j=1,2,…,n+nclin+ncnln;
  • if bl[j]=bu[j]=β, β<bigbnd.
iter
Type: System..::..Int32 %
On intermediate re-entry: must remain unchanged from a previous call to e04uf.
On final exit: the number of major iterations performed.
istate
Type: array< System..::..Int32 >[]()[][]
An array of size [n+nclin+ncnln]
On initial entry: need not be set if the (default) optional parameter Cold Start is used.
If the optional parameter Warm Start has been chosen, the elements of istate corresponding to the bounds and linear constraints define the initial working set for the procedure that finds a feasible point for the linear constraints and bounds. The active set at the conclusion of this procedure and the elements of istate corresponding to nonlinear constraints then define the initial working set for the first QP subproblem. More precisely, the first n elements of istate refer to the upper and lower bounds on the variables, the next nL elements refer to the upper and lower bounds on AL x, and the next nN elements refer to the upper and lower bounds on c x. Possible values for istate[j-1] are as follows:
istate[j-1] | Meaning
0 | The corresponding constraint is not in the initial QP working set.
1 | This inequality constraint should be in the working set at its lower bound.
2 | This inequality constraint should be in the working set at its upper bound.
3 | This equality constraint should be in the initial working set. This value must not be specified unless bl[j-1]=bu[j-1].
The values -2, -1 and 4 are also acceptable but will be modified by the method. If e04uf has been called previously with the same values of n, nclin and ncnln, istate already contains satisfactory information. (See also the description of the optional parameter Warm Start.) The method also adjusts (if necessary) the values supplied in x to be consistent with istate.
Constraint: -2≤istate[j-1]≤4, for j=1,2,…,n+nclin+ncnln.
On final exit: the status of the constraints in the QP working set at the point returned in x. The significance of each possible value of istate[j-1] is as follows:
istate[j-1] | Meaning
-2 | This constraint violates its lower bound by more than the appropriate feasibility tolerance (see the optional parameters Linear Feasibility Tolerance and Nonlinear Feasibility Tolerance). This value can occur only when no feasible point can be found for a QP subproblem.
-1 | This constraint violates its upper bound by more than the appropriate feasibility tolerance (see the optional parameters Linear Feasibility Tolerance and Nonlinear Feasibility Tolerance). This value can occur only when no feasible point can be found for a QP subproblem.
-0 | The constraint is satisfied to within the feasibility tolerance, but is not in the QP working set.
-1 | This inequality constraint is included in the QP working set at its lower bound.
-2 | This inequality constraint is included in the QP working set at its upper bound.
-3 | This constraint is included in the QP working set as an equality. This value of istate can occur only when bl[j-1]=bu[j-1].
c
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array c must be at least max 1,ncnln.
On initial entry: need not be set.
On intermediate re-entry: if irevcm=4 or 6 and needc[i-1]>0, c[i-1] must contain the value of the ith constraint at x. The remaining elements of c, corresponding to the non-positive elements of needc, are ignored.
On final exit: if ncnln>0, c[i-1] contains the value of the ith nonlinear constraint function ci at the final iterate, for i=1,2,…,ncnln.
If ncnln=0, the array c is not referenced.
cjac
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,ncnln
Note: the second dimension of the array cjac must be at least n if ncnln>0, and at least 1 otherwise.
On initial entry: in general, cjac need not be initialized before the call to e04uf. However, if the optional parameter Derivative Level=2 or 3, you may optionally set the constant elements of cjac. Such constant elements need not be re-assigned on subsequent intermediate exits.
If all elements of the constraint Jacobian are known (i.e., Derivative Level=2 or 3), any constant elements may be assigned to cjac one time only at the start of the optimization. An element of cjac that is not subsequently assigned during an intermediate exit will retain its initial value throughout. Constant elements may be loaded into cjac either before the call to e04uf or during the first intermediate exit. The ability to preload constants is useful when many Jacobian elements are identically zero, in which case cjac may be initialized to zero and nonzero elements may be reset during intermediate exits.
On intermediate re-entry: if irevcm=5 or 6 and needc[i-1]>0, the ith row of cjac must contain the available elements of the vector ∇ci given by
∇ci=∂ci∂x 1,∂ci∂x 2,…,∂ci∂xn T,
where ∂ci∂xj is the partial derivative of the ith constraint with respect to the jth variable, evaluated at the point x. The remaining rows of cjac, corresponding to non-positive elements of needc, are ignored. The ith row of the Jacobian should be stored in elements cjac[i-1,j-1], for i=1,2,…,ncnln and j=1,2,…,n.
Note that constant nonzero elements do affect the values of the constraints. Thus, if cjac[i-1,j-1] is set to a constant value, it need not be reset during subsequent intermediate exits, but the value cjac[i-1,j-1]×x[j-1] must nonetheless be added to c[i-1]. For example, if cjac[0,0]=2 and cjac[0,1]=-5, then the term 2×x[0]-5×x[1] must be included in the definition of c[0].
It must be emphasized that, if Derivative Level=0 or 1, unassigned elements of cjac are not treated as constant; they are estimated by finite differences, at nontrivial expense. If you do not supply a value for the optional parameter Difference Interval, an interval for each element of x is computed automatically at the start of the optimization. The automatic procedure can usually identify constant elements of cjac, which are then computed once only by finite differences.
See also the description of the optional parameter Verify.
On final exit: if ncnln>0, cjac contains the Jacobian matrix of the nonlinear constraint functions at the final iterate, i.e., cjac[i-1,j-1] contains the partial derivative of the ith constraint function with respect to the jth variable, for i=1,2,…,ncnln and j=1,2,…,n.
If ncnln=0, the array cjac is not referenced.
clamda
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin+ncnln]
On initial entry: need not be set if the (default) optional parameter Cold Start is used.
If the optional parameter Warm Start has been chosen, clamda[j-1] must contain a multiplier estimate for each nonlinear constraint with a sign that matches the status of the constraint specified by the istate array, for j=n+nclin+1,…,n+nclin+ncnln. The remaining elements need not be set. Note that if the jth constraint is defined as ‘inactive’ by the initial value of the istate array (i.e. istate[j-1]=0), clamda[j-1] should be zero; if the jth constraint is an inequality active at its lower bound (i.e. istate[j-1]=1), clamda[j-1] should be non-negative; if the jth constraint is an inequality active at its upper bound (i.e. istate[j-1]=2), clamda[j-1] should be non-positive. If necessary, the method will modify clamda to match these rules.
On final exit: the values of the QP multipliers from the last QP subproblem. clamda[j-1] should be non-negative if istate[j-1]=1 and non-positive if istate[j-1]=2.
objf
Type: System..::..Double %
On initial entry: need not be set.
On intermediate re-entry: if irevcm=1 or 3, objf must be set to the value of the objective function at x.
On final exit: the value of the objective function at the final iterate.
objgrd
Type: array< System..::..Double >[]()[][]
An array of size [n]
On initial entry: need not be set.
On intermediate re-entry: if irevcm=2 or 3, objgrd must contain the available elements of the gradient evaluated at x.
See also the description of the optional parameter Verify.
On final exit: the gradient of the objective function at the final iterate (or its finite difference approximation).
r
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥n
On initial entry: need not be initialized if the (default) optional parameter Cold Start is used.
If the optional parameter Warm Start has been chosen, r must contain the upper triangular Cholesky factor R of the initial approximation of the Hessian of the Lagrangian function, with the variables in the natural order. Elements not in the upper triangular part of r are assumed to be zero and need not be assigned.
On final exit: if Hessian=NO, r contains the upper triangular Cholesky factor R of QT H~Q, an estimate of the transformed and reordered Hessian of the Lagrangian at x (see (6) in [Overview]).
If Hessian=YES, r contains the upper triangular Cholesky factor R of H, the approximate (untransformed) Hessian of the Lagrangian, with the variables in the natural order.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On initial entry: an initial estimate of the solution.
On intermediate exit: the point x at which the objective function, constraint functions or their derivatives are to be evaluated.
On final exit: the final estimate of the solution.
needc
Type: array< System..::..Int32 >[]()[][]
An array of size [max 1,ncnln]
On intermediate exit: if irevcm≥4, needc specifies the indices of the elements of c and/or cjac that must be assigned. If needc[i-1]>0, then the ith element of c and/or the available elements of the ith row of cjac must be evaluated at x.
iwork
Type: array< System..::..Int32 >[]()[][]
An array of size [liwork]
the dimension of the array iwork.
On initial entry: the dimension of the array iwork as declared in the (sub)program from which e04uf is called.
Constraint: liwork≥3×n+nclin+2×ncnln.
work
Type: array< System..::..Double >[]()[][]
An array of size [lwork]
the dimension of the array work.
On initial entry: the dimension of the array work as declared in the (sub)program from which e04uf is called.
Constraints:
  • if ncnln=0 and nclin=0, lwork≥21×n+2;
  • if ncnln=0 and nclin>0, lwork≥2×n 2+21×n+11×nclin+2;
  • if ncnln>0 and nclin≥0, lwork≥2×n 2+n×nclin+2×n×ncnln+21×n+11×nclin+22×ncnln+1.
The amounts of workspace provided and required may be (by default for e04uf) output on the current advisory message unit (as defined by (X04ABF not in this release)). As an alternative to computing liwork and lwork from the formulae given above, you may prefer to obtain appropriate values from the output of a preliminary run with liwork and lwork set to 1. (e04uf will then terminate with ifail=9.)
options
Type: NagLibrary..::..E04..::..e04ufOptions
An Object of type E04.e04ufOptions. Used to configure optional parameters to this method.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04uf is designed to solve the nonlinear programming problem – the minimization of a smooth nonlinear function subject to a set of constraints on the variables. The problem is assumed to be stated in the following form:
minimize x∈Rn​ ​F x  subject to  l≤xAL xc x≤u, (1)
where F x (the objective function) is a nonlinear function, AL is an nL by n constant matrix, and c x is an nN element vector of nonlinear constraint functions. (The matrix AL and the vector c x may be empty.) The objective function and the constraint functions are assumed to be smooth, i.e., at least twice-continuously differentiable. (The method of e04uf will usually solve (1) if there are only isolated discontinuities away from the solution.)
Note that although the bounds on the variables could be included in the definition of the linear constraints, we prefer to distinguish between them for reasons of computational efficiency. For the same reason, the linear constraints should not be included in the definition of the nonlinear constraints. Upper and lower bounds are specified for all the variables and for all the constraints. An equality constraint can be specified by setting li=ui. If certain bounds are not present, the associated elements of l or u can be set to special values that will be treated as -∞ or +∞. (See the description of the optional parameter Infinite Bound Size.)
If there are no nonlinear constraints in (1) and F is linear or quadratic then it will generally be more efficient to use one of e04mf, e04nc or e04nf, or e04nq if the problem is large and sparse. If the problem is large and sparse and does have nonlinear constraints, e04ug should be used, since e04uf treats all matrices as dense.
e04uf uses reverse communication for evaluating F x, c x and as many of their first partial derivatives as possible; any remaining derivatives are approximated by finite differences. See the description of the optional parameter Derivative Level.
On initial entry, you must supply an initial estimate of the solution to (1).
On intermediate exits, the calling program must compute appropriate values for the objective function, the nonlinear constraints or their derivatives, as specified by the parameter irevcm, and then re-enter the method.
For maximum reliability, it is preferable to provide all partial derivatives (see Chapter 8 of Gill et al. (1981), for a detailed discussion). If they cannot all be provided, it is advisable to provide as many as possible. While developing code to evaluate the objective function and the constraints, the optional parameter Verify should be used to check the calculation of any known derivatives.
The method used by e04uf is described in detail in [Algorithmic Details].
e04wd is an alternative method which uses a similar method, but with forward communication: that is, the objective and constraint functions are evaluated by methods, supplied as parameters to the method.

References

Dennis J E Jr and Moré J J (1977) Quasi-Newton methods, motivation and theory SIAM Rev. 19 46–89
Dennis J E Jr and Schnabel R B (1981) A new derivation of symmetric positive-definite secant updates nonlinear programming (eds O L Mangasarian, R R Meyer and S M Robinson) 4 167–199 Academic Press
Dennis J E Jr and Schnabel R B (1983) Numerical Methods for Unconstrained Optimization and Nonlinear Equations Prentice–Hall
Fletcher R (1987) Practical Methods of Optimization (2nd Edition) Wiley
Gill P E, Hammarling S, Murray W, Saunders M A and Wright M H (1986) Users' guide for LSSOL (Version 1.0) Report SOL 86-1 Department of Operations Research, Stanford University
Gill P E, Murray W, Saunders M A and Wright M H (1984a) Procedures for optimization problems with a mixture of bounds and general linear constraints ACM Trans. Math. Software 10 282–298
Gill P E, Murray W, Saunders M A and Wright M H (1984b) Users' guide for SOL/QPSOL version 3.2 Report SOL 84–5 Department of Operations Research, Stanford University
Gill P E, Murray W, Saunders M A and Wright M H (1986a) Some theoretical properties of an augmented Lagrangian merit function Report SOL 86–6R Department of Operations Research, Stanford University
Gill P E, Murray W, Saunders M A and Wright M H (1986b) Users' guide for NPSOL (Version 4.0): a Fortran package for nonlinear programming Report SOL 86-2 Department of Operations Research, Stanford University
Gill P E, Murray W and Wright M H (1981) Practical Optimization Academic Press
Hock W and Schittkowski K (1981) Test Examples for Nonlinear Programming Codes. Lecture Notes in Economics and Mathematical Systems 187 Springer–Verlag
Murtagh B A and Saunders M A (1983) MINOS 5.0 user's guide Report SOL 83-20 Department of Operations Research, Stanford University
Powell M J D (1974) Introduction to constrained optimization Numerical Methods for Constrained Optimization (eds P E Gill and W Murray) 1–28 Academic Press
Powell M J D (1983) Variable metric methods in constrained optimization Mathematical Programming: the State of the Art (eds A Bachem, M Grötschel and B Korte) 288–311 Springer–Verlag

Error Indicators and Warnings

Note: e04uf may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA, LDCJ, LDR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail<0
A negative value of ifail indicates an exit from e04uf because you set irevcm<0 during an intermediate exit. The value of ifail will be the same as your setting of irevcm.
ifail=1
The final iterate x satisfies the first-order Kuhn–Tucker conditions (see [Overview]) to the accuracy requested, but the sequence of iterates has not yet converged. e04uf was terminated because no further improvement could be made in the merit function (see [Description of the Printed Output]).
This value of ifail may occur in several circumstances. The most common situation is that you ask for a solution with accuracy that is not attainable with the given precision of the problem (as specified by the optional parameter Function Precision). This condition will also occur if, by chance, an iterate is an ‘exact’ Kuhn–Tucker point, but the change in the variables was significant at the previous iteration. (This situation often happens when minimizing very simple functions, such as quadratics.)
If the four conditions listed in [Parameters] for ifail=0 are satisfied, x is likely to be a solution of (1) even if ifail=1.
ifail=2
e04uf has terminated without finding a feasible point for the linear constraints and bounds, which means that either no feasible point exists for the given value of the optional parameter Linear Feasibility Tolerance, or no feasible point could be found in the number of iterations specified by the optional parameter Minor Iteration Limit. You should check that there are no constraint redundancies. If the data for the constraints are accurate only to an absolute precision σ, you should ensure that the value of the optional parameter Linear Feasibility Tolerance is greater than σ. For example, if all elements of AL are of order unity and are accurate to only three decimal places, Linear Feasibility Tolerance should be at least 10-3.
ifail=3
No feasible point could be found for the nonlinear constraints. The problem may have no feasible solution. This means that there has been a sequence of QP subproblems for which no feasible point could be found (indicated by I at the end of each line of intermediate printout produced by the major iterations; see [Description of the Printed Output]). This behaviour will occur if there is no feasible point for the nonlinear constraints. (However, there is no general test that can determine whether a feasible point exists for a set of nonlinear constraints.) If the infeasible subproblems occur from the very first major iteration, it is highly likely that no feasible point exists. If infeasibilities occur when earlier subproblems have been feasible, small constraint inconsistencies may be present. You should check the validity of constraints with negative values of istate. If you are convinced that a feasible point does exist, e04uf should be restarted at a different starting point.
ifail=4
The limiting number of iterations (as determined by the optional parameter Major Iteration Limit) has been reached.
If the algorithm appears to be making satisfactory progress, then optional parameter Major Iteration Limit may be too small. If so, either increase its value and rerun e04uf or, alternatively, rerun e04uf using the optional parameter Warm Start. If the algorithm seems to be making little or no progress however, then you should check for incorrect gradients or ill-conditioning as described under ifail=6.
Note that ill-conditioning in the working set is sometimes resolved automatically by the algorithm, in which case performing additional iterations may be helpful. However, ill-conditioning in the Hessian approximation tends to persist once it has begun, so that allowing additional iterations without altering r is usually inadvisable. If the quasi-Newton update of the Hessian approximation was reset during the latter major iterations (i.e., an R occurs at the end of each line of intermediate printout; see [Description of the Printed Output]), it may be worthwhile to try a Warm Start at the final point as suggested above.
ifail=5
Not used by this method.
ifail=6
x does not satisfy the first-order Kuhn–Tucker conditions (see [Overview]), and no improved point for the merit function (see [Description of the Printed Output]) could be found during the final linesearch.
This sometimes occurs because an overly stringent accuracy has been requested, i.e., the value of the optional parameter Optimality Tolerance (default value=εr 0.8, where εr is the value of the optional parameter Function Precision) is too small. In this case you should apply the four tests described under ifail=0 to determine whether or not the final solution is acceptable (see Gill et al. (1981), for a discussion of the attainable accuracy).
If many iterations have occurred in which essentially no progress has been made and e04uf has failed completely to move from the initial point, then values set by the calling program for the objective or constraint functions or their derivatives during intermediate exits may be incorrect. You should refer to comments under ifail=7 and check the gradients using the optional parameter Verify. Unfortunately, there may be small errors in the objective and constraint gradients that cannot be detected by the verification process. Finite difference approximations to first derivatives are catastrophically affected by even small inaccuracies. An indication of this situation is a dramatic alteration in the iterates if the finite difference interval is altered. One might also suspect this type of error if a switch is made to central differences even when Norm Gz and Violtn (see [Description of the Printed Output]) are large.
Another possibility is that the search direction has become inaccurate because of ill-conditioning in the Hessian approximation or the matrix of constraints in the working set; either form of ill-conditioning tends to be reflected in large values of Mnr (the number of iterations required to solve each QP subproblem; see [Description of the Printed Output]).
If the condition estimate of the projected Hessian (Cond Hz; see [Description of the Printed Output]) is extremely large, it may be worthwhile rerunning e04uf from the final point with the optional parameter Warm Start. In this situation, istate and clamda should be left unaltered and r should be reset to the identity matrix.
If the matrix of constraints in the working set is ill-conditioned (i.e., Cond T is extremely large; see [Description of Monitoring Information]), it may be helpful to run e04uf with a relaxed value of the optional parameter Feasibility Tolerance. (Constraint dependencies are often indicated by wide variations in size in the diagonal elements of the matrix T, whose diagonals will be printed if Major Print Level≥30.)
ifail=7
The user-supplied derivatives of the objective function and/or nonlinear constraints appear to be incorrect.
Large errors were found in the derivatives of the objective function and/or nonlinear constraints. This value of ifail will occur if the verification process indicated that at least one gradient or Jacobian element had no correct figures. You should refer to the printed output to determine which elements are suspected to be in error.
As a first-step, you should check that the code for the objective and constraint values is correct – for example, by computing the function at a point where the correct value is known. However, care should be taken that the chosen point fully tests the evaluation of the function. It is remarkable how often the values x=0 or x=1 are used in such a test, and how often the special properties of these numbers make the test meaningless.
Special care should be used in the test if computation of the objective function involves subsidiary data communicated in storage. Although the first evaluation of the function may be correct, subsequent calculations may be in error because some of the subsidiary data has accidentally been overwritten.
Gradient checking will be ineffective if the objective function uses information computed by the constraints, since they are not necessarily computed before each function evaluation.
Errors in programming the function may be quite subtle in that the function value is ‘almost’ correct. For example, the function may not be accurate to full precision because of the inaccurate calculation of a subsidiary quantity, or the limited accuracy of data upon which the function depends. A common error on machines where numerical calculations are usually performed in double precision is to include even one single precision constant in the calculation of the function; since some compilers do not convert such constants to double precision, half the correct figures may be lost by such a seemingly trivial error.
ifail=8
Not used by this method.
ifail=9
An input parameter is invalid.
Overflow
If overflow occurs then either an element of C is very large, or the singular values or singular vectors have been incorrectly supplied.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

If ifail=0 on final exit then the vector returned in the array x is an estimate of the solution to an accuracy of approximately Optimality Tolerance (default value=ε 0.8, where ε is the machine precision).

Parallelism and Performance

None.

Further Comments

Description of the Printed Output

This section describes the intermediate printout and final printout produced by e04uf. The intermediate printout is a subset of the monitoring information produced by e04uf at every iteration (see [Description of Monitoring Information]). You can control the level of printed output (see the description of the optional parameter Major Print Level). Note that the intermediate printout and final printout are produced only if Major Print Level≥10 (the default for e04uf, by default no output is produced by ).
The following line of summary output (<80 characters) is produced at every major iteration. In all cases, the values of the quantities printed are those in effect on completion of the given iteration.
Maj | is the major iteration count.
Mnr is the number of minor iterations required by the feasibility and optimality phases of the QP subproblem. Generally, Mnr will be 1 in the later iterations, since theoretical analysis predicts that the correct active set will be identified near the solution (see [Algorithmic Details]).
Note that Mnr may be greater than the optional parameter Minor Iteration Limit if some iterations are required for the feasibility phase.
Step | is the step αk taken along the computed search direction. On reasonably well-behaved problems, the unit step (i.e., αk=1) will be taken as the solution is approached.
Merit Function is the value of the augmented Lagrangian merit function (12) at the current iterate. This function will decrease at each iteration unless it was necessary to increase the penalty parameters (see [The Merit Function]). As the solution is approached, Merit Function will converge to the value of the objective function at the solution.
If the QP subproblem does not have a feasible point (signified by I at the end of the current output line) then the merit function is a large multiple of the constraint violations, weighted by the penalty parameters. During a sequence of major iterations with infeasible subproblems, the sequence of Merit Function values will decrease monotonically until either a feasible subproblem is obtained or e04uf terminates with ifail=3 (no feasible point could be found for the nonlinear constraints).
If there are no nonlinear constraints present (i.e., ncnln=0) then this entry contains Objective, the value of the objective function F x. The objective function will decrease monotonically to its optimal value when there are no nonlinear constraints.
Norm Gz | is ZT gFR, the Euclidean norm of the projected gradient (see [Solution of the Quadratic Programming Subproblem]). Norm Gz will be approximately zero in the neighbourhood of a solution.
Violtn | is the Euclidean norm of the residuals of constraints that are violated or in the predicted active set (not printed if ncnln is zero). Violtn will be approximately zero in the neighbourhood of a solution.
Cond Hz | is a lower bound on the condition number of the projected Hessian approximation HZ (HZ=ZT HFR Z=RZT RZ; see (6)). The larger this number, the more difficult the problem.
M | is printed if the quasi-Newton update has been modified to ensure that the Hessian approximation is positive definite (see [The Quasi-Newton Update]).
I | is printed if the QP subproblem has no feasible point.
C | is printed if central differences have been used to compute the unspecified objective and constraint gradients. If the value of Step is zero then the switch to central differences was made because no lower point could be found in the linesearch. (In this case, the QP subproblem is resolved with the central difference gradient and Jacobian.) If the value of Step is nonzero then central differences were computed because Norm Gz and Violtn imply that x is close to a Kuhn–Tucker point (see [Overview]).
L | is printed if the linesearch has produced a relative change in x greater than the value defined by the optional parameter Step Limit. If this output occurs frequently during later iterations of the run, optional parameter Step Limit should be set to a larger value.
R | is printed if the approximate Hessian has been refactorized. If the diagonal condition estimator of R indicates that the approximate Hessian is badly conditioned then the approximate Hessian is refactorized using column interchanges. If necessary, R is modified so that its diagonal condition estimator is bounded.
The final printout includes a listing of the status of every variable and constraint.
The following describes the printout for each variable. A full stop (.) is printed for any numerical value that is zero.
Varbl | gives the name (V) and index j, for j=1,2,…,n, of the variable.
State gives the state of the variable (FR if neither bound is in the working set, EQ if a fixed variable, LL if on its lower bound, UL if on its upper bound, TF if temporarily fixed at its current value). If Value lies outside the upper or lower bounds by more than the Feasibility Tolerance, State will be ++ or -- respectively.
A key is sometimes printed before State.
A | Alternative optimum possible. The variable is active at one of its bounds, but its Lagrange multiplier is essentially zero. This means that if the variable were allowed to start moving away from its bound then there would be no change to the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case the values of the Lagrange multipliers might also change.
D | Degenerate. The variable is free, but it is equal to (or very close to) one of its bounds.
I | Infeasible. The variable is currently violating one of its bounds by more than the Feasibility Tolerance.
Value | is the value of the variable at the final iteration.
Lower Bound | is the lower bound specified for the variable. None indicates that bl[j-1]≤-bigbnd.
Upper Bound | is the upper bound specified for the variable. None indicates that bu[j-1]≥bigbnd.
Lagr Mult | is the Lagrange multiplier for the associated bound. This will be zero if State is FR unless bl[j-1]≤-bigbnd and bu[j-1]≥bigbnd, in which case the entry will be blank. If x is optimal, the multiplier should be non-negative if State is LL and non-positive if State is UL.
Slack | is the difference between the variable Value and the nearer of its (finite) bounds bl[j-1] and bu[j-1]. A blank entry indicates that the associated variable is not bounded (i.e., bl[j-1]≤-bigbnd and bu[j-1]≥bigbnd).
The meaning of the printout for linear and nonlinear constraints is the same as that given above for variables, with ‘variable’ replaced by ‘constraint’, bl[j-1] and bu[j-1] replaced by bl[n+j-1] and bu[n+j-1] respectively and with the following changes in the heading:
L Con | gives the name (L) and index j, for j=1,2,…,nL, of the linear constraint.
N Con | gives the name (N) and index (j-nL), for j=nL+1,…,nL+nN, of the nonlinear constraint.
Note that movement off a constraint (as opposed to a variable moving away from its bound) can be interpreted as allowing the entry in the Slack column to become positive.
Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.

Example

This is based on Problem 71 in Murtagh and Saunders (1983) and involves the minimization of the nonlinear function
F x=x 1x 4 x 1+x 2+x 3+x 3
subject to the bounds
1≤x 1≤51≤x 2≤51≤x 3≤51≤x 4≤5
to the general linear constraint
x 1+x 2+x 3+x 4≤20,
and to the nonlinear constraints
x 12+x 22+x 32+x 42≤40,x 1x 2x 3x 4≥25.
The initial point, which is infeasible, is
x 0=1,5,5,1 T,
and F x 0=16.
The optimal solution (to five figures) is
x*=1.0,4.7430,3.8211,1.3794 T,
and F x*=17.014. One bound constraint and both nonlinear constraints are active at the solution.

Example program (C#): e04ufe.cs

Example program data: e04ufe.d

Example program results: e04ufe.r

Algorithmic Details

This section contains a detailed description of the method used by e04uf.

Overview

e04uf is essentially identical to the method NPSOL described in Gill et al. (1986b).
At a solution of (1), some of the constraints will be active, i.e., satisfied exactly. An active simple bound constraint implies that the corresponding variable is fixed at its bound, and hence the variables are partitioned into fixed and free variables. Let C denote the m by n matrix of gradients of the active general linear and nonlinear constraints. The number of fixed variables will be denoted by nFX, with nFR (nFR=n-nFX) the number of free variables. The subscripts ‘FX’ and ‘FR’ on a vector or matrix will denote the vector or matrix composed of the elements corresponding to fixed or free variables.
A point x is a first-order Kuhn–Tucker point for (1) (see Powell (1974)) if the following conditions hold:
(i) | x is feasible;
(ii) there exist vectors ξ and λ (the Lagrange multiplier vectors for the bound and general constraints) such that
g=CT λ+ξ (2)
where g is the gradient of F evaluated at x and ξj=0 if the jth variable is free.
(iii) | the Lagrange multiplier corresponding to an inequality constraint active at its lower bound must be non-negative. It is non-positive for an inequality constraint active at its upper bound.
Let Z denote a matrix whose columns form a basis for the set of vectors orthogonal to the rows of CFR; i.e., CFR Z=0. An equivalent statement of the condition (2) in terms of Z is
ZT gFR=0.
The vector ZT gFR is termed the projected gradient of F at x. Certain additional conditions must be satisfied in order for a first-order Kuhn–Tucker point to be a solution of (1) (see Powell (1974)).
e04uf implements a sequential quadratic programming (SQP) method. For an overview of SQP methods, see Fletcher (1987), Gill et al. (1981) and Powell (1983).
The basic structure of e04uf involves major and minor iterations. The major iterations generate a sequence of iterates xk that converge to x*, a first-order Kuhn–Tucker point of (1). At a typical major iteration, the new iterate x- is defined by
x-=x+αp (3)
where x is the current iterate, the non-negative scalar α is the step length, and p is the search direction. (For simplicity, we shall always consider a typical iteration and avoid reference to the index of the iteration.) Also associated with each major iteration are estimates of the Lagrange multipliers and a prediction of the active set.
The search direction p in (3) is the solution of a quadratic programming subproblem of the form
minimizep gT p+12 pT Hp  subject to  l-≤pAL pAN p≤u-, (4)
where g is the gradient of F at x, the matrix H is a positive definite quasi-Newton approximation to the Hessian of the Lagrangian function (see [The Quasi-Newton Update]), and AN is the Jacobian matrix of c evaluated at x. (Finite difference estimates may be used for g and AN; see the optional parameter Derivative Level.) Let l in (1) be partitioned into three sections: lB, lL and lN, corresponding to the bound, linear and nonlinear constraints. The vector l- in (4) is similarly partitioned and is defined as
l-B=lB-x,  l-L=lL-AL x,   and  l-N=lN-c,
where c is the vector of nonlinear constraints evaluated at x. The vector u- is defined in an analogous fashion.
The estimated Lagrange multipliers at each major iteration are the Lagrange multipliers from the subproblem (4) (and similarly for the predicted active set). (The numbers of bounds, general linear and nonlinear constraints in the QP active set are the quantities Bnd, Lin and Nln in the monitoring file output of e04uf; see [Description of Monitoring Information].) In e04uf, (4) is solved using e04nc. Since solving a quadratic program is itself an iterative procedure, the minor iterations of e04uf are the iterations of e04nc. (More details about solving the subproblem are given in [Solution of the Quadratic Programming Subproblem].)
Certain matrices associated with the QP subproblem are relevant in the major iterations. Let the subscripts ‘FX’ and ‘FR’ refer to the predicted fixed and free variables, and let C denote the m by n matrix of gradients of the general linear and nonlinear constraints in the predicted active set. Firstly, we have available the TQ factorization of CFR:
CFRQFR=0 T, (5)
where T is a nonsingular m by m reverse-triangular matrix (i.e., t ij=0 if i+j<m), and the nonsingular nFR by nFR matrix QFR is the product of orthogonal transformations (see Gill et al. (1984b)). Secondly, we have the upper triangular Cholesky factor R of the transformed and reordered Hessian matrix
RT R=HQ≡QT H~Q, (6)
where H~ is the Hessian H with rows and columns permuted so that the free variables are first and Q is the n by n matrix
Q=QFRIFX (7)
with IFX the identity matrix of order nFX. If the columns of QFR are partitioned so that
QFR=ZY,
then the nZ (nZ≡nFR-m) columns of Z form a basis for the null space of CFR. The matrix Z is used to compute the projected gradient ZT gFR at the current iterate. (The values Nz and Norm Gz printed by e04uf give nZ and ZT gFR, see [Description of Monitoring Information].)
A theoretical characteristic of SQP methods is that the predicted active set from the QP subproblem (4) is identical to the correct active set in a neighbourhood of x*. In e04uf, this feature is exploited by using the QP active set from the previous iteration as a prediction of the active set for the next QP subproblem, which leads in practice to optimality of the subproblems in only one iteration as the solution is approached. Separate treatment of bound and linear constraints in e04uf also saves computation in factorizing CFR and HQ.
Once p has been computed, the major iteration proceeds by determining a step length α that produces a ‘sufficient decrease’ in an augmented Lagrangian merit function (see [The Merit Function]). Finally, the approximation to the transformed Hessian matrix HQ is updated using a modified BFGS quasi-Newton update (see [The Quasi-Newton Update]) to incorporate new curvature information obtained in the move from x to x-.
On entry to e04uf, an iterative procedure from e04nc is executed, starting with the user-supplied initial point, to find a point that is feasible with respect to the bounds and linear constraints (using the tolerance specified by the optional parameter Linear Feasibility Tolerance). If no feasible point exists for the bound and linear constraints, (1) has no solution and e04uf terminates. Otherwise, the problem functions will thereafter be evaluated only at points that are feasible with respect to the bounds and linear constraints. The only exception involves variables whose bounds differ by an amount comparable to the finite difference interval (see the discussion of the optional parameter Difference Interval). In contrast to the bounds and linear constraints, it must be emphasized that the nonlinear constraints will not generally be satisfied until an optimal point is reached.
Facilities are provided to check whether the user-supplied gradients appear to be correct (see the description of the optional parameter Verify). In general, the check is provided at the first point that is feasible with respect to the linear constraints and bounds. However, you may request that the check be performed at the initial point.
In summary, the method of e04uf first determines a point that satisfies the bound and linear constraints. Thereafter, each iteration includes:
(a) | the solution of a quadratic programming subproblem;
(b) | a linesearch with an augmented Lagrangian merit function; and
(c) | a quasi-Newton update of the approximate Hessian of the Lagrangian function.
These three procedures are described in more detail in [Solution of the Quadratic Programming Subproblem] to [The Quasi-Newton Update].

Solution of the Quadratic Programming Subproblem

The search direction p is obtained by solving (4) using e04nc (see Gill et al. (1986)), which was specifically designed to be used within an SQP algorithm for nonlinear programming.
e04nc is based on a two-phase (primal) quadratic programming method. The two phases of the method are: finding an initial feasible point by minimizing the sum of infeasibilities (the feasibility phase) and minimizing the quadratic objective function within the feasible region (the optimality phase). The computations in both phases are performed by the same methods. The two-phase nature of the algorithm is reflected by changing the function being minimized from the sum of infeasibilities to the quadratic objective function.
In general, a quadratic program must be solved by iteration. Let p denote the current estimate of the solution of (4); the new iterate p- is defined by
p-=p+σd (8)
where, as in (3), σ is a non-negative step length and d is a search direction.
At the beginning of each iteration of e04nc, a working set is defined of constraints (general and bound) that are satisfied exactly. The vector d is then constructed so that the values of constraints in the working set remain unaltered for any move along d. For a bound constraint in the working set, this property is achieved by setting the corresponding element of d to zero, i.e., by fixing the variable at its bound. As before, the subscripts ‘FX’ and ‘FR’ denote selection of the elements associated with the fixed and free variables.
Let C denote the sub-matrix of rows of
ALAN
corresponding to general constraints in the working set. The general constraints in the working set will remain unaltered if
CFRdFR=0, (9)
which is equivalent to defining dFR as
dFR=Z dZ (10)
for some vector dZ, where Z is the matrix associated with the TQ factorization (5) of CFR.
The definition of dZ in (10) depends on whether the current p is feasible. If not, dZ is zero except for an element γ in the jth position, where j and γ are chosen so that the sum of infeasibilities is decreasing along d. (For further details, see Gill et al. (1986).) In the feasible case, dZ satisfies the equations
RZT RZdZ=-ZT qFR, (11)
where RZ is the Cholesky factor of ZT HFR Z and q is the gradient of the quadratic objective function q=g+Hp. (The vector ZT qFR is the projected gradient of the QP.) With (11), p+d is the minimizer of the quadratic objective function subject to treating the constraints in the working set as equalities.
If the QP projected gradient is zero, the current point is a constrained stationary point in the subspace defined by the working set. During the feasibility phase, the projected gradient will usually be zero only at a vertex (although it may vanish at non-vertices in the presence of constraint dependencies). During the optimality phase, a zero projected gradient implies that p minimizes the quadratic objective function when the constraints in the working set are treated as equalities. In either case, Lagrange multipliers are computed. Given a positive constant δ of the order of the machine precision, the Lagrange multiplier μj corresponding to an inequality constraint in the working set is said to be optimal if μj≤δ when the jth constraint is at its upper bound, or if μj≥-δ when the associated constraint is at its lower bound. If any multiplier is nonoptimal, the current objective function (either the true objective or the sum of infeasibilities) can be reduced by deleting the corresponding constraint from the working set.
If optimal multipliers occur during the feasibility phase and the sum of infeasibilities is nonzero, no feasible point exists. The QP algorithm will then continue iterating to determine the minimum sum of infeasibilities. At this point, the Lagrange multiplier μj will satisfy -1+δ≤μj≤δ for an inequality constraint at its upper bound, and -δ≤μj≤1+δ for an inequality at its lower bound. The Lagrange multiplier for an equality constraint will satisfy μj≤1+δ.
The choice of step length σ in the QP iteration (8) is based on remaining feasible with respect to the satisfied constraints. During the optimality phase, if p+d is feasible, σ will be taken as unity. (In this case, the projected gradient at p- will be zero.) Otherwise, σ is set to σM, the step to the ‘nearest’ constraint, which is added to the working set at the next iteration.
Each change in the working set leads to a simple change to CFR: if the status of a general constraint changes, a row of CFR is altered; if a bound constraint enters or leaves the working set, a column of CFR changes. Explicit representations are recurred of the matrices T, QFR and R, and of the vectors QT q and QT g.

The Merit Function

After computing the search direction as described in [Solution of the Quadratic Programming Subproblem], each major iteration proceeds by determining a step length α in (3) that produces a ‘sufficient decrease’ in the augmented Lagrangian merit function
L x,λ,s=F x-∑i λi ci x-si+12∑i ρi ci x-si 2, (12)
where x, λ and s vary during the linesearch. The summation terms in (12) involve only the nonlinear constraints. The vector λ is an estimate of the Lagrange multipliers for the nonlinear constraints of (1). The non-negative slack variables si allow nonlinear inequality constraints to be treated without introducing discontinuities. The solution of the QP subproblem (4) provides a vector triple that serves as a direction of search for the three sets of variables. The non-negative vector ρ of penalty parameters is initialized to zero at the beginning of the first major iteration. Thereafter, selected elements are increased whenever necessary to ensure descent for the merit function. Thus, the sequence of norms of ρ (the printed quantity Penalty; see [Description of Monitoring Information]) is generally nondecreasing, although each ρi may be reduced a limited number of times.
The merit function (12) and its global convergence properties are described in Gill et al. (1986a).

The Quasi-Newton Update

The matrix H in (4) is a positive definite quasi-Newton approximation to the Hessian of the Lagrangian function. (For a review of quasi-Newton methods, see Dennis and Schnabel (1983).) At the end of each major iteration, a new Hessian approximation H- is defined as a rank-two modification of H. In e04uf, the BFGS (Broyden–Fletcher–Goldfarb–Shanno) quasi-Newton update is used:
H-=H-1 sT Hs Hs sT H+1 yT s y yT, (13)
where s=x--x (the change in x).
In e04uf, H is required to be positive definite. If H is positive definite, H- defined by (13) will be positive definite if and only if yT s is positive (see Dennis and Moré (1977)). Ideally, y in (13) would be taken as yL, the change in gradient of the Lagrangian function
yL=g--A-NT μN-g+ANT μN, (14)
where μN denotes the QP multipliers associated with the nonlinear constraints of the original problem. If yLT s is not sufficiently positive, an attempt is made to perform the update with a vector y of the form
y=yL+∑i=1 mN ωi ai x^ci x^-ai x ci x,
where ωi≥0. If no such vector can be found, the update is performed with a scaled yL. In this case, M is printed to indicate that the update was modified.
Rather than modifying H itself, the Cholesky factor of the transformed Hessian HQ (6) is updated, where Q is the matrix from (5) associated with the active set of the QP subproblem. The update (13) is equivalent to the following update to HQ:
H-Q=HQ-1 sQT HQsQ HQsQ sQT HQ+1 yQT sQ yQ yQT, (15)
where yQ=QT y, and sQ=QT s. This update may be expressed as a rank-one update to R (see Dennis and Schnabel (1981)).

Description of Monitoring Information

This section describes the long line of output (>80 characters) which forms part of the monitoring information produced by e04uf. (See also the description of the optional parameters Major Print Level, Minor Print Level and Monitoring File.) You can control the level of printed output (see the description of the optional parameter Major Print Level).
When Major Print Level≥5 and Monitoring File≥0, the following line of output is produced at every major iteration of e04uf on the unit number specified by Monitoring File. In all cases, the values of the quantities printed are those in effect on completion of the given iteration.
Maj | is the major iteration count.
Mnr is the number of minor iterations required by the feasibility and optimality phases of the QP subproblem. Generally, Mnr will be 1 in the later iterations, since theoretical analysis predicts that the correct active set will be identified near the solution (see [Algorithmic Details]).
Note that Mnr may be greater than the optional parameter Minor Iteration Limit if some iterations are required for the feasibility phase.
Step | is the step αk taken along the computed search direction. On reasonably well-behaved problems, the unit step (i.e., αk=1) will be taken as the solution is approached.
Nfun | is the cumulative number of evaluations of the objective function needed for the linesearch. Evaluations needed for the estimation of the gradients by finite differences are not included. Nfun is printed as a guide to the amount of work required for the linesearch.
Merit Function is the value of the augmented Lagrangian merit function (12) at the current iterate. This function will decrease at each iteration unless it was necessary to increase the penalty parameters (see [The Merit Function]). As the solution is approached, Merit Function will converge to the value of the objective function at the solution.
If the QP subproblem does not have a feasible point (signified by I at the end of the current output line) then the merit function is a large multiple of the constraint violations, weighted by the penalty parameters. During a sequence of major iterations with infeasible subproblems, the sequence of Merit Function values will decrease monotonically until either a feasible subproblem is obtained or e04uf terminates with ifail=3 (no feasible point could be found for the nonlinear constraints).
If there are no nonlinear constraints present (i.e., ncnln=0) then this entry contains Objective, the value of the objective function F x. The objective function will decrease monotonically to its optimal value when there are no nonlinear constraints.
Norm Gz | is ZT gFR, the Euclidean norm of the projected gradient (see [Solution of the Quadratic Programming Subproblem]). Norm Gz will be approximately zero in the neighbourhood of a solution.
Violtn | is the Euclidean norm of the residuals of constraints that are violated or in the predicted active set (not printed if ncnln is zero). Violtn will be approximately zero in the neighbourhood of a solution.
Nz | is the number of columns of Z (see [Solution of the Quadratic Programming Subproblem]). The value of Nz is the number of variables minus the number of constraints in the predicted active set; i.e., Nz=n-Bnd+Lin+Nln.
Bnd | is the number of simple bound constraints in the predicted active set.
Lin | is the number of general linear constraints in the predicted working set.
Nln | is the number of nonlinear constraints in the predicted active set (not printed if ncnln is zero).
Penalty | is the Euclidean norm of the vector of penalty parameters used in the augmented Lagrangian merit function (not printed if ncnln is zero).
Cond H | is a lower bound on the condition number of the Hessian approximation H.
Cond Hz | is a lower bound on the condition number of the projected Hessian approximation HZ (HZ=ZT HFR Z=RZT RZ; see (6)). The larger this number, the more difficult the problem.
Cond T | is a lower bound on the condition number of the matrix of predicted active constraints.
Conv is a three-letter indication of the status of the three convergence tests (16)–(18) defined in the description of the optional parameter Optimality Tolerance. Each letter is T if the test is satisfied and F otherwise. The three tests indicate whether:
(i) | the sequence of iterates has converged;
(ii) | the projected gradient (Norm Gz) is sufficiently small; and
(iii) | the norm of the residuals of constraints in the predicted active set (Violtn) is small enough.
If any of these indicators is F when e04uf terminates with ifail=0, you should check the solution carefully.
M | is printed if the quasi-Newton update has been modified to ensure that the Hessian approximation is positive definite (see [The Quasi-Newton Update]).
I | is printed if the QP subproblem has no feasible point.
C | is printed if central differences have been used to compute the unspecified objective and constraint gradients. If the value of Step is zero then the switch to central differences was made because no lower point could be found in the linesearch. (In this case, the QP subproblem is resolved with the central difference gradient and Jacobian.) If the value of Step is nonzero then central differences were computed because Norm Gz and Violtn imply that x is close to a Kuhn–Tucker point (see [Overview]).
L | is printed if the linesearch has produced a relative change in x greater than the value defined by the optional parameter Step Limit. If this output occurs frequently during later iterations of the run, optional parameter Step Limit should be set to a larger value.
On entry: need not be initialized if the (default) optional parameter Cold Start is used.
If the optional parameter Warm Start has been chosen, r must contain the upper triangular Cholesky factor R of the initial approximation of the Hessian of the Lagrangian function, with the variables in the natural order. Elements not in the upper triangular part of r are assumed to be zero and need not be assigned.
On exit: if Hessian=NO, r contains the upper triangular Cholesky factor R of QT H~Q, an estimate of the transformed and reordered Hessian of the Lagrangian at x (see (6) in [Overview]). If Hessian=YES, r contains the upper triangular Cholesky factor R of H, the approximate (untransformed) Hessian of the Lagrangian, with the variables in the natural order.

See Also

E04 Class
E04 Members


e04ug Method

[image]

NAG Library for .NET Release 2
E04..::e04ug Method
E04 Class See Also Send Feedback
e04ug solves sparse nonlinear programming problems.

Syntax

C#
public static void e04ug(
    E04..::..E04UG_CONFUN confun,
    E04..::..E04UG_OBJFUN objfun,
    int n,
    int m,
    int ncnln,
    int nonln,
    int njnln,
    int iobj,
    int nnz,
    double[] a,
    int[] ha,
    int[] ka,
    double[] bl,
    double[] bu,
    string start,
    int nname,
    string[] names,
    ref int ns,
    double[] xs,
    int[] istate,
    double[] clamda,
    out int miniz,
    out int minz,
    out int ninf,
    out double sinf,
    out double obj,
    int[] iz,
    double[] z,
    E04..::..e04ugOptions options,
    out int ifail
)
Visual Basic
Public Shared Sub e04ug ( _
    confun As E04..::..E04UG_CONFUN, _
    objfun As E04..::..E04UG_OBJFUN, _
    n As Integer, _
    m As Integer, _
    ncnln As Integer, _
    nonln As Integer, _
    njnln As Integer, _
    iobj As Integer, _
    nnz As Integer, _
    a As Double(), _
    ha As Integer(), _
    ka As Integer(), _
    bl As Double(), _
    bu As Double(), _
    start As String, _
    nname As Integer, _
    names As String(), _
    ByRef ns As Integer, _
    xs As Double(), _
    istate As Integer(), _
    clamda As Double(), _
    <OutAttribute> ByRef miniz As Integer, _
    <OutAttribute> ByRef minz As Integer, _
    <OutAttribute> ByRef ninf As Integer, _
    <OutAttribute> ByRef sinf As Double, _
    <OutAttribute> ByRef obj As Double, _
    iz As Integer(), _
    z As Double(), _
    options As E04..::..e04ugOptions, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04ug(
    E04..::..E04UG_CONFUN^ confun,
    E04..::..E04UG_OBJFUN^ objfun,
    int n,
    int m,
    int ncnln,
    int nonln,
    int njnln,
    int iobj,
    int nnz,
    array<double>^ a,
    array<int>^ ha,
    array<int>^ ka,
    array<double>^ bl,
    array<double>^ bu,
    String^ start,
    int nname,
    array<String^>^ names,
    int% ns,
    array<double>^ xs,
    array<int>^ istate,
    array<double>^ clamda,
    [OutAttribute] int% miniz,
    [OutAttribute] int% minz,
    [OutAttribute] int% ninf,
    [OutAttribute] double% sinf,
    [OutAttribute] double% obj,
    array<int>^ iz,
    array<double>^ z,
    E04..::..e04ugOptions^ options,
    [OutAttribute] int% ifail
)
F#
static member e04ug :
        confun : E04..::..E04UG_CONFUN *
        objfun : E04..::..E04UG_OBJFUN *
        n : int *
        m : int *
        ncnln : int *
        nonln : int *
        njnln : int *
        iobj : int *
        nnz : int *
        a : float[] *
        ha : int[] *
        ka : int[] *
        bl : float[] *
        bu : float[] *
        start : string *
        nname : int *
        names : string[] *
        ns : int byref *
        xs : float[] *
        istate : int[] *
        clamda : float[] *
        miniz : int byref *
        minz : int byref *
        ninf : int byref *
        sinf : float byref *
        obj : float byref *
        iz : int[] *
        z : float[] *
        options : E04..::..e04ugOptions *
        ifail : int byref -> unit

Parameters

confun
Type: NagLibrary..::..E04..::..E04UG_CONFUN
confun must calculate the vector F x of nonlinear constraint functions and (optionally) its Jacobian =∂F∂x for a specified n 1′′ (≤n) element vector x. If there are no nonlinear constraints (i.e., ncnln=0), confun will never be called by e04ug and confun may be the dummy method E04UGM. (E04UGM is included in the NAG Library.) If there are nonlinear constraints, the first call to confun will occur before the first call to objfun.

A delegate of type E04UG_CONFUN.

objfun
Type: NagLibrary..::..E04..::..E04UG_OBJFUN
objfun must calculate the nonlinear part of the objective function f x and (optionally) its gradient =∂f∂x for a specified n 1′ (≤n) element vector x. If there are no nonlinear objective variables (i.e., nonln=0), objfun will never be called by e04ug and objfun may be the dummy method E04UGN. (E04UGN is included in the NAG Library.)

A delegate of type E04UG_OBJFUN.

n
Type: System..::..Int32
On entry: n, the number of variables (excluding slacks). This is the number of columns in the full Jacobian matrix A.
Constraint: n≥1.
m
Type: System..::..Int32
On entry: m, the number of general constraints (or slacks). This is the number of rows in A, including the free row (if any; see iobj). Note that A must contain at least one row. If your problem has no constraints, or only upper and lower bounds on the variables, then you must include a dummy ‘free’ row consisting of a single (zero) element subject to ‘infinite’ upper and lower bounds. Further details can be found under the descriptions for iobj, nnz, a, ha, ka, bl and bu.
Constraint: m≥1.
ncnln
Type: System..::..Int32
On entry: nN, the number of nonlinear constraints.
Constraint: 0≤ncnln≤m.
nonln
Type: System..::..Int32
On entry: n 1′, the number of nonlinear objective variables. If the objective function is nonlinear, the leading n 1′ columns of A belong to the nonlinear objective variables. (See also the description for njnln.)
Constraint: 0≤nonln≤n.
njnln
Type: System..::..Int32
On entry: n 1′′, the number of nonlinear Jacobian variables. If there are any nonlinear constraints, the leading n 1′′ columns of A belong to the nonlinear Jacobian variables. If n 1′>0 and n 1′′>0, the nonlinear objective and Jacobian variables overlap. The total number of nonlinear variables is given by n-=max n 1′,n 1′′.
Constraints:
  • if ncnln=0, njnln=0;
  • if ncnln>0, 1≤njnln≤n.
iobj
Type: System..::..Int32
On entry: if iobj>ncnln, row iobj of A is a free row containing the nonzero elements of the linear part of the objective function.
iobj=0
There is no free row.
iobj=-1
There is a dummy ‘free’ row.
Constraints:
  • if iobj>0, ncnln<iobj≤m;
  • otherwise iobj≥-1.
nnz
Type: System..::..Int32
On entry: the number of nonzero elements in A (including the Jacobian for any nonlinear constraints). If iobj=-1, set nnz=1.
Constraint: 1≤nnz≤n×m.
a
Type: array< System..::..Double >[]()[][]
An array of size [nnz]
On entry: the nonzero elements of the Jacobian matrix A, ordered by increasing column index. Since the constraint Jacobian matrix J x′′ must always appear in the top left-hand corner of A, those elements in a column associated with any nonlinear constraints must come before any elements belonging to the linear constraint matrix G and the free row (if any; see iobj).
In general, a is partitioned into a nonlinear part and a linear part corresponding to the nonlinear variables and linear variables in the problem. Elements in the nonlinear part may be set to any value (e.g., zero) because they are initialized at the first point that satisfies the linear constraints and the upper and lower bounds.
If Derivative Level=2 or 3, the nonlinear part may also be used to store any constant Jacobian elements. Note that if confun does not define the constant Jacobian element fjac[i-1] then the missing value will be obtained directly from a[j] for some j≥i.
If Derivative Level=0 or 1, unassigned elements of fjac are not treated as constant; they are estimated by finite differences, at nontrivial expense.
The linear part must contain the nonzero elements of G and the free row (if any). If iobj=-1, set a[0]=0. Elements with the same row and column indices are not allowed. (See also the descriptions for ha and ka.)
On exit: elements in the nonlinear part corresponding to nonlinear Jacobian variables are overwritten.
ha
Type: array< System..::..Int32 >[]()[][]
An array of size [nnz]
On entry: ha[i-1] must contain the row index of the nonzero element stored in a[i-1], for i=1,2,…,nnz. The row indices for a column may be supplied in any order subject to the condition that those elements in a column associated with any nonlinear constraints must appear before those elements associated with any linear constraints (including the free row, if any). Note that confun must define the Jacobian elements in the same order. If iobj=-1, set ha[0]=1.
Constraint: 1≤ha[i-1]≤m, for i=1,2,…,nnz.
ka
Type: array< System..::..Int32 >[]()[][]
An array of size [n+1]
On entry: ka[j-1] must contain the index in a of the start of the jth column, for j=1,2,…,n. To specify the jth column as empty, set ka[j-1]=ka[j]. Note that the first and last elements of ka must be such that ka[0]=1 and ka[n]=nnz+1. If iobj=-1, set ka[j-1]=2, for j=2,3,…,n.
Constraints:
  • ka[0]=1;
  • ka[j-1]≥1, for j=2,3,…,n;
  • ka[n]=nnz+1;
  • 0≤ka[j]-ka[j-1]≤m, for j=1,2,…,n.
bl
Type: array< System..::..Double >[]()[][]
An array of size [n+m]
On entry: l, the lower bounds for all the variables and general constraints, in the following order. The first n elements of bl must contain the bounds on the variables x, the next ncnln elements the bounds for the nonlinear constraints F x (if any) and the next (m-ncnln) elements the bounds for the linear constraints Gx and the free row (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j-1]≤-bigbnd. To specify the jth constraint as an equality, set bl[j-1]=bu[j-1]=β, say, where β<bigbnd. If iobj=-1, set bl[n+abs iobj-1]≤-bigbnd.
Constraint: if ncnln<iobj≤m or iobj=-1, bl[n+abs iobj-1]≤-bigbnd
(See also the description for bu.)
bu
Type: array< System..::..Double >[]()[][]
An array of size [n+m]
On entry: u, the upper bounds for all the variables and general constraints, in the following order. The first n elements of bu must contain the bounds on the variables x, the next ncnln elements the bounds for the nonlinear constraints F x (if any) and the next (m-ncnln) elements the bounds for the linear constraints Gx and the free row (if any). To specify a nonexistent upper bound (i.e., uj=+∞), set bu[j-1]≥bigbnd. To specify the jth constraint as an equality, set bu[j-1]=bl[j-1]=β, say, where β<bigbnd. If iobj=-1, set bu[n+abs iobj-1]≥bigbnd.
Constraints:
  • if ncnln<iobj≤m or iobj=-1, bu[n+abs iobj-1]≥bigbnd;
  • bl[j-1]≤bu[j-1], for j=1,2,…,n+m;
  • if bl[j-1]=bu[j-1]=β, β<bigbnd.
start
Type: System..::..String
On entry: indicates how a starting basis is to be obtained.
start="C"
An internal Crash procedure will be used to choose an initial basis.
start="W"
A basis is already defined in istate and ns (probably from a previous call).
Constraint: start="C" or "W".
nname
Type: System..::..Int32
On entry: the number of column (i.e., variable) and row (i.e., constraint) names supplied in names.
nname=1
There are no names. Default names will be used in the printed output.
nname=n+m
All names must be supplied.
Constraint: nname=1 or n+m.
names
Type: array< System..::..String >[]()[][]
An array of size [nname]
On entry: specifies the column and row names to be used in the printed output.
If nname=1, names is not referenced and the printed output will use default names for the columns and rows.
If nname=n+m, the first n elements must contain the names for the columns, the next ncnln elements must contain the names for the nonlinear rows (if any) and the next m-ncnln elements must contain the names for the linear rows (if any) to be used in the printed output. Note that the name for the free row or dummy ‘free’ row must be stored in names[n+abs iobj-1].
ns
Type: System..::..Int32 %
On entry: nS, the number of superbasics. It need not be specified if start="C", but must retain its value from a previous call when start="W".
On exit: the final number of superbasics.
xs
Type: array< System..::..Double >[]()[][]
An array of size [n+m]
On entry: the initial values of the variables and slacks x,s. (See the description for istate.)
On exit: the final values of the variables and slacks x,s.
istate
Type: array< System..::..Int32 >[]()[][]
An array of size [n+m]
On entry: if start="C", the first n elements of istate and xs must specify the initial states and values, respectively, of the variables x. (The slacks s need not be initialized.) An internal Crash procedure is then used to select an initial basis matrix B. The initial basis matrix will be triangular (neglecting certain small elements in each column). It is chosen from various rows and columns of A-I. Possible values for istate[j-1] are as follows:
istate[j-1] | State of xs[j-1] during Crash procedure
0 or 1 | Eligible for the basis
2 | Ignored
3 | Eligible for the basis (given preference over 0 or 1)
4 or 5 | Ignored
If nothing special is known about the problem, or there is no wish to provide special information, you may set istate[j-1]=0 and xs[j-1]=0.0, for j=1,2,…,n. All variables will then be eligible for the initial basis. Less trivially, to say that the jth variable will probably be equal to one of its bounds, set istate[j-1]=4 and xs[j-1]=bl[j-1] or istate[j-1]=5 and xs[j-1]=bu[j-1] as appropriate.
Following the Crash procedure, variables for which istate[j-1]=2 are made superbasic. Other variables not selected for the basis are then made nonbasic at the value xs[j-1] if bl[j-1]≤xs[j-1]≤bu[j-1], or at the value bl[j-1] or bu[j-1] closest to xs[j-1].
If start="W", istate and xs must specify the initial states and values, respectively, of the variables and slacks x,s. If the method has been called previously with the same values of n and m, istate already contains satisfactory information.
Constraints:
  • if start="C", 0≤istate[j-1]≤5, for j=1,2,…,n;
  • if start="W", 0≤istate[j-1]≤3, for j=1,2,…,n+m.
On exit: the final states of the variables and slacks x,s. The significance of each possible value of istate[j-1] is as follows:
istate[j-1] | State of variable j | Normal value of xs[j-1]
0 | Nonbasic | bl[j-1]
1 | Nonbasic | bu[j-1]
2 | Superbasic | Between bl[j-1] and bu[j-1]
3 | Basic | Between bl[j-1] and bu[j-1]
If ninf=0, basic and superbasic variables may be outside their bounds by as much as the value of the optional parameter Minor Feasibility Tolerance. Note that if scaling is specified, the optional parameter Minor Feasibility Tolerance applies to the variables of the scaled problem. In this case, the variables of the original problem may be as much as 0.1 outside their bounds, but this is unlikely unless the problem is very badly scaled.
Very occasionally some nonbasic variables may be outside their bounds by as much as the optional parameter Minor Feasibility Tolerance and there may be some nonbasic variables for which xs[j-1] lies strictly between its bounds.
If ninf>0, some basic and superbasic variables may be outside their bounds by an arbitrary amount (bounded by sinf if scaling was not used).
clamda
Type: array< System..::..Double >[]()[][]
An array of size [n+m]
On entry: if ncnln>0, clamda[j-1] must contain a Lagrange multiplier estimate for the jth nonlinear constraint Fj x, for j=n+1,…,n+ncnln. If nothing special is known about the problem, or there is no wish to provide special information, you may set clamda[j-1]=0.0. The remaining elements need not be set.
On exit: a set of Lagrange multipliers for the bounds on the variables (reduced costs) and the general constraints (shadow costs). More precisely, the first n elements contain the multipliers for the bounds on the variables, the next ncnln elements contain the multipliers for the nonlinear constraints F x (if any) and the next (m-ncnln) elements contain the multipliers for the linear constraints Gx and the free row (if any).
miniz
Type: System..::..Int32 %
On exit: the minimum value of _leniz required to start solving the problem. If ifail=12, e04ug may be called again with _leniz suitably larger than miniz. (The bigger the better, since it is not certain how much workspace the basis factors need.)
minz
Type: System..::..Int32 %
On exit: the minimum value of lenz required to start solving the problem. If ifail=13, e04ug may be called again with lenz suitably larger than minz. (The bigger the better, since it is not certain how much workspace the basis factors need.)
ninf
Type: System..::..Int32 %
On exit: the number of constraints that lie outside their bounds by more than the value of the optional parameter Minor Feasibility Tolerance.
If the linear constraints are infeasible, the sum of the infeasibilities of the linear constraints is minimized subject to the upper and lower bounds being satisfied. In this case, ninf contains the number of elements of Gx that lie outside their upper or lower bounds. Note that the nonlinear constraints are not evaluated.
Otherwise, the sum of the infeasibilities of the nonlinear constraints is minimized subject to the linear constraints and the upper and lower bounds being satisfied. In this case, ninf contains the number of elements of F x that lie outside their upper or lower bounds.
sinf
Type: System..::..Double %
On exit: the sum of the infeasibilities of constraints that lie outside their bounds by more than the value of the optional parameter Minor Feasibility Tolerance.
obj
Type: System..::..Double %
On exit: the value of the objective function.
iz
Type: array< System..::..Int32 >[]()[][]
An array of size [dim1]
Note: dim1 must satisfy the constraint: _leniz≥max 500,n+m
z
Type: array< System..::..Double >[]()[][]
An array of size [lenz]
the dimension of the array z.
On entry: the dimension of the array z as declared in the (sub)program from which e04ug is called.
Constraint: lenz≥500.
The amounts of workspace provided (i.e., _leniz and lenz) and required (i.e., miniz and minz) are (by default) output on the current advisory message unit (as defined by (X04ABF not in this release)). Since the minimum values of _leniz and lenz required to start solving the problem are returned in miniz and minz respectively, you may prefer to obtain appropriate values from the output of a preliminary run with _leniz set to max 500,n+m and/or lenz set to 500. (e04ug will then terminate with ifail=15 or 16.)
options
Type: NagLibrary..::..E04..::..e04ugOptions
An Object of type E04.e04ugOptions. Used to configure optional parameters to this method.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04ug is designed to solve a class of nonlinear programming problems that are assumed to be stated in the following general form:
minimize x∈Rn f x  subject to  l≤xF xGx≤u, (1)
where x=x 1,x 2,…,xn T is a set of variables, f x is a smooth scalar objective function, l and u are constant lower and upper bounds, F x is a vector of smooth nonlinear constraint functions Fi x and G is a sparse matrix.
The constraints involving F and Gx are called the general constraints. Note that upper and lower bounds are specified for all variables and constraints. This form allows full generality in specifying various types of constraint. In particular, the jth constraint can be defined as an equality by setting lj=uj. If certain bounds are not present, the associated elements of l or u can be set to special values that will be treated as -∞ or +∞. (See the description of the optional parameter Infinite Bound Size.)
e04ug converts the upper and lower bounds on the m elements of F and Gx to equalities by introducing a set of slack variables s, where s=s 1,s 2,…,sm T. For example, the linear constraint 5≤2 x 1+3 x 2≤+∞ is replaced by 2 x 1+3 x 2-s 1=0, together with the bounded slack 5≤s 1≤+∞. The problem defined by (1) can therefore be re-written in the following equivalent form:
minimize x∈Rn,s∈Rm f x  subject to  Gx-s=0,  l≤xs≤u. (2)
Since the slack variables s are subject to the same upper and lower bounds as the elements of F and Gx, the bounds on F and Gx can simply be thought of as bounds on the combined vector x,s. The elements of x and s are partitioned into basic, nonbasic and superbasic variables defined as follows:
– | a basic variable (xj say) is the jth variable associated with the jth column of the basis matrix B;
– | a nonbasic variable is a variable that is temporarily fixed at its current value (usually its upper or lower bound);
– | a superbasic variable is a nonbasic variable which is not at one of its bounds that is free to move in any desired direction (namely one that will improve the value of the objective function or reduce the sum of infeasibilities).
For example, in the simplex method (see Gill et al. (1981)) the elements of x can be partitioned at each vertex into a set of m basic variables (all non-negative) and a set of n-m nonbasic variables (all zero). This is equivalent to partitioning the columns of the constraint matrix as BN, where B contains the m columns that correspond to the basic variables and N contains the n-m columns that correspond to the nonbasic variables. Note that B is square and nonsingular.
The optional parameter Maximize may be used to specify an alternative problem in which f x is maximized. If the objective function is nonlinear and all the constraints are linear, F is absent and the problem is said to be linearly constrained. In general, the objective and constraint functions are structured in the sense that they are formed from sums of linear and nonlinear functions. This structure can be exploited by the method during the solution process as follows.
Consider the following nonlinear optimization problem with four variables (u,v,z,w):
minimize u,v,z,w u+v+z 2+3 z+5 w
subject to the constraints
u 2+v 2+z+w=2u 4+v 4+z+w=42 u+4 v+z+w≥0
and to the bounds
z≥0.w≥0.
This problem has several characteristics that can be exploited by the method:
– | the objective function is nonlinear. It is the sum of a nonlinear function of the variables (u,v,z) and a linear function of the variables (z,w);
– | the first two constraints are nonlinear. The third is linear;
– | each nonlinear constraint function is the sum of a nonlinear function of the variables (u,v) and a linear function of the variables (z,w).
The nonlinear terms are defined by objfun and confun (see [Parameters]), which involve only the appropriate subset of variables.
For the objective, we define the function f u,v,z=u+v+z 2 to include only the nonlinear part of the objective. The three variables (u,v,z) associated with this function are known as the nonlinear objective variables. The number of them is given by nonln (see [Parameters]) and they are the only variables needed in objfun. The linear part 3 z+5 w of the objective is stored in row iobj (see [Parameters]) of the (constraint) Jacobian matrix A (see below).
Thus, if x′ and y′ denote the nonlinear and linear objective variables, respectively, the objective may be re-written in the form
f x′+cTx′+dTy′,
where f x′ is the nonlinear part of the objective and c and d are constant vectors that form a row of A. In this example, x′=u,v,z and y′=w.
Similarly for the constraints, we define a vector function F u,v to include just the nonlinear terms. In this example, F 1 u,v=u 2+v 2 and F 2 u,v=u 4+v 4, where the two variables (u,v) are known as the nonlinear Jacobian variables. The number of them is given by njnln (see [Parameters]) and they are the only variables needed in confun. Thus, if x′′ and y′′ denote the nonlinear and linear Jacobian variables, respectively, the constraint functions and the linear part of the objective have the form
F x′′+A 2 y′′A 3 x′′+A 4 y′′, (3)
where x′′=u,v and y′′=z,w in this example. This ensures that the Jacobian is of the form
A=J x′′A 2A 3A 4,
where J x′′=∂F x′′∂x. Note that J x′′ always appears in the top left-hand corner of A.
The inequalities l 1≤F x′′+A 2 y′′≤u 1 and l 2≤A 3 x′′+A 4 y′′≤u 2 implied by the constraint functions in (3) are known as the nonlinear and linear constraints, respectively. The nonlinear constraint vector F x′′ in (3) and (optionally) its partial derivative matrix J x′′ are set in confun. The matrices A 2, A 3 and A 4 contain any (constant) linear terms. Along with the sparsity pattern of J x′′ they are stored in the arrays a, ha and ka (see [Parameters]).
In general, the vectors x′ and x′′ have different dimensions, but they always overlap, in the sense that the shorter vector is always the beginning of the other. In the above example, the nonlinear Jacobian variables u,v are an ordered subset of the nonlinear objective variables u,v,z. In other cases it could be the other way round (whichever is the most convenient), but the first way keeps J x′′ as small as possible.
Note that the nonlinear objective function f x′ may involve either a subset or superset of the variables appearing in the nonlinear constraint functions F x′′. Thus, nonln≤njnln (or vice-versa). Sometimes the objective and constraints really involve disjoint sets of nonlinear variables. In such cases the variables should be ordered so that nonln>njnln and x′=x′′,x′′′, where the objective is nonlinear in just the last vector x′′′. The first njnln elements of the gradient array objgrd should also be set to zero in objfun. This is illustrated in [Example].
If all elements of the constraint Jacobian are known (i.e., the optional parameter Derivative Level=2 or 3), any constant elements may be assigned their correct values in a, ha and ka. The corresponding elements of the constraint Jacobian array fjac need not be reset in confun. This includes values that are identically zero as constraint Jacobian elements are assumed to be zero unless specified otherwise. It must be emphasized that, if Derivative Level=0 or 1, unassigned elements of fjac are not treated as constant; they are estimated by finite differences, at nontrivial expense.
If there are no nonlinear constraints in (1) and f x is linear or quadratic, then it may be more efficient to use e04nq to solve the resulting linear or quadratic programming problem, or one of e04mf, e04nc or e04nf if G is a dense matrix. If the problem is dense and does have nonlinear constraints then one of e04uf, e04us or e04wd (as appropriate) should be used instead.
You must supply an initial estimate of the solution to (1), together with versions of objfun and confun that define f x′ and F x′′, respectively, and as many first partial derivatives as possible. Note that if there are any nonlinear constraints, then the first call to confun will precede the first call to objfun.
e04ug is based on the SNOPT package described in Gill et al. (2002), which in turn utilizes methods from the MINOS package (see Murtagh and Saunders (1995)). It incorporates a sequential quadratic programming (SQP) method that obtains search directions from a sequence of quadratic programming (QP) subproblems. Each QP subproblem minimizes a quadratic model of a certain Lagrangian function subject to a linearization of the constraints. An augmented Lagrangian merit function is reduced along each search direction to ensure convergence from any starting point. Further details can be found in [Algorithmic Details].
Throughout this document the symbol ε is used to represent the machine precision (see x02aj).

References

Conn A R (1973) Constrained optimization using a nondifferentiable penalty function SIAM J. Numer. Anal. 10 760–779
Eldersveld S K (1991) Large-scale sequential quadratic programming algorithms PhD Thesis Department of Operations Research, Stanford University, Stanford
Fletcher R (1984) An l 1 penalty method for nonlinear constraints Numerical Optimization 1984 (eds P T Boggs, R H Byrd and R B Schnabel) 26–40 SIAM Philadelphia
Fourer R (1982) Solving staircase linear programs by the simplex method Math. Programming 23 274–313
Gill P E, Murray W and Saunders M A (2002) SNOPT: An SQP Algorithm for Large-scale Constrained Optimization 12 979–1006 SIAM J. Optim.
Gill P E, Murray W, Saunders M A and Wright M H (1986) Users' guide for NPSOL (Version 4.0): a Fortran package for nonlinear programming Report SOL 86-2 Department of Operations Research, Stanford University
Gill P E, Murray W, Saunders M A and Wright M H (1989) A practical anti-cycling procedure for linearly constrained optimization Math. Programming 45 437–474
Gill P E, Murray W, Saunders M A and Wright M H (1992) Some theoretical properties of an augmented Lagrangian merit function Advances in Optimization and Parallel Computing (ed P M Pardalos) 101–128 North Holland
Gill P E, Murray W and Wright M H (1981) Practical Optimization Academic Press
Hock W and Schittkowski K (1981) Test Examples for Nonlinear Programming Codes. Lecture Notes in Economics and Mathematical Systems 187 Springer–Verlag
Murtagh B A and Saunders M A (1995) MINOS 5.4 users' guide Report SOL 83-20R Department of Operations Research, Stanford University
Ortega J M and Rheinboldt W C (1970) Iterative Solution of Nonlinear Equations in Several Variables Academic Press
Powell M J D (1974) Introduction to constrained optimization Numerical Methods for Constrained Optimization (eds P E Gill and W Murray) 1–28 Academic Press

Error Indicators and Warnings

Note: e04ug may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LENIZ) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail<0
A negative value of ifail indicates an exit from e04ug because you set mode<0 in objfun or confun. The value of ifail will be the same as your setting of mode.
ifail=1
The problem is infeasible. The general constraints cannot all be satisfied simultaneously to within the values of the optional parameters Major Feasibility Tolerance (default value=ε) and Minor Feasibility Tolerance (default value=ε).
ifail=2
The problem is unbounded (or badly scaled). The objective function is not bounded below (or above in the case of maximization) in the feasible region because a nonbasic variable can apparently be increased or decreased by an arbitrary amount without causing a basic variable to violate a bound. Add an upper or lower bound to the variable (whose index is printed by default by e04ug) and rerun e04ug.
ifail=3
The problem may be unbounded. Check that the values of the optional parameters Unbounded Objective (default value=1015) and Unbounded Step Size (default value=max bigbnd,1020) are not too small. This exit also implies that the objective function is not bounded below (or above in the case of maximization) in the feasible region defined by expanding the bounds by the value of the optional parameter Violation Limit (default value=10.0).
ifail=4
Too many iterations. The values of the optional parameters Major Iteration Limit (default value=1000) and/or Iteration Limit (default value=10000) are too small.
ifail=5
Feasible solution found, but requested accuracy could not be achieved. Check that the value of the optional parameter Major Optimality Tolerance (default value=ε) is not too small (say, <ε).
ifail=6
The value of the optional parameter Superbasics Limit (default value=min 500,n-+1) is too small.
ifail=7
An input parameter is invalid.
ifail=8
The user-supplied derivatives of the objective function computed by objfun appear to be incorrect. Check that objfun has been coded correctly and that all relevant elements of the objective gradient have been assigned their correct values.
ifail=9
The user-supplied derivatives of the nonlinear constraint functions computed by confun appear to be incorrect. Check that confun has been coded correctly and that all relevant elements of the nonlinear constraint Jacobian have been assigned their correct values.
ifail=10
The current point cannot be improved upon. Check that objfun and confun have been coded correctly and that they are consistent with the value of the optional parameter Derivative Level (default value=3).
ifail=11
Numerical error in trying to satisfy the linear constraints (or the linearized nonlinear constraints). The basis is very ill-conditioned.
ifail=12
Not enough integer workspace for the basis factors. Increase _leniz and rerun e04ug.
ifail=13
Not enough real workspace for the basis factors. Increase lenz and rerun e04ug.
ifail=14
The basis is singular after 15 attempts to factorize it (and adding slacks where necessary). Either the problem is badly scaled or the value of the optional parameter LU Factor Tolerance (default value=5.0 or 100.0) is too large.
ifail=15
Not enough integer workspace to start solving the problem. Increase _leniz to at least miniz and rerun e04ug.
ifail=16
Not enough real workspace to start solving the problem. Increase lenz to at least minz and rerun e04ug.
ifail=17
An unexpected error has occurred. Please contact NAG.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

If the value of the optional parameter Major Optimality Tolerance is set to 10-d (default value=ε) and ifail=0 on exit, then the final value of f x should have approximately d correct significant digits.

Parallelism and Performance

None.

Further Comments

This section contains a description of the printed output.

Major Iteration Printout

This section describes the intermediate printout and final printout produced by the major iterations of e04ug. The intermediate printout is a subset of the monitoring information produced by the method at every iteration (see [Description of Monitoring Information]). You can control the level of printed output (see the description of the optional parameter Major Print Level). Note that the intermediate printout and final printout are produced only if Major Print Level≥10 (the default for e04ug, by default no output is produced by ).
The following line of summary output (<80 characters) is produced at every major iteration. In all cases, the values of the quantities printed are those in effect on completion of the given iteration.
Maj | is the major iteration count.
Mnr is the number of minor iterations required by the feasibility and optimality phases of the QP subproblem. Generally, Mnr will be 1 in the later iterations, since theoretical analysis predicts that the correct active set will be identified near the solution (see [Algorithmic Details]).
Note that Mnr may be greater than the optional parameter Minor Iteration Limit if some iterations are required for the feasibility phase.
Step | is the step αk taken along the computed search direction. On reasonably well-behaved problems, the unit step (i.e., αk=1) will be taken as the solution is approached.
Merit Function is the value of the augmented Lagrangian merit function (6) at the current iterate. This function will decrease at each iteration unless it was necessary to increase the penalty parameters (see [Major Iteration Printout]). As the solution is approached, Merit Function will converge to the value of the objective function at the solution.
In elastic mode (see [Treatment of Constraint Infeasibilities]) then the merit function is a composite function involving the constraint violations weighted by the value of the optional parameter Elastic Weight.
If there are no nonlinear constraints present then this entry contains Objective, the value of the objective function f x. In this case, f x will decrease monotonically to its optimal value.
Feasibl is the value of rowerr, the largest element of the scaled nonlinear constraint residual vector defined in the description of the optional parameter Major Feasibility Tolerance. The solution is regarded as ‘feasible’ if Feasibl is less than (or equal to) the optional parameter Major Feasibility Tolerance. Feasibl will be approximately zero in the neighbourhood of a solution.
If there are no nonlinear constraints present, all iterates are feasible and this entry is not printed.
Optimal | is the value of maxgap, the largest element of the maximum complementarity gap vector defined in the description of the optional parameter Major Optimality Tolerance. The Lagrange multipliers are regarded as ‘optimal’ if Optimal is less than (or equal to) the optional parameter Major Optimality Tolerance. Optimal will be approximately zero in the neighbourhood of a solution.
Cond Hz | is an estimate of the condition number of the reduced Hessian of the Lagrangian (not printed if ncnln and nonln are both zero). It is the square of the ratio between the largest and smallest diagonal elements of the upper triangular matrix R. This constitutes a lower bound on the condition number of the matrix RT R that approximates the reduced Hessian. The larger this number, the more difficult the problem.
PD | is a two-letter indication of the status of the convergence tests involving the feasibility and optimality of the iterates defined in the descriptions of the optional parameters Major Feasibility Tolerance and Major Optimality Tolerance. Each letter is T if the test is satisfied and F otherwise. The tests indicate whether the values of Feasibl and Optimal are sufficiently small. For example, TF or TT is printed if there are no nonlinear constraints present (since all iterates are feasible). If either indicator is F when e04ug terminates with ifail=0, you should check the solution carefully.
M | is printed if an extra evaluation of user-supplied delegates objfun and confun was needed in order to define an acceptable positive definite quasi-Newton update to the Hessian of the Lagrangian. This modification is only performed when there are nonlinear constraints present.
m | is printed if, in addition, it was also necessary to modify the update to include an augmented Lagrangian term.
s | is printed if a self-scaled BFGS (Broyden–Fletcher–Goldfarb–Shanno) update was performed. This update is always used when the Hessian approximation is diagonal and hence always follows a Hessian reset.
S | is printed if, in addition, it was also necessary to modify the self-scaled update in order to maintain positive-definiteness.
n | is printed if no positive definite BFGS update could be found, in which case the approximate Hessian is unchanged from the previous iteration.
r | is printed if the approximate Hessian was reset after 10 consecutive major iterations in which no BFGS update could be made. The diagonal elements of the approximate Hessian are retained if at least one update has been performed since the last reset. Otherwise, the approximate Hessian is reset to the identity matrix.
R | is printed if the approximate Hessian has been reset by discarding all but its diagonal elements. This reset will be forced periodically by the values of the optional parameters Hessian Frequency and Hessian Updates. However, it may also be necessary to reset an ill-conditioned Hessian from time to time.
l | is printed if the change in the norm of the variables was greater than the value defined by the optional parameter Major Step Limit. If this output occurs frequently during later iterations, it may be worthwhile increasing the value of Major Step Limit.
c | is printed if central differences have been used to compute the unknown elements of the objective and constraint gradients. A switch to central differences is made if either the linesearch gives a small step, or x is close to being optimal. In some cases, it may be necessary to re-solve the QP subproblem with the central difference gradient and Jacobian.
u | is printed if the QP subproblem was unbounded.
t | is printed if the minor iterations were terminated after the number of iterations specified by the value of the optional parameter Minor Iteration Limit was reached.
i | is printed if the QP subproblem was infeasible when the method was not in elastic mode. This event triggers the start of nonlinear elastic mode, which remains in effect for all subsequent iterations. Once in elastic mode, the QP subproblems are associated with the elastic problem (8) (see [Treatment of Constraint Infeasibilities]). It is also printed if the minimizer of the elastic subproblem does not satisfy the linearized constraints when the method is already in elastic mode. (In this case, a feasible point for the usual QP subproblem may or may not exist.)
w | is printed if a weak solution of the QP subproblem was found.
The final printout includes a listing of the status of every variable and constraint.
The following describes the printout for each variable. A full stop (.) is printed for any numerical value that is zero.
Variable | gives the name of the variable. If nname=1, a default name is assigned to the jth variable, for j=1,2,…,n. If nname=n+m, the name supplied in names[j-1] is assigned to the jth variable.
State gives the state of the variable (LL if nonbasic on its lower bound, UL if nonbasic on its upper bound, EQ if nonbasic and fixed, FR if nonbasic and strictly between its bounds, BS if basic and SBS if superbasic).
A key is sometimes printed before State. Note that unless the optional parameter Scale Option=0 is specified, the tests for assigning a key are applied to the variables of the scaled problem.
A | Alternative optimum possible. The variable is nonbasic, but its reduced gradient is essentially zero. This means that if the variable were allowed to start moving away from its current value, there would be no change in the value of the objective function. The values of the basic and superbasic variables might change, giving a genuine alternative solution. The values of the Lagrange multipliers might also change.
D | Degenerate. The variable is basic, but it is equal to (or very close to) one of its bounds.
I | Infeasible. The variable is basic and is currently violating one of its bounds by more than the value of the optional parameter Minor Feasibility Tolerance.
N | Not precisely optimal. The variable is nonbasic. Its reduced gradient is larger than the value of the optional parameter Major Feasibility Tolerance.
Value | is the value of the variable at the final iteration.
Lower Bound | is the lower bound specified for the variable. None indicates that bl[j-1]≤-bigbnd.
Upper Bound | is the upper bound specified for the variable. None indicates that bu[j-1]≥bigbnd.
Lagr Mult | is the Lagrange multiplier for the associated bound. This will be zero if State is FR. If x is optimal, the multiplier should be non-negative if State is LL, non-positive if State is UL and zero if State is BS or SBS.
Residual | is the difference between the variable Value and the nearer of its (finite) bounds bl[j-1] and bu[j-1]. A blank entry indicates that the associated variable is not bounded (i.e., bl[j-1]≤-bigbnd and bu[j-1]≥bigbnd).
The meaning of the printout for general constraints is the same as that given above for variables, with ‘variable’ replaced by ‘constraint’, n replaced by m, names[j-1] replaced by names[n+j-1], bl[j-1] and bu[j-1] are replaced by bl[n+j-1] and bu[n+j-1] respectively. The heading is changed as follows:
Constrnt gives the name of the general constraint.
Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.

Minor Iteration Printout

This section describes the printout produced by the minor iterations of e04ug, which involve solving a QP subproblem at every major iteration. (Further details can be found in [Major Iteration Printout].) The printout is a subset of the monitoring information produced by the method at every iteration (see [Description of Monitoring Information]). You can control the level of printed output (see the description of the optional parameter Minor Print Level). Note that the printout is produced only if Minor Print Level≥1 (default value=0, which produces no output).
The following line of summary output (<80 characters) is produced at every minor iteration. In all cases, the values of the quantities printed are those in effect on completion of the given iteration of the QP subproblem.
Itn | is the iteration count.
Step | is the step taken along the computed search direction.
Ninf | is the number of infeasibilities. This will not increase unless the iterations are in elastic mode. Ninf will be zero during the optimality phase.
Sinf | is the value of the sum of infeasibilities if Ninf is nonzero. This will be zero during the optimality phase.
Objective | is the value of the current QP objective function when Ninf is zero and the iterations are not in elastic mode. The switch to elastic mode is indicated by a change in the heading to Composite Obj.
Composite Obj | is the value of the composite objective function (9) when the iterations are in elastic mode. This function will decrease monotonically at each iteration.
Norm rg | is the Euclidean norm of the reduced gradient of the QP objective function. During the optimality phase, this norm will be approximately zero after a unit step.
Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.

Example

This is a reformulation of Problem 74 in Hock and Schittkowski (1981) and involves the minimization of the nonlinear function
f x=10-6 x 33+23×10-6 x 43+3 x 3+2 x 4
subject to the bounds
-0.55≤x 1≤0.55,-0.55≤x 2≤0.55,-0.0 0≤x 3≤1200,-0.0 0≤x 4≤1200,
to the nonlinear constraints
1000 sin-x 1-0.25+1000 sin-x 2-0.25-x 3=-894.8,1000 sin x 1-0.25+1000 sin x 1-x 2-0.25-x 4=-894.8,1000 sin x 2-0.25+1000 sin x 2-x 1-0.25=-1294.8,
and to the linear constraints
-x 1+x 2≥-0.55,-x 1-x 2≥-0.55.
The initial point, which is infeasible, is
x 0=0,0,0,0 T,
and f x 0=0.
The optimal solution (to five figures) is
x*=0.11887,-0.39623,679.94,1026.0 T,
and f x*=5126.4. All the nonlinear constraints are active at the solution.

Example program (C#): e04uge.cs

Example program data: e04uge.d

Example program results: e04uge.r

Algorithmic Details

This section contains a detailed description of the method used by e04ug.

Overview

Here we briefly summarise the main features of the method and introduce some terminology. Where possible, explicit reference is made to the names of variables that are parameters of the method or appear in the printed output. Further details can be found in Gill et al. (2002).
At a solution of (1), some of the constraints will be active, i.e., satisfied exactly. Let
r x=xF xGx
and G denote the set of indices of r x corresponding to active constraints at an arbitrary point x. Let rj′x denote the usual derivative of rj x, which is the row vector of first partial derivatives of rj x (see Ortega and Rheinboldt (1970)). The vector rj′x comprises the jth row of r′x so that
r′x=IJ xG,
where J x is the Jacobian of F x.
A point x is a first-order Kuhn–Karesh–Tucker (KKT) point for (1) (see Powell (1974)) if the following conditions hold:
(a) | x is feasible;
(b) there exists a vector λ (the Lagrange multiplier vector for the bound and general constraints) such that
g x=r′x T λ=I J x T GT λ, (4)
where g is the gradient of f evaluated at x;
(c) | the Lagrange multiplier λj associated with the jth constraint satisfies λj=0 if lj<rj x<uj; λj≥0 if lj=rj x; λj≤0 if rj x=uj; and λj can have any value if lj=uj.
An equivalent statement of the condition (4) is
ZT g x=0,
where Z is a matrix defined as follows. Consider the set N of vectors orthogonal to the gradients of the active constraints, i.e.,
N=z ∣ rj′x z=0  for all  j∈G.
The columns of Z may then be taken as any basis for the vector space N. The vector ZT g is termed the reduced gradient of f at x. Certain additional conditions must be satisfied in order for a first-order KKT point to be a solution of (1) (see Powell (1974)).
The basic structure of e04ug involves major and minor iterations. The major iterations generate a sequence of iterates xk that satisfy the linear constraints and converge to a point x* that satisfies the first-order KKT optimality conditions. At each iterate a QP subproblem is used to generate a search direction towards the next iterate (x k+1). The constraints of the subproblem are formed from the linear constraints Gx-sL=0 and the nonlinear constraint linearization
F xk+F′xkx-xk-sN=0,
where F′xk denotes the Jacobian matrix, whose rows are the first partial derivatives of F x evaluated at the point xk. The QP constraints therefore comprise the m linear constraints
F′xk x-sN-sL=-F xk+F′xk xk,'xk Gx-sN-sL=0,F xk+F′xk xk
where x and s=sN,sL T are bounded above and below by u and l as before. If the m by n matrix A and m element vector b are defined as
A=F′xkG  and  b=-F xk+F′xk xk0,
then the QP subproblem can be written as
minimize x,s q x  subject to  Ax-s=b,  l≤xs≤u, (5)
where q x is a quadratic approximation to a modified Lagrangian function (see Gill et al. (2002)).
The linear constraint matrix A is stored in the arrays a, ha and ka (see [Parameters]). This allows you to specify the sparsity pattern of nonzero elements in F′x and G and to identify any nonzero elements that remain constant throughout the minimization.
Solving the QP subproblem is itself an iterative procedure, with the minor iterations of an SQP method being the iterations of the QP method. At each minor iteration, the constraints Ax-s=b are (conceptually) partitioned into the form
B xB+S xS+N xN=b,
where the basis matrix B is square and nonsingular. The elements of xB, xS and xN are called the basic, superbasic and nonbasic variables respectively; they are a permutation of the elements of x and s. At a QP solution, the basic and superbasic variables will lie somewhere between their bounds, while the nonbasic variables will be equal to one of their upper or lower bounds. At each minor iteration, xS is regarded as a set of independent variables that are free to move in any desired direction, namely one that will improve the value of the QP objective function q x or sum of infeasibilities (as appropriate). The basic variables are then adjusted in order to ensure that (x,s) continues to satisfy Ax-s=b. The number of superbasic variables (nS say) therefore indicates the number of degrees of freedom remaining after the constraints have been satisfied. In broad terms, nS is a measure of how nonlinear the problem is. In particular, nS will always be zero if there are no nonlinear constraints in (1) and f x is linear.
If it appears that no improvement can be made with the current definition of B, S and N, a nonbasic variable is selected to be added to S and the process is repeated with the value of nS increased by one. At all stages, if a basic or superbasic variable encounters one of its bounds, the variable is made nonbasic and the value of nS decreased by one.
Associated with each of the m equality constraints Ax-s=b is a dual variable πi. Similarly, each variable in x,s has an associated reduced gradient dj (also known as a reduced cost). The reduced gradients for the variables x are the quantities g-AT π, where g is the gradient of the QP objective function q x; the reduced gradients for the slack variables s are the dual variables π. The QP subproblem (5) is optimal if dj≥0 for all nonbasic variables at their lower bounds, dj≤0 for all nonbasic variables at their upper bounds and dj=0 for other variables (including superbasics). In practice, an approximate QP solution is found by slightly relaxing these conditions on dj (see the description of the optional parameter Minor Optimality Tolerance).
After a QP subproblem has been solved, new estimates of the solution to (1) are computed using a linesearch on the augmented Lagrangian merit function
M x,s,π=f x-πT F x-sN+12 F x-sN T D F x-sN, (6)
where D is a diagonal matrix of penalty parameters. If (xk,sk,πk) denotes the current estimate of the solution and (x^,s^,π^) denotes the optimal QP solution, the linesearch determines a step αk (where 0<αk≤1) such that the new point
x k+1s k+1π k+1=xkskπk+αk x^k-xks^k-skπ^k-πk
produces a sufficient decrease in the merit function (6). When necessary, the penalties in D are increased by the minimum-norm perturbation that ensures descent for M (see Gill et al. (1992)). As in e04wd, sN is adjusted to minimize the merit function as a function of s before the solution of the QP subproblem. Further details can be found in Eldersveld (1991) and Gill et al. (1986).

Treatment of Constraint Infeasibilities

e04ug makes explicit allowance for infeasible constraints. Infeasible linear constraints are detected first by solving a problem of the form
minimize x,v,w eT v+w  subject to  l≤xGx-v+w≤u,  v≥0,  w≥0, (7)
where e=1,1,…,1 T. This is equivalent to minimizing the sum of the general linear constraint violations subject to the simple bounds. (In the linear programming literature, the approach is often called elastic programming.)
If the linear constraints are infeasible (i.e., v≠0 or w≠0), the method terminates without computing the nonlinear functions.
If the linear constraints are feasible, all subsequent iterates will satisfy the linear constraints. (Such a strategy allows linear constraints to be used to define a region in which f x and F x can be safely evaluated.) The method then proceeds to solve (1) as given, using search directions obtained from a sequence of QP subproblems (5). Each QP subproblem minimizes a quadratic model of a certain Lagrangian function subject to linearized constraints. An augmented Lagrangian merit function (6) is reduced along each search direction to ensure convergence from any starting point.
The method enters ‘elastic’ mode if the QP subproblem proves to be infeasible or unbounded (or if the dual variables π for the nonlinear constraints become ‘large’) by solving a problem of the form
minimize x,v,w f-x,v,w  subject to  l≤xF x-v+wGx≤u,  v≥0,  w≥0, (8)
where
f-x,v,w=f x+γ eT v+w (9)
is called a composite objective and γ is a non-negative parameter (the elastic weight). If γ is sufficiently large, this is equivalent to minimizing the sum of the nonlinear constraint violations subject to the linear constraints and bounds. A similar l 1 formulation of (1) is fundamental to the Sl 1QP algorithm of Fletcher (1984). See also Conn (1973).

Description of Monitoring Information

This section describes the intermediate printout and final printout which constitutes the monitoring information produced by e04ug. (See also the description of the optional parameters Monitoring File, Major Print Level and Minor Print Level.) You can control the level of printed output.
When Major Print Level≥20 and Monitoring File≥0, the following line of intermediate printout (<120 characters) is produced at every major iteration on the unit number specified by optional parameter Monitoring File. Unless stated otherwise, the values of the quantities printed are those in effect on completion of the given iteration.
Major | is the major iteration count.
Minor | is the number of minor iterations required by the feasibility and optimality phases of the QP subproblem. Generally, Minor will be 1 in the later iterations, since theoretical analysis predicts that the correct active set will be identified near the solution (see [Algorithmic Details]).
Step | is the step αk taken along the computed search direction. On reasonably well-behaved problems, the unit step (i.e., αk=1) will be taken as the solution is approached.
nObj | is the number of times objfun has been called to evaluate the nonlinear part of the objective function. Evaluations needed for the estimation of the gradients by finite differences are not included. nObj is printed as a guide to the amount of work required for the linesearch.
nCon | is the number of times confun has been called to evaluate the nonlinear constraint functions (not printed if ncnln is zero).
Merit is the value of the augmented Lagrangian merit function (6) at the current iterate. This function will decrease at each iteration unless it was necessary to increase the penalty parameters (see [Major Iteration Printout]). As the solution is approached, Merit will converge to the value of the objective function at the solution.
In elastic mode (see [Treatment of Constraint Infeasibilities]), the merit function is a composite function involving the constraint violations weighted by the value of the optional parameter Elastic Weight.
If there are no nonlinear constraints present, this entry contains Objective, the value of the objective function f x. In this case, f x will decrease monotonically to its optimal value.
Feasibl is the value of rowerr, the largest element of the scaled nonlinear constraint residual vector defined in the description of the optional parameter Major Feasibility Tolerance. The solution is regarded as ‘feasible’ if Feasibl is less than (or equal to) the optional parameter Major Feasibility Tolerance. Feasibl will be approximately zero in the neighbourhood of a solution.
If there are no nonlinear constraints present, all iterates are feasible and this entry is not printed.
Optimal | is the value of maxgap, the largest element of the maximum complementarity gap vector defined in the description of the optional parameter Major Optimality Tolerance. The Lagrange multipliers are regarded as ‘optimal’ if Optimal is less than (or equal to) the optional parameter Major Optimality Tolerance. Optimal will be approximately zero in the neighbourhood of a solution.
nS | is the current number of superbasic variables.
Penalty | is the Euclidean norm of the vector of penalty parameters used in the augmented Lagrangian merit function (not printed if ncnln is zero).
LU is the number of nonzeros representing the basis factors L and U on completion of the QP subproblem.
If there are nonlinear constraints present, the basis factorization B=LU is computed at the start of the first minor iteration. At this stage, LU=lenL+lenU, where lenL is the number of subdiagonal elements in the columns of a lower triangular matrix and lenU is the number of diagonal and superdiagonal elements in the rows of an upper triangular matrix. As columns of B are replaced during the minor iterations, the value of LU may fluctuate up or down (but in general will tend to increase). As the solution is approached and the number of minor iterations required to solve each QP subproblem decreases towards zero, LU will reflect the number of nonzeros in the LU factors at the start of each QP subproblem.
If there are no nonlinear constraints present, refactorization is subject only to the value of the optional parameter Factorization Frequency and hence LU will tend to increase between factorizations.
Swp | is the number of columns of the basis matrix B that were swapped with columns of S in order to improve the condition number of B (not printed if ncnln is zero). The swaps are determined by an LU factorization of the rectangular matrix BS=BS T, with stability being favoured more than sparsity.
Cond Hz | is an estimate of the condition number of the reduced Hessian of the Lagrangian (not printed if ncnln and nonln are both zero). It is the square of the ratio between the largest and smallest diagonal elements of the upper triangular matrix R. This constitutes a lower bound on the condition number of the matrix RT R that approximates the reduced Hessian. The larger this number, the more difficult the problem.
PD | is a two-letter indication of the status of the convergence tests involving the feasibility and optimality of the iterates defined in the descriptions of the optional parameters Major Feasibility Tolerance and Major Optimality Tolerance. Each letter is T if the test is satisfied and F otherwise. The tests indicate whether the values of Feasibl and Optimal are sufficiently small. For example, TF or TT is printed if there are no nonlinear constraints present (since all iterates are feasible). If either indicator is F when e04ug terminates with ifail=0, you should check the solution carefully.
M | is printed if an extra evaluation of user-supplied delegates objfun and confun was needed in order to define an acceptable positive definite quasi-Newton update to the Hessian of the Lagrangian. This modification is only performed when there are nonlinear constraints present.
m | is printed if, in addition, it was also necessary to modify the update to include an augmented Lagrangian term.
s | is printed if a self-scaled BFGS (Broyden–Fletcher–Goldfarb–Shanno) update was performed. This update is always used when the Hessian approximation is diagonal and hence always follows a Hessian reset.
S | is printed if, in addition, it was also necessary to modify the self-scaled update in order to maintain positive-definiteness.
n | is printed if no positive definite BFGS update could be found, in which case the approximate Hessian is unchanged from the previous iteration.
r | is printed if the approximate Hessian was reset after 10 consecutive major iterations in which no BFGS update could be made. The diagonal elements of the approximate Hessian are retained if at least one update has been performed since the last reset. Otherwise, the approximate Hessian is reset to the identity matrix.
R | is printed if the approximate Hessian has been reset by discarding all but its diagonal elements. This reset will be forced periodically by the values of the optional parameters Hessian Frequency and Hessian Updates. However, it may also be necessary to reset an ill-conditioned Hessian from time to time.
l | is printed if the change in the norm of the variables was greater than the value defined by the optional parameter Major Step Limit. If this output occurs frequently during later iterations, it may be worthwhile increasing the value of Major Step Limit.
c | is printed if central differences have been used to compute the unknown elements of the objective and constraint gradients. A switch to central differences is made if either the linesearch gives a small step, or x is close to being optimal. In some cases, it may be necessary to re-solve the QP subproblem with the central difference gradient and Jacobian.
u | is printed if the QP subproblem was unbounded.
t | is printed if the minor iterations were terminated after the number of iterations specified by the value of the optional parameter Minor Iteration Limit was reached.
i | is printed if the QP subproblem was infeasible when the method was not in elastic mode. This event triggers the start of nonlinear elastic mode, which remains in effect for all subsequent iterations. Once in elastic mode, the QP subproblems are associated with the elastic problem (8) (see [Treatment of Constraint Infeasibilities]). It is also printed if the minimizer of the elastic subproblem does not satisfy the linearized constraints when the method is already in elastic mode. (In this case, a feasible point for the usual QP subproblem may or may not exist.)
w | is printed if a weak solution of the QP subproblem was found.
When Minor Print Level≥1 and Monitoring File≥0, the following line of intermediate printout (<120 characters) is produced at every minor iteration on the unit number specified by optional parameter Monitoring File. Unless stated otherwise, the values of the quantities printed are those in effect on completion of the given iteration.
In the description below, a ‘pricing’ operation is defined to be the process by which a nonbasic variable is selected to become superbasic (in addition to those already in the superbasic set). If the problem is purely linear, the variable selected will usually become basic immediately (unless it happens to reach its opposite bound and return to the nonbasic set).
Itn | is the iteration count.
pp | is the partial price indicator. The variable selected by the last pricing operation came from the ppth partition of A and -I. Note that pp is reset to zero whenever the basis is refactorized.
dj | is the value of the reduced gradient (or reduced cost) for the variable selected by the pricing operation at the start of the current iteration.
+SBS | is the variable selected by the pricing operation to be added to the superbasic set.
-SBS | is the variable chosen to leave the superbasic set. It has become basic if the entry under -B is nonzero; otherwise it has become nonbasic.
-BS | is the variable removed from the basis (if any) to become nonbasic.
-B | is the variable removed from the basis (if any) to swap with a slack variable made superbasic by the latest pricing operation. The swap is done to ensure that there are no superbasic slacks.
Step | is the value of the step length α taken along the current search direction p. The variables x have just been changed to x+αp. If a variable is made superbasic during the current iteration (i.e., +SBS is positive), Step will be the step to the nearest bound. During the optimality phase, the step can be greater than unity only if the reduced Hessian is not positive definite.
Pivot | is the rth element of a vector y satisfying By=aq whenever aq (the qth column of the constraint matrix A-I) replaces the rth column of the basis matrix B. Wherever possible, Step is chosen so as to avoid extremely small values of Pivot (since they may cause the basis to be nearly singular). In extreme cases, it may be necessary to increase the value of the optional parameter Pivot Tolerance to exclude very small elements of y from consideration during the computation of Step.
Ninf | is the number of infeasibilities. This will not increase unless the iterations are in elastic mode. Ninf will be zero during the optimality phase.
Sinf/Objective | is the value of the current objective function. If x is infeasible, Sinf gives the value of the sum of infeasibilities at the start of the current iteration. It will usually decrease at each nonzero value of Step, but may occasionally increase if the value of Ninf decreases by a factor of 2 or more. However, in elastic mode this entry gives the value of the composite objective function (9), which will decrease monotonically at each iteration. If x is feasible, Objective is the value of the current QP objective function.
L | is the number of nonzeros in the basis factor L. Immediately after a basis factorization B=LU, this entry contains lenL. Further nonzeros are added to L when various columns of B are later replaced. (Thus, L increases monotonically.)
U | is the number of nonzeros in the basis factor U. Immediately after a basis factorization B=LU, this entry contains lenU. As columns of B are replaced, the matrix U is maintained explicitly (in sparse form). The value of U may fluctuate up or down; in general, it will tend to increase.
Ncp | is the number of compressions required to recover workspace in the data structure for U. This includes the number of compressions needed during the previous basis factorization. Normally, Ncp should increase very slowly. If it does not, increase _leniz and lenz by at least L+U and rerun e04ug (possibly using start="W"; see [Parameters]).
The following items are printed only if the problem is nonlinear or the superbasic set is non-empty (i.e., if the current solution is nonbasic).
Norm rg | is the Euclidean norm of the reduced gradient of the QP objective function. During the optimality phase, this norm will be approximately zero after a unit step.
nS | is the current number of superbasic variables.
Cond Hz | is an estimate of the condition number of the reduced Hessian of the Lagrangian (not printed if ncnln and nonln are both zero). It is the square of the ratio between the largest and smallest diagonal elements of the upper triangular matrix R. This constitutes a lower bound on the condition number of the matrix RT R that approximates the reduced Hessian. The larger this number, the more difficult the problem.
When Major Print Level≥20 and Monitoring File≥0, the following lines of intermediate printout (<120 characters) are produced on the unit number specified by optional parameter Monitoring File whenever the matrix B or BS=B S T is factorized before solving the next QP subproblem. Gaussian elimination is used to compute a sparse LU factorization of B or BS, where PL PT is a lower triangular matrix and PUQ is an upper triangular matrix for some permutation matrices P and Q. The factorization is stabilized in the manner described under the optional parameter LU Factor Tolerance (default value=5.0 or 100.0).
Note that BS may be factorized at the beginning of just some of the major iterations. It is immediately followed by a factorization of B itself.
Factorize | is the factorization count.
Iteration | is the iteration count.
Nonlinear | is the number of nonlinear variables in the current basis B (not printed if BS is factorized).
Linear | is the number of linear variables in B (not printed if BS is factorized).
Slacks | is the number of slack variables in B (not printed if BS is factorized).
Elems | is the number of nonzeros in B (not printed if BS is factorized).
Density | is the percentage nonzero density of B (not printed if BS is factorized). More precisely, Density=100×Elems/Nonlinear+Linear+Slacks 2.
Compressns | is the number of times the data structure holding the partially factorized matrix needed to be compressed, in order to recover unused workspace. Ideally, it should be zero. If it is more than 3 or 4, increase _leniz and lenz and rerun e04ug (possibly using start="W"; see [Parameters]).
Merit | is the average Markowitz merit count for the elements chosen to be the diagonals of PUQ. Each merit count is defined to be c-1r-1, where c and r are the number of nonzeros in the column and row containing the element at the time it is selected to be the next diagonal. Merit is the average of m such quantities. It gives an indication of how much work was required to preserve sparsity during the factorization.
lenL | is the number of nonzeros in L.
lenU | is the number of nonzeros in U.
Increase | is the percentage increase in the number of nonzeros in L and U relative to the number of nonzeros in B. More precisely, Increase=100×lenL+lenU-Elems/Elems.
m | is the number of rows in the problem. Note that m=Ut+Lt+bp.
Ut | is the number of triangular rows of B at the top of U.
d1 | is the number of columns remaining when the density of the basis matrix being factorized reached 0.3.
Lmax | is the maximum subdiagonal element in the columns of L. This will not exceed the value of the optional parameter LU Factor Tolerance.
Bmax | is the maximum nonzero element in B (not printed if BS is factorized).
BSmax | is the maximum nonzero element in BS (not printed if B is factorized).
Umax | is the maximum nonzero element in U, excluding elements of B that remain in U unchanged. (For example, if a slack variable is in the basis, the corresponding row of B will become a row of U without modification. Elements in such rows will not contribute to Umax. If the basis is strictly triangular then none of the elements of B will contribute and Umax will be zero.) Ideally, Umax should not be significantly larger than Bmax. If it is several orders of magnitude larger, it may be advisable to reset the optional parameter LU Factor Tolerance to some value nearer unity. Umax is not printed if BS is factorized.
Umin | is the magnitude of the smallest diagonal element of PUQ.
Growth | is the value of the ratio Umax/Bmax, which should not be too large. Providing Lmax is not large (say, <10.0), the ratio max Bmax,Umax/Umin is an estimate of the condition number of B. If this number is extremely large, the basis is nearly singular and some numerical difficulties might occur. (However, an effort is made to avoid near-singularity by using slacks to replace columns of B that would have made Umin extremely small and the modified basis is refactorized.)
Lt | is the number of triangular columns of B at the left of L.
bp | is the size of the ‘bump’ or block to be factorized nontrivially after the triangular rows and columns of B have been removed.
d2 | is the number of columns remaining when the density of the basis matrix being factorized has reached 0.6.
When Major Print Level≥20, Monitoring File≥0 and Crash Option>0 (default value=0​ or ​3), the following lines of intermediate printout (<80 characters) are produced on the unit number specified by optional parameter Monitoring File whenever start="C" (see [Parameters]). They refer to the number of columns selected by the Crash procedure during each of several passes through A while searching for a triangular basis matrix.
Slacks | is the number of slacks selected initially.
Free cols | is the number of free columns in the basis, including those whose bounds are rather far apart.
Preferred | is the number of ‘preferred’ columns in the basis (i.e., istate[j-1]=3 for some j≤n). It will be a subset of the columns for which istate[j-1]=3 was specified.
Unit | is the number of unit columns in the basis.
Double | is the number of columns in the basis containing two nonzeros.
Triangle | is the number of triangular columns in the basis with three (or more) nonzeros.
Pad | is the number of slacks used to pad the basis (to make it a nonsingular triangle).
When Major Print Level=1 or ≥10 and Monitoring File≥0, the following lines of final printout (<120 characters) are produced on the unit number specified by optional parameter Monitoring File.
Let xj denote the jth ‘column variable’, for j=1,2,…,n. We assume that a typical variable xj has bounds α≤xj≤β.
The following describes the printout for each column (or variable). A full stop (.) is printed for any numerical value that is zero.
Number | is the column number j. (This is used internally to refer to xj in the intermediate output.)
Column | gives the name of xj.
State gives the state of xj relative to the bounds α and β.
The various possible states are as follows:
LL | xj is nonbasic at its lower limit, α.
UL | xj is nonbasic at its upper limit, β.
EQ | xj is nonbasic and fixed at the value α=β.
FR | xj is nonbasic at some value strictly between its bounds: α<xj<β.
BS | xj is basic. Usually α<xj<β.
A key is sometimes printed before State. Note that unless the optional parameter Scale Option=0 is specified, the tests for assigning a key are applied to the variables of the scaled problem.
A | Alternative optimum possible. The variable is nonbasic, but its reduced gradient is essentially zero. This means that if the variable were allowed to start moving away from its current value, there would be no change in the value of the objective function. The values of the basic and superbasic variables might change, giving a genuine alternative solution. The values of the Lagrange multipliers might also change.
D | Degenerate. The variable is basic, but it is equal to (or very close to) one of its bounds.
I | Infeasible. The variable is basic and is currently violating one of its bounds by more than the value of the optional parameter Minor Feasibility Tolerance.
N | Not precisely optimal. The variable is nonbasic. Its reduced gradient is larger than the value of the optional parameter Major Feasibility Tolerance.
Activity | is the value of xj at the final iterate.
Obj Gradient | is the value of gj at the final iterate. (If any xj is infeasible, gj is the gradient of the sum of infeasibilities.)
Lower Bound | is the lower bound specified for the variable. None indicates that bl[j-1]≤-bigbnd.
Upper Bound | is the upper bound specified for the variable. None indicates that bu[j-1]≥bigbnd.
Reduced Gradnt | is the value of dj at the final iterate.
m + j | is the value of m+j.
General linear constraints take the form l≤Ax≤u. The ith constraint is therefore of the form α≤aiT x≤β and the value of aiT x is called the row activity. Internally, the linear constraints take the form Ax-s=0, where the slack variables s should satisfy the bounds l≤s≤u. For the ith ‘row’, it is the slack variable si that is directly available and it is sometimes convenient to refer to its state. Slacks may be basic or nonbasic (but not superbasic).
Nonlinear constraints α≤Fi x+aiT x≤β are treated similarly, except that the row activity and degree of infeasibility are computed directly from Fi x+aiT x rather than from si.
The following describes the printout for each row (or constraint). A full stop (.) is printed for any numerical value that is zero.
Number | is the value of n+i. (This is used internally to refer to si in the intermediate output.)
Row | gives the name of the ith row.
State gives the state of the ith row relative to the bounds α and β.
The various possible states are as follows:
LL | The row is at its lower limit, α.
UL | The row is at its upper limit, β.
EQ | The limits are the same α=β.
BS | The constraint is not binding. si is basic.
A key is sometimes printed before State. Note that unless the optional parameter Scale Option=0 is specified, the tests for assigning a key are applied to the variables of the scaled problem.
A | Alternative optimum possible. The variable is nonbasic, but its reduced gradient is essentially zero. This means that if the variable were allowed to start moving away from its current value, there would be no change in the value of the objective function. The values of the basic and superbasic variables might change, giving a genuine alternative solution. The values of the Lagrange multipliers might also change.
D | Degenerate. The variable is basic, but it is equal to (or very close to) one of its bounds.
I | Infeasible. The variable is basic and is currently violating one of its bounds by more than the value of the optional parameter Minor Feasibility Tolerance.
N | Not precisely optimal. The variable is nonbasic. Its reduced gradient is larger than the value of the optional parameter Major Feasibility Tolerance.
Activity | is the value of aiT x (or Fi x+aiT x for nonlinear rows) at the final iterate.
Slack Activity | is the value by which the row differs from its nearest bound. (For the free row (if any), it is set to Activity.)
Lower Bound | is α, the lower bound specified for the ith row. None indicates that bl[n+i-1]≤-bigbnd.
Upper Bound | is β, the upper bound specified for the ith row. None indicates that bu[n+i-1]≥bigbnd.
Dual Activity | is the value of the dual variable πi.
i | gives the index i of the ith row.
Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.

See Also

E04 Class
E04 Members


e04ugm Method

[image]

NAG Library for .NET Release 2
E04..::e04ugm Method
E04 Class See Also Send Feedback
Auxiliary for use as a delegate parameter

Syntax

C#
public static void e04ugm(
    ref int mode,
    int ncnln,
    int njnln,
    int nnzjac,
    double[] x,
    double[] f,
    double[] fjac,
    int nstate
)
Visual Basic
Public Shared Sub e04ugm ( _
    ByRef mode As Integer, _
    ncnln As Integer, _
    njnln As Integer, _
    nnzjac As Integer, _
    x As Double(), _
    f As Double(), _
    fjac As Double(), _
    nstate As Integer _
)
Visual C++
public:
static void e04ugm(
    int% mode,
    int ncnln,
    int njnln,
    int nnzjac,
    array<double>^ x,
    array<double>^ f,
    array<double>^ fjac,
    int nstate
)
F#
static member e04ugm :
        mode : int byref *
        ncnln : int *
        njnln : int *
        nnzjac : int *
        x : float[] *
        f : float[] *
        fjac : float[] *
        nstate : int -> unit

Parameters

mode
Type: System..::..Int32 %
On entry: indicates which values must be assigned during each call of _confun. Only the following values need be assigned:
mode=0
f.
mode=1
All available elements of fjac.
mode=2
f and all available elements of fjac.
On exit: you may set to a negative value as follows:
mode≤-2
The solution to the current problem is terminated and in this case e04ug will terminate with _ifail set to mode.
mode=-1
The nonlinear constraint functions cannot be calculated at the current x. e04ug will then terminate with ifail=-1 unless this occurs during the linesearch; in this case, the linesearch will shorten the step and try again.
ncnln
Type: System..::..Int32
On initial entry: nN, the number of nonlinear constraints.
Constraint: ncnln≥0.
njnln
Type: System..::..Int32
On entry: n 1′′, the number of nonlinear variables. These must be the first njnln variables in the problem.
nnzjac
Type: System..::..Int32
On entry: the number of nonzero elements in the constraint Jacobian. Note that nnzjac will usually be less than ncnln×njnln.
x
Type: array< System..::..Double >[]()[][]
An array of size [njnln]
On entry: x, the vector of nonlinear Jacobian variables at which the nonlinear constraint functions and/or the available elements of the constraint Jacobian are to be evaluated.
f
Type: array< System..::..Double >[]()[][]
An array of size [ncnln]
On exit: if mode=0 or 2, f[i-1] must contain the value of the ith nonlinear constraint function at x.
fjac
Type: array< System..::..Double >[]()[][]
An array of size [nnzjac]
On entry: the elements of fjac are set to special values which enable e04ug to detect whether they are changed by _confun.
On exit: if mode=1 or 2, fjac must return the available elements of the constraint Jacobian evaluated at x. These elements must be stored in exactly the same positions as implied by the definitions of the arrays _a, _ha and _ka. If optional parameter optparam_derivativelevel=2 or 3, the value of any constant Jacobian element not defined by _confun will be obtained directly from _a. Note that the method does not perform any internal checks for consistency (except indirectly via the optional parameter optparam_verifylevel), so great care is essential.
nstate
Type: System..::..Int32
On entry: if nstate=1, then e04ug is calling _confun for the first time. This parameter setting allows you to save computation time if certain data must be read or calculated only once.
If nstate≥2, then e04ug is calling _confun for the last time. This parameter setting allows you to perform some additional computation on the final solution. In general, the last call to _confun is made with nstate=2+_ifail (see [Error Indicators and Warnings]).
Otherwise, nstate=0.

Description

Auxiliary for use as a delegate parameter

References

None.

Error Indicators and Warnings

None.

Accuracy

Not applicable.

Further Comments

None.

Example

None.

See Also

E04 Class
E04 Members


e04ugn Method

[image]

NAG Library for .NET Release 2
E04..::e04ugn Method
E04 Class See Also Send Feedback
Auxiliary for use as a delegate parameter

Syntax

C#
public static void e04ugn(
    ref int mode,
    int nonln,
    double[] x,
    ref double objf,
    double[] objgrd,
    int nstate
)
Visual Basic
Public Shared Sub e04ugn ( _
    ByRef mode As Integer, _
    nonln As Integer, _
    x As Double(), _
    ByRef objf As Double, _
    objgrd As Double(), _
    nstate As Integer _
)
Visual C++
public:
static void e04ugn(
    int% mode,
    int nonln,
    array<double>^ x,
    double% objf,
    array<double>^ objgrd,
    int nstate
)
F#
static member e04ugn :
        mode : int byref *
        nonln : int *
        x : float[] *
        objf : float byref *
        objgrd : float[] *
        nstate : int -> unit

Parameters

mode
Type: System..::..Int32 %
On entry: indicates which values must be assigned during each call of _objfun. Only the following values need be assigned:
mode=0
objf.
mode=1
All available elements of objgrd.
mode=2
objf and all available elements of objgrd.
On exit: you may set to a negative value as follows:
mode≤-2
The solution to the current problem is terminated and in this case e04ug will terminate with _ifail set to mode.
mode=-1
The nonlinear part of the objective function cannot be calculated at the current x. e04ug will then terminate with ifail=-1 unless this occurs during the linesearch; in this case, the linesearch will shorten the step and try again.
nonln
Type: System..::..Int32
On entry: n 1′, the number of nonlinear objective variables. These must be the first nonln variables in the problem.
x
Type: array< System..::..Double >[]()[][]
An array of size [nonln]
On entry: x, the vector of nonlinear variables at which the nonlinear part of the objective function and/or all available elements of its gradient are to be evaluated.
objf
Type: System..::..Double %
On exit: if mode=0 or 2, objf must be set to the value of the objective function at x.
objgrd
Type: array< System..::..Double >[]()[][]
An array of size [nonln]
On entry: the elements of objgrd are set to special values which enable e04ug to detect whether they are changed by _objfun.
On exit: if mode=1 or 2, objgrd must return the available elements of the gradient evaluated at x.
nstate
Type: System..::..Int32
On entry: if nstate=1, e04ug is calling _objfun for the first time. This parameter setting allows you to save computation time if certain data must be read or calculated only once.
If nstate≥2, e04ug is calling _objfun for the last time. This parameter setting allows you to perform some additional computation on the final solution. In general, the last call to _objfun is made with nstate=2+_ifail (see [Error Indicators and Warnings]).
Otherwise, nstate=0.

Description

Auxiliary for use as a delegate parameter

References

None.

Error Indicators and Warnings

None.

Accuracy

Not applicable.

Further Comments

None.

Example

None.

See Also

E04 Class
E04 Members


e04us Method

[image]

NAG Library for .NET Release 2
E04..::e04us Method
E04 Class See Also Send Feedback
e04us is designed to minimize an arbitrary smooth sum of squares function subject to constraints (which may include simple bounds on the variables, linear constraints and smooth nonlinear constraints) using a sequential quadratic programming (SQP) method. As many first derivatives as possible should be supplied by you; any unspecified derivatives are approximated by finite differences. See the description of the optional parameter Derivative Level, in [Description of the Optional Parameters]. It is not intended for large sparse problems.
e04us may also be used for unconstrained, bound-constrained and linearly constrained optimization.

Syntax

C#
public static void e04us(
    int m,
    int n,
    int nclin,
    int ncnln,
    double[,] a,
    double[] bl,
    double[] bu,
    double[] y,
    E04..::..E04US_CONFUN confun,
    E04..::..E04US_OBJFUN objfun,
    out int iter,
    int[] istate,
    double[] c,
    double[,] cjac,
    double[] f,
    double[,] fjac,
    double[] clamda,
    out double objf,
    double[,] r,
    double[] x,
    E04..::..e04usOptions options,
    out int ifail
)
Visual Basic
Public Shared Sub e04us ( _
    m As Integer, _
    n As Integer, _
    nclin As Integer, _
    ncnln As Integer, _
    a As Double(,), _
    bl As Double(), _
    bu As Double(), _
    y As Double(), _
    confun As E04..::..E04US_CONFUN, _
    objfun As E04..::..E04US_OBJFUN, _
    <OutAttribute> ByRef iter As Integer, _
    istate As Integer(), _
    c As Double(), _
    cjac As Double(,), _
    f As Double(), _
    fjac As Double(,), _
    clamda As Double(), _
    <OutAttribute> ByRef objf As Double, _
    r As Double(,), _
    x As Double(), _
    options As E04..::..e04usOptions, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04us(
    int m,
    int n,
    int nclin,
    int ncnln,
    array<double,2>^ a,
    array<double>^ bl,
    array<double>^ bu,
    array<double>^ y,
    E04..::..E04US_CONFUN^ confun,
    E04..::..E04US_OBJFUN^ objfun,
    [OutAttribute] int% iter,
    array<int>^ istate,
    array<double>^ c,
    array<double,2>^ cjac,
    array<double>^ f,
    array<double,2>^ fjac,
    array<double>^ clamda,
    [OutAttribute] double% objf,
    array<double,2>^ r,
    array<double>^ x,
    E04..::..e04usOptions^ options,
    [OutAttribute] int% ifail
)
F#
static member e04us :
        m : int *
        n : int *
        nclin : int *
        ncnln : int *
        a : float[,] *
        bl : float[] *
        bu : float[] *
        y : float[] *
        confun : E04..::..E04US_CONFUN *
        objfun : E04..::..E04US_OBJFUN *
        iter : int byref *
        istate : int[] *
        c : float[] *
        cjac : float[,] *
        f : float[] *
        fjac : float[,] *
        clamda : float[] *
        objf : float byref *
        r : float[,] *
        x : float[] *
        options : E04..::..e04usOptions *
        ifail : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: m, the number of subfunctions associated with F x.
Constraint: m>0.
n
Type: System..::..Int32
On entry: n, the number of variables.
Constraint: n>0.
nclin
Type: System..::..Int32
On entry: nL, the number of general linear constraints.
Constraint: nclin≥0.
ncnln
Type: System..::..Int32
On entry: nN, the number of nonlinear constraints.
Constraint: ncnln≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,nclin
Note: the second dimension of the array a must be at least n if nclin>0, and at least 1 otherwise.
On entry: the ith row of a contains the ith row of the matrix AL of general linear constraints in (1). That is, the ith row contains the coefficients of the ith general linear constraint, for i=1,2,…,nclin.
If nclin=0, the array a is not referenced.
bl
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin+ncnln]
On entry: must contain the lower bounds and bu the upper bounds, for all the constraints in the following order. The first n elements of each array must contain the bounds on the variables, the next nL elements the bounds for the general linear constraints (if any) and the next nN elements the bounds for the general nonlinear constraints (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j-1]≤-bigbnd, and to specify a nonexistent upper bound (i.e., uj=+∞), set bu[j-1]≥bigbnd; the default value of bigbnd is 1020, but this may be changed by the optional parameter Infinite Bound Size. To specify the jth constraint as an equality, set bl[j-1]=bu[j-1]=β, say, where β<bigbnd.
Constraints:
  • bl[j-1]≤bu[j-1], for j=1,2,…,n+nclin+ncnln;
  • if bl[j-1]=bu[j-1]=β, β<bigbnd.
bu
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin+ncnln]
On entry: must contain the lower bounds and bu the upper bounds, for all the constraints in the following order. The first n elements of each array must contain the bounds on the variables, the next nL elements the bounds for the general linear constraints (if any) and the next nN elements the bounds for the general nonlinear constraints (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j-1]≤-bigbnd, and to specify a nonexistent upper bound (i.e., uj=+∞), set bu[j-1]≥bigbnd; the default value of bigbnd is 1020, but this may be changed by the optional parameter Infinite Bound Size. To specify the jth constraint as an equality, set bl[j-1]=bu[j-1]=β, say, where β<bigbnd.
Constraints:
  • bl[j-1]≤bu[j-1], for j=1,2,…,n+nclin+ncnln;
  • if bl[j-1]=bu[j-1]=β, β<bigbnd.
y
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: the coefficients of the constant vector y of the objective function.
confun
Type: NagLibrary..::..E04..::..E04US_CONFUN
confun must calculate the vector c x of nonlinear constraint functions and (optionally) its Jacobian (=∂c∂x) for a specified n-element vector x. If there are no nonlinear constraints (i.e., ncnln=0), confun will never be called by e04us and confun may be the dummy method E04UDM. (E04UDM is included in the NAG Library.) If there are nonlinear constraints, the first call to confun will occur before the first call to objfun.

A delegate of type E04US_CONFUN.

Note: confun should be tested separately before being used in conjunction with e04us. See also the description of the optional parameter Verify.
objfun
Type: NagLibrary..::..E04..::..E04US_OBJFUN
objfun must calculate either the ith element of the vector f x=f 1 x,f 2 x,…,fm x T or all m elements of f x and (optionally) its Jacobian (=∂f∂x) for a specified n-element vector x.

A delegate of type E04US_OBJFUN.

Note: objfun should be tested separately before being used in conjunction with e04us. See also the description of the optional parameter Verify.
iter
Type: System..::..Int32 %
On exit: the number of major iterations performed.
istate
Type: array< System..::..Int32 >[]()[][]
An array of size [n+nclin+ncnln]
On entry: need not be set if the (default) optional parameter Cold Start is used.
If the optional parameter Warm Start has been chosen, the elements of istate corresponding to the bounds and linear constraints define the initial working set for the procedure that finds a feasible point for the linear constraints and bounds. The active set at the conclusion of this procedure and the elements of istate corresponding to nonlinear constraints then define the initial working set for the first QP subproblem. More precisely, the first n elements of istate refer to the upper and lower bounds on the variables, the next nL elements refer to the upper and lower bounds on AL x, and the next nN elements refer to the upper and lower bounds on c x. Possible values for istate[j-1] are as follows:
istate[j-1] | Meaning
0 | The corresponding constraint is not in the initial QP working set.
1 | This inequality constraint should be in the working set at its lower bound.
2 | This inequality constraint should be in the working set at its upper bound.
3 | This equality constraint should be in the initial working set. This value must not be specified unless bl[j-1]=bu[j-1].
The values -2, -1 and 4 are also acceptable but will be modified by the method. If e04us has been called previously with the same values of n, nclin and ncnln, istate already contains satisfactory information. (See also the description of the optional parameter Warm Start.) The method also adjusts (if necessary) the values supplied in x to be consistent with istate.
Constraint: -2≤istate[j-1]≤4, for j=1,2,…,n+nclin+ncnln.
On exit: the status of the constraints in the QP working set at the point returned in x. The significance of each possible value of istate[j-1] is as follows:
istate[j-1] | Meaning
-2 | This constraint violates its lower bound by more than the appropriate feasibility tolerance (see the optional parameters Linear Feasibility Tolerance and Nonlinear Feasibility Tolerance). This value can occur only when no feasible point can be found for a QP subproblem.
-1 | This constraint violates its upper bound by more than the appropriate feasibility tolerance (see the optional parameters Linear Feasibility Tolerance and Nonlinear Feasibility Tolerance). This value can occur only when no feasible point can be found for a QP subproblem.
-0 | The constraint is satisfied to within the feasibility tolerance, but is not in the QP working set.
-1 | This inequality constraint is included in the QP working set at its lower bound.
-2 | This inequality constraint is included in the QP working set at its upper bound.
-3 | This constraint is included in the QP working set as an equality. This value of istate can occur only when bl[j-1]=bu[j-1].
c
Type: array< System..::..Double >[]()[][]
An array of size [max 1,ncnln]
On exit: if ncnln>0, c[i-1] contains the value of the ith nonlinear constraint function ci at the final iterate, for i=1,2,…,ncnln.
If ncnln=0, the array c is not referenced.
cjac
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,ncnln
Note: the second dimension of the array cjac must be at least n if ncnln>0, and at least 1 otherwise.
On entry: in general, cjac need not be initialized before the call to e04us. However, if Derivative Level=3, you may optionally set the constant elements of cjac (see parameter nstate in the description of confun). Such constant elements need not be re-assigned on subsequent calls to confun.
On exit: if ncnln>0, cjac contains the Jacobian matrix of the nonlinear constraint functions at the final iterate, i.e., cjac[i-1,j-1] contains the partial derivative of the ith constraint function with respect to the jth variable, for i=1,2,…,ncnln and j=1,2,…,n. (See the discussion of parameter cjac under confun.)
If ncnln=0, the array cjac is not referenced.
f
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: f[i-1] contains the value of the ith function fi at the final iterate, for i=1,2,…,m.
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥m
On entry: in general, fjac need not be initialized before the call to e04us. However, if Derivative Level=3, you may optionally set the constant elements of fjac (see parameter nstate in the description of objfun). Such constant elements need not be re-assigned on subsequent calls to objfun.
On exit: the Jacobian matrix of the functions f 1,f 2,…,fm at the final iterate, i.e., fjac[i-1,j-1] contains the partial derivative of the ith function with respect to the jth variable, for i=1,2,…,m and j=1,2,…,n. (See also the discussion of parameter fjac under objfun.)
clamda
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin+ncnln]
On entry: need not be set if the (default) optional parameter Cold Start is used.
If the optional parameter Warm Start has been chosen, clamda[j-1] must contain a multiplier estimate for each nonlinear constraint with a sign that matches the status of the constraint specified by the istate array, for j=n+nclin+1,…,n+nclin+ncnln. The remaining elements need not be set. Note that if the jth constraint is defined as ‘inactive’ by the initial value of the istate array (i.e., istate[j-1]=0), clamda[j-1] should be zero; if the jth constraint is an inequality active at its lower bound (i.e., istate[j-1]=1), clamda[j-1] should be non-negative; if the jth constraint is an inequality active at its upper bound (i.e., istate[j-1]=2, clamda[j-1] should be non-positive. If necessary, the method will modify clamda to match these rules.
On exit: the values of the QP multipliers from the last QP subproblem. clamda[j-1] should be non-negative if istate[j-1]=1 and non-positive if istate[j-1]=2.
objf
Type: System..::..Double %
On exit: the value of the objective function at the final iterate.
r
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: need not be initialized if the (default) optional parameter Cold Start is used.
If the optional parameter Warm Start has been chosen, r must contain the upper triangular Cholesky factor R of the initial approximation of the Hessian of the Lagrangian function, with the variables in the natural order. Elements not in the upper triangular part of r are assumed to be zero and need not be assigned.
On exit: if Hessian=NO, r contains the upper triangular Cholesky factor R of QT H~Q, an estimate of the transformed and reordered Hessian of the Lagrangian at x (see (6) in e04uf). If Hessian=YES, r contains the upper triangular Cholesky factor R of H, the approximate (untransformed) Hessian of the Lagrangian, with the variables in the natural order.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: an initial estimate of the solution.
On exit: the final estimate of the solution.
options
Type: NagLibrary..::..E04..::..e04usOptions
An Object of type E04.e04usOptions. Used to configure optional parameters to this method.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04us is designed to solve the nonlinear least squares programming problem – the minimization of a smooth nonlinear sum of squares function subject to a set of constraints on the variables. The problem is assumed to be stated in the following form:
minimize x∈Rn F x=12∑i=1 m yi-fi x 2  subject to  l≤xAL xc x≤u, (1)
where F x (the objective function) is a nonlinear function which can be represented as the sum of squares of m subfunctions y 1-f 1 x,y 2-f 2 x,…,ym-fm x, the yi are constant, AL is an nL by n constant matrix, and c x is an nN element vector of nonlinear constraint functions. (The matrix AL and the vector c x may be empty.) The objective function and the constraint functions are assumed to be smooth, i.e., at least twice-continuously differentiable. (The method of e04us will usually solve (1) if any isolated discontinuities are away from the solution.)
Note that although the bounds on the variables could be included in the definition of the linear constraints, we prefer to distinguish between them for reasons of computational efficiency. For the same reason, the linear constraints should not be included in the definition of the nonlinear constraints. Upper and lower bounds are specified for all the variables and for all the constraints. An equality constraint can be specified by setting li=ui. If certain bounds are not present, the associated elements of l or u can be set to special values that will be treated as -∞ or +∞. (See the description of the optional parameter Infinite Bound Size.)
You must supply an initial estimate of the solution to (1), together with methods that define f x=f 1 x,f 2 x,…,fm x T, c x and as many first partial derivatives as possible; unspecified derivatives are approximated by finite differences.
The subfunctions are defined by the array y and objfun, and the nonlinear constraints are defined by confun. On every call, these methods must return appropriate values of f x and c x. You should also provide the available partial derivatives. Any unspecified derivatives are approximated by finite differences for a discussion of the optional parameter Derivative Level. Note that if there are any nonlinear constraints, then the first call to confun will precede the first call to objfun.
For maximum reliability, it is preferable for you to provide all partial derivatives (see Chapter 8 of Gill et al. (1981) for a detailed discussion). If all gradients cannot be provided, it is similarly advisable to provide as many as possible. While developing objfun and confun, the optional parameter Verify should be used to check the calculation of any known gradients.

References

Gill P E, Murray W and Wright M H (1981) Practical Optimization Academic Press
Hock W and Schittkowski K (1981) Test Examples for Nonlinear Programming Codes. Lecture Notes in Economics and Mathematical Systems 187 Springer–Verlag

Error Indicators and Warnings

Note: e04us may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA, LDCJ, LDFJ, LDR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail<0
A negative value of ifail indicates an exit from e04us because you set mode<0 in objfun or confun. The value of ifail will be the same as your setting of mode.
ifail=1
The final iterate x satisfies the first-order Kuhn–Tucker conditions (see [] in e04uf) to the accuracy requested, but the sequence of iterates has not yet converged. e04us was terminated because no further improvement could be made in the merit function (see [Description of the Printed Output]).
This value of ifail may occur in several circumstances. The most common situation is that you ask for a solution with accuracy that is not attainable with the given precision of the problem (as specified by the optional parameter Function Precision (default value=ε 0.9, where ε is the machine precision)). This condition will also occur if, by chance, an iterate is an ‘exact’ Kuhn–Tucker point, but the change in the variables was significant at the previous iteration. (This situation often happens when minimizing very simple functions, such as quadratics.)
If the four conditions listed in [Parameters] for ifail=0 are satisfied, x is likely to be a solution of (1) even if ifail=1.
ifail=2
e04us has terminated without finding a feasible point for the linear constraints and bounds, which means that either no feasible point exists for the given value of the optional parameter Linear Feasibility Tolerance (default value=ε, where ε is the machine precision), or no feasible point could be found in the number of iterations specified by the optional parameter Minor Iteration Limit (default value=max 50,3 n+nL+nN). You should check that there are no constraint redundancies. If the data for the constraints are accurate only to an absolute precision σ, you should ensure that the value of the optional parameter Linear Feasibility Tolerance is greater than σ. For example, if all elements of AL are of order unity and are accurate to only three decimal places, Linear Feasibility Tolerance should be at least 10-3.
ifail=3
No feasible point could be found for the nonlinear constraints. The problem may have no feasible solution. This means that there has been a sequence of QP subproblems for which no feasible point could be found (indicated by I at the end of each line of intermediate printout produced by the major iterations; see [Description of the Printed Output]). This behaviour will occur if there is no feasible point for the nonlinear constraints. (However, there is no general test that can determine whether a feasible point exists for a set of nonlinear constraints.) If the infeasible subproblems occur from the very first major iteration, it is highly likely that no feasible point exists. If infeasibilities occur when earlier subproblems have been feasible, small constraint inconsistencies may be present. You should check the validity of constraints with negative values of istate. If you are convinced that a feasible point does exist, e04us should be restarted at a different starting point.
ifail=4
The limiting number of iterations (as determined by the optional parameter Major Iteration Limit (default value=max 50,3 n+nL+10 nN) has been reached.
If the algorithm appears to be making satisfactory progress, then Major Iteration Limit may be too small. If so, either increase its value and rerun e04us or, alternatively, rerun e04us using the optional parameter Warm Start. If the algorithm seems to be making little or no progress however, then you should check for incorrect gradients or ill-conditioning as described under ifail=6.
Note that ill-conditioning in the working set is sometimes resolved automatically by the algorithm, in which case performing additional iterations may be helpful. However, ill-conditioning in the Hessian approximation tends to persist once it has begun, so that allowing additional iterations without altering r is usually inadvisable. If the quasi-Newton update of the Hessian approximation was reset during the latter major iterations (i.e., an r occurs at the end of each line of intermediate printout; see [Description of the Printed Output]), it may be worthwhile to try a Warm Start at the final point as suggested above.
ifail=5
Not used by this method.
ifail=6
x does not satisfy the first-order Kuhn–Tucker conditions (see [] in e04uf), and no improved point for the merit function (see [Description of the Printed Output]) could be found during the final linesearch.
This sometimes occurs because an overly stringent accuracy has been requested, i.e., the value of the optional parameter Optimality Tolerance (default value=εr 0.8, where εr is the value of the optional parameter Function Precision (default value=ε 0.9, where ε is the machine precision)) is too small. In this case you should apply the four tests described under ifail=0 to determine whether or not the final solution is acceptable (see Gill et al. (1981), for a discussion of the attainable accuracy).
If many iterations have occurred in which essentially no progress has been made and e04us has failed completely to move from the initial point then user-supplied delegates objfun and/or confun may be incorrect. You should refer to comments under ifail=7 and check the gradients using the optional parameter Verify (default value=0). Unfortunately, there may be small errors in the objective and constraint gradients that cannot be detected by the verification process. Finite difference approximations to first derivatives are catastrophically affected by even small inaccuracies. An indication of this situation is a dramatic alteration in the iterates if the finite difference interval is altered. One might also suspect this type of error if a switch is made to central differences even when Norm Gz and Violtn (see [Description of the Printed Output]) are large.
Another possibility is that the search direction has become inaccurate because of ill-conditioning in the Hessian approximation or the matrix of constraints in the working set; either form of ill-conditioning tends to be reflected in large values of Mnr (the number of iterations required to solve each QP subproblem; see [Description of the Printed Output]).
If the condition estimate of the projected Hessian (Cond Hz; see [Description of Monitoring Information]) is extremely large, it may be worthwhile rerunning e04us from the final point with the optional parameter Warm Start. In this situation, istate and clamda should be left unaltered and r should be reset to the identity matrix.
If the matrix of constraints in the working set is ill-conditioned (i.e., Cond T is extremely large; see [Description of Monitoring Information]), it may be helpful to run e04us with a relaxed value of the optional parameter Feasibility Tolerance (default value=ε, where ε is the machine precision). (Constraint dependencies are often indicated by wide variations in size in the diagonal elements of the matrix T, whose diagonals will be printed if Major Print Level≥30).
ifail=7
The user-supplied derivatives of the subfunctions and/or nonlinear constraints appear to be incorrect.
Large errors were found in the derivatives of the subfunctions and/or nonlinear constraints. This value of ifail will occur if the verification process indicated that at least one Jacobian element had no correct figures. You should refer to the printed output to determine which elements are suspected to be in error.
As a first-step, you should check that the code for the subfunction and constraint values is correct – for example, by computing the subfunctions at a point where the correct value of F x is known. However, care should be taken that the chosen point fully tests the evaluation of the subfunctions. It is remarkable how often the values x=0 or x=1 are used to test function evaluation procedures, and how often the special properties of these numbers make the test meaningless.
Special care should be used in this test if computation of the subfunctions involves subsidiary data communicated in storage. Although the first evaluation of the subfunctions may be correct, subsequent calculations may be in error because some of the subsidiary data has accidentally been overwritten.
Gradient checking will be ineffective if the objective function uses information computed by the constraints, since they are not necessarily computed before each function evaluation.
Errors in programming the subfunctions may be quite subtle in that the subfunction values are ‘almost’ correct. For example, a subfunction may not be accurate to full precision because of the inaccurate calculation of a subsidiary quantity, or the limited accuracy of data upon which the subfunction depends. A common error on machines where numerical calculations are usually performed in double precision is to include even one single precision constant in the calculation of the subfunction; since some compilers do not convert such constants to double precision, half the correct figures may be lost by such a seemingly trivial error.
ifail=8
Not used by this method.
ifail=9
An input parameter is invalid.
overflow
If overflow occurs then either an element of C is very large, or the singular values or singular vectors have been incorrectly supplied.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

If ifail=0 on exit, then the vector returned in the array x is an estimate of the solution to an accuracy of approximately Optimality Tolerance (default value=ε 0.8, where ε is the machine precision).

Parallelism and Performance

None.

Further Comments

Description of the Printed Output

This section describes the intermediate printout and final printout produced by e04us. The intermediate printout is a subset of the monitoring information produced by the method at every iteration (see [Description of Monitoring Information]). You can control the level of printed output (see the description of the optional parameter Major Print Level). Note that the intermediate printout and final printout are produced only if Major Print Level≥10 (the default for e04us, by default no output is produced by ). (by default no output is produced by e04us).
The following line of summary output (<80 characters) is produced at every major iteration. In all cases, the values of the quantities printed are those in effect on completion of the given iteration.
Maj | is the major iteration count.
Mnr is the number of minor iterations required by the feasibility and optimality phases of the QP subproblem. Generally, Mnr will be 1 in the later iterations, since theoretical analysis predicts that the correct active set will be identified near the solution (see [Algorithmic Details] in e04uf).
Note that Mnr may be greater than the optional parameter Minor Iteration Limit if some iterations are required for the feasibility phase.
Step | is the step αk taken along the computed search direction. On reasonably well-behaved problems, the unit step (i.e., αk=1) will be taken as the solution is approached.
Merit Function is the value of the augmented Lagrangian merit function (see (12) in e04uf) at the current iterate. This function will decrease at each iteration unless it was necessary to increase the penalty parameters (see [] in e04uf). As the solution is approached, Merit Function will converge to the value of the objective function at the solution.
If the QP subproblem does not have a feasible point (signified by I at the end of the current output line) then the merit function is a large multiple of the constraint violations, weighted by the penalty parameters. During a sequence of major iterations with infeasible subproblems, the sequence of Merit Function values will decrease monotonically until either a feasible subproblem is obtained or e04us terminates with ifail=3 (no feasible point could be found for the nonlinear constraints).
If there are no nonlinear constraints present (i.e., ncnln=0) then this entry contains Objective, the value of the objective function F x. The objective function will decrease monotonically to its optimal value when there are no nonlinear constraints.
Norm Gz | is ZT gFR, the Euclidean norm of the projected gradient (see [] in e04uf). Norm Gz will be approximately zero in the neighbourhood of a solution.
Violtn | is the Euclidean norm of the residuals of constraints that are violated or in the predicted active set (not printed if ncnln is zero). Violtn will be approximately zero in the neighbourhood of a solution.
Cond Hz | is a lower bound on the condition number of the projected Hessian approximation HZ (HZ=ZT HFR Z=RZT RZ; see (6) and (11) in e04uf). The larger this number, the more difficult the problem.
M | is printed if the quasi-Newton update has been modified to ensure that the Hessian approximation is positive definite (see [] in e04uf).
I | is printed if the QP subproblem has no feasible point.
C | is printed if central differences have been used to compute the unspecified objective and constraint gradients. If the value of Step is zero then the switch to central differences was made because no lower point could be found in the linesearch. (In this case, the QP subproblem is resolved with the central difference gradient and Jacobian.) If the value of Step is nonzero then central differences were computed because Norm Gz and Violtn imply that x is close to a Kuhn–Tucker point (see [] in e04uf).
L | is printed if the linesearch has produced a relative change in x greater than the value defined by the optional parameter Step Limit. If this output occurs frequently during later iterations of the run, optional parameter Step Limit should be set to a larger value.
R | is printed if the approximate Hessian has been refactorized. If the diagonal condition estimator of R indicates that the approximate Hessian is badly conditioned then the approximate Hessian is refactorized using column interchanges. If necessary, R is modified so that its diagonal condition estimator is bounded.
The final printout includes a listing of the status of every variable and constraint.
The following describes the printout for each variable. A full stop (.) is printed for any numerical value that is zero.
Varbl | gives the name (V) and index j, for j=1,2,…,n, of the variable.
State gives the state of the variable (FR if neither bound is in the working set, EQ if a fixed variable, LL if on its lower bound, UL if on its upper bound, TF if temporarily fixed at its current value). If Value lies outside the upper or lower bounds by more than the Feasibility Tolerance, State will be ++ or -- respectively.
A key is sometimes printed before State.
A | Alternative optimum possible. The variable is active at one of its bounds, but its Lagrange multiplier is essentially zero. This means that if the variable were allowed to start moving away from its bound then there would be no change to the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case the values of the Lagrange multipliers might also change.
D | Degenerate. The variable is free, but it is equal to (or very close to) one of its bounds.
I | Infeasible. The variable is currently violating one of its bounds by more than the Feasibility Tolerance.
Value | is the value of the variable at the final iteration.
Lower Bound | is the lower bound specified for the variable. None indicates that bl[j-1]≤-bigbnd.
Upper Bound | is the upper bound specified for the variable. None indicates that bu[j-1]≥bigbnd.
Lagr Mult | is the Lagrange multiplier for the associated bound. This will be zero if State is FR unless bl[j-1]≤-bigbnd and bu[j-1]≥bigbnd, in which case the entry will be blank. If x is optimal, the multiplier should be non-negative if State is LL and non-positive if State is UL.
Slack | is the difference between the variable Value and the nearer of its (finite) bounds bl[j-1] and bu[j-1]. A blank entry indicates that the associated variable is not bounded (i.e., bl[j-1]≤-bigbnd and bu[j-1]≥bigbnd).
The meaning of the printout for linear and nonlinear constraints is the same as that given above for variables, with ‘variable’ replaced by ‘constraint’, bl[j-1] and bu[j-1] are replaced by bl[n+j-1] and bu[n+j-1] respectively, and with the following changes in the heading:
L Con | gives the name (L) and index j, for j=1,2,…,nL, of the linear constraint.
N Con | gives the name (N) and index (j-nL), for j=nL+1,…,nL+nN, of the nonlinear constraint.
Note that movement off a constraint (as opposed to a variable moving away from its bound) can be interpreted as allowing the entry in the Slack column to become positive.
Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.

Example

This example is based on Problem 57 in Hock and Schittkowski (1981) and involves the minimization of the sum of squares function
F x=12∑i=1 44 yi-fi x 2,
where
fi x=x 1+0.49-x 1 e-x 2 ai-8
and
iyiaiiyiai10.498230.412220.498240.402230.4810250.422440.4710260.402450.4810270.402460.4710280.412670.4612290.402680.4612300.412690.4512310.4128100.4312320.4028110.4514330.4030120.4314340.4030130.4314350.3830140.4416360.4132150.4316370.4032160.4316380.4034170.4618390.4136180.4518400.3836190.4220410.4038200.4220420.4038210.4320430.3940220.4122440.3942
subject to the bounds
x 1≥-0.4x 2≥-4.0
to the general linear constraint
x 1+x 2≥1.0
and to the nonlinear constraint
0.49 x 2-x 1x 2≥0.09.
The initial point, which is infeasible, is
x 0=0.4,0.0 T
and F x 0=0.002241.
The optimal solution (to five figures) is
x*=0.41995,1.28484 T,
and F x*=0.01423. The nonlinear constraint is active at the solution.

Example program (C#): e04use.cs

Example program data: e04use.d

Example program results: e04use.r

Algorithmic Details

e04us implements a sequential quadratic programming (SQP) method incorporating an augmented Lagrangian merit function and a BFGS (Broyden–Fletcher–Goldfarb–Shanno) quasi-Newton approximation to the Hessian of the Lagrangian, and is based on e04wd. The documents for e04nc, e04uf and e04wd should be consulted for details of the method.

Description of Monitoring Information

This section describes the long line of output (>80 characters) which forms part of the monitoring information produced by e04us. (See also the description of the optional parameters Major Print Level, Minor Print Level and Monitoring File.) You can control the level of printed output.
When Major Print Level≥5 and Monitoring File≥0, the following line of output is produced at every major iteration of e04us on the unit number specified by optional parameter Monitoring File. In all cases, the values of the quantities printed are those in effect on completion of the given iteration.
Maj | is the major iteration count.
Mnr is the number of minor iterations required by the feasibility and optimality phases of the QP subproblem. Generally, Mnr will be 1 in the later iterations, since theoretical analysis predicts that the correct active set will be identified near the solution (see [Algorithmic Details] in e04uf).
Note that Mnr may be greater than the optional parameter Minor Iteration Limit if some iterations are required for the feasibility phase.
Step | is the step αk taken along the computed search direction. On reasonably well-behaved problems, the unit step (i.e., αk=1) will be taken as the solution is approached.
Nfun | is the cumulative number of evaluations of the objective function needed for the linesearch. Evaluations needed for the estimation of the gradients by finite differences are not included. Nfun is printed as a guide to the amount of work required for the linesearch.
Merit Function is the value of the augmented Lagrangian merit function (see (12) in e04uf) at the current iterate. This function will decrease at each iteration unless it was necessary to increase the penalty parameters (see [] in e04uf). As the solution is approached, Merit Function will converge to the value of the objective function at the solution.
If the QP subproblem does not have a feasible point (signified by I at the end of the current output line) then the merit function is a large multiple of the constraint violations, weighted by the penalty parameters. During a sequence of major iterations with infeasible subproblems, the sequence of Merit Function values will decrease monotonically until either a feasible subproblem is obtained or e04us terminates with ifail=3 (no feasible point could be found for the nonlinear constraints).
If there are no nonlinear constraints present (i.e., ncnln=0) then this entry contains Objective, the value of the objective function F x. The objective function will decrease monotonically to its optimal value when there are no nonlinear constraints.
Norm Gz | is ZT gFR, the Euclidean norm of the projected gradient (see [] in e04uf). Norm Gz will be approximately zero in the neighbourhood of a solution.
Violtn | is the Euclidean norm of the residuals of constraints that are violated or in the predicted active set (not printed if ncnln is zero). Violtn will be approximately zero in the neighbourhood of a solution.
Nz | is the number of columns of Z (see [] in e04uf). The value of Nz is the number of variables minus the number of constraints in the predicted active set; i.e., Nz=n-Bnd+Lin+Nln.
Bnd | is the number of simple bound constraints in the current working set.
Lin | is the number of general linear constraints in the current working set.
Nln | is the number of nonlinear constraints in the predicted active set (not printed if ncnln is zero).
Penalty | is the Euclidean norm of the vector of penalty parameters used in the augmented Lagrangian merit function (not printed if ncnln is zero).
Cond H | is a lower bound on the condition number of the Hessian approximation H.
Cond Hz | is a lower bound on the condition number of the projected Hessian approximation HZ (HZ=ZT HFR Z=RZT RZ; see (6) and (11) in e04uf). The larger this number, the more difficult the problem.
Cond T | is a lower bound on the condition number of the matrix of predicted active constraints.
Conv is a three-letter indication of the status of the three convergence tests (2)–(4) defined in the description of the optional parameter Optimality Tolerance. Each letter is T if the test is satisfied and F otherwise. The three tests indicate whether:
(i) | the sequence of iterates has converged;
(ii) | the projected gradient (Norm Gz) is sufficiently small; and
(iii) | the norm of the residuals of constraints in the predicted active set (Violtn) is small enough.
If any of these indicators is F when e04us terminates with ifail=0, you should check the solution carefully.
M | is printed if the quasi-Newton update has been modified to ensure that the Hessian approximation is positive definite (see [] in e04uf).
I | is printed if the QP subproblem has no feasible point.
C | is printed if central differences have been used to compute the unspecified objective and constraint gradients. If the value of Step is zero then the switch to central differences was made because no lower point could be found in the linesearch. (In this case, the QP subproblem is resolved with the central difference gradient and Jacobian.) If the value of Step is nonzero then central differences were computed because Norm Gz and Violtn imply that x is close to a Kuhn–Tucker point (see [] in e04uf).
L | is printed if the linesearch has produced a relative change in x greater than the value defined by the optional parameter Step Limit. If this output occurs frequently during later iterations of the run, optional parameter Step Limit should be set to a larger value.
R | is printed if the approximate Hessian has been refactorized. If the diagonal condition estimator of R indicates that the approximate Hessian is badly conditioned then the approximate Hessian is refactorized using column interchanges. If necessary, R is modified so that its diagonal condition estimator is bounded.

See Also

E04 Class
E04 Members


e04vh Method

[image]

NAG Library for .NET Release 2
E04..::e04vh Method
E04 Class See Also Send Feedback
e04vh solves sparse linear and nonlinear programming problems.

Syntax

C#
public static void e04vh(
    int start,
    int nf,
    int n,
    int nxname,
    int nfname,
    double objadd,
    int objrow,
    string prob,
    E04..::..E04VH_USRFUN usrfun,
    int[] iafun,
    int[] javar,
    int nea,
    double[] a,
    int[] igfun,
    int[] jgvar,
    int neg,
    double[] xlow,
    double[] xupp,
    string[] xnames,
    double[] flow,
    double[] fupp,
    string[] fnames,
    double[] x,
    int[] xstate,
    double[] xmul,
    double[] f,
    int[] fstate,
    double[] fmul,
    ref int ns,
    out int ninf,
    out double sinf,
    E04..::..e04vhOptions options,
    out int ifail
)
Visual Basic
Public Shared Sub e04vh ( _
    start As Integer, _
    nf As Integer, _
    n As Integer, _
    nxname As Integer, _
    nfname As Integer, _
    objadd As Double, _
    objrow As Integer, _
    prob As String, _
    usrfun As E04..::..E04VH_USRFUN, _
    iafun As Integer(), _
    javar As Integer(), _
    nea As Integer, _
    a As Double(), _
    igfun As Integer(), _
    jgvar As Integer(), _
    neg As Integer, _
    xlow As Double(), _
    xupp As Double(), _
    xnames As String(), _
    flow As Double(), _
    fupp As Double(), _
    fnames As String(), _
    x As Double(), _
    xstate As Integer(), _
    xmul As Double(), _
    f As Double(), _
    fstate As Integer(), _
    fmul As Double(), _
    ByRef ns As Integer, _
    <OutAttribute> ByRef ninf As Integer, _
    <OutAttribute> ByRef sinf As Double, _
    options As E04..::..e04vhOptions, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04vh(
    int start,
    int nf,
    int n,
    int nxname,
    int nfname,
    double objadd,
    int objrow,
    String^ prob,
    E04..::..E04VH_USRFUN^ usrfun,
    array<int>^ iafun,
    array<int>^ javar,
    int nea,
    array<double>^ a,
    array<int>^ igfun,
    array<int>^ jgvar,
    int neg,
    array<double>^ xlow,
    array<double>^ xupp,
    array<String^>^ xnames,
    array<double>^ flow,
    array<double>^ fupp,
    array<String^>^ fnames,
    array<double>^ x,
    array<int>^ xstate,
    array<double>^ xmul,
    array<double>^ f,
    array<int>^ fstate,
    array<double>^ fmul,
    int% ns,
    [OutAttribute] int% ninf,
    [OutAttribute] double% sinf,
    E04..::..e04vhOptions^ options,
    [OutAttribute] int% ifail
)
F#
static member e04vh :
        start : int *
        nf : int *
        n : int *
        nxname : int *
        nfname : int *
        objadd : float *
        objrow : int *
        prob : string *
        usrfun : E04..::..E04VH_USRFUN *
        iafun : int[] *
        javar : int[] *
        nea : int *
        a : float[] *
        igfun : int[] *
        jgvar : int[] *
        neg : int *
        xlow : float[] *
        xupp : float[] *
        xnames : string[] *
        flow : float[] *
        fupp : float[] *
        fnames : string[] *
        x : float[] *
        xstate : int[] *
        xmul : float[] *
        f : float[] *
        fstate : int[] *
        fmul : float[] *
        ns : int byref *
        ninf : int byref *
        sinf : float byref *
        options : E04..::..e04vhOptions *
        ifail : int byref -> unit

Parameters

start
Type: System..::..Int32
On entry: indicates how a starting point is to be obtained.
start=0
Requests that the Crash procedure be used, unless a Basis file is provided via optional parameters Old Basis File, Insert File or Load File.
start=1
Is the same as start=0 but is more meaningful when a Basis file is given.
start=2
Means that xstate and fstate define a valid starting point (probably from an earlier call, though not necessarily).
Constraint: start=0, 1 or 2.
nf
Type: System..::..Int32
On entry: nf, the number of problem functions in F x, including the objective function (if any) and the linear and nonlinear constraints. Upper and lower bounds on x can be defined using the parameters xlow and xupp and should not be included in F.
Constraint: nf>0.
n
Type: System..::..Int32
On entry: n, the number of variables.
Constraint: n>0.
nxname
Type: System..::..Int32
On entry: the number of names provided in the array xnames.
nxname=1
There are no names provided and generic names will be used in the output.
nxname=n
Names for all variables must be provided and will be used in the output.
Constraint: nxname=1​ or ​n.
nfname
Type: System..::..Int32
On entry: the number of names provided in the array fnames.
nfname=1
There are no names provided and generic names will be used in the output.
nfname=nf
Names for all functions must be provided and will be used in the output.
Constraint: nfname=1​ or ​nf.
Note: if nxname=1 then nfname must also be 1 (and vice versa). Similarly, if nxname=n then nfname must be nf (and vice versa).
objadd
Type: System..::..Double
On entry: is a constant that will be added to the objective row Fobj for printing purposes. Typically, objadd=0.0E+0.
objrow
Type: System..::..Int32
On entry: says which row of F x is to act as the objective function. If there is no such row, set objrow=0. Then e04vh will seek a feasible point such that lF≤F x≤uF and lx≤x≤ux.
Constraint: 1≤objrow≤nf​ or ​objrow=0 (or a feasible point problem).
prob
Type: System..::..String
On entry: is an 8-character name for the problem. prob is used in the printed solution and in some methods that output Basis files. A blank name may be used.
usrfun
Type: NagLibrary..::..E04..::..E04VH_USRFUN
usrfun must define the nonlinear portion f x of the problem functions F x=f x+Ax, along with its gradient elements G ij x=∂fi x∂xj. (A dummy method is needed even if f≡0 and all functions are linear.)
In general, usrfun should return all function and gradient values on every entry except perhaps the last. This provides maximum reliability and corresponds to the default option setting, Derivative Option=1.
The elements of G x are stored in the array g 1:usrfun_leng in the order specified by the input arrays igfun and jgvar.
In practice it is often convenient not to code gradients. e04vh is able to estimate them by finite differences, using a call to usrfun for each variable xj for which some ∂fi x∂xj needs to be estimated. However, this reduces the reliability of the optimization algorithm, and it can be very expensive if there are many such variables xj.
As a compromise, e04vh allows you to code as many gradients as you like. This option is implemented as follows. Just before usrfun is called, each element of the derivative array g is initialized to a specific value. On exit, any element retaining that value must be estimated by finite differences.
Some rules of thumb follow:
(i) | for maximum reliability, compute all gradients;
(ii) | if the gradients are expensive to compute, specify optional parameter Nonderivative Linesearch and use the value of the input parameter needg to avoid computing them on certain entries. (There is no need to compute gradients if needg=0 on entry to usrfun.);
(iii) | if not all gradients are known, you must specify Derivative Option=0. You should still compute as many gradients as you can. (It often happens that some of them are constant or zero.);
(iv) | again, if the known gradients are expensive, don't compute them if needg=0 on entry to usrfun;
(v) | use the input parameter status to test for special actions on the first or last entries;
(vi) | while usrfun is being developed, use the optional parameter Verify Level to check the computation of gradients that are supposedly known;
(vii) | usrfun is not called until the linear constraints and bounds on x are satisfied. This helps confine x to regions where the functions fi x are likely to be defined. However, be aware of the optional parameter Minor Feasibility Tolerance if the functions have singularities on the constraint boundaries;
(viii) | set status=-1 if some of the functions are undefined. The linesearch will shorten the step and try again;
(ix) | set status≤-2 if you want e04vh to stop.

A delegate of type E04VH_USRFUN.

iafun
Type: array< System..::..Int32 >[]()[][]
An array of size [lena]
On entry: define the coordinates i,j and values A ij of the nonzero elements of the linear part A of the function F x=f x+Ax.
In particular, nea triples iafun[k-1],javar[k-1],a[k-1] define the row and column indices i=iafun[k-1] and j=javar[k-1] of the element A ij=a[k-1].
The coordinates may define the elements of A in any order.
javar
Type: array< System..::..Int32 >[]()[][]
An array of size [lena]
On entry: define the coordinates i,j and values A ij of the nonzero elements of the linear part A of the function F x=f x+Ax.
In particular, nea triples iafun[k-1],javar[k-1],a[k-1] define the row and column indices i=iafun[k-1] and j=javar[k-1] of the element A ij=a[k-1].
The coordinates may define the elements of A in any order.
nea
Type: System..::..Int32
On entry: is the number of nonzero entries in A such that F x=f x+Ax.
Constraint: 0≤nea≤lena.
a
Type: array< System..::..Double >[]()[][]
An array of size [lena]
On entry: define the coordinates i,j and values A ij of the nonzero elements of the linear part A of the function F x=f x+Ax.
In particular, nea triples iafun[k-1],javar[k-1],a[k-1] define the row and column indices i=iafun[k-1] and j=javar[k-1] of the element A ij=a[k-1].
The coordinates may define the elements of A in any order.
igfun
Type: array< System..::..Int32 >[]()[][]
An array of size [leng]
On entry: define the coordinates i,j of the nonzero elements of G, the nonlinear part of the derivative J x=G x+A of the function F x=f x+Ax. e04vj may be used to define these two arrays.
The coordinates can define the elements of G in any order. However, usrfun must define the actual elements of g in exactly the same order as defined by the coordinates igfun,jgvar.
jgvar
Type: array< System..::..Int32 >[]()[][]
An array of size [leng]
On entry: define the coordinates i,j of the nonzero elements of G, the nonlinear part of the derivative J x=G x+A of the function F x=f x+Ax. e04vj may be used to define these two arrays.
The coordinates can define the elements of G in any order. However, usrfun must define the actual elements of g in exactly the same order as defined by the coordinates igfun,jgvar.
neg
Type: System..::..Int32
On entry: the number of nonzero entries in G.
Constraint: 0≤neg≤leng.
xlow
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: contain the lower and upper bounds lx and ux on the variables x.
To specify a nonexistent lower bound lx j=-∞, set xlow[j-1]≤-bigbnd, where bigbnd is the optional parameter Infinite Bound Size. To specify a nonexistent upper bound ux j=∞, set xupp[j-1]≥bigbnd.
To fix the jth variable at xj=β, where β<bigbnd, set xlow[j-1]=xupp[j-1]=β.
Constraint: xlow[i-1]≤xupp[i-1], for i=1,2,…,n.
xupp
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: contain the lower and upper bounds lx and ux on the variables x.
To specify a nonexistent lower bound lx j=-∞, set xlow[j-1]≤-bigbnd, where bigbnd is the optional parameter Infinite Bound Size. To specify a nonexistent upper bound ux j=∞, set xupp[j-1]≥bigbnd.
To fix the jth variable at xj=β, where β<bigbnd, set xlow[j-1]=xupp[j-1]=β.
Constraint: xlow[i-1]≤xupp[i-1], for i=1,2,…,n.
xnames
Type: array< System..::..String >[]()[][]
An array of size [nxname]
On entry: the optional names for the variables.
If nxname=1, xnames is not referenced and default names will be used for output.
If nxname=n, xnames[j-1] should contain the 8-character name of the jth variable.
flow
Type: array< System..::..Double >[]()[][]
An array of size [nf]
On entry: contain the lower and upper bounds lF and uF on F x.
To specify a nonexistent lower bound lF i=-∞, set flow[i-1]≤-bigbnd. For a nonexistent upper bound uF i=∞, set fupp[i-1]≥bigbnd.
To make the ith constraint an equality at Fi=β, where β<bigbnd, set flow[i-1]=fupp[i-1]=β.
Constraint: flow[i-1]≤fupp[i-1], for i=1,2,…,n.
fupp
Type: array< System..::..Double >[]()[][]
An array of size [nf]
On entry: contain the lower and upper bounds lF and uF on F x.
To specify a nonexistent lower bound lF i=-∞, set flow[i-1]≤-bigbnd. For a nonexistent upper bound uF i=∞, set fupp[i-1]≥bigbnd.
To make the ith constraint an equality at Fi=β, where β<bigbnd, set flow[i-1]=fupp[i-1]=β.
Constraint: flow[i-1]≤fupp[i-1], for i=1,2,…,n.
fnames
Type: array< System..::..String >[]()[][]
An array of size [nfname]
On entry: the optional names for the problem functions.
If nfname=1, fnames is not referenced and default names will be used for output.
If nfname=nf, fnames[i-1] should contain the 8-character name of the ith row of F.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: an initial estimate of the variables x. See the following description of xstate.
On exit: the final values of the variable x.
xstate
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On entry: the initial state for each variable x.
If start=0 or 1 and no basis information is provided (the optional parameters Old Basis File, Insert File and Load File are all set to 0; the default) x and xstate must be defined.
If nothing special is known about the problem, or if there is no wish to provide special information, you may set x[j-1]=0.0, xstate[j-1]=0, for all j=1,2,…,n. If you set x[j-1]=xlow[j-1] set xstate[j-1]=4; if you set x[j-1]=xupp[j-1] then set xstate[j-1]=5. In this case a Crash procedure is used to select an initial basis.
If start=0 or 1 and basis information is provided (at least one of the optional parameters Old Basis File, Insert File and Load File is nonzero) x and xstate need not be set.
If start=2 (Warm Start), x and xstate must be set (probably from a previous call). In this case xstate[j-1] must be 0, 1, 2​ or ​3, for j=1,2,…,n.
On exit: the final state of the variables.
xstate[j-1] | State of variable j | Usual value of x[j-1]
0 | nonbasic | xlow[j-1]
1 | nonbasic | xupp[j-1]
2 | superbasic | Between xlow[j-1] and xupp[j-1]
3 | basic | Between xlow[j-1] and xupp[j-1]
Basic and superbasic variables may be outside their bounds by as much as the optional parameter Minor Feasibility Tolerance. Note that if scaling is specified, the feasibility tolerance applies to the variables of the scaled problem. In this case, the variables of the original problem may be as much as 0.1 outside their bounds, but this is unlikely unless the problem is very badly scaled. Check the value of Primal infeasibility output to the unit number associated with the optional parameter Print File.
Very occasionally some nonbasic variables may be outside their bounds by as much as the optional parameter Minor Feasibility Tolerance, and there may be some nonbasics for which x[j-1] lies strictly between its bounds.
If ninf>0, some basic and superbasic variables may be outside their bounds by an arbitrary amount (bounded by sinf if scaling was not used).
Constraint: 0≤xstate[j-1]≤5, for ​j=1,2,…,n.
xmul
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the vector of the dual variables (Lagrange multipliers) for the simple bounds lx≤x≤ux.
f
Type: array< System..::..Double >[]()[][]
An array of size [nf]
On entry: an initial value for the problem functions F. See the following description of fstate.
On exit: the final values for the problem functions F (the values F at the final point x).
fstate
Type: array< System..::..Int32 >[]()[][]
An array of size [nf]
On entry: the initial state for the problem functions F.
If start=0 or 1 and no basis information is provided (the optional parameters Old Basis File, Insert File and Load File are all set to 0; the default, f and fstate must be defined.
If nothing special is known about the problem, or if there is no wish to provide special information, you may set f[i-1]=0.0, fstate[i-1]=0, for all i=1,2,…,nf. Less trivially, to say that the optimal value of function f[i-1] will probably be equal to one of its bounds, set f[i-1]=flow[i-1] and fstate[i-1]=4 or f[i-1]=fupp[i-1] and fstate[i-1]=5 as appropriate. In this case a Crash procedure is used to select an initial basis.
If start=0 or 1 and basis information is provided (at least one of the optional parameters Old Basis File, Insert File and Load File is nonzero), f and fstate need not be set.
If start=2 (Warm Start), f and fstate must be set (probably from a previous call). In this case fstate[i-1] must be 0, 1, 2 or 3, for i=1,2,…,nf.
On exit: the final state of the variables. The elements of fstate have the following meaning:
fstate[i-1] State of the corresponding
slack variable 		Usual value of f[i-1]
0 | nonbasic | flow[i-1]
1 | nonbasic | fupp[i-1]
2 | superbasic | Between flow[i-1] and fupp[i-1]
3 | basic | Between flow[i-1] and fupp[i-1]
Basic and superbasic slack variables may lead to the corresponding functions being outside their bounds by as much as the optional parameter Minor Feasibility Tolerance.
Very occasionally some functions may be outside their bounds by as much as the optional parameter Minor Feasibility Tolerance, and there may be some nonbasics for which f[i-1] lies strictly between its bounds.
If ninf>0, some basic and superbasic variables may be outside their bounds by an arbitrary amount (bounded by sinf if scaling was not used).
Constraint: 0≤fstate[i-1]≤5, for ​i=1,2,…,nf.
fmul
Type: array< System..::..Double >[]()[][]
An array of size [nf]
On entry: an estimate of γ, the vector of Lagrange multipliers (shadow prices) for the constraints lF≤F x≤uF. All nf components must be defined. If nothing is known about γ, set fmul[i-1]=0.0, for i=1,2,…,nf. For warm start use the values from a previous call.
On exit: the vector of the dual variables (Lagrange multipliers) for the general constraints lF≤F x≤uF
ns
Type: System..::..Int32 %
On entry: the number of superbasic variables. ns need not be specified for cold starts, but should retain its value from a previous call when warm start is used.
On exit: the final number of superbasic variables.
ninf
Type: System..::..Int32 %
On exit: are the number and the sum of the infeasibilities of constraints that lie outside one of their bounds by more than the optional parameter Minor Feasibility Tolerance before the solution is unscaled.
If any linear constraints are infeasible, x minimizes the sum of the infeasibilities of the linear constraints subject to the upper and lower bounds being satisfied. In this case ninf gives the number of variables and linear constraints lying outside their upper or lower bounds. The nonlinear constraints are not evaluated.
Otherwise, x minimizes the sum of infeasibilities of the nonlinear constraints subject to the linear constraints and upper and lower bounds being satisfied. In this case ninf gives the number of components of F x lying outside their bounds by more than the optional parameter Minor Feasibility Tolerance. Again this is before the solution is unscaled.
sinf
Type: System..::..Double %
On exit: are the number and the sum of the infeasibilities of constraints that lie outside one of their bounds by more than the optional parameter Minor Feasibility Tolerance before the solution is unscaled.
If any linear constraints are infeasible, x minimizes the sum of the infeasibilities of the linear constraints subject to the upper and lower bounds being satisfied. In this case ninf gives the number of variables and linear constraints lying outside their upper or lower bounds. The nonlinear constraints are not evaluated.
Otherwise, x minimizes the sum of infeasibilities of the nonlinear constraints subject to the linear constraints and upper and lower bounds being satisfied. In this case ninf gives the number of components of F x lying outside their bounds by more than the optional parameter Minor Feasibility Tolerance. Again this is before the solution is unscaled.
options
Type: NagLibrary..::..E04..::..e04vhOptions
An Object of type E04.e04vhOptions. Used to configure optional parameters to this method.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04vh is designed to minimize a linear or nonlinear function subject to bounds on the variables and sparse linear or nonlinear constraints. It is suitable for large-scale linear and quadratic programming and for linearly constrained optimization, as well as for general nonlinear programs of the form
minimizex f 0 x  subject to ​l≤xf xAL x≤u, (1)
where x is an n-vector of variables, l and u are constant lower and upper bounds, f 0 x is a smooth scalar objective function, AL is a sparse matrix, and f x is a vector of smooth nonlinear constraint functions fi x. The optional parameter Maximize specifies that f 0 x should be maximized instead of minimized.
Ideally, the first derivatives (gradients) of f 0 x and fi x should be known and coded by you. If only some of the gradients are known, e04vh estimates the missing ones by finite differences.
If f 0 x is linear and f x is absent, (1) is a linear program (LP) and e04vh applies the primal simplex method (see Dantzig (1963)). Sparse basis factors are maintained by LUSOL (see Gill et al. (1987)) as in MINOS (see Murtagh and Saunders (1995)).
If only the objective is nonlinear, the problem is linearly constrained (LC) and tends to solve more easily than the general case with nonlinear constraints (NC). For both nonlinear cases, e04vh applies a sparse sequential quadratic programming (SQP) method (see Gill et al. (2002)), using limited-memory quasi-Newton approximations to the Hessian of the Lagrangian. The merit function for step-length control is an augmented Lagrangian, as in the dense SQP solver e04wd (see Gill et al. (1986) and Gill et al. (1992)).
e04vh is suitable for nonlinear problems with thousands of constraints and variables, and is most efficient if only some of the variables enter nonlinearly, or there are relatively few degrees of freedom at a solution (i.e., many constraints are active). However, there is no limit on the number of degrees of freedom.
e04vh allows linear and nonlinear constraints and variables to be entered in an arbitrary order, and uses one method to define all the nonlinear functions.
The optimization problem is assumed to be in the form
minimizex Fobj x  subject to ​lx≤x≤ux,  lF≤F x≤uF, (2)
where the upper and lower bounds are constant, F x is a vector of smooth linear and nonlinear constraint functions Fi x, and Fobj x is one of the components of F to be minimized, as specified by the input parameter objrow. e04vh reorders the variables and constraints so that the problem is in the form (1).
Upper and lower bounds are specified for all variables and functions. The jth constraint may be defined as an equality by setting lj=uj. If certain bounds are not present, the associated elements of l or u should be set to special values that are treated as -∞ or +∞. Free variables and free constraints (‘free rows’) have both bounds infinite.
In general, the components of F are structured in the sense that they are formed from sums of linear and nonlinear functions of just some of the variables. This structure can be exploited by e04vh.
In many cases, the vector F x is a sum of linear and nonlinear functions. e04vh allows these terms to be specified separately, so that the linear part is defined just once by the input arguments iafun, javar and a. Only the nonlinear part is recomputed at each x.
Suppose that each component of F x is of the form
Fi x=fi x+∑j=1 n A ijxj,
where fi x is a nonlinear function (possibly zero) and the elements A ij are constant. The nf by n Jacobian of F x is the sum of two sparse matrices of the same size: F′x=G x+A, where G x=f′x and A is the matrix with elements A ij. The two matrices must be non-overlapping in the sense that each element of the Jacobian F′x=G x+A comes from G x or A, but not both. The element cannot be split between G x and A.
For example, the function
F x=3 x 1+e x 2 x 4+x 22+4 x 4-x 3+x 5x 2+x 32+sin x 4-3 x 5x 1-x 3
can be written as
F x=f x+Ax=e x 2 x 4+x 22+4 x 4x 32+sin x 40+3 x 1-x 3+x 5x 2-3 x 5x 1-x 3,
in which case
F′x=3e x 2 x 4+2 x 2-1e x 2+4-1012 x 3cos x 4-310-10-0
can be written as F′x=f′x+A=G x+A, where
G x=0e x 2 x 4+2 x 20e x 2+40002 x 3cos x 4000000,  A=30-10-101-00-310-10-0.
Note: the element e x 2+4 of F′x appears in G x and is not split between G x and A although it contains a linear term.
The nonzero elements of A and G are provided to e04vh in coordinate form. The elements of A are entered as triples i,j,A ij in the arrays iafun, javar and a. The sparsity pattern G is entered as pairs i,j in the arrays igfun and jgvar. The corresponding entries G ij (any that are known) are assigned to appropriate array elements g k in usrfun.
The elements of A and G may be stored in any order. Duplicate entries are ignored. igfun and jgvar may be defined automatically by method e04vj when Derivative Option=0 is specified and usrfun does not provide any gradients.
Throughout this document the symbol ε is used to represent the machine precision (see x02aj).
e04vh is based on SNOPTA, which is part of the SNOPT package described in Gill et al. (2005b).

References

Dantzig G B (1963) Linear Programming and Extensions Princeton University Press
Eldersveld S K (1991) Large-scale sequential quadratic programming algorithms PhD Thesis Department of Operations Research, Stanford University, Stanford
Fourer R (1982) Solving staircase linear programs by the simplex method Math. Programming 23 274–313
Gill P E, Murray W and Saunders M A (2002) SNOPT: An SQP Algorithm for Large-scale Constrained Optimization 12 979–1006 SIAM J. Optim.
Gill P E, Murray W and Saunders M A (2005a) Users' guide for SQOPT 7: a Fortran package for large-scale linear and quadratic programming Report NA 05-1 Department of Mathematics, University of California, San Diego http://www.ccom.ucsd.edu/~peg/papers/sqdoc7.pdf
Gill P E, Murray W and Saunders M A (2005b) Users' guide for SNOPT 7.1: a Fortran package for large-scale linear nonlinear programming Report NA 05-2 Department of Mathematics, University of California, San Diego http://www.ccom.ucsd.edu/~peg/papers/sndoc7.pdf
Gill P E, Murray W, Saunders M A and Wright M H (1986) Users' guide for NPSOL (Version 4.0): a Fortran package for nonlinear programming Report SOL 86-2 Department of Operations Research, Stanford University
Gill P E, Murray W, Saunders M A and Wright M H (1987) Maintaining LU factors of a general sparse matrix Linear Algebra and its Applics. 88/89 239–270
Gill P E, Murray W, Saunders M A and Wright M H (1992) Some theoretical properties of an augmented Lagrangian merit function Advances in Optimization and Parallel Computing (ed P M Pardalos) 101–128 North Holland
Hock W and Schittkowski K (1981) Test Examples for Nonlinear Programming Codes. Lecture Notes in Economics and Mathematical Systems 187 Springer–Verlag
Murtagh B A and Saunders M A (1978) Large-scale linearly constrained optimization 14 41–72 Math. Programming
Murtagh B A and Saunders M A (1982) A projected Lagrangian algorithm and its implementation for sparse nonlinear constraints Math. Program. Stud. 16 84–118
Murtagh B A and Saunders M A (1995) MINOS 5.4 users' guide Report SOL 83-20R Department of Operations Research, Stanford University

Error Indicators and Warnings

Note: e04vh may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail=1
The initialization method (E04VGF not in this release) has not been called or at least one of lencw, leniw and lenrw is less than 600.
ifail=2
An input parameter is invalid. The output message provides more details of the invalid argument.
ifail=3
Requested accuracy could not be achieved.
A feasible solution has been found, but the requested accuracy in the dual infeasibilities could not be achieved. An abnormal termination has occurred, but e04vh is within 10-2 of satisfying the Major Optimality Tolerance. Check that the Major Optimality Tolerance is not too small.
ifail=4
The problem appears to be infeasible.
When the constraints are linear, this message is based on a relatively reliable indicator of infeasibility. Feasibility is measured with respect to the upper and lower bounds on the variables and slacks. Among all the points satisfying the general constraints Ax-s=0 (see (6) and (7) in [Major Iterations]), there is apparently no point that satisfies the bounds on x and s. Violations as small as the Minor Feasibility Tolerance are ignored, but at least one component of x or s violates a bound by more than the tolerance.
When nonlinear constraints are present, infeasibility is much harder to recognize correctly. Even if a feasible solution exists, the current linearization of the constraints may not contain a feasible point. In an attempt to deal with this situation, when solving each QP subproblem, e04vh is prepared to relax the bounds on the slacks associated with nonlinear rows.
If a QP subproblem proves to be infeasible or unbounded (or if the Lagrange multiplier estimates for the nonlinear constraints become large), e04vh enters so-called ‘nonlinear elastic’ mode. The subproblem includes the original QP objective and the sum of the infeasibilities – suitably weighted using the optional parameter Elastic Weight. In elastic mode, some of the bounds on the nonlinear rows are ‘elastic’ – i.e., they are allowed to violate their specific bounds. Variables subject to elastic bounds are known as elastic variables. An elastic variable is free to violate one or both of its original upper or lower bounds. If the original problem has a feasible solution and the elastic weight is sufficiently large, a feasible point eventually will be obtained for the perturbed constraints, and optimization can continue on the subproblem. If the nonlinear problem has no feasible solution, e04vh will tend to determine a ‘good’ infeasible point if the elastic weight is sufficiently large. (If the elastic weight were infinite, e04vh would locally minimize the nonlinear constraint violations subject to the linear constraints and bounds.)
Unfortunately, even though e04vh locally minimizes the nonlinear constraint violations, there may still exist other regions in which the nonlinear constraints are satisfied. Wherever possible, nonlinear constraints should be defined in such a way that feasible points are known to exist when the constraints are linearized.
ifail=5
The problem appears to be unbounded (or badly scaled).
For linear problems, unboundedness is detected by the simplex method when a nonbasic variable can be increased or decreased by an arbitrary amount without causing a basic variable to violate a bound. Consider adding an upper or lower bound to the variable. Also, examine the constraints that have nonzeros in the associated column, to see if they have been formulated as intended.
Very rarely, the scaling of the problem could be so poor that numerical error will give an erroneous indication of unboundedness. Consider using the optional parameter Scale Option.
For nonlinear problems, e04vh monitors both the size of the current objective function and the size of the change in the variables at each step. If either of these is very large (as judged by the unbounded parameters (see [Major Iteration Log])), the problem is terminated and declared unbounded. To avoid large function values, it may be necessary to impose bounds on some of the variables in order to keep them away from singularities in the nonlinear functions.
The message may indicate an abnormal termination while enforcing the limit on the constraint violations. This exit implies that the objective is not bounded below in the feasible region defined by expanding the bounds by the value of the Violation Limit.
ifail=6
Iteration limit reached.
Either the Iterations Limit or the Major Iterations Limit was exceeded before the required solution could be found. Check the iteration log to be sure that progress was being made. If so, and if you caused a basis file to be saved by using the optional parameter New Basis File, consider restarting the run using the optional parameter Old Basis File to see whether further progress can be made. If you have no basis file available, you might rerun the problem after increasing the optional parameters Minor Iterations Limit and/or Major Iterations Limit.
If none of the above limits have been reached, this error may mean that the problem appears to be more nonlinear than anticipated. The current set of basic and superbasic variables have been optimized as much as possible and a pricing operation (where a nonbasic variable is selected to become superbasic) is necessary to continue, but it can't continue as the number of superbasic variables has already reached the limit specified by the optional parameter Superbasics Limit. In general, raise the Superbasics Limit s by a reasonable amount, bearing in mind the storage needed for the reduced Hessian.
ifail=7
Numerical difficulties have been encountered and no further progress can be made.
Several circumstances could lead to this exit.
1. | usrfun could be returning accurate function values but inaccurate gradients (or vice versa). This is the most likely cause. Study the comments given for ifail=8, and do your best to ensure that the coding is correct.
2. | The function and gradient values could be consistent, but their precision could be too low. For example, accidental use of a low precision data type when a higher precision was intended would lead to a relative function precision of about 10-6 instead of something like 10-15. The default Major Optimality Tolerance of 2×10-6 would need to be raised to about 10-3 for optimality to be declared (at a rather suboptimal point). Of course, it is better to revise the function coding to obtain as much precision as economically possible.
3. If function values are obtained from an expensive iterative process, they may be accurate to rather few significant figures, and gradients will probably not be available. One should specify
  • Function Precision t
  • Major Optimality Tolerance t
but even then, if t is as large as 10-5 or 10-6 (only 5 or 6 significant figures), the same exit condition may occur. At present the only remedy is to increase the accuracy of the function calculation.
4. An LU factorization of the basis has just been obtained and used to recompute the basic variables xB, given the present values of the superbasic and nonbasic variables. A step of ‘iterative refinement’ has also been applied to increase the accuracy of xB. However, a row check has revealed that the resulting solution does not satisfy the current constraints Ax-s=0 sufficiently well.
This probably means that the current basis is very ill-conditioned. If there are some linear constraints and variables, try Scale Option=1 if scaling has not yet been used.
For certain highly structured basis matrices (notably those with band structure), a systematic growth may occur in the factor U. Consult the description of Umax and Growth in [Basis Factorization Statistics] and set the LU Factor Tolerance to 2.0 (or possibly even smaller, but not less than 1.0).
5. | The first factorization attempt will have found the basis to be structurally or numerically singular. (Some diagonals of the triangular matrix U were respectively zero or smaller than a certain tolerance.) The associated variables are replaced by slacks and the modified basis is refactorized, but singularity persists. This must mean that the problem is badly scaled, or the LU Factor Tolerance is too much larger than 1.0. This is highly unlikely to occur.
ifail=8
Derivative appears to be incorrect.
A check has been made on some elements of the Jacobian as returned in the parameter g of usrfun. At least one value disagrees remarkably with its associated forward difference estimate (the relative difference between the computed and estimated values is 1.0 or more). This exit is a safeguard, since e04vh will usually fail to make progress when the computed gradients are seriously inaccurate. In the process it may expend considerable effort before terminating with ifail=7.
Check the function and Jacobian computation very carefully in usrfun. A simple omission could explain everything. If a component is very large, then give serious thought to scaling the function or the nonlinear variables.
If you feel certain that the computed Jacobian is correct (and that the forward-difference estimate is therefore wrong), you can specify Verify Level=0 to prevent individual elements from being checked. However, the optimization procedure may have difficulty.
ifail=9
Undefined user-supplied function.
You have indicated that the problem functions are undefined by assigning the value status=-1 on exit from usrfun. e04vh attempts to evaluate the problem functions closer to a point at which the functions are already known to be defined. This exit occurs if e04vh is unable to find a point at which the functions are defined. This will occur in the case of:
– undefined functions with no recovery possible;
– undefined functions at the first point;
– undefined functions at the first feasible point; or
– undefined functions when checking derivatives.
ifail=10
User requested termination.
You have indicated the wish to terminate solution of the current problem by setting status to a value <-1 on exit from usrfun.
ifail=11
Internal memory allocation failed when attempting to obtain the required workspace. Please contact NAG.
ifail=12
Internal memory allocation was insufficient. Please contact NAG.
ifail=13
An error has occurred in the basis package, perhaps indicating incorrect setup of arrays. Set the optional parameter Print File and examine the output carefully for further information.
ifail=14
An unexpected error has occurred. Set the optional parameter Print File and examine the output carefully for further information.
ifail=-9000
An error occured, see message report.
ifail=-1000
The array lengths are not the same for arrays
ifail=-1000
The array lengths are not the same for arrays
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

If the value of the optional parameter Major Optimality Tolerance is set to 10-d (default value=ε) and ifail=0 on exit, then the final value of f x should have approximately d correct significant digits.

Parallelism and Performance

None.

Further Comments

This section describes the final output produced by e04vh. Intermediate and other output are given in [Description of Monitoring Information].

The Final Output

If Print File>0, the final output, including a listing of the status of every variable and constraint will be sent to the channel numbers associated with Print File. The following describes the output for each constraint (row) and variable (column).

The ROWS section

General linear constraints take the form l≤AL x≤u. The ith constraint is therefore of the form
α≤νi x≤β,
where νi is the ith row of AL.
Internally, the constraints take the form AL x-s=0, where s is the set of slack variables (which satisfy the bounds l≤s≤u). For the ith row it is the slack variable si that is directly available and it is sometimes convenient to refer to its state. Nonlinear constraints α≤fi x+νi x≤β are treated similarly, except that the row activity and degree of infeasibility are computed directly from fi x+νi x, rather than si.
A full stop (.) is printed for any numerical value that is exactly zero.
Label | Description
Number | is the value of n+i. (This is used internally to refer to si in the intermediate output.)
Row | gives the name of the ith row.
State the state of the ith row relative to the bounds α and β. The various states possible are as follows:
LL | the row is at its lower limit, α.
UL | the row is at its upper limit, β.
EQ | the limits are the same (α=β).
FR | si is nonbasic and currently zero, even though it is free to take any value between its bounds α and β.
BS | si is basic.
SBS | si is superbasic.
A key is sometimes printed before State. Note that unless the optional parameter Scale Option=0 is specified, the tests for assigning a key are applied to the variables of the scaled problem.
A | Alternative optimum possible. The variable is nonbasic, but its reduced gradient is essentially zero. This means that if the variable were allowed to start moving away from its bound, there would be no change in the value of the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case, the values of the Lagrange multipliers might also change.
D | Degenerate. The variable is basic or superbasic, but it is equal (or very close) to one of its bounds.
I | Infeasible. The variable is basic or superbasic and is currently violating one of its bounds by more than the value of the Feasibility Tolerance.
N | Not precisely optimal. The variable is nonbasic or superbasic. If the value of the reduced gradient for the variable exceeds the value of the optional parameter Major Optimality Tolerance, the solution would not be declared optimal because the reduced gradient for the variable would not be considered negligible.
Activity | is the value of νi x (or fi x+νi x for nonlinear rows) at the final iterate.
Slack Activity | is the value by which the row differs from its nearest bound. (For the free row (if any), it is set to Activity.)
Lower Limit | is α, the lower bound on the row.
Upper Limit | is β, the upper bound on the row.
Dual Activity | is the value of the dual variable πi (the Lagrange multiplier for the ith constraint). The full vector π always satisfies BT π=gB, where B is the current basis matrix and gB contains the associated gradients for the current objective function. For FP problems, πi is set to zero.
i | gives the index i of the ith row.

The COLUMNS section

Let the jth component of x be the variable xj and assume that it satisfies the bounds α≤xj≤β. A fullstop (.) is printed for any numerical value that is exactly zero.
Label | Description
Number | is the column number j. (This is used internally to refer to xj in the intermediate output.)
Column | gives the name of xj.
State the state of xj relative to the bounds α and β. The various states possible are as follows:
LL | xj is nonbasic at its lower limit, α.
UL | xj is nonbasic at its upper limit, β.
EQ | xj is nonbasic and fixed at the value α=β.
FR | xj is nonbasic at some value strictly between its bounds: α<xj<β.
BS | xj is basic. Usually α<xj<β.
SBS | xj is superbasic. Usually α<xj<β.
A key is sometimes printed before State. Note that unless the optional parameter Scale Option=0 is specified, the tests for assigning a key are applied to the variables of the scaled problem.
A | Alternative optimum possible. The variable is nonbasic, but its reduced gradient is essentially zero. This means that if the variable were allowed to start moving away from its bound, there would be no change in the value of the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case, the values of the Lagrange multipliers might also change.
D | Degenerate. The variable is basic or superbasic, but it is equal (or very close) to one of its bounds.
I | Infeasible. The variable is basic or superbasic and is currently violating one of its bounds by more than the value of the Feasibility Tolerance.
N | Not precisely optimal. The variable is nonbasic or superbasic. If the value of the reduced gradient for the variable exceeds the value of the optional parameter Major Optimality Tolerance, the solution would not be declared optimal because the reduced gradient for the variable would not be considered negligible.
Activity | is the value of xj at the final iterate.
Obj Gradient | is the value of gj at the final iterate. For FP problems, gj is set to zero.
Lower Limit | is the lower bound specified for the variable. None indicates that xlow[j-1]≤-infbnd.
Upper Limit | is the upper bound specified for the variable. None indicates that xupp[j-1]≥infbnd.
Reduced Gradnt | is the value of the reduced gradient dj=gj-πT aj where aj is the jth column of the constraint matrix. For FP problems, dj is set to zero.
m + j | is the value of m+j.
Note that movement off a constraint (as opposed to a variable moving away from its bound) can be interpreted as allowing the entry in the Slack Activity column to become positive.
Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.

Example

This example is a reformulation of Problem 74 from Hock and Schittkowski (1981) and involves the minimization of the nonlinear function
f x=10-6 x 33+23×10-6 x 43+3 x 3+2 x 4
subject to the bounds
-0.55≤x 1≤0.55,-0.55≤x 2≤0.55,-0.0 0≤x 3≤1200,-0.0 0≤x 4≤1200,
to the nonlinear constraints
1000 sin-x 1-0.25+1000 sin-x 2-0.25-x 3=-894.8,1000 sin x 1-0.25+1000 sin x 1-x 2-0.25-x 4=-894.8,1000 sin x 2-0.25+1000 sin x 2-x 1-0.25=-1294.8,
and to the linear constraints
-x 1+x 2≥-0.55,-x 1-x 2≥-0.55.
The initial point, which is infeasible, is
x 0=0,0,0,0 T,
and f x 0=0.
The optimal solution (to five figures) is
x*=0.11887,-0.39623,679.94,1026.0 T,
and f x*=5126.4. All the nonlinear constraints are active at the solution.
The formulation of the problem combines the constraints and the objective into a single vector (F) which is split into linear part (AL x) and a nonlinear part (f). For example we could write
F=1000 sin-x 1-0.25+1000 sin-x 2-0.25-x 31000 sin x 1-0.25+1000 sin x 1-x 2-0.25-x 41000 sin x 2-0.25+1000 sin x 2-x 1-0.25-x 1+x 2-x 1-x 210-6 x 33+23×10-6 x 43+3 x 3+2 x 4=f+AL x
where
f=1000 sin-x 1-0.25+1000 sin-x 2-0.251000 sin x 1-0.25+1000 sin x 1-x 2-0.251000 sin x 2-0.25+1000 sin x 2-x 1-0.250010-6 x 33+23×10-6 x 43
and
AL=00-10000-10000-11001-1000032.
The nonzero elements of AL need to be stored in the triples iafun[k-1],javar[k-1],a[k-1] in any order. For example
k | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8
iafun[k-1] | 1 | 2 | 4 | 4 | 5 | 5 | 6 | 6
javar[k-1] | 3 | 4 | 1 | 2 | 1 | 2 | 3 | 4
a[k-1] | -1 | -1 | -1 | 1 | 1 | -1 | 3 | 2
The nonlinear functions f and the Jacobian need to be supplied in usrfun. Please note that there is no need to assign any value to f 4 or f 5 as there is no nonlinear part in F 4 or F 5.
The nonzero entries of the Jacobian of f are
∂f 1∂x 1=-1000cos-x 1-0.25∂f 1∂x 2=-1000cos-x 2-0.25∂f 2∂x 1=1000 cos x 1-0.25+1000 cos x 1-x 2-0.25∂f 2∂x 2=-1000cos x 1-x 2-0.25∂f 3∂x 1=-1000cos x 2-x 1-0.25∂f 3∂x 2=1000 cos x 2-0.25+1000 cos x 2-x 1-0.25∂f 6∂x 3=3×10-6 x 32∂f 6∂x 4=2×10-6 x 42
So the arrays igfun and jgvar must contain:
k | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8
igfun[k-1] | 1 | 1 | 2 | 2 | 3 | 3 | 6 | 6
jgvar[k-1] | 1 | 2 | 1 | 2 | 1 | 2 | 3 | 4
and usrfun must return in g[k-1] the value of ∂fi∂xj, where i=igfun[k-1] and j=jgvar[k-1].

Example program (C#): e04vhe.cs

Example program data: e04vhe.d

Example program results: e04vhe.r

Algorithmic Details

Here we summarise the main features of the SQP algorithm used in e04vh and introduce some terminology used in the description of the method and its arguments. The SQP algorithm is fully described in Gill et al. (2002).

Constraints and Slack Variables

Problem (1) contains n variables in x. Let m be the number of components of f x and AL x combined. The upper and lower bounds on those terms define the general constraints of the problem. e04vh converts the general constraints to equalities by introducing a set of slack variables s=s 1,s 2,…,sm T. For example, the linear constraint 5≤2 x 1+3 x 2≤∞ is replaced by 2 x 1+3 x 2-s 1=0 together with the bounded slack 5≤s 1≤∞. The minimization problem (1) can therefore be written in the equivalent form
minimize x,s f 0 x subject to ​f xAL x-s=0, l≤xs≤u. (3)
The general constraints become the equalities f x-sN=0 and AL x-sL=0, where sL and sN are the linear and nonlinear slacks.

Major Iterations

The basic structure of the SQP algorithm involves major and minor iterations. The major iterations generate a sequence of iterates xk that satisfy the linear constraints and converge to a point that satisfies the nonlinear constraints and the first-order conditions for optimality. At each iterate xk a QP subproblem is used to generate a search direction towards the next iterate x k+1. The constraints of the subproblem are formed from the linear constraints AL x-sL=0 and the linearized constraint
f xk+f′xkx-xk-sN=0, (4)
where f′xk denotes the Jacobian matrix, whose elements are the first derivatives of f x evaluated at xk. The QP constraints therefore comprise the m linear constraints
f′xk x-sN=-f xk+f′xk xk,AL x-sN-sL=0, (5)
where x and s are bounded above and below by u and l as before. If the m by n matrix A and m-vector b are defined as
A=f′xkAL and b=-f xk+f′xk xk0, (6)
then the QP subproblem can be written as
minimize x,s q x,xk=gkT x-xk+12 x-xk T Hk x-xk subject to ​Ax-s=b, l≤xs≤u, (7)
where q x,xk is a quadratic approximation to a modified Lagrangian function (see Gill et al. (2002)). The matrix Hk is a quasi-Newton approximation to the Hessian of the Lagrangian. A BFGS update is applied after each major iteration. If some of the variables enter the Lagrangian linearly the Hessian will have some zero rows and columns. If the nonlinear variables appear first, then only the n 1 rows and columns of the Hessian need to be approximated, where n 1 is the number of nonlinear variables. This quantity is determined by the implicit values of the number of nonlinear objective and Jacobian variables determined after the constraints and variables are reordered.

Minor Iterations

Solving the QP subproblem is itself an iterative procedure. Here, the iterations of the QP solver e04nq form the minor iterations of the SQP method. e04nq uses a reduced-Hessian active-set method implemented as a reduced-gradient method. At each minor iteration, the constraints Ax-s=b are partitioned into the form
B xB+S xS+N xN=b, (8)
where the basis matrix B is square and nonsingular, and the matrices S and N are the remaining columns of A-I. The vectors xB, xS and xN are the associated basic, superbasic and nonbasic variables respectively; they are a permutation of the elements of x and s. At a QP subproblem, the basic and superbasic variables will lie somewhere between their bounds, while the nonbasic variables will normally be equal to one of their bounds. At each iteration, xS is regarded as a set of independent variables that are free to move in any desired direction, namely one that will improve the value of the QP objective (or the sum of infeasibilities). The basic variables are then adjusted in order to ensure that x,s continues to satisfy Ax-s=b. The number of superbasic variables (nS, say) therefore indicates the number of degrees of freedom remaining after the constraints have been satisfied. In broad terms, nS is a measure of how nonlinear the problem is. In particular, nS will always be zero for LP problems.
If it appears that no improvement can be made with the current definition of B, S and N, a nonbasic variable is selected to be added to S, and the process is repeated with the value of nS increased by one. At all stages, if a basic or superbasic variable encounters one of its bounds, the variable is made nonbasic and the value of nS is decreased by one.
Associated with each of the m equality constraints Ax-s=b are the dual variables π. Similarly, each variable in x,s has an associated reduced gradient dj. The reduced gradients for the variables x are the quantities g-AT π, where g is the gradient of the QP objective, and the reduced gradients for the slacks are the dual variables π. The QP subproblem is optimal if dj≥0 for all nonbasic variables at their lower bounds, dj≤0 for all nonbasic variables at their upper bounds, and dj=0 for other variables, including superbasics. In practice, an approximate QP solution x^k,s^k,π^k is found by relaxing these conditions.

The Merit Function

After a QP subproblem has been solved, new estimates of the solution are computed using a linesearch on the augmented Lagrangian merit function
M x,s,π=f 0 x-πT f x-sN+12 f x-sN T D f x-sN, (9)
where D is a diagonal matrix of penalty parameters D ii≥0, and π now refers to dual variables for the nonlinear constraints in (1). If xk,sk,πk denotes the current solution estimate and x^k,s^k,π^k denotes the QP solution, the linesearch determines a step αk 0<αk≤1 such that the new point
x k+1s k+1π k+1=xkskπk+αk x^k-xks^k-skπ^k-πk (10)
gives a sufficient decrease in the merit function M. When necessary, the penalties in D are increased by the minimum-norm perturbation that ensures descent for M (see Gill et al. (1992)). The value of sN is adjusted to minimize the merit function as a function of s before the solution of the QP subproblem (see Gill et al. (1986) and Eldersveld (1991)).

Treatment of Constraint Infeasibilities

e04vh makes explicit allowance for infeasible constraints. First, infeasible linear constraints are detected by solving the linear program
minimize x,v,w eT v+w subject to ​l≤xAL x-v+w≤u, v≥0, w≥0, (11)
where e is a vector of ones, and the nonlinear constraint bounds are temporarily excluded from l and u. This is equivalent to minimizing the sum of the general linear constraint violations subject to the bounds on x. (The sum is the ℓ 1-norm of the linear constraint violations. In the linear programming literature, the approach is called elastic programming.)
The linear constraints are infeasible if the optimal solution of (11) has v≠0 or w≠0. e04vh then terminates without computing the nonlinear functions.
Otherwise, all subsequent iterates satisfy the linear constraints. (Such a strategy allows linear constraints to be used to define a region in which the functions can be safely evaluated.) e04vh proceeds to solve nonlinear problems as given, using search directions obtained from the sequence of QP subproblems (see (7)).
If a QP subproblem proves to be infeasible or unbounded (or if the dual variables π for the nonlinear constraints become large), e04vh enters ‘elastic’ mode and thereafter solves the problem
minimize x,v,w f 0 x+γ eT v+w subject to ​l≤xf x-v+wAL x≤u, v≥0, w≥0, (12)
where γ is a non-negative parameter (the elastic weight), and f 0 x+γ eT v+w is called a composite objective (the ℓ 1 penalty function for the nonlinear constraints).
The value of γ may increase automatically by multiples of 10 if the optimal v and w continue to be nonzero. If γ is sufficiently large, this is equivalent to minimizing the sum of the nonlinear constraint violations subject to the linear constraints and bounds.
The initial value of γ is controlled by the optional parameter Elastic Weight.

Description of Monitoring Information

e04vh produces monitoring information, statistical information and information about the solution. [The Final Output] contains details of the final output information sent to the unit specified by the optional parameter Print File. This section contains other details of output information.

Major Iteration Log

This section describes the output to unit Print File if Major Print Level>0. One line of information is output every kth major iteration, where k is Print Frequency.
Label | Description
Itns | is the cumulative number of minor iterations.
Major | is the current major iteration number.
Minors | is the number of iterations required by both the feasibility and optimality phases of the QP subproblem. Generally, Minors will be 1 in the later iterations, since theoretical analysis predicts that the correct active set will be identified near the solution (see [Algorithmic Details]).
Step | is the step length α taken along the current search direction p. The variables x have just been changed to x+αp. On reasonably well-behaved problems, the unit step will be taken as the solution is approached.
nCon | the number of times usrfun has been called to evaluate the nonlinear problem functions. Evaluations needed for the estimation of the derivatives by finite differences are not included. nCon is printed as a guide to the amount of work required for the linesearch.
Feasible is the value of vmax (see (13)), the maximum component of the scaled nonlinear constraint residual (see optional parameter Major Feasibility Tolerance). The solution is regarded as acceptably feasible if Feasible is less than the Major Feasibility Tolerance. In this case, the entry is contained in parentheses.
If the constraints are linear, all iterates are feasible and this entry is not printed.
Optimal | is the value of cmax (see (14)), the maximum complementary gap (see optional parameter Major Optimality Tolerance). It is an estimate of the degree of nonoptimality of the reduced costs. Both Feasible and Optimal are small in the neighbourhood of a solution.
MeritFunction is the value of the augmented Lagrangian merit function (see (8)). This function will decrease at each iteration unless it was necessary to increase the penalty parameters (see [The Merit Function]). As the solution is approached, MeritFunction will converge to the value of the objective at the solution.
In elastic mode, the merit function is a composite function involving the constraint violations weighted by the elastic weight.
If the constraints are linear, this item is labelled Objective, the value of the objective function. It will decrease monotonically to its optimal value.
L+U is the number of nonzeros representing the basis factors L and U on completion of the QP subproblem.
If nonlinear constraints are present, the basis factorization B=LU is computed at the start of the first minor iteration. At this stage, L+U=lenL+lenU, where lenL (see [Basis Factorization Statistics]) is the number of subdiagonal elements in the columns of a lower triangular matrix and lenU (see [Basis Factorization Statistics]) is the number of diagonal and superdiagonal elements in the rows of an upper-triangular matrix.
As columns of B are replaced during the minor iterations, L+U may fluctuate up or down but, in general, will tend to increase. As the solution is approached and the minor iterations decrease towards zero, L+U will reflect the number of nonzeros in the LU factors at the start of the QP subproblem.
If the constraints are linear, refactorization is subject only to the Factorization Frequency, and L+U will tend to increase between factorizations.
BSwap | is the number of columns of the basis matrix B that were swapped with columns of S to improve the condition of B. The swaps are determined by an LU factorization of the rectangular matrix BS=B S T with stability being favoured more than sparsity.
nS | is the current number of superbasic variables.
condHz is an estimate of the condition number of RT R, itself an estimate of ZT HZ, the reduced Hessian of the Lagrangian. The condition number is the square of the ratio of the largest and smallest diagonals of the upper triangular matrix R, this being a lower bound on the condition number of RT R. condHz gives a rough indication of whether or not the optimization procedure is having difficulty. If ε is the relative machine precision being used, the SQP algorithm will make slow progress if condHz becomes as large as ε-1/2≈108, and will probably fail to find a better solution if condHz reaches ε-3/4≈1012.
To guard against high values of condHz, attention should be given to the scaling of the variables and the constraints. In some cases it may be necessary to add upper or lower bounds to certain variables to keep them a reasonable distance from singularities in the nonlinear functions or their derivatives.
Penalty | is the Euclidean norm of the vector of penalty parameters used in the augmented Lagrangian merit function (not printed if there are no nonlinear constraints).
The summary line may include additional code characters that indicate what happened during the course of the major iteration. These will follow the separator ‘_’ in the output
Label | Description
c | central differences have been used to compute the unknown components of the objective and constraint gradients. A switch to central differences is made if either the linesearch gives a small step, or x is close to being optimal. In some cases, it may be necessary to re-solve the QP subproblem with the central difference gradient and Jacobian.
d | during the linesearch it was necessary to decrease the step in order to obtain a maximum constraint violation conforming to the value of the optional parameter Violation Limit.
D | you set status=-1 on exit from usrfun, indicating that the linesearch needed to be done with a smaller value of the step length α.
l | the norm wise change in the variables was limited by the value of the optional parameter Major Step Limit. If this output occurs repeatedly during later iterations, it may be worthwhile increasing the value of the optional parameter Major Step Limit.
i | if e04vh is not in elastic mode, an i signifies that the QP subproblem is infeasible. This event triggers the start of nonlinear elastic mode, which remains in effect for all subsequent iterations. Once in elastic mode, the QP subproblems are associated with the elastic problem (12) (see [Treatment of Constraint Infeasibilities]). If e04vh is already in elastic mode, an i indicates that the minimizer of the elastic subproblem does not satisfy the linearized constraints. (In this case, a feasible point for the usual QP subproblem may or may not exist.)
M | an extra evaluation of the problem functions was needed to define an acceptable positive definite quasi-Newton update to the Lagrangian Hessian. This modification is only done when there are nonlinear constraints.
m | this is the same as M except that it was also necessary to modify the update to include an augmented Lagrangian term.
n | no positive definite BFGS update could be found. The approximate Hessian is unchanged from the previous iteration.
R | the approximate Hessian has been reset by discarding all but the diagonal elements. This reset will be forced periodically by the Hessian Frequency and Hessian Updates keywords. However, it may also be necessary to reset an ill-conditioned Hessian from time to time.
r | the approximate Hessian was reset after ten consecutive major iterations in which no BFGS update could be made. The diagonals of the approximate Hessian are retained if at least one update has been done since the last reset. Otherwise, the approximate Hessian is reset to the identity matrix.
s | a self-scaled BFGS update was performed. This update is used when the Hessian approximation is diagonal, and hence always follows a Hessian reset.
t | the minor iterations were terminated because of the Minor Iterations Limit.
T | the minor iterations were terminated because of the New Superbasics Limit.
u | the QP subproblem was unbounded.
w | a weak solution of the QP subproblem was found.
z | the Superbasics Limit was reached.

Minor Iteration Log

If Minor Print Level>0, one line of information is output to the Print file every kth minor iteration, where k is the specified Print Frequency. A heading is printed before the first such line following a basis factorization. The heading contains the items described below. In this description, a pricing operation is the process by which a nonbasic variable is selected to become superbasic (in addition to those already in the superbasic set). The selected variable is denoted by jq. Variable jq often becomes basic immediately. Otherwise it remains superbasic, unless it reaches its opposite bound and returns to the nonbasic set.
If Partial Price is in effect, variable jq is selected from App or Ipp, the ppth segments of the constraint matrix A-I.
Label | Description
Itn | the current iteration number.
LPmult or QPmult | is the reduced cost (or reduced gradient) of the variable jq selected by the pricing procedure at the start of the present iteration. Algebraically, the reduced gradient is dj=gj-πT aj for j=jq, where gj is the gradient of the current objective function, π is the vector of dual variables for the QP subproblem, and aj is the jth column of A-I. Note that the reduced cost is the 1-norm of the reduced-gradient vector at the start of the iteration, just after the pricing procedure.
LPstep or QPstep | is the step length α taken along the current search direction p. The variables x have just been changed to x+αp. Write Step to stand for LPStep or QPStep, depending on the problem. If a variable is made superbasic during the current iteration (+SBS>0), Step will be the step to the nearest bound. During Phase 2, the step can be greater than one only if the reduced Hessian is not positive definite.
nInf | is the number of infeasibilities after the present iteration. This number will not increase unless the iterations are in elastic mode.
SumInf | is the sum of infeasibilities after the present iteration, if nInf>0. The value usually decreases at each nonzero Step, but if it decreases by 2 or more, SumInf may occasionally increase.
rgNorm | is the norm of the reduced-gradient vector at the start of the iteration. (It is the norm of the vector with elements dj for variables j in the superbasic set.) During Phase 2 this norm will be approximately zero after a unit step. (The heading is not printed if the problem is linear.)
LPobjective or QPobjective | the QP objective function after the present iteration. In elastic mode, the heading is changed to Elastic QPobj. In either case, the value printed decreases monotonically.
+SBS | is the variable jq selected by the pricing operation to be added to the superbasic set.
-SBS | is the superbasic variable chosen to become nonbasic.
-BS | is the basis variable removed (if any) to become nonbasic.
Pivot | if column aq replaces the rth column of the basis B, Pivot is the rth element of a vector y satisfying By=aq. Wherever possible, Step is chosen to avoid extremely small values of Pivot (since they cause the basis to be nearly singular). In rare cases, it may be necessary to increase the Pivot Tolerance to exclude very small elements of y from consideration during the computation of Step.
L+U | is the number of nonzeros representing the basis factors L and U. Immediately after a basis factorization B=LU, L+U is lenL+lenU, the number of subdiagonal elements in the columns of a lower triangular matrix and the number of diagonal and superdiagonal elements in the rows of an upper-triangular matrix. Further nonzeros are added to L when various columns of B are later replaced. As columns of B are replaced, the matrix U is maintained explicitly (in sparse form). The value of L will steadily increase, whereas the value of U may fluctuate up or down. Thus the value of L+U may fluctuate up or down (in general, it will tend to increase).
ncp | is the number of compressions required to recover storage in the data structure for U. This includes the number of compressions needed during the previous basis factorization.
nS | is the current number of superbasic variables. (The heading is not printed if the problem is linear.)
condHz | see [Major Iteration Log]. (The heading is not printed if the problem is linear.)

Crash Statistics

If Major Print Level≥10 and System Information Yes has been specified, the following items are output to the Print file when start=0 and no Basis file is loaded. They refer to the number of columns that the Crash procedure selects during selected passes through A while searching for a triangular basis matrix.
Label | Description
Slacks | is the number of slacks selected initially.
Free cols | is the number of free columns in the basis.
Preferred | is the number of ‘preferred’ columns in the basis (i.e., xstate[j-1]=3 for some j≤n).
Unit | is the number of unit columns in the basis.
Double | is the number of columns in the basis containing 2 nonzeros.
Triangle | is the number of triangular columns in the basis.
Pad | is the number of slacks used to pad the basis (to make it a nonsingular triangle).

Basis Factorization Statistics

If Major Print Level≥10, the first seven items listed below are output to the Print file whenever the basis B or the rectangular matrix BS=B S T is factorized before solution of the next QP subproblem (see [Description of the Optional Parameters]).
Note that BS may be factorized at the start of just some of the major iterations. It is immediately followed by a factorization of B itself.
Gaussian elimination is used to compute a sparse LU factorization of B or BS, where PL PT and PUQ are lower and upper triangular matrices, for some permutation matrices P and Q. Stability is ensured as described under optional parameter LU Factor Tolerance.
If Minor Print Level≥10, the same items are printed during the QP solution whenever the current B is factorized. In addition, if System Information Yes has been specified, the entries from Elems onwards are also printed.
Label | Description
Factor | the number of factorizations since the start of the run.
Demand a code giving the reason for the present factorization, as follows:
Code | Meaning
0 | First LU factorization.
1 | The number of updates reached the Factorization Frequency.
2 | The nonzeros in the updated factors have increased significantly.
7 | Not enough storage to update factors.
10 | Row residuals are too large (see the description of the optional parameter Check Frequency).
11 | Ill-conditioning has caused inconsistent results.
Itn | is the current minor iteration number.
Nonlin | is the number of nonlinear variables in the current basis B.
Linear | is the number of linear variables in B.
Slacks | is the number of slack variables in B.
B, BR, BS or BT factorize is the type of LU factorization.
B | periodic factorization of the basis B.
BR | more careful rank-revealing factorization of B using threshold rook pivoting. This occurs mainly at the start, if the first basis factors seem singular or ill-conditioned. Followed by a normal B factorize.
BS | BS is factorized to choose a well-conditioned B from the current B S. Followed by a normal B factorize.
BT | same as BS except the current B is tried first and accepted if it appears to be not much more ill-conditioned than after the previous BS factorize.
m | is the number of rows in B or BS.
n | is the number of columns in B or BS. Preceded by ‘=’ or ‘>’ respectively.
Elems | is the number of nonzero elements in B or BS.
Amax | is the largest nonzero in B or BS.
Density | is the percentage nonzero density of B or BS.
Merit/MerRP/MerCP | Merit is the average Markowitz merit count for the elements chosen to be the diagonals of PUQ. Each merit count is defined to be c-1r-1 where c and r are the number of nonzeros in the column and row containing the element at the time it is selected to be the next diagonal. Merit is the average of n such quantities. It gives an indication of how much work was required to preserve sparsity during the factorization. If LU Complete Pivoting or LU Rook Pivoting has been selected, this heading is changed to MerCP, respectively MerRP.
lenL | is the number of nonzeros in L.
L+U | is the number of nonzeros representing the basis factors L and U. Immediately after a basis factorization B=LU, this is lenL+lenU, the number of subdiagonal elements in the columns of a lower triangular matrix and the number of diagonal and superdiagonal elements in the rows of an upper-triangular matrix. Further nonzeros are added to L when various columns of B are later replaced. As columns of B are replaced, the matrix U is maintained explicitly (in sparse form). The value of L will steadily increase, whereas the value of U may fluctuate up or down. Thus the value of L+U may fluctuate up or down (in general, it will tend to increase).
Cmpressns | is the number of times the data structure holding the partially factored matrix needed to be compressed to recover unused storage. Ideally this number should be zero. If it is more than 3 or 4, the amount of workspace available to e04vh should be increased for efficiency.
Incres | is the percentage increase in the number of nonzeros in L and U relative to the number of nonzeros in B or BS.
Utri | is the number of triangular rows of B or BS at the top of U.
lenU | the number of nonzeros in U, including its diagonals.
Ltol | is the largest subdiagonal element allowed in L. This is the specified LU Factor Tolerance or a smaller value that is currently being used for greater stability.
Umax | the maximum nonzero element in U.
Ugrwth is the ratio Umax/Amax, which ideally should not be substantially larger than 10.0 or 100.0. If it is orders of magnitude larger, it may be advisable to reduce the LU Factor Tolerance to 5.0, 4.0, 3.0 or 2.0, say (but bigger than 1.0).
As long as Lmax is not large (say 5.0 or less), max Amax,Umax/DUmin gives an estimate of the condition number B. If this is extremely large, the basis is nearly singular. Slacks are used to replace suspect columns of B and the modified basis is refactored.
Ltri | is the number of triangular columns of B or BS at the left of L.
dense1 | is the number of columns remaining when the density of the basis matrix being factorized reached 0.3.
Lmax | is the actual maximum subdiagonal element in L (bounded by Ltol).
Akmax | is the largest nonzero generated at any stage of the LU factorization. (Values much larger than Amax indicate instability.) Akmax is not printed if LU Partial Pivoting is selected.
Agrwth | is the ratio Akmax/Amax. Values much larger than 100 (say) indicate instability. Agrwth is not printed if LU Partial Pivoting is selected.
bump | is the size of the block to be factorized nontrivially after the triangular rows and columns of B or BS have been removed.
dense2 | is the number of columns remaining when the density of the basis matrix being factorized reached 0.6. (The Markowitz pivot strategy searches fewer columns at that stage.)
DUmax | is the largest diagonal of PUQ.
DUmin | is the smallest diagonal of PUQ.
condU | the ratio DUmax/DUmin, which estimates the condition number of U (and of B if Ltol is less than 5.0, say).

The Solution File

At the end of a run, the final solution may be output as a Solution file, according to Solution File. Some header information appears first to identify the problem and the final state of the optimization procedure. A ROWS section and a COLUMNS section then follow, giving one line of information for each row and column. The format used is similar to certain commercial systems, though there is no industry standard.
In general, numerical values are output with format f16.5. The maximum record length is 111 characters, including the first (carriage-control) character.
To reduce clutter, a full stop (.) is printed for any numerical value that is exactly zero. The values ±1 are also printed specially as 1.0 and -1.0. Infinite bounds (±1020 or larger) are printed as None.
A Solution file is intended to be read from disk by a self-contained program that extracts and saves certain values as required for possible further computation. Typically, the first 14 records would be ignored. Each subsequent record may be read using adapted to suit the occasion. The end of the ROWS section is marked by a record that starts with a 1 and is otherwise blank. If this and the next 4 records are skipped, the COLUMNS section can then be read under the same format. (There should be no need for backspace statements.)
A full description of the ROWS section and the COLUMNS section is given in [The ROWS section] and [The COLUMNS section].

The Summary File

If Summary File>0, the following information is output to the unit number associated with Summary File. (It is a brief summary of the output directed to unit Print File):
– | the optional parameters supplied via the option setting methods, if any;
– | the Basis file loaded, if any;
– | a brief major iteration log (see [Major Iteration Log]);
– | a brief minor iteration log (see [Minor Iteration Log]);
– | the exit condition, ifail;
– | a summary of the final iterate.

See Also

E04 Class
E04 Members


e04vj Method

[image]

NAG Library for .NET Release 2
E04..::e04vj Method
E04 Class See Also Send Feedback
e04vj may be used before e04vh to determine the sparsity pattern for the Jacobian.

Syntax

C#
public static void e04vj(
    int nf,
    int n,
    E04..::..E04VJ_USRFUN usrfun,
    int[] iafun,
    int[] javar,
    out int nea,
    double[] a,
    int[] igfun,
    int[] jgvar,
    out int neg,
    double[] x,
    double[] xlow,
    double[] xupp,
    E04..::..e04vhOptions options,
    out int ifail
)
Visual Basic
Public Shared Sub e04vj ( _
    nf As Integer, _
    n As Integer, _
    usrfun As E04..::..E04VJ_USRFUN, _
    iafun As Integer(), _
    javar As Integer(), _
    <OutAttribute> ByRef nea As Integer, _
    a As Double(), _
    igfun As Integer(), _
    jgvar As Integer(), _
    <OutAttribute> ByRef neg As Integer, _
    x As Double(), _
    xlow As Double(), _
    xupp As Double(), _
    options As E04..::..e04vhOptions, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04vj(
    int nf,
    int n,
    E04..::..E04VJ_USRFUN^ usrfun,
    array<int>^ iafun,
    array<int>^ javar,
    [OutAttribute] int% nea,
    array<double>^ a,
    array<int>^ igfun,
    array<int>^ jgvar,
    [OutAttribute] int% neg,
    array<double>^ x,
    array<double>^ xlow,
    array<double>^ xupp,
    E04..::..e04vhOptions^ options,
    [OutAttribute] int% ifail
)
F#
static member e04vj :
        nf : int *
        n : int *
        usrfun : E04..::..E04VJ_USRFUN *
        iafun : int[] *
        javar : int[] *
        nea : int byref *
        a : float[] *
        igfun : int[] *
        jgvar : int[] *
        neg : int byref *
        x : float[] *
        xlow : float[] *
        xupp : float[] *
        options : E04..::..e04vhOptions *
        ifail : int byref -> unit

Parameters

nf
Type: System..::..Int32
On entry: nf, the number of problem functions in F x, including the objective function (if any) and the linear and nonlinear constraints. Simple upper and lower bounds on x can be defined using the parameters xlow and xupp and should not be included in F.
Constraint: nf>0.
n
Type: System..::..Int32
On entry: n, the number of variables.
Constraint: n>0.
usrfun
Type: NagLibrary..::..E04..::..E04VJ_USRFUN
usrfun must define the problem functions F x. This method is passed to e04vj as the external parameter usrfun.

A delegate of type E04VJ_USRFUN.

iafun
Type: array< System..::..Int32 >[]()[][]
An array of size [lena]
On exit: define the coordinates i,j and values A ij of the nonzero elements of the linear part A of the function F x=f x+Ax.
In particular, nea triples iafun[k-1],javar[k-1],a[k-1] define the row and column indices i=iafun[k-1] and j=javar[k-1] of the element A ij=a[k-1].
javar
Type: array< System..::..Int32 >[]()[][]
An array of size [lena]
On exit: define the coordinates i,j and values A ij of the nonzero elements of the linear part A of the function F x=f x+Ax.
In particular, nea triples iafun[k-1],javar[k-1],a[k-1] define the row and column indices i=iafun[k-1] and j=javar[k-1] of the element A ij=a[k-1].
nea
Type: System..::..Int32 %
On exit: is the number of nonzero entries in A such that F x=f x+Ax.
a
Type: array< System..::..Double >[]()[][]
An array of size [lena]
On exit: define the coordinates i,j and values A ij of the nonzero elements of the linear part A of the function F x=f x+Ax.
In particular, nea triples iafun[k-1],javar[k-1],a[k-1] define the row and column indices i=iafun[k-1] and j=javar[k-1] of the element A ij=a[k-1].
igfun
Type: array< System..::..Int32 >[]()[][]
An array of size [leng]
On exit: define the coordinates i,j of the nonzero elements of G, the nonlinear part of the derivatives J x=G x+A of the function F x=f x+Ax.
jgvar
Type: array< System..::..Int32 >[]()[][]
An array of size [leng]
On exit: define the coordinates i,j of the nonzero elements of G, the nonlinear part of the derivatives J x=G x+A of the function F x=f x+Ax.
neg
Type: System..::..Int32 %
On exit: the number of nonzero entries in G.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: an initial estimate of the variables x. The contents of x will be used by e04vj in the call of usrfun, and so each element of x should be within the bounds given by xlow and xupp.
xlow
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: contain the lower and upper bounds lx and ux on the variables x.
To specify a nonexistent lower bound lx j=-∞, set xlow[j-1]≤-bigbnd, where bigbnd is the optional parameter Infinite Bound Size. To specify a nonexistent upper bound xupp[j-1]≥bigbnd.
To fix the jth variable (say, xj=β, where β<bigbnd), set xlow[j-1]=xupp[j-1]=β.
xupp
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: contain the lower and upper bounds lx and ux on the variables x.
To specify a nonexistent lower bound lx j=-∞, set xlow[j-1]≤-bigbnd, where bigbnd is the optional parameter Infinite Bound Size. To specify a nonexistent upper bound xupp[j-1]≥bigbnd.
To fix the jth variable (say, xj=β, where β<bigbnd), set xlow[j-1]=xupp[j-1]=β.
options
Type: NagLibrary..::..E04..::..e04vhOptions
An Object of type E04.e04vjOptions. Used to configure optional parameters to this method.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

When using e04vh, if you set the optional parameter Derivative Option=0 and usrfun provides none of the derivatives, you may need to call e04vj to determine the input arrays iafun, javar, a, igfun and jgvar. These arrays define the pattern of nonzeros in the Jacobian matrix. A typical sequence of calls could be
e04vj determines the sparsity pattern for the Jacobian and identifies the constant elements automatically. To do so, e04vj approximates the problem functions, F x, at three random perturbations of the given initial point x. If an element of the approximate Jacobian is the same at all three points, then it is taken to be constant. If it is zero, it is taken to be identically zero. Since the random points are not chosen close together, the heuristic will correctly classify the Jacobian elements in the vast majority of cases. In general, e04vj finds that the Jacobian can be permuted to the form:
G xA 3A 2A 4,
where A 2, A 3 and A 4 are constant. Note that G x might contain elements that are also constant, but e04vj must classify them as nonlinear. This is because e04vh ‘removes’ linear variables from the calculation of F by setting them to zero before calling usrfun. A knowledgeable user would be able to move such elements from F x in usrfun and enter them as part of iafun, javar and a for e04vh.

References

Hock W and Schittkowski K (1981) Test Examples for Nonlinear Programming Codes. Lecture Notes in Economics and Mathematical Systems 187 Springer–Verlag

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
The initialization method (E04VGF not in this release) has not been called or at least one of lencw, leniw or lenrw is less than 600.
ifail=2
An input parameter is invalid. The output message provides more details of the invalid parameter.
ifail=3
Undefined user-supplied function.
You have indicated that the problem functions are undefined by setting status=-1 on exit from usrfun. This exit occurs if e04vj is unable to find a point at which the functions are defined.
ifail=4
User requested termination.
You have indicated the wish to terminate the call to e04vj by setting status to a value <-1 on exit from usrfun.
ifail=5
Either lena or leng is too small, resulting in insufficient array to store the Jacobian information. Increase lena and/or leng
ifail=6
Unable to estimate the Jacobian structure.
ifail=7
Internal memory allocation failed when attempting to obtain the required workspace. Please contact NAG.
ifail=8
Internal memory allocation insufficient. Please contact NAG.
ifail=-9000
An error occured, see message report.
ifail=-1000
The array lengths are not the same for arrays
ifail=-1000
The array lengths are not the same for arrays
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

It is a reformulation of Problem 74 from Hock and Schittkowski (1981) and involves the minimization of the nonlinear function
f x=10-6 x 33+23×10-6 x 43+3 x 3+2 x 4
subject to the bounds
-0.55≤x 1≤0.55,-0.55≤x 2≤0.55,0≤x 3≤1200,0≤x 4≤1200,
to the nonlinear constraints
1000 sin-x 1-0.25+1000 sin-x 2-0.25-x 3=-894.8,1000 sin x 1-0.25+1000 sin x 1-x 2-0.25-x 4=-894.8,1000 sin x 2-0.25+1000 sin x 2-x 1-0.25=-1294.8,
and to the linear constraints
-x 1+x 2≥-0.55,-x 1-x 2≥-0.55.
The initial point, which is infeasible, is
x 0=0,0,0,0 T,
and f x 0=0.
The optimal solution (to five figures) is
x*=0.11887,-0.39623,679.94,1026.0 T,
and f x*=5126.4. All the nonlinear constraints are active at the solution.
The formulation of the problem combines the constraints and the objective into a single vector (F).
F=1000 sin-x 1-0.25+1000 sin-x 2-0.25-x 31000 sin x 1-0.25+1000 sin x 1-x 2-0.25-x 41000 sin x 2-0.25+1000 sin x 2-x 1-0.25-x 1+x 2x 1-x 210-6 x 33+23×10-6 x 43+3 x 3+2 x 4

Example program (C#): e04vje.cs

Example program data: e04vje.d

Example program results: e04vje.r

See Also

E04 Class
E04 Members


e04wd Method

[image]

NAG Library for .NET Release 2
E04..::e04wd Method
E04 Class See Also Send Feedback
e04wd is designed to minimize an arbitrary smooth function subject to constraints (which may include simple bounds on the variables, linear constraints and smooth nonlinear constraints) using a sequential quadratic programming (SQP) method. As many first derivatives as possible should be supplied by you; any unspecified derivatives are approximated by finite differences. It is not intended for large sparse problems.
e04wd may also be used for unconstrained, bound-constrained and linearly constrained optimization.
e04wd uses forward communication for evaluating the objective function, the nonlinear constraint functions, and any of their derivatives.
The initialization method (E04WCF not in this release) must have been called before to calling e04wd.

Syntax

C#
public static void e04wd(
    int n,
    int nclin,
    int ncnln,
    double[,] a,
    double[] bl,
    double[] bu,
    E04..::..E04WD_CONFUN confun,
    E04..::..E04WD_OBJFUN objfun,
    out int majits,
    int[] istate,
    double[] ccon,
    double[,] cjac,
    double[] clamda,
    out double objf,
    double[] grad,
    double[,] h,
    double[] x,
    E04..::..e04wdOptions options,
    out int ifail
)
Visual Basic
Public Shared Sub e04wd ( _
    n As Integer, _
    nclin As Integer, _
    ncnln As Integer, _
    a As Double(,), _
    bl As Double(), _
    bu As Double(), _
    confun As E04..::..E04WD_CONFUN, _
    objfun As E04..::..E04WD_OBJFUN, _
    <OutAttribute> ByRef majits As Integer, _
    istate As Integer(), _
    ccon As Double(), _
    cjac As Double(,), _
    clamda As Double(), _
    <OutAttribute> ByRef objf As Double, _
    grad As Double(), _
    h As Double(,), _
    x As Double(), _
    options As E04..::..e04wdOptions, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04wd(
    int n,
    int nclin,
    int ncnln,
    array<double,2>^ a,
    array<double>^ bl,
    array<double>^ bu,
    E04..::..E04WD_CONFUN^ confun,
    E04..::..E04WD_OBJFUN^ objfun,
    [OutAttribute] int% majits,
    array<int>^ istate,
    array<double>^ ccon,
    array<double,2>^ cjac,
    array<double>^ clamda,
    [OutAttribute] double% objf,
    array<double>^ grad,
    array<double,2>^ h,
    array<double>^ x,
    E04..::..e04wdOptions^ options,
    [OutAttribute] int% ifail
)
F#
static member e04wd :
        n : int *
        nclin : int *
        ncnln : int *
        a : float[,] *
        bl : float[] *
        bu : float[] *
        confun : E04..::..E04WD_CONFUN *
        objfun : E04..::..E04WD_OBJFUN *
        majits : int byref *
        istate : int[] *
        ccon : float[] *
        cjac : float[,] *
        clamda : float[] *
        objf : float byref *
        grad : float[] *
        h : float[,] *
        x : float[] *
        options : E04..::..e04wdOptions *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of variables.
Constraint: n>0.
nclin
Type: System..::..Int32
On entry: nL, the number of general linear constraints.
Constraint: nclin≥0.
ncnln
Type: System..::..Int32
On entry: nN, the number of nonlinear constraints.
Constraint: ncnln≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,nclin
Note: the second dimension of the array a must be at least n if nclin>0, and at least 1 otherwise.
On entry: the ith row of a contains the ith row of the matrix AL of general linear constraints in (1). That is, the ith row contains the coefficients of the ith general linear constraint, for i=1,2,…,nclin.
If nclin=0, the array a is not referenced.
bl
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin+ncnln]
On entry: bl must contain the lower bounds and bu the upper bounds for all the constraints, in the following order. The first n elements of each array must contain the bounds on the variables, the next nL elements the bounds for the general linear constraints (if any) and the next nN elements the bounds for the general nonlinear constraints (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j-1]≤-bigbnd, and to specify a nonexistent upper bound (i.e., uj=+∞), set bu[j-1]≥bigbnd; where bigbnd is the optional parameter Infinite Bound Size. To specify the jth constraint as an equality, set bl[j-1]=bu[j-1]=β, say, where β<bigbnd.
Constraints:
  • bl[j-1]≤bu[j-1], for j=1,2,…,n+nclin+ncnln;
  • if bl[j-1]=bu[j-1]=β, β<bigbnd.
bu
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin+ncnln]
On entry: bl must contain the lower bounds and bu the upper bounds for all the constraints, in the following order. The first n elements of each array must contain the bounds on the variables, the next nL elements the bounds for the general linear constraints (if any) and the next nN elements the bounds for the general nonlinear constraints (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j-1]≤-bigbnd, and to specify a nonexistent upper bound (i.e., uj=+∞), set bu[j-1]≥bigbnd; where bigbnd is the optional parameter Infinite Bound Size. To specify the jth constraint as an equality, set bl[j-1]=bu[j-1]=β, say, where β<bigbnd.
Constraints:
  • bl[j-1]≤bu[j-1], for j=1,2,…,n+nclin+ncnln;
  • if bl[j-1]=bu[j-1]=β, β<bigbnd.
confun
Type: NagLibrary..::..E04..::..E04WD_CONFUN
confun must calculate the vector c x of nonlinear constraint functions and (optionally) its Jacobian, ∂c∂x, for a specified n-vector x. If there are no nonlinear constraints (i.e., ncnln=0), e04wd will never call confun, so it may be the dummy method E04WDP. (E04WDP is included in the NAG Library). If there are nonlinear constraints, the first call to confun will occur before the first call to objfun.
If all constraint gradients (Jacobian elements) are known (i.e., Derivative Level=2 or 3), any constant elements may be assigned to cjac once only at the start of the optimization. An element of cjac that is not subsequently assigned in confun will retain its initial value throughout. Constant elements may be loaded in cjac during the first call to confun (signalled by the value of nstate=1). The ability to preload constants is useful when many Jacobian elements are identically zero, in which case cjac may be initialized to zero and nonzero elements may be reset by confun.
It must be emphasized that, if Derivative Level<2, unassigned elements of cjac are not treated as constant; they are estimated by finite differences, at nontrivial expense.

A delegate of type E04WD_CONFUN.

confun should be tested separately before being used in conjunction with e04wd. See also the description of the optional parameter Verify Level.
objfun
Type: NagLibrary..::..E04..::..E04WD_OBJFUN
objfun must calculate the objective function F x and (optionally) its gradient g x=∂F∂x for a specified n-vector x.

A delegate of type E04WD_OBJFUN.

objfun should be tested separately before being used in conjunction with e04wd. See also the description of the optional parameter Verify Level.
majits
Type: System..::..Int32 %
On exit: the number of major iterations performed.
istate
Type: array< System..::..Int32 >[]()[][]
An array of size [n+nclin+ncnln]
On entry: is an integer array that need not be initialized if e04wd is called with the Cold Start option (the default).
If optional parameter Warm Start has been chosen, every element of istate must be set. If e04wd has just been called on a problem with the same dimensions, istate already contains valid values. Otherwise, istate[j-1] should indicate whether either of the constraints rj x≥lj or rj x≤uj is expected to be active at a solution of (1).
The ordering of istate is the same as for bl, bu and r x, i.e., the first n components of istate refer to the upper and lower bounds on the variables, the next nclin refer to the bounds on AL x, and the last ncnln refer to the bounds on c x. Possible values of istate[i-1] follow:
0 | Neither rj x≥lj nor rj x≤uj is expected to be active.
1 | rj x≥lj is expected to be active.
2 | rj x≤uj is expected to be active.
3 | This may be used if lj=uj. Normally an equality constraint rj x=lj=uj is active at a solution.
The values 1, 2 or 3 all have the same effect when bl[j-1]=bu[j-1]. If necessary, e04wd will override your specification of istate, so that a poor choice will not cause the algorithm to fail.
On exit: describes the status of the constraints l≤r x≤u. For the jth lower or upper bound, j=1,2,…,n+nclin+ncnln, the possible values of istate[j-1] are as follows (see Figure 1). δ is the appropriate feasibility tolerance.
-2 | (Region 1) The lower bound is violated by more than δ.
-1 | (Region 5) The upper bound is violated by more than δ.
-0 | (Region 3) Both bounds are satisfied by more than δ.
-1 | (Region 2) The lower bound is active (to within δ).
-2 | (Region 4) The upper bound is active (to within δ).
-3 | (Region 2=Region 4) The bounds are equal and the equality constraint is satisfied (to within δ).
These values of istate are labelled in the printed solution according to Table 1.
Region | 1 | 2 | 3 | 4 | 5 | 2≡4
istate[j-1] | -2 | 1 | 0 | 2 | -1 | 3
Printed solution -- LL FR UL ++ EQ
Table 1
Labels used in the printed solution for the regions in Figure 1
ccon
Type: array< System..::..Double >[]()[][]
An array of size [max 1,ncnln]
On entry: ccon need not be initialized if the (default) optional parameter Cold Start is used.
For a Warm Start, and if ncnln>0, ccon contains values of the nonlinear constraint functions ci, for i=1,2,…,ncnln, calculated in a previous call to e04wd.
On exit: if ncnln>0, ccon[i-1] contains the value of the ith nonlinear constraint function ci at the final iterate, for i=1,2,…,ncnln.
If ncnln=0, the array ccon is not referenced.
cjac
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,ncnln
Note: the second dimension of the array cjac must be at least n if ncnln>0, and at least 1 otherwise.
On entry: in general, cjac need not be initialized before the call to e04wd. However, if Derivative Level=2 or 3, any constant elements of cjac may be initialized. Such elements need not be reassigned on subsequent calls to confun.
On exit: if ncnln>0, cjac contains the Jacobian matrix of the nonlinear constraint functions at the final iterate, i.e., cjac[i-1,j-1] contains the partial derivative of the ith constraint function with respect to the jth variable, for i=1,2,…,ncnln and j=1,2,…,n. (See the discussion of parameter cjac under confun.)
If ncnln=0, the array cjac is not referenced.
clamda
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin+ncnln]
On entry: need not be set if the (default) optional parameter Cold Start is used.
If the optional parameter Warm Start has been chosen, clamda[j-1] must contain a multiplier estimate for each nonlinear constraint, with a sign that matches the status of the constraint specified by the istate array, for j=n+nclin+1,…,n+nclin+ncnln. The remaining elements need not be set. If the jth constraint is defined as ‘inactive’ by the initial value of the istate array (i.e., istate[j-1]=0), clamda[j-1] should be zero; if the jth constraint is an inequality active at its lower bound (i.e., istate[j-1]=1), clamda[j-1] should be non-negative; if the jth constraint is an inequality active at its upper bound (i.e., istate[j-1]=2), clamda[j-1] should be non-positive. If necessary, the method will modify clamda to match these rules.
On exit: the values of the QP multipliers from the last QP subproblem. clamda[j-1] should be non-negative if istate[j-1]=1 and non-positive if istate[j-1]=2.
objf
Type: System..::..Double %
On exit: the value of the objective function at the final iterate.
grad
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the gradient of the objective function (or its finite difference approximation) at the final iterate.
h
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥n unless optional parameter Hessian Limited Memory is in effect
Note: the second dimension of the array h must be at least n unless the optional parameter Hessian Limited Memory is in effect. If Hessian Limited Memory is in effect, array h is not referenced.
On entry: h need not be initialized if the (default) optional parameter Cold Start is used, and will be set to the identity.
If the optional parameter Warm Start has been chosen, h provides the initial approximation of the Hessian of the Lagrangian, i.e., h[i-1,j-1]≈∂2 L x,λ∂xi∂xj, where L x,λ=F x-c x T λ and λ is an estimate of the Lagrange multipliers. h must be a positive definite matrix.
On exit: contains the Hessian of the Lagrangian at the final estimate x.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: an initial estimate of the solution.
On exit: the final estimate of the solution.
options
Type: NagLibrary..::..E04..::..e04wdOptions
An Object of type E04.e04wdOptions. Used to configure optional parameters to this method.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04wd is designed to solve nonlinear programming problems – the minimization of a smooth nonlinear function subject to a set of constraints on the variables. e04wd is suitable for small dense problems. The problem is assumed to be stated in the following form:
minimize x∈Rn F x  subject to  l≤xAL xc x≤u, (1)
where F x (the objective function) is a nonlinear scalar function, AL is an nL by n constant matrix, and c x is an nN-vector of nonlinear constraint functions. (The matrix AL and the vector c x may be empty.) The objective function and the constraint functions are assumed to be smooth, here meaning at least twice-continuously differentiable. (The method of e04wd will usually solve (1) if there are only isolated discontinuities away from the solution.) We also write r x for the vector of combined functions:
r x=xAL xc x T.
Note that although the bounds on the variables could be included in the definition of the linear constraints, we prefer to distinguish between them for reasons of computational efficiency. For the same reason, the linear constraints should not be included in the definition of the nonlinear constraints. Upper and lower bounds are specified for all the variables and for all the constraints. An equality constraint on ri can be specified by setting li=ui. If certain bounds are not present, the associated elements of l or u can be set to special values that will be treated as -∞ or +∞. (See the description of the optional parameter Infinite Bound Size.)
Figure 1 illustrates the feasible region for the jth pair of constraints lj≤rj x≤uj. The quantity of δ is the Feasibility Tolerance, which can be set by you (see [Optional Parameters]). The constraints lj≤rj≤uj are considered ‘satisfied’ if rj lies in Regions 2, 3 or 4, and ‘inactive’ if rj lies in Region 3. The constraint rj≥lj is considered ‘active’ in Region 2, and ‘violated’ in Region 1. Similarly, rj≤uj is active in Region 4, and violated in Region 5. For equality constraints (lj=uj), Regions 2 and 4 are the same and Region 3 is empty.
Illustration of the constraints lj≤rjx≤uj
Figure 1: Illustration of the constraints lj≤rj x≤uj
If there are no nonlinear constraints in (1) and F is linear or quadratic, then it will generally be more efficient to use one of e04mf, e04nc or e04nf. If the problem is large and sparse and does have nonlinear constraints, then e04vh should be used, since e04wd treats all matrices as dense.
You must supply an initial estimate of the solution to (1), together with methods that define F x and c x with as many first partial derivatives as possible; unspecified derivatives are approximated by finite differences; see [Description of the Optional Parameters] for a discussion of the optional parameter Derivative Level.
The objective function is defined by objfun, and the nonlinear constraints are defined by confun. Note that if there are any nonlinear constraints then the first call to confun will precede the first call to objfun.
For maximum reliability, it is preferable for you to provide all partial derivatives (see Chapter 8 of Gill et al. (1981), for a detailed discussion). If all gradients cannot be provided, it is similarly advisable to provide as many as possible. While developing objfun and confun, the optional parameter Verify Level should be used to check the calculation of any known gradients.
The method used by e04wd is based on NPOPT, which is part of the SNOPT package described in Gill et al. (2005b), and the algorithm it uses is described in detail in [Algorithmic Details].

References

Eldersveld S K (1991) Large-scale sequential quadratic programming algorithms PhD Thesis Department of Operations Research, Stanford University, Stanford
Fourer R (1982) Solving staircase linear programs by the simplex method Math. Programming 23 274–313
Gill P E, Murray W and Saunders M A (2002) SNOPT: An SQP Algorithm for Large-scale Constrained Optimization 12 979–1006 SIAM J. Optim.
Gill P E, Murray W and Saunders M A (2005a) Users' guide for SQOPT 7: a Fortran package for large-scale linear and quadratic programming Report NA 05-1 Department of Mathematics, University of California, San Diego http://www.ccom.ucsd.edu/~peg/papers/sqdoc7.pdf
Gill P E, Murray W and Saunders M A (2005b) Users' guide for SNOPT 7.1: a Fortran package for large-scale linear nonlinear programming Report NA 05-2 Department of Mathematics, University of California, San Diego http://www.ccom.ucsd.edu/~peg/papers/sndoc7.pdf
Gill P E, Murray W, Saunders M A and Wright M H (1986) Users' guide for NPSOL (Version 4.0): a Fortran package for nonlinear programming Report SOL 86-2 Department of Operations Research, Stanford University
Gill P E, Murray W, Saunders M A and Wright M H (1992) Some theoretical properties of an augmented Lagrangian merit function Advances in Optimization and Parallel Computing (ed P M Pardalos) 101–128 North Holland
Gill P E, Murray W and Wright M H (1981) Practical Optimization Academic Press
Hock W and Schittkowski K (1981) Test Examples for Nonlinear Programming Codes. Lecture Notes in Economics and Mathematical Systems 187 Springer–Verlag

Error Indicators and Warnings

Note: e04wd may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA, LDCJ, LDH) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
The initialization method (E04WCF not in this release) has not been called or at least one of leniw and lenrw is less than 600.
ifail=2
An input parameter is invalid. The output message provides more details of the invalid argument.
ifail=3
Requested accuracy could not be achieved.
A feasible solution has been found, but the requested accuracy in the dual infeasibilities could not be achieved. An abnormal termination has occurred, but e04wd is within 10-2 of satisfying the Major Optimality Tolerance. Check that the Major Optimality Tolerance is not too small.
ifail=4
The problem appears to be infeasible.
When the constraints are linear, this message is based on a relatively reliable indicator of infeasibility. Feasibility is measured with respect to the upper and lower bounds on the variables and slacks. Among all the points satisfying the general constraints Ax-s=0 (see (5) and (6) in [Major Iterations]), there is apparently no point that satisfies the bounds on x and s. Violations as small as the Minor Feasibility Tolerance are ignored, but at least one component of x or s violates a bound by more than the tolerance.
When nonlinear constraints are present, infeasibility is much harder to recognize correctly. Even if a feasible solution exists, the current linearization of the constraints may not contain a feasible point. In an attempt to deal with this situation, when solving each QP subproblem, e04wd is prepared to relax the bounds on the slacks associated with nonlinear rows.
If a QP subproblem proves to be infeasible or unbounded (or if the Lagrange multiplier estimates for the nonlinear constraints become large), e04wd enters so-called ‘nonlinear elastic’ mode. The subproblem includes the original QP objective and the sum of the infeasibilities – suitably weighted using the optional parameter Elastic Weight. In elastic mode, some of the bounds on the nonlinear rows are ‘elastic’ – i.e., they are allowed to violate their specific bounds. Variables subject to elastic bounds are known as elastic variables. An elastic variable is free to violate one or both of its original upper or lower bounds. If the original problem has a feasible solution and the elastic weight is sufficiently large, a feasible point eventually will be obtained for the perturbed constraints, and optimization can continue on the subproblem. If the nonlinear problem has no feasible solution, e04wd will tend to determine a ‘good’ infeasible point if the elastic weight is sufficiently large. (If the elastic weight were infinite, e04wd would locally minimize the nonlinear constraint violations subject to the linear constraints and bounds.)
Unfortunately, even though e04wd locally minimizes the nonlinear constraint violations, there may still exist other regions in which the nonlinear constraints are satisfied. Wherever possible, nonlinear constraints should be defined in such a way that feasible points are known to exist when the constraints are linearized.
ifail=5
The problem appears to be unbounded (or badly scaled).
For linear problems, unboundedness is detected by the simplex method when a nonbasic variable can be increased or decreased by an arbitrary amount without causing a basic variable to violate a bound. Consider adding an upper or lower bound to the variable. Also, examine the constraints that have nonzeros in the associated column, to see if they have been formulated as intended.
Very rarely, the scaling of the problem could be so poor that numerical error will give an erroneous indication of unboundedness. Consider using the optional parameter Scale Option.
For nonlinear problems, e04wd monitors both the size of the current objective function and the size of the change in the variables at each step. If either of these is very large (as judged by the unbounded parameters (see [Major Iteration Log])), the problem is terminated and declared unbounded. To avoid large function values, it may be necessary to impose bounds on some of the variables in order to keep them away from singularities in the nonlinear functions.
The message may indicate an abnormal termination while enforcing the limit on the constraint violations. This exit implies that the objective is not bounded below in the feasible region defined by expanding the bounds by the value of the Violation Limit.
ifail=6
Iteration limit reached.
Either the Iterations Limit or the Major Iterations Limit was exceeded before the required solution could be found. Check the iteration log to be sure that progress was being made. If so, and if you caused a basis file to be saved by using the optional parameter New Basis File, consider restarting the run using the optional parameter Old Basis File to see whether further progress can be made. If you have no basis file available, you might rerun the problem after increasing the optional parameters Minor Iterations Limit and/or Major Iterations Limit.
If none of the above limits have been reached, this error may mean that the problem appears to be more nonlinear than anticipated. The current set of basic and superbasic variables have been optimized as much as possible and a pricing operation (where a nonbasic variable is selected to become superbasic) is necessary to continue, but it can't continue as the number of superbasic variables has already reached the limit specified by the optional parameter Superbasics Limit. In general, raise the Superbasics Limit s by a reasonable amount, bearing in mind the storage needed for the reduced Hessian. (The Reduced Hessian Dimension h will also increase to s unless specified otherwise, and the associated storage will be about 12 s 2 words.) In some cases you may have to set h<s to conserve storage, but beware that the rate of convergence will probably fall off severely.
ifail=7
Numerical difficulties have been encountered and no further progress can be made.
Several circumstances could lead to this exit.
1. | The user-supplied delegates objfun or confun could be returning accurate function values but inaccurate gradients (or vice versa). This is the most likely cause. Study the comments given for ifail=8, and do your best to ensure that the coding is correct.
2. | The function and gradient values could be consistent, but their precision could be too low. For example, accidental use of a real data type when double precision was intended would lead to a relative function precision of about 10-6 instead of something like 10-15. The default Major Optimality Tolerance of 2×10-6 would need to be raised to about 10-3 for optimality to be declared (at a rather suboptimal point). Of course, it is better to revise the function coding to obtain as much precision as economically possible.
3. If function values are obtained from an expensive iterative process, they may be accurate to rather few significant figures, and gradients will probably not be available. One should specify
  • Function Precision t
  • Major Optimality Tolerance t
but even then, if t is as large as 10-5 or 10-6 (only 5 or 6 significant figures), the same exit condition may occur. At present the only remedy is to increase the accuracy of the function calculation.
4. An LU factorization of the basis has just been obtained and used to recompute the basic variables xB, given the present values of the superbasic and nonbasic variables. A step of ‘iterative refinement’ has also been applied to increase the accuracy of xB. However, a row check has revealed that the resulting solution does not satisfy the current constraints Ax-s=0 sufficiently well.
This probably means that the current basis is very ill-conditioned. If there are some linear constraints and variables, try Scale Option=1 if scaling has not yet been used.
For certain highly structured basis matrices (notably those with band structure), a systematic growth may occur in the factor U. Consult the description of Umax and Growth in [Basis Factorization Statistics] and set the LU Factor Tolerance to 2.0 (or possibly even smaller, but not less than 1.0).
5. | The first factorization attempt will have found the basis to be structurally or numerically singular. (Some diagonals of the triangular matrix U were respectively zero or smaller than a certain tolerance.) The associated variables are replaced by slacks and the modified basis is refactorized, but singularity persists. This must mean that the problem is badly scaled, or the LU Factor Tolerance is too much larger than 1.0. This is highly unlikely to occur.
ifail=8
Derivative appears to be incorrect.
If the message refers to the derivatives of the objective function, then a check has been made on some individual elements of the objective gradient array at the first point that satisfies the linear constraints. At least one component grad j-1 is being set to a value that disagrees markedly with its associated forward-difference estimate ∂F∂xj. (The relative difference between the computed and estimated values is 1.0 or more.) This exit is a safeguard, since e04wd will usually fail to make progress when the computed gradients are seriously inaccurate. In the process it may expend considerable effort before terminating with ifail=7.
Check the function and gradient computation very carefully in objfun. A simple omission could explain everything. If F or a component ∂F∂xj is very large, then give serious thought to scaling the function or the nonlinear variables.
If you feel certain that the computed grad[j-1] is correct (and that the forward-difference estimate is therefore wrong), you can specify Verify Level=0 to prevent individual elements from being checked. However, the optimization procedure may have difficulty.
If the message refers to derivatives of the constraints, then at least one of the computed constraint derivatives is significantly different from an estimate obtained by forward-differencing the vector c x. Follow the advice given above, trying to ensure that the arrays ccon and cjac are being set correctly in confun.
ifail=9
Undefined user-supplied function.
You have indicated that the problem functions are undefined by assigning the value mode=-1 on exit from objfun or confun. e04wd attempts to evaluate the problem functions closer to a point at which the functions are already known to be defined. This exit occurs if e04wd is unable to find a point at which the functions are defined. This will occur in the case of:
– undefined functions with no recovery possible;
– undefined functions at the first point;
– undefined functions at the first feasible point; or
– undefined functions when checking derivatives.
ifail=10
User requested termination.
You have indicated the wish to terminate solution of the current problem by setting mode to a value <-1 on exit from objfun or confun.
ifail=11
Internal memory allocation failed when attempting to obtain the required workspace. Please contact NAG.
ifail=12
Internal memory allocation was insufficient. Please contact NAG.
ifail=13
An error has occurred in the basis package, perhaps indicating incorrect setup of arrays. Set the optional parameter Print File and examine the output carefully for further information.
ifail=14
An unexpected error has occurred. Set the optional parameter Print File and examine the output carefully for further information.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

If ifail=0 on exit, then the vector returned in the array x is an estimate of the solution to an accuracy of approximately Major Optimality Tolerance.

Parallelism and Performance

None.

Further Comments

This section describes the final output produced by e04wd. Intermediate and other output are given in [Description of Monitoring Information].

The Final Output

If Print File>0, the final output, including a listing of the status of every variable and constraint will be sent to the channel numbers associated with Print File. The following describes the output for each variable. A full stop (.) is printed for any numerical value that is zero.
Variable | gives the name (Variable) and index j, for j=1,2,…,n, of the variable.
State gives the state of the variable (FR if neither bound is in the working set, EQ if a fixed variable, LL if on its lower bound, UL if on its upper bound, TF if temporarily fixed at its current value). If Value lies outside the upper or lower bounds by more than the Feasibility Tolerance, State will be ++ or -- respectively. (The latter situation can occur only when there is no feasible point for the bounds and linear constraints.)
A key is sometimes printed before State.
A | Alternative optimum possible. The variable is active at one of its bounds, but its Lagrange multiplier is essentially zero. This means that if the variable were allowed to start moving away from its bound then there would be no change to the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case the values of the Lagrange multipliers might also change.
D | Degenerate. The variable is free, but it is equal to (or very close to) one of its bounds.
I | Infeasible. The variable is currently violating one of its bounds by more than the Feasibility Tolerance.
Value | is the value of the variable at the final iteration.
Lower bound | is the lower bound specified for the variable. None indicates that bl[j-1]≤-bigbnd.
Upper bound | is the upper bound specified for the variable. None indicates that bu[j-1]≥bigbnd.
Lagr multiplier | is the Lagrange multiplier for the associated bound. This will be zero if State is FR unless bl[j-1]≤-bigbnd and bu[j-1]≥bigbnd, in which case the entry will be blank. If x is optimal, the multiplier should be non-negative if State is LL and non-positive if State is UL.
Slack | is the difference between the variable Value and the nearer of its (finite) bounds bl[j-1] and bu[j-1]. A blank entry indicates that the associated variable is not bounded (i.e., bl[j-1]≤-bigbnd and bu[j-1]≥bigbnd).
The meaning of the output for linear and nonlinear constraints is the same as that given above for variables, with bl[j-1] and bu[j-1] replaced by bl[n+j-1] and bu[n+j-1] respectively, and with the following changes in the heading:
Linear constrnt | gives the name (lincon) and index j, for j=1,2,…,nL, of the linear constraint.
Nonlin constrnt | gives the name (nlncon) and index (j-nL), for j=nL+1,…,nL+nN, of the nonlinear constraint.
Note that movement off a constraint (as opposed to a variable moving away from its bound) can be interpreted as allowing the entry in the Slack column to become positive.
Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.

Example

This example is based on Problem 71 in Hock and Schittkowski (1981) and involves the minimization of the nonlinear function
F x=x 1x 4 x 1+x 2+x 3+x 3
subject to the bounds
1≤x 1≤51≤x 2≤51≤x 3≤51≤x 4≤5,
to the general linear constraint
x 1+x 2+x 3+x 4≤20,
and to the nonlinear constraints
x 12+x 22+x 32+x 42≤40,x 1x 2x 3x 4≥25.
The initial point, which is infeasible, is
x 0=1,5,5,1 T,
with F x 0=16.
The optimal solution (to five figures) is
x*=1.0,4.7430,3.8211,1.3794 T,
and F x*=17.014. One bound constraint and both nonlinear constraints are active at the solution.

Example program (C#): e04wde.cs

Example program data: e04wde.d

Example program results: e04wde.r

Algorithmic Details

Here we summarise the main features of the SQP algorithm used in e04wd and introduce some terminology used in the description of the method and its arguments. The SQP algorithm is fully described in Gill et al. (2002).

Constraints and Slack Variables

The upper and lower bounds on the nL+nN components of AL xc x are said to define the general constraints of the problem. e04wd converts the general constraints to equalities by introducing a set of slack variables s=s 1,s 2,…,s nL+nN T. For example, the linear constraint 5≤2 x 1+3 x 2≤∞ is replaced by 2 x 1+3 x 2-s 1=0 together with the bounded slack 5≤s 1≤∞. The minimization problem (1) can therefore be written in the equivalent form
minimize x,s F x subject to ​AL xc x-s=0, l≤xs≤u. (2)
The general constraints become the equalities AL x-sL=0 and c x-sN=0, where sL and sN are the linear and nonlinear slacks.

Major Iterations

The basic structure of the SQP algorithm involves major and minor iterations. The major iterations generate a sequence of iterates xk that satisfy the linear constraints and converge to a point that satisfies the nonlinear constraints and the first-order conditions for optimality. At each iterate xk a QP subproblem is used to generate a search direction towards the next iterate x k+1. The constraints of the subproblem are formed from the linear constraints AL x-sL=0 and the linearized constraint
c xk+c′xkx-xk-sN=0, (3)
where c′xk denotes the Jacobian matrix, whose elements are the first derivatives of c x evaluated at xk. The QP constraints therefore comprise the nL+nN linear constraints
AL x-sL=0,c′xk x-sN=-c xk+c′xk xk, (4)
where x and s are bounded above and below by u and l as before. If the nL+nN×n matrix A and nL+nN-vector b are defined as
A=ALc′xk and b=0-c xk+c′xk xk, (5)
then the QP subproblem can be written as
minimize x,s q x,xk=gkT x-xk+12 x-xk Hk x-xk subject to ​Ax-s=b, l≤xs≤u, (6)
where q x,xk is a quadratic approximation to a modified Lagrangian function (see Gill et al. (2002)). The matrix Hk is a quasi-Newton approximation to the Hessian of the Lagrangian. A BGFS update is applied after each major iteration. If some of the variables enter the Lagrangian linearly the Hessian will have some zero rows and columns. If the nonlinear variables appear first, then only the leading nN rows and columns of the Hessian need to be approximated.

Minor Iterations

Solving the QP subproblem is itself an iterative procedure. Here, the iterations of the QP solver e04nq form the minor iterations of the SQP method. e04nq uses a reduced-Hessian active-set method implemented as a reduced-gradient method. At each minor iteration, the constraints Ax-s=b are partitioned into the form
B xB+S xS+N xN=b, (7)
where the basis matrix B is square and nonsingular, and the matrices S and N are the remaining columns of A-I. The vectors xB, xS and xN are the associated basic, superbasic and nonbasic variables respectively; they are a permutation of the elements of x and s. At a QP subproblem, the basic and superbasic variables will lie somewhere between their bounds, while the nonbasic variables will normally be equal to one of their bounds. At each iteration, xS is regarded as a set of independent variables that are free to move in any desired direction, namely one that will improve the value of the QP objective (or the sum of infeasibilities). The basic variables are then adjusted in order to ensure that x,s continues to satisfy Ax-s=b. The number of superbasic variables (nS, say) therefore indicates the number of degrees of freedom remaining after the constraints have been satisfied. In broad terms, nS is a measure of how nonlinear the problem is. In particular, nS will always be zero for LP problems.
If it appears that no improvement can be made with the current definition of B, S and N, a nonbasic variable is selected to be added to S, and the process is repeated with the value of nS increased by one. At all stages, if a basic or superbasic variable encounters one of its bounds, the variable is made nonbasic and the value of nS is decreased by one.
Associated with each of the nL+nN equality constraints Ax-s=b are the dual variables π. Similarly, each variable in x,s has an associated reduced gradient dj. The reduced gradients for the variables x are the quantities g-AT π, where g is the gradient of the QP objective, and the reduced gradients for the slacks are the dual variables π. The QP subproblem is optimal if dj≥0 for all nonbasic variables at their lower bounds, dj≤0 for all nonbasic variables at their upper bounds, and dj=0 for other variables, including superbasics. In practice, an approximate QP solution x^k,s^k,π^k is found by relaxing these conditions.

The Merit Function

After a QP subproblem has been solved, new estimates of the solution are computed using a linesearch on the augmented Lagrangian merit function
M x,s,π=F x-πT c x-sN+12 c x-sN T D c x-sN, (8)
where D is a diagonal matrix of penalty parameters D ii≥0, and π now refers to dual variables for the nonlinear constraints in (1). If xk,sk,πk denotes the current solution estimate and x^k,s^k,π^k denotes the QP solution, the linesearch determines a step αk 0<αk≤1 such that the new point
x k+1s k+1π k+1=xkskπk+αk x^k-xks^k-skπ^k-πk (9)
gives a sufficient decrease in the merit function M. When necessary, the penalties in D are increased by the minimum-norm perturbation that ensures descent for M (see Gill et al. (1992)). The value of sN is adjusted to minimize the merit function as a function of s before the solution of the QP subproblem (see Gill et al. (1986) and Eldersveld (1991)).

Treatment of Constraint Infeasibilities

e04wd makes explicit allowance for infeasible constraints. First, infeasible linear constraints are detected by solving the linear program
minimize x,v,w eT v+w subject to ​l≤xAL x-v+w≤u, v≥0, w≥0, (10)
where e is a vector of ones, and the nonlinear constraint bounds are temporarily excluded from l and u. This is equivalent to minimizing the sum of the general linear constraint violations subject to the bounds on x. (The sum is the ℓ 1-norm of the linear constraint violations. In the linear programming literature, the approach is called elastic programming.)
The linear constraints are infeasible if the optimal solution of (10) has v≠0 or w≠0. e04wd then terminates without computing the nonlinear functions.
Otherwise, all subsequent iterates satisfy the linear constraints. (Such a strategy allows linear constraints to be used to define a region in which the functions can be safely evaluated.) e04wd proceeds to solve nonlinear problems as given, using search directions obtained from the sequence of QP subproblems (see (6)).
If a QP subproblem proves to be infeasible or unbounded (or if the dual variables π for the nonlinear constraints become large), e04wd enters ‘elastic’ mode and thereafter solves the problem
minimize x,v,w F x+γ eT v+w subject to ​l≤xAL xc x-v+w≤u, v≥0, w≥0, (11)
where γ is a non-negative parameter (the elastic weight), and F x+γ eT v+w is called a composite objective (the ℓ 1 penalty function for the nonlinear constraints).
The value of γ may increase automatically by multiples of 10 if the optimal v and w continue to be nonzero. If γ is sufficiently large, this is equivalent to minimizing the sum of the nonlinear constraint violations subject to the linear constraints and bounds.
The initial value of γ is controlled by the optional parameter Elastic Weight.

Description of Monitoring Information

e04wd produces monitoring information, statistical information and information about the solution. [The Final Output] contains the final output information sent to unit Print File. This section contains other output information.

Major Iteration Log

This section describes the output to unit Print File if Major Print Level>0. One line of information is output every kth major iteration, where k is Print Frequency.
Label | Description
Itns | is the cumulative number of minor iterations.
Major | is the current major iteration number.
Minors | is the number of iterations required by both the feasibility and optimality phases of the QP subproblem. Generally, Minors will be 1 in the later iterations, since theoretical analysis predicts that the correct active set will be identified near the solution (see [Algorithmic Details]).
Step | is the step length α taken along the current search direction p. The variables x have just been changed to x+αp. On reasonably well-behaved problems, the unit step will be taken as the solution is approached.
nCon or nObj | nCon is the number of times confun has been called to evaluate the nonlinear problem functions. Evaluations needed for the estimation of the derivatives by finite differences are not included. nCon is printed as a guide to the amount of work required for the linesearch. If nN, the number of nonlinear constraints, is zero, nCon does not appear, but is replaced by nObj. This quantity is the number of calls made to objfun.
Feasible is the value of vmax (see (12)), the maximum component of the scaled nonlinear constraint residual (see the description of the optional parameter Major Feasibility Tolerance). The solution is regarded as acceptably feasible if Feasible is less than the Major Feasibility Tolerance. In this case, the entry is contained in parentheses.
If the constraints are linear, all iterates are feasible and this entry is not printed.
Optimal | is the value of cmax (see (13)), the maximum complementary gap (see the description of the optional parameter Major Optimality Tolerance). It is an estimate of the degree of nonoptimality of the reduced costs. Both Feasible and Optimal are small in the neighbourhood of a solution.
MeritFunction or Objective is the value of the augmented Lagrangian merit function (see (8)). This function will decrease at each iteration unless it was necessary to increase the penalty parameters (see [The Merit Function]). As the solution is approached, MeritFunction will converge to the value of the objective at the solution.
In elastic mode, the merit function is a composite function involving the constraint violations weighted by the elastic weight.
If the constraints are linear, this item is labelled Objective, the value of the objective function. It will decrease monotonically to its optimal value.
L+U is the number of nonzeros representing the basis factors L and U on completion of the QP subproblem.
If nonlinear constraints are present, the basis factorization B=LU is computed at the start of the first minor iteration. At this stage, L+U=lenL+lenU, where lenL (see [Basis Factorization Statistics]) is the number of subdiagonal elements in the columns of a lower triangular matrix and lenU (see [Basis Factorization Statistics]) is the number of diagonal and superdiagonal elements in the rows of an upper-triangular matrix.
As columns of B are replaced during the minor iterations, L+U may fluctuate up or down but, in general, will tend to increase. As the solution is approached and the minor iterations decrease towards zero, L+U will reflect the number of nonzeros in the LU factors at the start of the QP subproblem.
If the constraints are linear, refactorization is subject only to the Factorization Frequency, and L+U will tend to increase between factorizations.
BSwap | is the number of columns of the basis matrix B that were swapped with columns of S to improve the condition of B. The swaps are determined by an LU factorization of the rectangular matrix BS=BS T with stability being favoured more than sparsity.
nS | is the current number of superbasic variables.
condHz is an estimate of the condition number of RT R, itself an estimate of ZT HZ, the reduced Hessian of the Lagrangian. The condition number is the square of the ratio of the largest and smallest diagonals of the upper triangular matrix R, this being a lower bound on the condition number of RT R. condHz gives a rough indication of whether or not the optimization procedure is having difficulty. If ε is the relative machine precision being used, the SQP algorithm will make slow progress if condHz becomes as large as ε-1/2≈108, and will probably fail to find a better solution if condHz reaches ε-3/4≈1012.
To guard against high values of condHz, attention should be given to the scaling of the variables and the constraints. In some cases it may be necessary to add upper or lower bounds to certain variables to keep them a reasonable distance from singularities in the nonlinear functions or their derivatives.
Penalty | is the Euclidean norm of the vector of penalty parameters used in the augmented Lagrangian merit function (not printed if there are no nonlinear constraints).
The summary line may include additional code characters that indicate what happened during the course of the major iteration. These will follow the separator ‘_’ in the output.
Label | Description
c | central differences have been used to compute the unknown components of the objective and constraint gradients. A switch to central differences is made if either the linesearch gives a small step, or x is close to being optimal. In some cases, it may be necessary to re-solve the QP subproblem with the central difference gradient and Jacobian.
d | during the linesearch it was necessary to decrease the step in order to obtain a maximum constraint violation conforming to the value of Violation Limit.
D | you set mode=-1 on exit from objfun, indicating that the linesearch needed to be done with a smaller value of the step length α.
l | the norm wise change in the variables was limited by the value of the Major Step Limit. If this output occurs repeatedly during later iterations, it may be worthwhile increasing the value of Major Step Limit.
i | if e04wd is not in elastic mode, an i signifies that the QP subproblem is infeasible. This event triggers the start of nonlinear elastic mode, which remains in effect for all subsequent iterations. Once in elastic mode, the QP subproblems are associated with the elastic problem (11) (see [Treatment of Constraint Infeasibilities]). If e04wd is already in elastic mode, an i indicates that the minimizer of the elastic subproblem does not satisfy the linearized constraints. (In this case, a feasible point for the usual QP subproblem may or may not exist.)
M | an extra evaluation of the problem functions was needed to define an acceptable positive definite quasi-Newton update to the Lagrangian Hessian. This modification is only done when there are nonlinear constraints.
m | this is the same as M except that it was also necessary to modify the update to include an augmented Lagrangian term.
n | no positive definite BFGS update could be found. The approximate Hessian is unchanged from the previous iteration.
R | the approximate Hessian has been reset by discarding all but the diagonal elements. This reset will be forced periodically by the Hessian Frequency and Hessian Updates keywords. However, it may also be necessary to reset an ill-conditioned Hessian from time to time.
r | the approximate Hessian was reset after ten consecutive major iterations in which no BFGS update could be made. The diagonals of the approximate Hessian are retained if at least one update has been done since the last reset. Otherwise, the approximate Hessian is reset to the identity matrix.
s | a self-scaled BFGS update was performed. This update is used when the Hessian approximation is diagonal, and hence always follows a Hessian reset.
t | the minor iterations were terminated because of the Minor Iterations Limit.
T | the minor iterations were terminated because of the New Superbasics Limit.
u | the QP subproblem was unbounded.
w | a weak solution of the QP subproblem was found.
z | the Superbasics Limit was reached.

Minor Iteration Log

If Minor Print Level>0, one line of information is output to the Print file every kth minor iteration, where k is the specified Print Frequency. A heading is printed before the first such line following a basis factorization. The heading contains the items described below. In this description, a pricing operation is the process by which a nonbasic variable is selected to become superbasic (in addition to those already in the superbasic set). The selected variable is denoted by jq. Variable jq often becomes basic immediately. Otherwise it remains superbasic, unless it reaches its opposite bound and returns to the nonbasic set.
If Partial Price is in effect, variable jq is selected from App or Ipp, the ppth segments of the constraint matrix A-I.
Label | Description
Itn | the current iteration number.
LPmult or QPmult | is the reduced cost (or reduced gradient) of the variable jq selected by the pricing procedure at the start of the present iteration. Algebraically, the reduced gradient is dj=gj-πT aj for j=jq, where gj is the gradient of the current objective function, π is the vector of dual variables for the QP subproblem, and aj is the jth column of A-I. Note that the reduced cost is the 1-norm of the reduced-gradient vector at the start of the iteration, just after the pricing procedure.
LPstep or QPstep | is the step length α taken along the current search direction p. The variables x have just been changed to x+αp. Write Step to stand for LPStep or QPStep, depending on the problem. If a variable is made superbasic during the current iteration (+SBS>0), Step will be the step to the nearest bound. During the solution of (11), the step can be greater than one only if the reduced Hessian is not positive definite.
nInf | is the number of infeasibilities after the present iteration. This number will not increase unless the iterations are in elastic mode.
SumInf | is the sum of infeasibilities after the present iteration, if nInf>0. The value usually decreases at each nonzero Step, but if it decreases by 2 or more, SumInf may occasionally increase.
rgNorm | is the norm of the reduced-gradient vector at the start of the iteration. (It is the norm of the vector with elements dj for variables j in the superbasic set.) During the solution of subproblem (11) this norm will be approximately zero after a unit step. (The heading is not printed if the problem is linear.)
LPobjective, QPobjective or Elastic QPobj | the QP objective function after the present iteration. In elastic mode, the heading is changed to Elastic QPobj. In either case, the value printed decreases monotonically.
+SBS | is the variable jq selected by the pricing operation to be added to the superbasic set.
-SBS | is the superbasic variable chosen to become nonbasic.
-BS | is the basis variable removed (if any) to become nonbasic.
Pivot | if column aq replaces the rth column of the basis B, Pivot is the rth element of a vector y satisfying By=aq. Wherever possible, Step is chosen to avoid extremely small values of Pivot (since they cause the basis to be nearly singular). In rare cases, it may be necessary to increase the Pivot Tolerance to exclude very small elements of y from consideration during the computation of Step.
L+U | is the number of nonzeros representing the basis factors L and U. Immediately after a basis factorization B=LU, L+U is lenL+lenU, the number of subdiagonal elements in the columns of a lower triangular matrix and the number of diagonal and superdiagonal elements in the rows of an upper-triangular matrix. Further nonzeros are added to L when various columns of B are later replaced. As columns of B are replaced, the matrix U is maintained explicitly (in sparse form). The value of L will steadily increase, whereas the value of U may fluctuate up or down. Thus the value of L+U may fluctuate up or down (in general, it will tend to increase).
ncp | is the number of compressions required to recover storage in the data structure for U. This includes the number of compressions needed during the previous basis factorization.
nS | is the current number of superbasic variables. (The heading is not printed if the problem is linear.)
condHz | see [Major Iteration Log]. (The heading is not printed if the problem is linear.)

Crash Statistics

If Major Print Level≥10 and System Information Yes has been specified, the following items are output to the Print file when Cold Start and no Backup Basis file is loaded. They refer to the number of columns that the Crash procedure selects during selected passes through A while searching for a triangular basis matrix.
Label | Description
Slacks | is the number of slacks selected initially.
Free cols | is the number of free columns in the basis.
Preferred | is the number of ‘preferred’ columns in the basis (i.e., istate[j-1]=3 for some j≤n).
Unit | is the number of unit columns in the basis.
Double | is the number of columns in the basis containing 2 nonzeros.
Triangle | is the number of triangular columns in the basis.
Pad | is the number of slacks used to pad the basis (to make it a nonsingular triangle).

Basis Factorization Statistics

If Major Print Level≥10, the first seven items in the list below are output to the Print file whenever the basis B or the rectangular matrix BS=BS T is factorized before solution of the next QP subproblem. See [Description of the Optional Parameters] for a full description of an optional parameter.
Gaussian elimination is used to compute a sparse LU factorization of B or BS, where PL PT and PUQ are lower and upper triangular matrices for some permutation matrices P and Q. Stability is ensured as described under the optional parameter LU Factor Tolerance.
If Minor Print Level≥10, the same items are printed during the QP solution whenever the current B is factorized. In addition, if System Information Yes has been specified, the entries from Elems onwards are also printed.
Label | Description
Factor | the number of factorizations since the start of the run.
Demand a code giving the reason for the present factorization, as follows:
Code | Meaning
0 | First LU factorization.
1 | The number of updates reached the Factorization Frequency.
2 | The nonzeros in the updated factors have increased significantly.
7 | Not enough storage to update factors.
10 | Row residuals too large (see the description of the optional parameter Check Frequency).
11 | Ill-conditioning has caused inconsistent results.
Itn | is the current minor iteration number.
Nonlin | is the number of nonlinear variables in the current basis B.
Linear | is the number of linear variables in B.
Slacks | is the number of slack variables in B.
B BR BS or BT factorize is the type of LU factorization.
B | periodic factorization of the basis B.
BR | more careful rank-revealing factorization of B using threshold rook pivoting. This occurs mainly at the start, if the first basis factors seem singular or ill-conditioned. Followed by a normal B factorize.
BS | BS is factorized to choose a well-conditioned B from the current B S. Followed by a normal B factorize.
BT | same as BS except the current B is tried first and accepted if it appears to be not much more ill-conditioned than after the previous BS factorize.
m | is the number of rows in B or BS.
n | is the number of columns in B or BS. Preceded by ‘=’ or ‘>’ respectively.
Elems | is the number of nonzero elements in B or BS.
Amax | is the largest nonzero in B or BS.
Density | is the percentage nonzero density of B or BS.
Merit/MerRP/MerCP | is the average Markowitz merit count for the elements chosen to be the diagonals of PUQ. Each merit count is defined to be c-1r-1 where c and r are the number of nonzeros in the column and row containing the element at the time it is selected to be the next diagonal. Merit is the average of n such quantities. It gives an indication of how much work was required to preserve sparsity during the factorization. If LU Complete Pivoting or LU Rook Pivoting has been selected, this heading is changed to MerCP, respectively MerRP.
lenL | is the number of nonzeros in L.
L+U | is the number of nonzeros representing the basis factors L and U. Immediately after a basis factorization B=LU, L+U is lenL+lenU, the number of subdiagonal elements in the columns of a lower triangular matrix and the number of diagonal and superdiagonal elements in the rows of an upper-triangular matrix. Further nonzeros are added to L when various columns of B are later replaced. As columns of B are replaced, the matrix U is maintained explicitly (in sparse form). The value of L will steadily increase, whereas the value of U may fluctuate up or down. Thus the value of L+U may fluctuate up or down (in general, it will tend to increase).
Cmpressns | is the number of times the data structure holding the partially factored matrix needed to be compressed to recover unused storage. Ideally this number should be zero. If it is more than 3 or 4, the amount of workspace available to e04wd should be increased for efficiency.
Incres | is the percentage increase in the number of nonzeros in L and U relative to the number of nonzeros in B or BS.
Utri | is the number of triangular rows of B or BS at the top of U.
lenU | the number of nonzeros in U, including its diagonals.
Ltol | is the largest subdiagonal element allowed in L. This is the specified LU Factor Tolerance or a smaller value that is currently being used for greater stability.
Umax | the maximum nonzero element in U.
Ugrwth is the ratio Umax/Amax, which ideally should not be substantially larger than 10.0 or 100.0. If it is orders of magnitude larger, it may be advisable to reduce the LU Factor Tolerance to 5.0, 4.0, 3.0 or 2.0, say (but bigger than 1.0).
As long as Lmax is not large (say 5.0 or less), max Amax,Umax/DUmin gives an estimate of the condition number B. If this is extremely large, the basis is nearly singular. Slacks are used to replace suspect columns of B and the modified basis is refactored.
Ltri | is the number of triangular columns of B or BS at the left of L.
dense1 | is the number of columns remaining when the density of the basis matrix being factorized reached 0.3.
Lmax | is the actual maximum subdiagonal element in L (bounded by Ltol).
Akmax | is the largest nonzero generated at any stage of the LU factorization. (Values much larger than Amax indicate instability.) Akmax is not printed if LU Partial Pivoting is selected.
Agrwth | is the ratio Akmax/Amax. Values much larger than 100 (say) indicate instability. Growth is not printed if LU Partial Pivoting is selected.
bump | is the size of the block to be factorized nontrivially after the triangular rows and columns of B or BS have been removed.
dense2 | is the number of columns remaining when the density of the basis matrix being factorized reached 0.6. (The Markowitz pivot strategy searches fewer columns at that stage.)
DUmax | is the largest diagonal of PUQ.
DUmin | is the smallest diagonal of PUQ.
condU | the ratio DUmax/DUmin, which estimates the condition number of U (and of B if Ltol is less than 5.0, say).

The Solution File

At the end of a run, the final solution may be output as a Solution file, according to Solution File. Some header information appears first to identify the problem and the final state of the optimization procedure. A ROWS section and a COLUMNS section then follow, giving one line of information for each row and column. The format used is similar to certain commercial systems, though there is no industry standard.
In general, numerical values are output with format f16.5. The maximum record length is 111 characters, including the first (carriage-control) character.
To reduce clutter, a full stop (.) is printed for any numerical value that is exactly zero. The values ±1 are also printed specially as 1.0 and -1.0. Infinite bounds (±1020 or larger) are printed as None.
A Solution file is intended to be read from disk by a self-contained program that extracts and saves certain values as required for possible further computation. Typically, the first 14 records would be ignored. Each subsequent record may be read . The end of the ROWS section is marked by a record that starts with a 1 and is otherwise blank. If this and the next 4 records are skipped, the COLUMNS section can then be read under the same format. (There should be no need for backspace statements.)

The ROWS section

General linear constraints take the form l≤Ax≤u. The ith constraint is therefore of the form
α≤νi x≤β,
where νi is the ith row of A.
Internally, the constraints take the form Ax-s=0, where s is the set of slack variables (which happen to satisfy the bounds l≤s≤u). For the ith constraint it is the slack variable si that is directly available, and it is sometimes convenient to refer to its state. Nonlinear constraints α≤ci x+vi x≤β are treated similarly, except that the row activity and degree of infeasibility are computed directly from ci x+vi x rather than si. A fullstop (.) is printed for any numerical value that is exactly zero.
Label | Description
Number | is the value of n+i. (This is used internally to refer to si in the intermediate output.)
Row | gives the name of the ith row.
State the state of the ith row relative to the bounds α and β. The various states possible are as follows:
LL | the row is at its lower limit, α.
UL | the row is at its upper limit, β.
EQ | the limits are the same (α=β).
FR | si is nonbasic and currently zero, even though it is free to take any value between its bounds α and β.
BS | si is basic.
SBS | si is superbasic.
A key is sometimes printed before State. Note that unless the optional parameter Scale Option=0 is specified, the tests for assigning a key are applied to the variables of the scaled problem.
A | Alternative optimum possible. The variable is nonbasic, but its reduced gradient is essentially zero. This means that if the variable were allowed to start moving away from its bound, there would be no change in the value of the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case, the values of the Lagrange multipliers might also change.
D | Degenerate. The variable is basic or superbasic, but it is equal (or very close) to one of its bounds.
I | Infeasible. The variable is basic or superbasic and is currently violating one of its bounds by more than the value of the Feasibility Tolerance.
N | Not precisely optimal. The variable is nonbasic or superbasic. If the value of the reduced gradient for the variable exceeds the value of the optional parameter Major Optimality Tolerance, the solution would not be declared optimal because the reduced gradient for the variable would not be considered negligible.
Activity | is the value of vi x (or ci x+vi x for nonlinear rows) at the final iterate.
Slack Activity | is the value by which the row differs from its nearest bound. (For the free row (if any), it is set to Activity.)
Lower Limit | is α, the lower bound on the row.
Upper Limit | is β, the upper bound on the row.
Dual Activity | is the value of the dual variable πi (the Lagrange multiplier for the ith constraint). The full vector π always satisfies BT π=gB, where B is the current basis matrix and gB contains the associated gradients for the current objective function. For FP problems, πi is set to zero.
i | gives the index i of the ith row.

The COLUMNS section

Let the jth component of x be the variable xj and assume that it satisfies the bounds α≤xj≤β. A fullstop (.) is printed for any numerical value that is exactly zero.
Label | Description
Number | is the column number j. (This is used internally to refer to xj in the intermediate output.)
Column | gives the name of xj.
State the state of xj relative to the bounds α and β. The various states possible are as follows:
LL | xj is nonbasic at its lower limit, α.
UL | xj is nonbasic at its upper limit, β.
EQ | xj is nonbasic and fixed at the value α=β.
FR | xj is nonbasic at some value strictly between its bounds: α<xj<β.
BS | xj is basic. Usually α<xj<β.
SBS | xj is superbasic. Usually α<xj<β.
A key is sometimes printed before State. Note that unless the optional parameter Scale Option=0 is specified, the tests for assigning a key are applied to the variables of the scaled problem.
A | Alternative optimum possible. The variable is nonbasic, but its reduced gradient is essentially zero. This means that if the variable were allowed to start moving away from its bound, there would be no change in the value of the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case, the values of the Lagrange multipliers might also change.
D | Degenerate. The variable is basic or superbasic, but it is equal (or very close) to one of its bounds.
I | Infeasible. The variable is basic or superbasic and is currently violating one of its bounds by more than the value of the Feasibility Tolerance.
N | Not precisely optimal. The variable is nonbasic or superbasic. If the value of the reduced gradient for the variable exceeds the value of the optional parameter Major Optimality Tolerance, the solution would not be declared optimal because the reduced gradient for the variable would not be considered negligible.
Activity | is the value of xj at the final iterate.
Obj Gradient | is the value of gj at the final iterate. For FP problems, gj is set to zero.
Lower Limit | is the lower bound specified for the variable. None indicates that bl[j-1]≤-bigbnd.
Upper Limit | is the upper bound specified for the variable. None indicates that bu[j-1]≥bigbnd.
Reduced Gradnt | is the value of the reduced gradient dj=gj-πT aj where aj is the jth column of the constraint matrix. For FP problems, dj is set to zero.
m + j | is the value of m+j.
Note that movement off a constraint (as opposed to a variable moving away from its bound) can be interpreted as allowing the entry in the Slack Activity column to become positive.
Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.

The Summary File

If Summary File>0, the following information is output to the unit number associated with Summary File. (It is a brief summary of the output directed to unit Print File):
– | the optional parameters supplied via the option setting methods, if any;
– | the Basis file loaded, if any;
– | a brief major iteration log (see [Major Iteration Log]);
– | a brief minor iteration log (see [Minor Iteration Log]);
– | the exit condition, ifail;
– | a summary of the final iterate.

See Also

E04 Class
E04 Members


e04wdp Method

[image]

NAG Library for .NET Release 2
E04..::e04wdp Method
E04 Class See Also Send Feedback
Auxiliary for use as a delegate parameter

Syntax

C#
public static void e04wdp(
    ref int mode,
    int ncnln,
    int n,
    int[] needc,
    double[] x,
    double[] ccon,
    double[,] cjac,
    int nstate
)
Visual Basic
Public Shared Sub e04wdp ( _
    ByRef mode As Integer, _
    ncnln As Integer, _
    n As Integer, _
    needc As Integer(), _
    x As Double(), _
    ccon As Double(), _
    cjac As Double(,), _
    nstate As Integer _
)
Visual C++
public:
static void e04wdp(
    int% mode,
    int ncnln,
    int n,
    array<int>^ needc,
    array<double>^ x,
    array<double>^ ccon,
    array<double,2>^ cjac,
    int nstate
)
F#
static member e04wdp :
        mode : int byref *
        ncnln : int *
        n : int *
        needc : int[] *
        x : float[] *
        ccon : float[] *
        cjac : float[,] *
        nstate : int -> unit

Parameters

mode
Type: System..::..Int32 %
On entry: is set by e04wd to indicate which values must be assigned during each call of _confun. Only the following values need be assigned, for each value of i such that needc[i-1]>0:
mode=0
The components of ccon corresponding to positive values in needc must be set. Other components and the array cjac are ignored.
mode=1
The known components of the rows of cjac corresponding to positive values in needc must be set. Other rows of cjac and the array ccon will be ignored.
mode=2
Only the elements of ccon corresponding to positive values of needc need to be set (and similarly for the known components of the rows of cjac).
On exit: may be used to indicate that you are unable or unwilling to evaluate the constraint functions at the current x.
During the linesearch, the constraint functions are evaluated at points of the form x=xk+α pk after they have already been evaluated satisfactorily at xk. At any such α, if you set mode=-1, e04wd will evaluate the functions at some point closer to xk (where they are more likely to be defined).
If for some reason you wish to terminate the current problem, set mode<-1.
ncnln
Type: System..::..Int32
On entry: nN, the number of nonlinear constraints.
n
Type: System..::..Int32
On entry: n, the number of variables.
needc
Type: array< System..::..Int32 >[]()[][]
An array of size [ncnln]
On entry: the indices of the elements of ccon and/or cjac that must be evaluated by _confun. If needc[i-1]>0, the ith element of ccon and/or the available elements of the ith row of cjac (see parameter mode) must be evaluated at x.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x, the vector of variables at which the constraint functions and/or the available elements of the constraint Jacobian are to be evaluated.
ccon
Type: array< System..::..Double >[]()[][]
An array of size [max 1,ncnln]
On exit: if needc[i-1]>0 and mode=0 or 2, ccon[i-1] must contain the value of the ith constraint at x. The remaining elements of ccon, corresponding to the non-positive elements of needc, are ignored.
cjac
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint:
On entry: the elements of cjac are set to special values that enable e04wd to detect whether they are reset by _confun.
On exit: if needc[i-1]>0 and mode=1 or 2, the ith row of cjac must contain the available elements of the vector ∇ci given by
∇ci=∂ci∂x 1,∂ci∂x 2,…,∂ci∂xn T,
where ∂ci∂xj is the partial derivative of the ith constraint with respect to the jth variable, evaluated at the point x. See also the parameter nstate. The remaining rows of cjac, corresponding to non-positive elements of needc, are ignored.
If all elements of the constraint Jacobian are known (i.e., optparam_derivativelevel=2 or 3), any constant elements may be assigned to cjac one time only at the start of the optimization. An element of cjac that is not subsequently assigned in _confun will retain its initial value throughout. Constant elements may be loaded into cjac during the first call to _confun (signalled by the value nstate=1). The ability to preload constants is useful when many Jacobian elements are identically zero, in which case cjac may be initialized to zero and nonzero elements may be reset by _confun.
Note that constant nonzero elements do affect the values of the constraints. Thus, if cjac[i-1,j-1] is set to a constant value, it need not be reset in subsequent calls to _confun, but the value cjac[i-1,j-1]×x[j-1] must nonetheless be added to ccon[i-1]. For example, if cjac[0,0]=2 and cjac[0,1]=-5 then the term 2×x[0]-5×x[1] must be included in the definition of ccon[0].
It must be emphasized that, if optparam_derivativelevel=0 or 1, unassigned elements of cjac are not treated as constant; they are estimated by finite differences, at nontrivial expense. If you do not supply a value for the optional parameter optparam_differenceinterval, an interval for each element of x is computed automatically at the start of the optimization. The automatic procedure can usually identify constant elements of cjac, which are then computed once only by finite differences.
nstate
Type: System..::..Int32
On entry: if nstate=1 then e04wd is calling _confun for the first time. This parameter setting allows you to save computation time if certain data must be read or calculated only once.

Description

Auxiliary for use as a delegate parameter

References

None.

Error Indicators and Warnings

None.

Accuracy

Not applicable.

Further Comments

None.

Example

None.

See Also

E04 Class
E04 Members


e04xa Method

[image]

NAG Library for .NET Release 2
E04..::e04xa Method
E04 Class See Also Send Feedback
e04xa computes an approximation to the gradient vector and/or the Hessian matrix for use in conjunction with, or following the use of an optimization method (such as e04uf).

Syntax

C#
public static void e04xa(
    int msglvl,
    int n,
    double epsrf,
    double[] x,
    ref int mode,
    E04..::..E04XA_OBJFUN objfun,
    double[] hforw,
    out double objf,
    double[] objgrd,
    double[] hcntrl,
    double[,] h,
    out int iwarn,
    int[] info,
    out int ifail
)
Visual Basic
Public Shared Sub e04xa ( _
    msglvl As Integer, _
    n As Integer, _
    epsrf As Double, _
    x As Double(), _
    ByRef mode As Integer, _
    objfun As E04..::..E04XA_OBJFUN, _
    hforw As Double(), _
    <OutAttribute> ByRef objf As Double, _
    objgrd As Double(), _
    hcntrl As Double(), _
    h As Double(,), _
    <OutAttribute> ByRef iwarn As Integer, _
    info As Integer(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04xa(
    int msglvl,
    int n,
    double epsrf,
    array<double>^ x,
    int% mode,
    E04..::..E04XA_OBJFUN^ objfun,
    array<double>^ hforw,
    [OutAttribute] double% objf,
    array<double>^ objgrd,
    array<double>^ hcntrl,
    array<double,2>^ h,
    [OutAttribute] int% iwarn,
    array<int>^ info,
    [OutAttribute] int% ifail
)
F#
static member e04xa :
        msglvl : int *
        n : int *
        epsrf : float *
        x : float[] *
        mode : int byref *
        objfun : E04..::..E04XA_OBJFUN *
        hforw : float[] *
        objf : float byref *
        objgrd : float[] *
        hcntrl : float[] *
        h : float[,] *
        iwarn : int byref *
        info : int[] *
        ifail : int byref -> unit

Parameters

msglvl
Type: System..::..Int32
On entry: must indicate the amount of intermediate output desired (see [Description of the Printed Output] for a description of the printed output). All output is written on the current advisory message unit (see (X04ABF not in this release)).
Value | Definition
0 | No printout
1 | A summary is printed out for each variable plus any warning messages.
Other | Values other than 0 and 1 should normally be used only at the direction of NAG.
n
Type: System..::..Int32
On entry: the number n of independent variables.
Constraint: n≥1.
epsrf
Type: System..::..Double
On entry: must define eR, which is intended to be a measure of the accuracy with which the problem function F can be computed. The value of eR should reflect the relative precision of 1+F x, i.e., acts as a relative precision when F is large, and as an absolute precision when F is small. For example, if F x is typically of order 1000 and the first six significant digits are known to be correct, an appropriate value for eR would be 1.0E−6.
A discussion of epsrf is given in Chapter 8 of Gill et al. (1981). If epsrf is either too small or too large on entry a warning will be printed if msglvl=1, the parameter iwarn set to the appropriate value on exit and e04xa will use a default value of eM 0.9, where eM is the machine precision.
If epsrf≤0.0 on entry then e04xa will use the default value internally. The default value will be appropriate for most simple functions that are computed with full accuracy.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the point x at which the derivatives are to be computed.
mode
Type: System..::..Int32 %
On entry: indicates which derivatives are required.
mode=0
The gradient and Hessian diagonal values having supplied the objective function via objfun.
mode=1
The Hessian matrix having supplied both the objective function and gradients via objfun.
mode=2
The gradient values and Hessian matrix having supplied the objective function via objfun.
On exit: is changed only if you set mode negative in objfun, i.e., you have requested termination of e04xa.
objfun
Type: NagLibrary..::..E04..::..E04XA_OBJFUN
If mode=0 or 2, objfun must calculate the objective function; otherwise if mode=1, objfun must calculate the objective function and the gradients.

A delegate of type E04XA_OBJFUN.

hforw
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the initial trial interval for computing the appropriate partial derivative to the jth variable.
If hforw[j-1]≤0.0, then the initial trial interval is computed by e04xa (see [Description]).
On exit: hforw[j-1] is the best interval found for computing a forward-difference approximation to the appropriate partial derivative for the jth variable.
objf
Type: System..::..Double %
On exit: the value of the objective function evaluated at the input vector in x.
objgrd
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: if mode=0 or 2, objgrd[j-1] contains the best estimate of the first partial derivative for the jth variable.
If mode=1, objgrd[j-1] contains the first partial derivative for the jth variable evaluated at the input vector in x.
hcntrl
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: hcntrl[j-1] is the best interval found for computing a central-difference approximation to the appropriate partial derivative for the jth variable.
h
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥n
Note: the second dimension of the array h must be at least 1 if mode=0 and at least n if mode=1 or 2.
On exit: if mode=0, the estimated Hessian diagonal elements are contained in the first column of this array.
If mode=1 or 2, the estimated Hessian matrix is contained in the leading n by n part of this array.
iwarn
Type: System..::..Int32 %
On exit: iwarn=0 on successful exit.
If the value of epsrf on entry is too small or too large then iwarn is set to 1 or 2 respectively on exit and the default value for epsrf is used within e04xa.
If msglvl>0 then warnings will be printed if epsrf is too small or too large.
info
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On exit: info[j-1] represents diagnostic information on variable j. (See [Error Indicators and Warnings] for more details.)
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e04xa is similar to routine FDCALC described in Gill et al. (1983a). It should be noted that this method aims to compute sufficiently accurate estimates of the derivatives for use with an optimization algorithm. If you require more accurate estimates you should refer to (D04 not in this release).
e04xa computes finite difference approximations to the gradient vector and the Hessian matrix for a given function. The simplest approximation involves the forward-difference formula, in which the derivative f′x of a univariate function f x is approximated by the quantity
ρF f,h=f x+h-f x h
for some interval h>0, where the subscript "F" denotes ‘forward-difference’ (see Gill et al. (1983b)).
To summarise the procedure used by e04xa (for the case when the objective function is available and you require estimates of gradient values and Hessian matrix diagonal values, i.e., mode=0) consider a univariate function f at the point x. (In order to obtain the gradient of a multivariate function F x, where x is an n-vector, the procedure is applied to each component of x, keeping the other components fixed.) Roughly speaking, the method is based on the fact that the bound on the relative truncation error in the forward-difference approximation tends to be an increasing function of h, while the relative condition error bound is generally a decreasing function of h, hence changes in h will tend to have opposite effects on these errors (see Gill et al. (1983b)).
The ‘best’ interval h is given by
hF=2 1+f x eR Φ (1)
where Φ is an estimate of f′′x, and eR is an estimate of the relative error associated with computing the function (see Chapter 8 of Gill et al. (1981)). Given an interval h, Φ is defined by the second-order approximation
Φ=f x+h-2 f x+f x-h h 2.
The decision as to whether a given value of Φ is acceptable involves c^Φ, the following bound on the relative condition error in Φ:
c^Φ=4 eR 1+fh 2 Φ
(When Φ is zero, c^Φ is taken as an arbitrary large number.)
The procedure selects the interval hϕ (to be used in computing Φ) from a sequence of trial intervals hk. The initial trial interval is taken as 10 h-, where
h-=2 1+x eR
unless you specify the initial value to be used.
The value of c^Φ for a trial value hk is defined as ‘acceptable’ if it lies in the interval 0.001,0.1. In this case hϕ is taken as hk, and the current value of Φ is used to compute hF from (1). If c^Φ is unacceptable, the next trial interval is chosen so that the relative condition error bound will either decrease or increase, as required. If the bound on the relative condition error is too large, a larger interval is used as the next trial value in an attempt to reduce the condition error bound. On the other hand, if the relative condition error bound is too small, hk is reduced.
The procedure will fail to produce an acceptable value of c^Φ in two situations. Firstly, if f′′x is extremely small, then c^Φ may never become small, even for a very large value of the interval. Alternatively, c^Φ may never exceed 0.001, even for a very small value of the interval. This usually implies that f′′x is extremely large, and occurs most often near a singularity.
As a check on the validity of the estimated first derivative, the procedure provides a comparison of the forward-difference approximation computed with hF (as above) and the central-difference approximation computed with hϕ. Using the central-difference formula the first derivative can be approximated by
ρc f,h=f x+h-f x-h2 h
where h>0. If the values hF and hϕ do not display some agreement, neither can be considered reliable.
When both function and gradients are available and you require the Hessian matrix (i.e., mode=1) e04xa follows a similar procedure to the case above with the exception that the gradient function g x is substituted for the objective function and so the forward-difference interval for the first derivative of g x with respect to variable xj is computed. The jth column of the approximate Hessian matrix is then defined as in Chapter 2 of Gill et al. (1981), by
g x+hjej-g x hj
where hj is the best forward-difference interval associated with the jth component of g and ej is the vector with unity in the jth position and zeros elsewhere.
When only the objective function is available and you require the gradients and Hessian matrix (i.e., mode=2) e04xa again follows the same procedure as the case for mode=0 except that this time the value of c^Φ for a trial value hk is defined as acceptable if it lies in the interval 0.0001,0.01 and the initial trial interval is taken as
h-=2 1+x eR 4.
The approximate Hessian matrix G is then defined as in Chapter 2 of Gill et al. (1981), by
G ij x=1 hihj f x+hiei+hjej-f x+hiei-f x+hjej+f x.

References

Gill P E, Murray W, Saunders M A and Wright M H (1983a) Documentation for FDCALC and FDCORE Technical Report SOL 83–6 Stanford University
Gill P E, Murray W, Saunders M A and Wright M H (1983b) Computing forward-difference intervals for numerical optimization SIAM J. Sci. Statist. Comput. 4 310–321
Gill P E, Murray W and Wright M H (1981) Practical Optimization Academic Press

Error Indicators and Warnings

On exit from e04xa both diagnostic parameters info and ifail should be tested. ifail represents an overall diagnostic indicator, whereas the integer array info represents diagnostic information on each variable.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDH) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail<0
A negative value of ifail indicates an exit from e04xa because you set mode negative in objfun. The value of ifail will be the same as your setting of mode.
ifail=1
On entry, one or more of the following conditions are satisfied: n<1, ldh<n​ or ​mode is invalid.
ifail=2
One or more variables have a nonzero info value. This may not necessarily represent an unsuccessful exit – see diagnostic information on info.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
Diagnostic information returned via info is as follows:
Some error messages may refer to parameters that are dropped from this interface (LDH) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info=1
The appropriate function appears to be constant. hforw[i-1] is set to the initial trial interval value (see [Description]) corresponding to a well-scaled problem and Error est. in the printed output is set to zero. This value occurs when the estimated relative condition error in the first derivative approximation is unacceptably large for every value of the finite difference interval. If this happens when the function is not constant the initial interval may be too small; in this case, it may be worthwhile to rerun e04xa with larger initial trial interval values supplied in hforw (see [Description]). This error may also occur if the function evaluation includes an inordinately large constant term or if epsrf is too large.
info=2
The appropriate function appears to be linear or odd. hforw[i-1] is set to the smallest interval with acceptable bounds on the relative condition error in the forward- and backward-difference estimates. In this case, the estimated relative condition error in the second derivative approximation remained large for every trial interval, but the estimated error in the first derivative approximation was acceptable for at least one interval. If the function is not linear or odd the relative condition error in the second derivative may be decreasing very slowly, it may be worthwhile to rerun e04xa with larger initial trial interval values supplied in hforw (see [Description]).
info=3
The second derivative of the appropriate function appears to be so large that it cannot be reliably estimated (i.e., near a singularity). hforw[i-1] is set to the smallest trial interval.
This value occurs when the relative condition error estimate in the second derivative remained very small for every trial interval.
If the second derivative is not large the relative condition error in the second derivative may be increasing very slowly. It may be worthwhile to rerun e04xa with smaller initial trial interval values supplied in hforw (see [Description]). This error may also occur when the given value of epsrf is not a good estimate of a bound on the absolute error in the appropriate function (i.e., epsrf is too small).
info=4
The algorithm terminated with an apparently acceptable estimate of the second derivative. However the forward-difference estimates of the appropriate first derivatives (computed with the final estimate of the ‘optimal’ forward-difference interval) and the central difference estimates (computed with the interval used to compute the final estimate of the second derivative) do not agree to half a decimal place. The usual reason that the forward- and central-difference estimates fail to agree is that the first derivative is small.
If the first derivative is not small, it may be helpful to execute the procedure at a different point.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

If ifail=0 on exit the algorithm terminated successfully, i.e., the forward-difference estimates of the appropriate first derivatives (computed with the final estimate of the ‘optimal’ forward-difference interval hF) and the central-difference estimates (computed with the interval hϕ used to compute the final estimate of the second derivative) agree to at least half a decimal place.
In short word length implementations when computing the full Hessian matrix given function values only (i.e., mode=2) the elements of the computed Hessian will have at best 1 to 2 figures of accuracy.

Parallelism and Performance

None.

Further Comments

To evaluate an acceptable set of finite difference intervals for a well-scaled problem, the method will require around two function evaluations per variable; in a badly scaled problem however, as many as six function evaluations per variable may be needed.
If you request the full Hessian matrix supplying both function and gradients (i.e., mode=1) or function only (i.e., mode=2) then a further n or 3×n×n+1/2 function evaluations respectively are required.

Description of the Printed Output

The following is a description of the printed output from e04xa as controlled by the parameter msglvl.
Output when msglvl=1 is as follows:
J | number of variable for which the difference interval has been computed.
X j | jth variable of x as set by you.
F. dif. int. | the best interval found for computing a forward-difference approximation to the appropriate partial derivative with respect to the jth variable.
C. dif. int. | the best interval found for computing a central-difference approximation to the appropriate partial derivative with respect to the jth variable.
Error est. | a bound on the estimated error in the final forward-difference approximation. When info[j-1]=1, Error est. is set to zero.
Grad. est. | best estimate of the first partial derivative with respect to the jth variable.
Hess diag est. | best estimate of the second partial derivative with respect to the jth variable.
fun evals. | the number of function evaluations used to compute the final difference intervals for the jth variable.
info j | the value of info for the jth variable.

Example

This example computes the gradient vector and the Hessian matrix of the following function:
F x=x 1+10 x 2 2+5⁢x 3-x 4 2+x 2-2 x 3 4+10⁢x 1-x 4 4
at the point 3,-1,0,1.

Example program (C#): e04xae.cs

Example program results: e04xae.r

See Also

E04 Class
E04 Members


e04ya Method

[image]

NAG Library for .NET Release 2
E04..::e04ya Method
E04 Class See Also Send Feedback
e04ya checks that a user-supplied method for evaluating a vector of functions and the matrix of their first derivatives produces derivative values which are consistent with the function values calculated.

Syntax

C#
public static void e04ya(
    int m,
    int n,
    E04..::..E04YA_LSQFUN lsqfun,
    double[] x,
    double[] fvec,
    double[,] fjac,
    out int ifail
)
Visual Basic
Public Shared Sub e04ya ( _
    m As Integer, _
    n As Integer, _
    lsqfun As E04..::..E04YA_LSQFUN, _
    x As Double(), _
    fvec As Double(), _
    fjac As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04ya(
    int m,
    int n,
    E04..::..E04YA_LSQFUN^ lsqfun,
    array<double>^ x,
    array<double>^ fvec,
    array<double,2>^ fjac,
    [OutAttribute] int% ifail
)
F#
static member e04ya :
        m : int *
        n : int *
        lsqfun : E04..::..E04YA_LSQFUN *
        x : float[] *
        fvec : float[] *
        fjac : float[,] *
        ifail : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: the number m of residuals, fi x, and the number n of variables, xj.
Constraint: 1≤n≤m.
n
Type: System..::..Int32
On entry: the number m of residuals, fi x, and the number n of variables, xj.
Constraint: 1≤n≤m.
lsqfun
Type: NagLibrary..::..E04..::..E04YA_LSQFUN
lsqfun must calculate the vector of values fi x and their first derivatives ∂fi∂xj at any point x. (The minimization methods mentioned in [Description] give you the option of resetting a parameter to terminate immediately. e04ya will also terminate immediately, without finishing the checking process, if the parameter in question is reset.)

A delegate of type E04YA_LSQFUN.

x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x[j-1], for j=1,2,…,n, must be set to the coordinates of a suitable point at which to check the derivatives calculated by lsqfun. ‘Obvious’ settings, such as 0 or 1, should not be used since, at such particular points, incorrect terms may take correct values (particularly zero), so that errors can go undetected. For a similar reason, it is preferable that no two elements of x should have the same value.
fvec
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: unless you set iflag negative in the first call of lsqfun, fvec[i-1] contains the value of fi at the point supplied by you in x, for i=1,2,…,m.
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: unless you set iflag negative in the first call of lsqfun, fjac[i-1,j-1] contains the value of the first derivative ∂fi∂xj at the point given in x, as calculated by lsqfun, for i=1,2,…,m and j=1,2,…,n.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Routines for minimizing a sum of squares of m nonlinear functions (or ‘residuals’), fi x 1,x 2,…,xn, for i=1,2,…,m and m≥n, may require you to supply a method to evaluate the fi and their first derivatives. e04ya checks the derivatives calculated by such user-supplied delegates, e.g., methods of the form required for (E04GBF not in this release) e04gd e04he. As well as the method to be checked (lsqfun), you must supply a point x=x 1,x 2,…,xn T at which the check will be made. e04ya is essentially identical to CHKLSJ in the NPL Algorithms Library.
e04ya first calls lsqfun to evaluate the fi x and their first derivatives, and uses these to calculate the sum of squares F x=∑i=1 m fi x 2, and its first derivatives gj=∂F∂xj x, for j=1,2,…,n. The components of g along two orthogonal directions (defined by unit vectors p 1 and p 2, say) are then calculated; these will be gT p 1 and gT p 2 respectively. The same components are also estimated by finite differences, giving quantities
vk=F x+h pk-F x h,  k=1,2
where h is a small positive scalar. If the relative difference between v 1 and gT p 1 or between v 2 and gT p 2 is judged too large, an error indicator is set.

References

None.

Error Indicators and Warnings

Note: e04ya may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDFJAC, IW, LIW, W, LW) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail<0
A negative value of ifail indicates an exit from e04ya because you have set iflag negative in lsqfun. The setting of ifail will be the same as your setting of iflag. The check on lsqfun will not have been completed.
ifail=1
On entry, | m<n,
or | n<1,
ifail=2
You should check carefully the derivation and programming of expressions for the ∂fi∂xj, because it is very unlikely that lsqfun is calculating them correctly.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

ifail is set to 2 if
vk-gT pk 2≥h×gT pk 2+1
for k=1​ or ​2. (See [Description] for definitions of the quantities involved.) The scalar h is set equal to ε, where ε is the machine precision as given by x02aj.

Parallelism and Performance

None.

Further Comments

e04ya calls lsqfun three times.
Before using e04ya to check the calculation of the first derivatives, you should be confident that lsqfun is calculating the residuals correctly.
e04ya only checks the derivatives calculated by a user-supplied method when iflag=2. So, if lsqfun is intended for use in conjunction with a minimization method which may set iflag to 1, you must check that, for given settings of the xc[j-1], lsqfun produces the same values for the ∂fi∂xj when iflag is set to 1 as when iflag is set to 2.

Example

Example program (C#): e04yae.cs

Example program data: e04yae.d

Example program results: e04yae.r

See Also

E04 Class
E04 Members


e04yb Method

[image]

NAG Library for .NET Release 2
E04..::e04yb Method
E04 Class See Also Send Feedback
e04yb checks that a user-supplied method for evaluating the second derivative term of the Hessian matrix of a sum of squares is consistent with a user-supplied method for calculating the corresponding first derivatives.

Syntax

C#
public static void e04yb(
    int m,
    int n,
    E04..::..E04YB_LSQFUN lsqfun,
    E04..::..E04YB_LSQHES lsqhes,
    double[] x,
    double[] fvec,
    double[,] fjac,
    double[] b,
    out int ifail
)
Visual Basic
Public Shared Sub e04yb ( _
    m As Integer, _
    n As Integer, _
    lsqfun As E04..::..E04YB_LSQFUN, _
    lsqhes As E04..::..E04YB_LSQHES, _
    x As Double(), _
    fvec As Double(), _
    fjac As Double(,), _
    b As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e04yb(
    int m,
    int n,
    E04..::..E04YB_LSQFUN^ lsqfun,
    E04..::..E04YB_LSQHES^ lsqhes,
    array<double>^ x,
    array<double>^ fvec,
    array<double,2>^ fjac,
    array<double>^ b,
    [OutAttribute] int% ifail
)
F#
static member e04yb :
        m : int *
        n : int *
        lsqfun : E04..::..E04YB_LSQFUN *
        lsqhes : E04..::..E04YB_LSQHES *
        x : float[] *
        fvec : float[] *
        fjac : float[,] *
        b : float[] *
        ifail : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: the number m of residuals, fi x, and the number n of variables, xj.
Constraint: 1≤n≤m.
n
Type: System..::..Int32
On entry: the number m of residuals, fi x, and the number n of variables, xj.
Constraint: 1≤n≤m.
lsqfun
Type: NagLibrary..::..E04..::..E04YB_LSQFUN
lsqfun must calculate the vector of values fi x and their first derivatives ∂fi∂xj at any point x. (e04he gives you the option of resetting parameters of lsqfun to cause the minimization process to terminate immediately. e04yb will also terminate immediately, without finishing the checking process, if the parameter in question is reset.)

A delegate of type E04YB_LSQFUN.

Note: e04ya should be used to check the first derivatives calculated by lsqfun before e04yb is used to check the b jk since e04yb assumes that the first derivatives are correct.
lsqhes
Type: NagLibrary..::..E04..::..E04YB_LSQHES
lsqhes must calculate the elements of the symmetric matrix
B x=∑i=1 m fi x Gi x,
at any point x, where Gi x is the Hessian matrix of fi x. (As with lsqfun, a parameter can be set to cause immediate termination.)

A delegate of type E04YB_LSQHES.

x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x[j-1], for j=1,2,…,n, must be set to the coordinates of a suitable point at which to check the b jk calculated by lsqhes. ‘Obvious’ settings, such as 0 or 1, should not be used since, at such particular points, incorrect terms may take correct values (particularly zero), so that errors could go undetected. For a similar reason, it is preferable that no two elements of x should have the same value.
fvec
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: unless you set iflag negative in the first call of lsqfun, fvec[i-1] contains the value of fi at the point supplied by you in x, for i=1,2,…,m.
fjac
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: unless you set iflag negative in the first call of lsqfun, fjac[i-1,j-1] contains the value of the first derivative ∂fi∂xj at the point given in x, as calculated by lsqfun, for i=1,2,…,m and j=1,2,…,n.
b
Type: array< System..::..Double >[]()[][]
An array of size [lb]
On exit: unless you set iflag negative in lsqhes, b[j×j-1/2+k-1] contains the value of b jk at the point given in x as calculated by lsqhes, for j=1,2,…,n and k=1,2,…,j.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Methods for minimizing a sum of squares of m nonlinear functions (or ‘residuals’), fi x 1,x 2,…,xn, for i=1,2,…,m and m≥n, may require you to supply a method to evaluate the quantities
b jk=∑i=1 m fi∂2 fi∂xj∂xk
for j=1,2,…,n and k=1,2,…,j. e04yb is designed to check the b jk calculated by such user-supplied delegates. As well as the method to be checked (lsqhes), you must supply a method (lsqfun) to evaluate the fi and their first derivatives, and a point x=x 1,x 2,…,xn T at which the checks will be made. Note that e04yb checks methods of the form required by e04he. e04yb is essentially identical to CHKLSH in the NPL Algorithms Library.
e04yb first calls user-supplied delegates lsqfun and lsqhes to evaluate the first derivatives and the b jk at x. Let J denote the m by n matrix of first derivatives of the residuals. The Hessian matrix of the sum of squares,
G=JT J+B,
is calculated and projected onto two orthogonal vectors y and z to give the scalars yT Gy and zT Gz respectively. The same projections of the Hessian matrix are also estimated by finite differences, giving
p=yT g x+hy-yT g x/h  andq=zT g x+hz-zT g x/h
respectively, where g denotes the gradient vector of the sum of squares at the point in brackets and h is a small positive scalar. If the relative difference between p and yT Gy or between q and zT Gz is judged too large, an error indicator is set.

References

None.

Error Indicators and Warnings

Note: e04yb may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDFJAC, IW, LIW, W, LW) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail<0
A negative value of ifail indicates an exit from e04yb because you have set iflag negative in user-supplied delegates lsqfun or lsqhes. The setting of ifail will be the same as your setting of iflag. The check on lsqhes will not have been completed.
ifail=1
On entry, | m<n,
or | n<1,
or | lb<n+1×n/2,
ifail=2
You should check carefully the derivation and programming of expressions for the b jk, because it is very unlikely that lsqhes is calculating them correctly.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

ifail is set to 2 if
yT Gy-p≥h yT Gy+1.0orzT Gz-q≥h zT Gz+1.0
where h is set equal to ε (ε being the machine precision as given by x02aj) and other quantities are defined as in [Description].

Parallelism and Performance

None.

Further Comments

e04yb calls lsqhes once and lsqfun three times.

Example

Example program (C#): e04ybe.cs

Example program data: e04ybe.d

Example program results: e04ybe.r

See Also

E04 Class
E04 Members


E05 Class

[image]

NAG Library for .NET Release 2
E05 Class
Members See Also Send Feedback
Global optimization involves finding the absolute maximum or minimum value of a function (the objective function) of several variables, possibly subject to restrictions (defined by a set of bounds or constraint functions) on the values of the variables. Such problems can be much harder to solve than local optimization problems (which are discussed in E04 class) because it is difficult to determine whether a potential optimum found is global, and because of the nonlocal methods required to avoid becoming trapped near local optima. Most optimization methods in the NAG Library are concerned with function minimization only, since the problem of maximizing a given objective function F is equivalent to minimizing -F. In e05jb, (E05SAF not in this release) and (E05SBF not in this release), you may specify whether you are solving a minimization or maximization problem; in the latter case, the required transformation of the objective function will be carried out automatically. In what follows we refer exclusively to minimization problems.
This introduction is a brief guide to the subject of global optimization, designed for the casual user. For further details you may find it beneficial to consult a more detailed text, such as Neumaier (2004). Furthermore, much of the material in the E04 class is relevant in this context also. In particular, it is strongly recommended that you read [] in the E04 class Chapter Introduction.

Syntax

C#
public static class E05
Visual Basic
Public NotInheritable Class E05
Visual C++
public ref class E05 abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type E05 =  class end

Background to the Problems

Problem Formulation

For the purposes of this Library, the global optimization problem is
minimize x∈Rn F x  subject to  lx≤x≤ux  and  lc≤c x≤uc, (1)
where F x (the objective function) is a real function; the vectors lx and ux are elements of R-n, where R- denotes the extended reals R∪-∞,∞; and where c is a vector of m constraint functions c 1,…,cm, with lc and uc defining the constraints on c x. If m=0 the problem is said to be bound constrained. Relational operators between vectors are interpreted elementwise. The feasible region Φ is the set of all points (feasible points) that satisfy all of the constraints. A solution of (1) is a feasible point x^∈Φ satisfying
F x^=min x∈Φ F x.
A local minimum minimizes F only on some neighbourhood of x^. If a local minimum has the smallest objective value over all the local minima, then it is a global minimum.

Terminology

Complete Methods

A global optimization algorithm is called asymptotically complete if
(i) | assuming indefinitely long run-time and exact computations, a global minimum will be found with certainty (probability one), but
(ii) | the algorithm has no way of knowing when a global minimum has been found.
In comparison, a complete method satisfies (i) as well as
(ii(a)) the algorithm is able to recognize a global minimum (to prescribed tolerances) within a finite amount of time.
It is important to appreciate that, for finding a solution exactly, bounds on the amount of work may be very pessimistic. What complete methods guarantee is the absence of any deficiency that would prevent a global minimum from eventually being found. To achieve termination with certainty in a finite amount of time, the algorithm requires access to global information about the problem. In the case where only function values are available, as in e05jb, stopping criteria based on heuristics are present. This is because such a class of method can only terminate with certainty by performing an expensive dense search.
In contrast, incomplete methods have intuitive heuristics for searching but no guarantee of not getting stuck near nonglobal, local, minima. Often, to make incomplete methods efficient, expert knowledge on the particular problem class to be solved is required. Examples of incomplete methods include Particle Swarm Optimization (PSO), Genetic Algorithms (GA), Simulated Annealing (SA), Ant Colony Optimization (ACO) and Covariance Matrix Adaptation Evolutionary Strategies (CMA-ES). PSO has been implemented in the methods (E05SAF not in this release) (E05SBF not in this release). Such methods must also use heuristics to stop the algorithm as again an expensive, dense search would be required to guarantee that no superior optima are present.
The heuristic nature of incomplete algorithms can make them very efficiently parallelizable. This is the case for (E05SAF not in this release) (E05SBF not in this release), which use a heavily asynchronous implementation of the particle swarm heuristic to be efficient in achieving a good solution in implementations of the NAG Library for SMP & Multicore.

Branching

Most complete methods recursively split the original problem into smaller, more manageable subproblems. This technique is called branching. Branching is usually accompanied by a selection process that splits favourable branches more frequently than others. For example, with branch and bound methods, bounds on the objective function for each subproblem are computed in an attempt to eliminate those subregions where no improvement will occur.
Branching methods use a branching scheme to generate sequences of sub-boxes that eventually cover the feasible region. At least one function evaluation is made for every sub-box, and new sub-boxes are generated by splitting existing ones. Using appropriate splitting rules, convergence to zero of the diameters of sub-boxes is assured. For example, always splitting the oldest box along the oldest side, provided the children do not have too small a volume compared with the parent, guarantees convergence of the method, in the sense described in Neumaier (2004).
Efficiency can be enhanced by carefully balancing global and local searches. While the global part of the search splits sub-boxes with large unexplored territory, the local part usually entails splitting boxes with good function values. For example, the sub-box with the best function value should always be split. A method may also be improved by launching local searches from appropriate candidate local minima.

Methods of Global Optimization

Multi-level Coordinate Search (MCS)

The method e05jb searches for a global minimizer using branching to recursively split the search space in a nonuniform manner. It divides, or splits, the root box of the search into smaller sub-boxes. Each sub-box contains a distinguished basepoint at which the objective function is sampled. We shall sometimes say ‘the function value of the (sub)box’ as shorthand for ‘the function value of the basepoint of the (sub)box’. The splitting procedure biases the search in favour of those sub-boxes where low function values are expected.
The global part of the algorithm entails splitting sub-boxes that enclose large unexplored territory, while the local part of the algorithm entails splitting sub-boxes that have good function values. A balance between the global and local part is achieved using a multi-level approach, where every sub-box is assigned a level s∈0,1,…,smax. You can control the value of smax using the optional parameter Splits Limit. Whenever a sub-box of intermediate level 0<s<smax is split each descendant will be given a new level, and the original sub-box's level is set to 0: a sub-box with level 0 has already been split; a sub-box with level smax will be split no further. This entire process is described in more detail in [] in e05jb, where the initialization procedure used to produce an initial set of sub-boxes is outlined, and the method by which the algorithm sweeps through levels is discussed. Each sweep starts with the sub-boxes at the lowest level, a process thus forming the global part of the algorithm. At each level the sub-box with the best function value is selected for splitting; this forms the local part of the algorithm.
The process by which sub-boxes are split is explained in [] in e05jb. It is a variant of the standard coordinate search method: the solver splits along a single coordinate at a time, at adaptively chosen points. In most cases one new function evaluation is needed to split a sub-box into two or three children. Each child is given a basepoint chosen to differ from the basepoint of the parent in at most one coordinate, and safeguards are present to ensure a degree of symmetry in the splits.
If you set the optional parameter Local Searches to be OFF, then the basepoints and function values of sub-boxes of maximum level smax are put into a ‘shopping basket’ of candidate minima. Turning Local Searches ON (the default setting) will enable local searches to be started from these basepoints before they go into the shopping basket. The local search will go ahead providing the basepoint is not likely to be in the basin of attraction of a previously-found local minimum. The search itself uses a trust region approach, and is explained in [] in e05jb: local quadratic models are built by a triple search, then a linesearch is made along the direction obtained by minimizing the quadratic on a region where it is a good approximation to the objective function. The quadratic need not be positive definite, so the general nonlinear optimizer e04vh is used to minimize the model.

Particle Swarm Optimization

The methods (E05SAF not in this release) (E05SBF not in this release) search for a global optimum using a variant of the Particle Swarm Optimization (PSO) algorithm. PSO is an heuristic algorithm similar in its behaviour to GA, ACO, SA and others. A set of particles (the swarm) is generated in the search space, and advances at each iteration following an heuristic velocity based upon the best candidate found by an individual particle (cognitive memory), the best candidate found by all the particles (global memory) and inertia. The inertia is provided by a decreasingly weighted contribution from a particle's current velocity. This mix allows for a global search of the domain in question.
The rate at which the swarm contracts and expands about potential optima is user controllable, allowing expert knowledge to be used when available. Furthermore, the algorithm may be coupled with a selection of local optimizers. These may be called during the iterations of the heuristic algorithm (the interior phase) to hasten the discovery of locally optimal points. They may also be called following the heuristic iterations (the exterior phase) to attempt to refine the final solution. Different options may be set for the local optimizer in each phase. For further details see Section in e05sa and e05sb.
These methods are most effectively used when multiple cores are available for computation, since very many function evaluations are required for a typical problem. In implementations of the NAG Library for SMP & Multicore the algorithm has been parallelized to allow for high levels of asynchronicity between threads. This allows individual threads to continue searching without the requirement for all threads to have returned solutions, and leads to excellent parallel speedup.

Multiple Start

Method e05uc attempts to find the global minimum of an arbitrary smooth function subject to constraints (which may include simple bounds on the variables, linear constraints and smooth nonlinear constraints) by generating a number of different starting points and using the local minimizer (E04UCA not in this release). Method e05us takes the same approach in attempting to find the global minimum of an arbitrary smooth sum of squares function using the local minimizer (E04USA not in this release).
The more starting points chosen, the greater the degree of confidence that you might have in the returned results. Facilities are provided to allow you to specify the starting points and to provide for subsequent runs with different starting points as an additional means of gaining confidence in the results.
You may also request that a number of solutions be provided, ordered in increasing value of the local optima. This may be useful if a local solution has a desirable property not exhibited by the best local optimum computed, the putative global optimum.

Recommendations on Choice and Use of Available Methods

The suite of multi-level coordinate search methods consists of:
  • an initialization method:
    • (E05JAF not in this release);
  • optional parameter setting methods:
    • (E05JCF not in this release),
    • (E05JDF not in this release),
    • (E05JEF not in this release),
    • (E05JFF not in this release),
    • (E05JGF not in this release);
  • an optional parameter checking method:
    • (E05JHF not in this release);
  • optional parameter getting methods:
    • (E05JKF not in this release),
    • (E05JLF not in this release);
  • and the solver:
    • e05jb.
e05jb is based on the multi-level coordinate search method of Huyer and Neumaier (1999). It is an asymptotically complete method for bound constrained problems based on local information (function values) only, employing branching and local searches to accelerate convergence.
If the problem has nonlinear constraints and is sufficiently smooth then you are advised to consider a multiple start technique. e05uc and e05us are provided for this purpose. Both e05uc and e05us use the methods (E05ZKF not in this release) (E05ZLF not in this release) for initialization and option setting.
The suite of particle swarm optimization (PSO) methods are to be considered as experimental and are not recommended for production or mission-critical applications. They are only recommended as a last resort (should other methods fail) or for comparitive purposes.
The suite consists of the solver methods:
  • (E05SAF not in this release);
  • (E05SBF not in this release).
Both (E05SAF not in this release) (E05SBF not in this release) use the methods (E05ZKF not in this release) (E05ZLF not in this release) for initialization and option setting. These methods predominantly use function values only, although derivatives can be provided for coupled local minimization methods. They are designed for use primarily with implementations of the NAG Library for SMP & Multicore (although they may also be used in serial implementations). In such implementations, a minimal knowledge of OpenMP parallel programming is required, specifically the use of basic OpenMP commands and operators such as OMP_GET_THREAD_NUM and CRITICAL sections to ensure the thread safety of provided callback routines. Additional example programs are provided to demonstrate how this may be done (see Section in e05sa and e05sb).
(E05SAF not in this release) is a simplified version of (E05SBF not in this release) with less functionality. In particular, (E05SAF not in this release) does not support general constraint handling whereas (E05SBF not in this release) does support general nonlinear, non-equality constraints.
If the objective function is smooth and the problem has only simple bound constraints then all algorithms are applicable. For low dimensional problems (up to 20) e05jb is preferred. With increasing dimension the multi-start methods may be better.
The particle swarm methods are potentially useful when there is no smoothness in the objective function (e.g., due to noise) and, for the simple-bound constrained problem, (E05SAF not in this release) may be appropriate.
Currently there is no routine in this chapter using a complete method that can handle constraints that are not bound constraints.

References

Gill P E, Murray W and Wright M H (1981) Practical Optimization Academic Press
Huyer W and Neumaier A (1999) Global optimization by multi-level coordinate search Journal of Global Optimization 14 331–355
Kennedy J and Eberhart R C (1995) Particle Swarm Optimization Proceedings of the 1995 IEEE International Conference on Neural Networks 1942–1948
Koh B, George A D, Haftka R T and Fregly B J (2006) Parallel Asynchronous Particle Swarm Optimization International Journal for Numerical Methods in Engineering 67(4) 578–595
Neumaier A (2004) Complete search in constrained global optimization Acta Numerica 13 271–369
Vaz A I and Vicente L N (2007) A Particle Swarm Pattern Search Method for Bound Constrained Global Optimization Journal of Global Optimization 39(2) 197–219 Kluwer Academic Publishers

Inheritance Hierarchy

System..::..Object
NagLibrary..::..E05

See Also

E05 Members


E05 Members

[image] [image]

NAG Library for .NET Release 2
E05 Members
E05 Class Methods See Also Send Feedback

The E05 type exposes the following members.

Methods

Name | Description
e05jb | e05jb is designed to find the global minimum or maximum of an arbitrary function, subject to simple bound-constraints using a multi-level coordinate search method. Derivatives are not required, but convergence is only guaranteed if the objective function is continuous in a neighbourhood of a global optimum. It is not intended for large problems. The initialization method (E05JAF not in this release) must have been called before calling e05jb.
e05jbk | Auxiliary for use as a delegate parameter
e05uc | e05uc is designed to find the global minimum of an arbitrary smooth function subject to constraints (which may include simple bounds on the variables, linear constraints and smooth nonlinear constraints) by generating a number of different starting points and performing a local search from each using sequential quadratic programming.
e05ucz | Auxiliary for use as a delegate parameter
e05us | e05us is designed to find the global minimum of an arbitrary smooth sum of squares function subject to constraints (which may include simple bounds on the variables, linear constraints and smooth nonlinear constraints) by generating a number of different starting points and performing a local search from each using sequential quadratic programming.

See Also

E05 Class


E05 Delegates

[image]

NAG Library for .NET Release 2
E05 Delegates

E05 Delegate Types

  • E05.E05JB_MONIT Delegate
  • E05.E05JB_OBJFUN Delegate
  • E05.E05UC_CONFUN Delegate
  • E05.E05UC_OBJFUN Delegate
  • E05.E05UC_START Delegate
  • E05.E05US_CONFUN Delegate
  • E05.E05US_OBJFUN Delegate
  • E05.E05US_START Delegate


E05.E05JB_MONIT Delegate

[image]

NAG Library for .NET Release 2
E05..::..E05JB_MONIT Delegate
E05 Class See Also Send Feedback
monit may be used to monitor the optimization process. It is invoked upon every successful completion of the procedure in which a sub-box is considered for splitting. It will also be called just before e05jb exits if that splitting procedure was not successful.
If no monitoring is required, monit may be the dummy monitoring method E05JBK supplied by the NAG Library.

Syntax

C#
public delegate void E05JB_MONIT(
    int n,
    int ncall,
    double[] xbest,
    int[] icount,
    double[,] list,
    int[] numpts,
    int[] initpt,
    int nbaskt,
    double[,] xbaskt,
    double[] boxl,
    double[] boxu,
    int nstate,
    out int inform
)
Visual Basic
Public Delegate Sub E05JB_MONIT ( _
    n As Integer, _
    ncall As Integer, _
    xbest As Double(), _
    icount As Integer(), _
    list As Double(,), _
    numpts As Integer(), _
    initpt As Integer(), _
    nbaskt As Integer, _
    xbaskt As Double(,), _
    boxl As Double(), _
    boxu As Double(), _
    nstate As Integer, _
    <OutAttribute> ByRef inform As Integer _
)
Visual C++
public delegate void E05JB_MONIT(
    int n,
    int ncall,
    array<double>^ xbest,
    array<int>^ icount,
    array<double,2>^ list,
    array<int>^ numpts,
    array<int>^ initpt,
    int nbaskt,
    array<double,2>^ xbaskt,
    array<double>^ boxl,
    array<double>^ boxu,
    int nstate,
    [OutAttribute] int% inform
)
F#
type E05JB_MONIT =
    delegate of
        n : int *
        ncall : int *
        xbest : float[] *
        icount : int[] *
        list : float[,] *
        numpts : int[] *
        initpt : int[] *
        nbaskt : int *
        xbaskt : float[,] *
        boxl : float[] *
        boxu : float[] *
        nstate : int *
        inform : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of variables.
ncall
Type: System..::..Int32
On entry: the cumulative number of calls to objfun.
xbest
Type: array< System..::..Double >[]()[][]
On entry: the current best point.
icount
Type: array< System..::..Int32 >[]()[][]
On entry: an array of counters.
icount[0]
nboxes, the current number of sub-boxes.
icount[1]
ncloc, the cumulative number of calls to objfun made in local searches.
icount[2]
nloc, the cumulative number of points used as start points for local searches.
icount[3]
nsweep, the cumulative number of sweeps through levels.
icount[4]
m, the cumulative number of splits by initialization list.
icount[5]
s, the current lowest level containing non-split boxes.
list
Type: array< System..::..Double ,2>[,](,)[,][,]
On entry: the initialization list.
numpts
Type: array< System..::..Int32 >[]()[][]
On entry: the number of points in each coordinate at which to split according to the initialization list list.
initpt
Type: array< System..::..Int32 >[]()[][]
On entry: a pointer to the ‘initial point’ in list. Element initpt[i-1] is the column index in list of the ith coordinate of the initial point.
nbaskt
Type: System..::..Int32
On entry: the number of points in the ‘shopping basket’ xbaskt.
xbaskt
Type: array< System..::..Double ,2>[,](,)[,][,]
Note: the jth candidate minimum has its ith coordinate stored in xbaskt[j-1,i-1], for i=1,2,…,n and j=1,2,…,nbaskt.
On entry: the ‘shopping basket’ of candidate minima.
boxl
Type: array< System..::..Double >[]()[][]
On entry: the array of lower bounds of the current search box.
boxu
Type: array< System..::..Double >[]()[][]
On entry: the array of upper bounds of the current search box.
nstate
Type: System..::..Int32
On entry: is set by e05jb to indicate at what stage of the minimization monit was called.
nstate=1
This is the first time that monit has been called.
nstate=-1
This is the last time monit will be called.
nstate=0
This is the first and last time monit will be called.
inform
Type: System..::..Int32 %
On exit: must be set to a value describing the action to be taken by the solver on return from monit. Specifically, if the value is negative the solution of the current problem will terminate immediately; otherwise, computations will continue.

See Also

NagLibrary Namespace
NAG Library Overview
e05jb


E05.E05JB_OBJFUN Delegate

[image]

NAG Library for .NET Release 2
E05..::..E05JB_OBJFUN Delegate
E05 Class See Also Send Feedback
objfun must evaluate the objective function F x for a specified n-vector x.

Syntax

C#
public delegate void E05JB_OBJFUN(
    int n,
    double[] x,
    out double f,
    int nstate,
    out int inform
)
Visual Basic
Public Delegate Sub E05JB_OBJFUN ( _
    n As Integer, _
    x As Double(), _
    <OutAttribute> ByRef f As Double, _
    nstate As Integer, _
    <OutAttribute> ByRef inform As Integer _
)
Visual C++
public delegate void E05JB_OBJFUN(
    int n,
    array<double>^ x,
    [OutAttribute] double% f,
    int nstate,
    [OutAttribute] int% inform
)
F#
type E05JB_OBJFUN =
    delegate of
        n : int *
        x : float[] *
        f : float byref *
        nstate : int *
        inform : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of variables.
x
Type: array< System..::..Double >[]()[][]
On entry: x, the vector at which the objective function is to be evaluated.
f
Type: System..::..Double %
On exit: must be set to the value of the objective function at x, unless you have specified termination of the current problem using inform.
nstate
Type: System..::..Int32
On entry: if nstate=1 then e05jb is calling objfun for the first time. This parameter setting allows you to save computation time if certain data must be read or calculated only once.
inform
Type: System..::..Int32 %
On exit: must be set to a value describing the action to be taken by the solver on return from objfun. Specifically, if the value is negative the solution of the current problem will terminate immediately; otherwise, computations will continue.

See Also

NagLibrary Namespace
NAG Library Overview
e05jb


E05.E05UC_CONFUN Delegate

[image]

NAG Library for .NET Release 2
E05..::..E05UC_CONFUN Delegate
E05 Class See Also Send Feedback
confun must calculate the vector c x of nonlinear constraint functions and (optionally) its Jacobian (=∂c∂x) for a specified n-element vector x. If there are no nonlinear constraints (i.e., ncnln=0), confun will never be called by e05uc and confun may be the dummy method E04UDM. (E04UDM is included in the NAG Library.) If there are nonlinear constraints, the first call to confun will occur before the first call to objfun.

Syntax

C#
public delegate void E05UC_CONFUN(
    ref int mode,
    int ncnln,
    int n,
    int[] needc,
    double[] x,
    double[] c,
    double[,] cjsl,
    int nstate
)
Visual Basic
Public Delegate Sub E05UC_CONFUN ( _
    ByRef mode As Integer, _
    ncnln As Integer, _
    n As Integer, _
    needc As Integer(), _
    x As Double(), _
    c As Double(), _
    cjsl As Double(,), _
    nstate As Integer _
)
Visual C++
public delegate void E05UC_CONFUN(
    int% mode,
    int ncnln,
    int n,
    array<int>^ needc,
    array<double>^ x,
    array<double>^ c,
    array<double,2>^ cjsl,
    int nstate
)
F#
type E05UC_CONFUN =
    delegate of
        mode : int byref *
        ncnln : int *
        n : int *
        needc : int[] *
        x : float[] *
        c : float[] *
        cjsl : float[,] *
        nstate : int -> unit

Parameters

mode
Type: System..::..Int32 %
On entry: indicates which values must be assigned during each call of confun. Only the following values need be assigned, for each value of i such that needc[i-1]>0:
mode=0
c[i-1].
mode=1
All available elements in the ith row of cjsl.
mode=2
c[i-1] and all available elements in the ith row of cjsl.
On exit: may be set to a negative value if you wish to abandon the solution to the current local minimization problem. In this case e05uc will move to the next local minimization problem.
ncnln
Type: System..::..Int32
On entry: nN, the number of nonlinear constraints.
n
Type: System..::..Int32
On entry: n, the number of variables.
needc
Type: array< System..::..Int32 >[]()[][]
On entry: the indices of the elements of c and/or cjsl that must be evaluated by confun. If needc[i-1]>0, c[i-1] and/or the available elements of the ith row of cjsl (see parameter mode) must be evaluated at x.
x
Type: array< System..::..Double >[]()[][]
On entry: x, the vector of variables at which the constraint functions and/or the available elements of the constraint Jacobian are to be evaluated.
c
Type: array< System..::..Double >[]()[][]
On exit: if needc[k-1]>0 and mode=0 or 2, c[k-1] must contain the value of ck x. The remaining elements of c, corresponding to the non-positive elements of needc, need not be set.
cjsl
Type: array< System..::..Double ,2>[,](,)[,][,]
cjsl may be regarded as a two-dimensional ‘slice’ of the three-dimensional array cjac of e05uc.
On entry: unless Derivative Level=2 or 3 (the default setting is Derivative Level=3, the elements of cjsl are set to special values which enable e05uc to detect whether they are changed by confun.
On exit: if needc[k-1]>0 and mode=1 or 2, the kth row of cjsl must contain the available elements of the vector ∇ck given by
∇ck=∂ck∂x 1,∂ck∂x 2,…,∂ck∂xn T,
where ∂ck∂xj is the partial derivative of the kth constraint with respect to the jth variable, evaluated at the point x. See also the parameter nstate. The remaining rows of cjsl, corresponding to non-positive elements of needc, need not be set.
If all elements of the constraint Jacobian are known (i.e., Derivative Level=2 or 3), any constant elements may be assigned to cjsl one time only at the start of each local optimization. An element of cjsl that is not subsequently assigned in confun will retain its initial value throughout the local optimization. Constant elements may be loaded into cjsl during the first call to confun for the local optimization (signalled by the value nstate=1). The ability to preload constants is useful when many Jacobian elements are identically zero, in which case cjsl may be initialized to zero and nonzero elements may be reset by confun.
Note that constant nonzero elements do affect the values of the constraints. Thus, if cjsl[k-1,j-1] is set to a constant value, it need not be reset in subsequent calls to confun, but the value cjsl[k-1,j-1]×x[j-1] must nonetheless be added to c[k-1]. For example, if cjsl[0,0]=2 and cjsl[0,1]=-5 then the term 2×x[0]-5×x[1] must be included in the definition of c[0].
It must be emphasized that, if Derivative Level=0 or 1, unassigned elements of cjsl are not treated as constant; they are estimated by finite differences, at nontrivial expense. If you do not supply a value for the optional parameter Difference Interval, an interval for each element of x is computed automatically at the start of each local optimization. The automatic procedure can usually identify constant elements of cjsl, which are then computed once only by finite differences.
nstate
Type: System..::..Int32
On entry: if nstate=1 then e05uc is calling confun for the first time on the current local optimization problem. This parameter setting allows you to save computation time if certain data must be calculated only once.

See Also

NagLibrary Namespace
NAG Library Overview
e05uc


E05.E05UC_OBJFUN Delegate

[image]

NAG Library for .NET Release 2
E05..::..E05UC_OBJFUN Delegate
E05 Class See Also Send Feedback
objfun must calculate the objective function F x and (optionally) its gradient g x=∂F∂x for a specified n-vector x.

Syntax

C#
public delegate void E05UC_OBJFUN(
    ref int mode,
    int n,
    double[] x,
    ref double objf,
    double[] objgrd,
    int nstate
)
Visual Basic
Public Delegate Sub E05UC_OBJFUN ( _
    ByRef mode As Integer, _
    n As Integer, _
    x As Double(), _
    ByRef objf As Double, _
    objgrd As Double(), _
    nstate As Integer _
)
Visual C++
public delegate void E05UC_OBJFUN(
    int% mode,
    int n,
    array<double>^ x,
    double% objf,
    array<double>^ objgrd,
    int nstate
)
F#
type E05UC_OBJFUN =
    delegate of
        mode : int byref *
        n : int *
        x : float[] *
        objf : float byref *
        objgrd : float[] *
        nstate : int -> unit

Parameters

mode
Type: System..::..Int32 %
On entry: indicates which values must be assigned during each call of objfun. Only the following values need be assigned:
mode=0
objf.
mode=1
All available elements of objgrd.
mode=2
objf and all available elements of objgrd.
On exit: may be set to a negative value if you wish to abandon the solution to the current local minimization problem. In this case e05uc will move to the next local minimization problem.
n
Type: System..::..Int32
On entry: n, the number of variables.
x
Type: array< System..::..Double >[]()[][]
On entry: x, the vector of variables at which the objective function and/or all available elements of its gradient are to be evaluated.
objf
Type: System..::..Double %
On exit: if mode=0 or 2, objf must be set to the value of the objective function at x.
objgrd
Type: array< System..::..Double >[]()[][]
On entry: the elements of objgrd are set to special values which enable e05uc to detect whether they are changed by objfun.
On exit: if mode=1 or 2, objgrd must return the available elements of the gradient evaluated at x.
nstate
Type: System..::..Int32
On entry: if nstate=1 then e05uc is calling objfun for the first time on the current local optimization problem. This parameter setting allows you to save computation time if certain data must be calculated only once.

See Also

NagLibrary Namespace
NAG Library Overview
e05uc


E05.E05UC_START Delegate

[image]

NAG Library for .NET Release 2
E05..::..E05UC_START Delegate
E05 Class See Also Send Feedback
start must calculate the npts starting points to be used by the local optimizer. If you do not wish to write a method specific to your problem then E05UCZ may be used as the actual argument. E05UCZ is supplied in the NAG Library and uses the NAG quasi-random number generators to distribute starting points uniformly across the domain. It is affected by the value of repeat.

Syntax

C#
public delegate void E05UC_START(
    int npts,
    double[,] quas,
    int n,
    bool repeat,
    double[] bl,
    double[] bu,
    ref int mode
)
Visual Basic
Public Delegate Sub E05UC_START ( _
    npts As Integer, _
    quas As Double(,), _
    n As Integer, _
    repeat As Boolean, _
    bl As Double(), _
    bu As Double(), _
    ByRef mode As Integer _
)
Visual C++
public delegate void E05UC_START(
    int npts,
    array<double,2>^ quas,
    int n,
    bool repeat,
    array<double>^ bl,
    array<double>^ bu,
    int% mode
)
F#
type E05UC_START =
    delegate of
        npts : int *
        quas : float[,] *
        n : int *
        repeat : bool *
        bl : float[] *
        bu : float[] *
        mode : int byref -> unit

Parameters

npts
Type: System..::..Int32
On entry: indicates the number of starting points.
quas
Type: array< System..::..Double ,2>[,](,)[,][,]
On entry: all elements of quas will have been set to zero, so only nonzero values need be set subsequently.
On exit: must contain the starting points for the npts local minimizations, i.e., quas[j-1,i-1] must contain the jth component of the ith starting point.
n
Type: System..::..Int32
On entry: the number of variables.
repeat
Type: System..::..Boolean
On entry: specifies whether a repeatable or non-repeatable sequence of points are to be generated.
bl
Type: array< System..::..Double >[]()[][]
On entry: the lower bounds on the variables. These may be used to ensure that the starting points generated in some sense ‘cover’ the region, but there is no requirement that a starting point be feasible.
bu
Type: array< System..::..Double >[]()[][]
On entry: the upper bounds on the variables. (See bl.)
mode
Type: System..::..Int32 %
On entry: mode will contain 0.
On exit: if you set mode to a negative value then e05uc will terminate immediately with ifail=9.

See Also

NagLibrary Namespace
NAG Library Overview
e05uc


E05.E05US_CONFUN Delegate

[image]

NAG Library for .NET Release 2
E05..::..E05US_CONFUN Delegate
E05 Class See Also Send Feedback
confun must calculate the vector c x of nonlinear constraint functions and (optionally) its Jacobian (=∂c∂x) for a specified n-element vector x. If there are no nonlinear constraints (i.e., ncnln=0), confun will never be called by e05us and confun may be the dummy method E04UDM. (E04UDM is included in the NAG Library.) If there are nonlinear constraints, the first call to confun will occur before the first call to objfun.

Syntax

C#
public delegate void E05US_CONFUN(
    ref int mode,
    int ncnln,
    int n,
    int[] needc,
    double[] x,
    double[] c,
    double[,] cjsl,
    int nstate
)
Visual Basic
Public Delegate Sub E05US_CONFUN ( _
    ByRef mode As Integer, _
    ncnln As Integer, _
    n As Integer, _
    needc As Integer(), _
    x As Double(), _
    c As Double(), _
    cjsl As Double(,), _
    nstate As Integer _
)
Visual C++
public delegate void E05US_CONFUN(
    int% mode,
    int ncnln,
    int n,
    array<int>^ needc,
    array<double>^ x,
    array<double>^ c,
    array<double,2>^ cjsl,
    int nstate
)
F#
type E05US_CONFUN =
    delegate of
        mode : int byref *
        ncnln : int *
        n : int *
        needc : int[] *
        x : float[] *
        c : float[] *
        cjsl : float[,] *
        nstate : int -> unit

Parameters

mode
Type: System..::..Int32 %
On entry: indicates which values must be assigned during each call of confun. Only the following values need be assigned, for each value of i such that needc[i-1]>0:
mode=0
c[i-1], the ith nonlinear constraint.
mode=1
All available elements in the ith row of cjsl.
mode=2
c[i-1] and all available elements in the ith row of cjsl.
On exit: may be set to a negative value if you wish to abandon the solution to the current local minimization problem. In this case e05us will move to the next local minimization problem.
ncnln
Type: System..::..Int32
On entry: nN, the number of nonlinear constraints.
n
Type: System..::..Int32
On entry: n, the number of variables.
needc
Type: array< System..::..Int32 >[]()[][]
On entry: the indices of the elements of c and/or cjsl that must be evaluated by confun. If needc[i-1]>0, c[i-1] and/or the available elements of the ith row of cjsl (see parameter mode) must be evaluated at x.
x
Type: array< System..::..Double >[]()[][]
On entry: x, the vector of variables at which the constraint functions and/or the available elements of the constraint Jacobian are to be evaluated.
c
Type: array< System..::..Double >[]()[][]
On exit: if needc[i-1]>0 and mode=0 or 2, c[i-1] must contain the value of ci x. The remaining elements of c, corresponding to the non-positive elements of needc, need not be set.
cjsl
Type: array< System..::..Double ,2>[,](,)[,][,]
cjsl may be regarded as a two-dimensional ‘slice’ of the three-dimensional array cjac of e05us.
On entry: unless Derivative Level=2 or 3, the elements of cjsl are set to special values which enable e05us to detect whether they are changed by confun.
On exit: if needc[i-1]>0 and mode=1 or 2, the ith row of cjsl must contain the available elements of the vector ∇ci given by
∇ci=∂ci∂x 1,∂ci∂x 2,…,∂ci∂xn T,
where ∂ci∂xj is the partial derivative of the ith constraint with respect to the jth variable, evaluated at the point x. See also the parameter nstate. The remaining rows of cjsl, corresponding to non-positive elements of needc, need not be set.
If all elements of the constraint Jacobian are known (i.e., Derivative Level=2 or 3; note the default is Derivative Level=3), any constant elements may be assigned to cjsl one time only at the start of each local optimization. An element of cjsl that is not subsequently assigned in confun will retain its initial value throughout the local optimization. Constant elements may be loaded into cjsl during the first call to confun for the local optimization (signalled by the value nstate=1). The ability to preload constants is useful when many Jacobian elements are identically zero, in which case cjsl may be initialized to zero and nonzero elements may be reset by confun.
Note that constant nonzero elements do affect the values of the constraints. Thus, if cjsl[i-1,j-1] is set to a constant value, it need not be reset in subsequent calls to confun, but the value cjsl[i-1,j-1]×x[j-1] must nonetheless be added to c[i-1]. For example, if cjsl[0,0]=2 and cjsl[0,1]=-5 then the term 2×x[0]-5×x[1] must be included in the definition of c[0].
It must be emphasized that, if Derivative Level=0 or 1, unassigned elements of cjsl are not treated as constant; they are estimated by finite differences, at nontrivial expense. If you do not supply a value for the optional parameter Difference Interval, an interval for each element of x is computed automatically at the start of each local optimization. The automatic procedure can usually identify constant elements of cjsl, which are then computed once only by finite differences.
nstate
Type: System..::..Int32
On entry: if nstate=1 then e05us is calling confun for the first time on the current local optimization problem. This parameter setting allows you to save computation time if certain data must be read or calculated only once.

See Also

NagLibrary Namespace
NAG Library Overview
e05us


E05.E05US_OBJFUN Delegate

[image]

NAG Library for .NET Release 2
E05..::..E05US_OBJFUN Delegate
E05 Class See Also Send Feedback
objfun must calculate either the ith element of the vector f x=f 1 x,f 2 x,…,fm x T or all m elements of f x and (optionally) its Jacobian (=∂f∂x) for a specified n-element vector x.

Syntax

C#
public delegate void E05US_OBJFUN(
    ref int mode,
    int m,
    int n,
    int needfi,
    double[] x,
    double[] f,
    double[,] fjsl,
    int nstate
)
Visual Basic
Public Delegate Sub E05US_OBJFUN ( _
    ByRef mode As Integer, _
    m As Integer, _
    n As Integer, _
    needfi As Integer, _
    x As Double(), _
    f As Double(), _
    fjsl As Double(,), _
    nstate As Integer _
)
Visual C++
public delegate void E05US_OBJFUN(
    int% mode,
    int m,
    int n,
    int needfi,
    array<double>^ x,
    array<double>^ f,
    array<double,2>^ fjsl,
    int nstate
)
F#
type E05US_OBJFUN =
    delegate of
        mode : int byref *
        m : int *
        n : int *
        needfi : int *
        x : float[] *
        f : float[] *
        fjsl : float[,] *
        nstate : int -> unit

Parameters

mode
Type: System..::..Int32 %
On entry: indicates which values must be assigned during each call of objfun. Only the following values need be assigned:
mode=0 and needfi=i, where i>0
f[i-1].
mode=0 and needfi<0
f.
mode=1 and needfi<0
All available elements of fjsl.
mode=2 and needfi<0
f and all available elements of fjsl.
On exit: may be set to a negative value if you wish to abandon the solution to the current local minimization problem. In this case e05us will move to the next local minimization problem.
m
Type: System..::..Int32
On entry: m, the number of subfunctions.
n
Type: System..::..Int32
On entry: n, the number of variables.
needfi
Type: System..::..Int32
On entry: if needfi=i>0, only the ith element of f x needs to be evaluated at x; the remaining elements need not be set. This can result in significant computational savings when m≫n.
x
Type: array< System..::..Double >[]()[][]
On entry: x, the vector of variables at which the objective function and/or all available elements of its gradient are to be evaluated.
f
Type: array< System..::..Double >[]()[][]
On exit: if mode=0 and needfi=i>0, f[i-1] must contain the value of fi at x.
If mode=0 or 2 and needfi<0, f[i-1] must contain the value of fi at x, for i=1,2,…,m.
fjsl
Type: array< System..::..Double ,2>[,](,)[,][,]
fjsl may be regarded as a two-dimensional ‘slice’ of the three-dimensional array fjac of e05us.
On entry: is set to a special value.
On exit: if mode=1 or 2 and needfi<0, the ith row of fjsl must contain the available elements of the vector ∇fi given by
∇fi=∂fi/∂x 1,∂fi/∂x 2,…,∂fi/∂xn T,
evaluated at the point x. See also the parameter nstate.
nstate
Type: System..::..Int32
On entry: if nstate=1 then e05us is calling objfun for the first time on the current local optimization problem. This parameter setting allows you to save computation time if certain data must be read or calculated only once.

See Also

NagLibrary Namespace
NAG Library Overview
e05us


E05.E05US_START Delegate

[image]

NAG Library for .NET Release 2
E05..::..E05US_START Delegate
E05 Class See Also Send Feedback
start must calculate the npts starting points to be used by the local optimizer. If you do not wish to write a method specific to your problem then E05UCZ may be used as the actual argument. E05UCZ is supplied in the NAG Library and uses the NAG quasi-random number generators to distribute starting points uniformly across the domain. It is affected by the value of repeat1.

Syntax

C#
public delegate void E05US_START(
    int npts,
    double[,] quas,
    int n,
    bool repeat1,
    double[] bl,
    double[] bu,
    ref int mode
)
Visual Basic
Public Delegate Sub E05US_START ( _
    npts As Integer, _
    quas As Double(,), _
    n As Integer, _
    repeat1 As Boolean, _
    bl As Double(), _
    bu As Double(), _
    ByRef mode As Integer _
)
Visual C++
public delegate void E05US_START(
    int npts,
    array<double,2>^ quas,
    int n,
    bool repeat1,
    array<double>^ bl,
    array<double>^ bu,
    int% mode
)
F#
type E05US_START =
    delegate of
        npts : int *
        quas : float[,] *
        n : int *
        repeat1 : bool *
        bl : float[] *
        bu : float[] *
        mode : int byref -> unit

Parameters

npts
Type: System..::..Int32
On entry: indicates the number of starting points.
quas
Type: array< System..::..Double ,2>[,](,)[,][,]
On entry: all elements of quas will have been set to zero, so only nonzero values need be set subsequently.
On exit: must contain the starting points for the npts local minimizations, i.e., quas[j-1,i-1] must contain the jth component of the ith starting point.
n
Type: System..::..Int32
On entry: the number of variables.
repeat1
Type: System..::..Boolean
On entry: specifies whether a repeatable or non-repeatable sequence of points are to be generated.
bl
Type: array< System..::..Double >[]()[][]
On entry: the lower bounds on the variables. These may be used to ensure that the starting points generated in some sense ‘cover’ the region, but there is no requirement that a starting point be feasible.
bu
Type: array< System..::..Double >[]()[][]
On entry: the upper bounds on the variables. (See bl.)
mode
Type: System..::..Int32 %
On entry: mode will contain 0.
On exit: if you set mode to a negative value then e05us will terminate immediately with ifail=9.

See Also

NagLibrary Namespace
NAG Library Overview
e05us


E05 Classes

[image]

NAG Library for .NET Release 2
E05 Classes

E05 Classes

  • E05.e05jbOptions Class
  • E05.e05ucOptions Class
  • E05.e05usOptions Class


E05.e05jbOptions Class

[image]

NAG Library for .NET Release 2
E05..::..e05jbOptions Class
E05 Class Members See Also Send Feedback
Options Class for e05jb

Syntax

C#
public class e05jbOptions
Visual Basic
Public Class e05jbOptions
Visual C++
public ref class e05jbOptions
F#
type e05jbOptions =  class end

Description of the Optional Parameters

For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
  • a parameter value, where the letters a, i​ and ​r denote options that take character, integer and real values respectively, and where the letter a denotes an option that takes an ON or OFF value;
  • the default value, where the symbol ε is a generic notation for machine precision (see x02aj), the symbol rmax stands for the largest positive model number (see x02al), nr represents the number of non-fixed variables, and the symbol d stands for the maximum number of decimal digits that can be represented (see x02be).
Option names are case-insensitive and must be provided in full; abbreviations are not recognized.
Defaults
This special keyword is used to reset all optional parameters to their default values, and any random state stored in the array comm will be destroyed.
Any option value given with this keyword will be ignored. This optional parameter cannot be queried or got.
Function Evaluations Limit
This puts an approximate limit on the number of function calls allowed. The total number of calls made is checked at the top of an internal iteration loop, so it is possible that a few calls more than nf may be made.
Constraint: nf>0.
Infinite Bound Size
This defines the ‘infinite’ bound infbnd in the definition of the problem constraints. Any upper bound greater than or equal to infbnd will be regarded as ∞ (and similarly any lower bound less than or equal to -infbnd will be regarded as -∞).
Constraint: rmax 14≤infbnd≤rmax 12.
Local Searches
If you want to try to accelerate convergence of e05jb by starting local searches from candidate minima, you will require lcsrch to be ON.
Constraint: lcsrch=ON​ or ​OFF.
Local Searches Limit
This defines the maximal number of iterations to be used in the trust-region loop of the local-search procedure.
Constraint: loclim>0.
Local Searches Tolerance
The value of loctol is the multiplier used during local searches as a stopping criterion for when the approximated gradient is small, in the sense described in [Local Search].
Constraint: loctol≥2 ε.
Minimize
Maximize
These keywords specify the required direction of optimization. Any option value given with these keywords will be ignored.
Nolist
List
These options control the echoing of each optional parameter specification as it is supplied. List turns printing on, Nolist turns printing off. The output is sent to the current advisory message unit (as defined by (X04ABF not in this release)).
Any option value given with these keywords will be ignored. This optional parameter cannot be queried or got.
Repeatability
For use with random initialization lists (iinit=4). When set to ON, an internally-initialized random state is stored in the array comm for use in subsequent calls to e05jb.
Constraint: repeat=ON​ or ​OFF.
Splits Limit
Along with the initialization list list, this defines a limit on the number of times the root box will be split along any single coordinate direction. If Local Searches is OFF you may find the default value to be too small.
Constraint: smax>nr+2.
Static Limit
As the default termination criterion, computation stops when the best function value is static for stclim sweeps through levels. This parameter is ignored if you have specified a target value to reach in Target Objective Value.
Constraint: stclim>0.
Target Objective Error
If you have given a target objective value to reach in objval (the value of the optional parameter Target Objective Value), objerr sets your desired relative error (from above if Minimize is set, from below if Maximize is set) between obj and objval, as described in [Accuracy]. See also the description of the optional parameter Target Objective Safeguard.
Constraint: objerr≥2 ε.
Target Objective Safeguard
If you have given a target objective value to reach in objval (the value of the optional parameter Target Objective Value), objsfg sets your desired safeguarded termination tolerance, for when objval is close to zero.
Constraint: objsfg≥2 ε.
Target Objective Value
This parameter may be set if you wish e05jb to use a specific value as the target function value to reach during the optimization. Setting objval overrides the default termination criterion determined by the optional parameter Static Limit.

Inheritance Hierarchy

System..::..Object
NagLibrary..::..E05..::..e05jbOptions

See Also

E05..::..e05jbOptions Members
NagLibrary Namespace
NAG Library Overview
e05jb


E05.e05jbOptions Members

[image] [image]

NAG Library for .NET Release 2
E05..::..e05jbOptions Members
E05..::..e05jbOptions Class Constructors Methods Properties See Also Send Feedback

Global optimization involves finding the absolute maximum or minimum value of a function (the objective function) of several variables, possibly subject to restrictions (defined by a set of bounds or constraint functions) on the values of the variables. Such problems can be much harder to solve than local optimization problems (which are discussed in E04 class) because it is difficult to determine whether a potential optimum found is global, and because of the nonlocal methods required to avoid becoming trapped near local optima. Most optimization methods in the NAG Library are concerned with function minimization only, since the problem of maximizing a given objective function F is equivalent to minimizing -F. In e05jb, (E05SAF not in this release) and (E05SBF not in this release), you may specify whether you are solving a minimization or maximization problem; in the latter case, the required transformation of the objective function will be carried out automatically. In what follows we refer exclusively to minimization problems.
This introduction is a brief guide to the subject of global optimization, designed for the casual user. For further details you may find it beneficial to consult a more detailed text, such as Neumaier (2004). Furthermore, much of the material in the E04 class is relevant in this context also. In particular, it is strongly recommended that you read [] in the E04 class Chapter Introduction.

The E05..::..e05jbOptions type exposes the following members.

Constructors

Name | Description
E05..::..e05jbOptions | Constructor

Methods

Name | Description
Set | Overloaded.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e05jb.
Warning | Set the method used for logging any warning or error messages from e05jb.

See Also

E05..::..e05jbOptions Class


E05.e05jbOptions Constructor

[image]

NAG Library for .NET Release 2
E05..::..e05jbOptions Constructor
E05..::..e05jbOptions Class See Also Send Feedback
Constructor

Syntax

C#
public e05jbOptions()
Visual Basic
Public Sub New
Visual C++
public:
e05jbOptions()
F#
new : unit -> e05jbOptions

See Also

E05..::..e05jbOptions Class
E05..::..e05jbOptions Members


E05.e05jbOptions Methods

[image] [image]

NAG Library for .NET Release 2
E05..::..e05jbOptions Methods
E05..::..e05jbOptions Class See Also Send Feedback

Methods

Name | Description
Set | Overloaded.

See Also

E05..::..e05jbOptions Class


Set Method

[image] [image]

NAG Library for .NET Release 2
E05..::..e05jbOptions..::Set Method
E05..::..e05jbOptions Class See Also Send Feedback

Overload List

Name | Description
Set(String) | Set an Option for e05jb
Set(DataReader) | Set Options for from a DataReader Stream.
Set(String, Double) | Set an Option for e05jb
Set(String, Int32) | Set an Option for e05jb
Set(String, String) | Set an Option for e05jb

See Also

E05..::..e05jbOptions Class
E05..::..e05jbOptions Members


Set Method (String)

[image]

NAG Library for .NET Release 2
E05..::..e05jbOptions..::Set Method (String)
E05..::..e05jbOptions Class See Also Send Feedback
Set an Option for e05jb

Syntax

C#
public void Set(
    string optstr
)
Visual Basic
Public Sub Set ( _
    optstr As String _
)
Visual C++
public:
void Set(
    String^ optstr
)
F#
member Set :
        optstr : string -> unit

Parameters

optstr
Type: System..::..String
A string of the form option = value, or for boolean options, simply option.

See Also

E05..::..e05jbOptions Class
E05..::..e05jbOptions Members
Set Overload


Set Method (DataReader)

[image]

NAG Library for .NET Release 2
E05..::..e05jbOptions..::Set Method (DataReader)
E05..::..e05jbOptions Class See Also Send Feedback
Set Options for from a DataReader Stream.

Syntax

C#
public void Set(
    DataReader sr
)
Visual Basic
Public Sub Set ( _
    sr As DataReader _
)
Visual C++
public:
void Set(
    DataReader^ sr
)
F#
member Set :
        sr : DataReader -> unit

Parameters

sr
Type: NagLibrary..::..DataReader
A DataReader Stream, containing an option setting on each line.

See Also

E05..::..e05jbOptions Class
E05..::..e05jbOptions Members
Set Overload


Set Method (String, Double)

[image]

NAG Library for .NET Release 2
E05..::..e05jbOptions..::Set Method (String, Double)
E05..::..e05jbOptions Class See Also Send Feedback
Set an Option for e05jb

Syntax

C#
public void Set(
    string optstr,
    double rvalue
)
Visual Basic
Public Sub Set ( _
    optstr As String, _
    rvalue As Double _
)
Visual C++
public:
void Set(
    String^ optstr,
    double rvalue
)
F#
member Set :
        optstr : string *
        rvalue : float -> unit

Parameters

optstr
Type: System..::..String
The name of an option.
rvalue
Type: System..::..Double
The option value.

See Also

E05..::..e05jbOptions Class
E05..::..e05jbOptions Members
Set Overload


Set Method (String, Int32)

[image]

NAG Library for .NET Release 2
E05..::..e05jbOptions..::Set Method (String, Int32)
E05..::..e05jbOptions Class See Also Send Feedback
Set an Option for e05jb

Syntax

C#
public void Set(
    string optstr,
    int ivalue
)
Visual Basic
Public Sub Set ( _
    optstr As String, _
    ivalue As Integer _
)
Visual C++
public:
void Set(
    String^ optstr,
    int ivalue
)
F#
member Set :
        optstr : string *
        ivalue : int -> unit

Parameters

optstr
Type: System..::..String
The name of an option.
ivalue
Type: System..::..Int32
The option value.

See Also

E05..::..e05jbOptions Class
E05..::..e05jbOptions Members
Set Overload


Set Method (String, String)

[image]

NAG Library for .NET Release 2
E05..::..e05jbOptions..::Set Method (String, String)
E05..::..e05jbOptions Class See Also Send Feedback
Set an Option for e05jb

Syntax

C#
public void Set(
    string optstr,
    string cvalue
)
Visual Basic
Public Sub Set ( _
    optstr As String, _
    cvalue As String _
)
Visual C++
public:
void Set(
    String^ optstr,
    String^ cvalue
)
F#
member Set :
        optstr : string *
        cvalue : string -> unit

Parameters

optstr
Type: System..::..String
The name of an option.
cvalue
Type: System..::..String
The option value.

See Also

E05..::..e05jbOptions Class
E05..::..e05jbOptions Members
Set Overload


E05.e05jbOptions Properties

[image] [image]

NAG Library for .NET Release 2
E05..::..e05jbOptions Properties
E05..::..e05jbOptions Class See Also Send Feedback

The E05..::..e05jbOptions type exposes the following members.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e05jb.
Warning | Set the method used for logging any warning or error messages from e05jb.

See Also

E05..::..e05jbOptions Class


Message Property

[image]

NAG Library for .NET Release 2
E05..::..e05jbOptions..::Message Property
E05..::..e05jbOptions Class See Also Send Feedback
Set the method used for logging any monitoring messages from e05jb.

Syntax

C#
public PrintManager..::..MessageLogger Message { get; set; }
Visual Basic
Public Property Message As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Message {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Message : PrintManager..::..MessageLogger with get, set

See Also

E05..::..e05jbOptions Class
E05..::..e05jbOptions Members


Warning Property

[image]

NAG Library for .NET Release 2
E05..::..e05jbOptions..::Warning Property
E05..::..e05jbOptions Class See Also Send Feedback
Set the method used for logging any warning or error messages from e05jb.

Syntax

C#
public PrintManager..::..MessageLogger Warning { get; set; }
Visual Basic
Public Property Warning As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Warning {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Warning : PrintManager..::..MessageLogger with get, set

See Also

E05..::..e05jbOptions Class
E05..::..e05jbOptions Members


E05.e05ucOptions Class

[image]

NAG Library for .NET Release 2
E05..::..e05ucOptions Class
E05 Class Members See Also Send Feedback
Options Class for e05uc

Syntax

C#
public class e05ucOptions
Visual Basic
Public Class e05ucOptions
Visual C++
public ref class e05ucOptions
F#
type e05ucOptions =  class end

Description of the Optional Parameters

e05uc supports two options that are distinct from those of e04uc:
Punch Unit
This option allows you to send information arising from an appropriate setting of Out_Level to be sent to the Fortran unit number defined by Punch Unit. If you wish this file to be different to the standard output unit (6) where other output is displayed then this file should be attached by calling (X04ACF not in this release) prior to calling e05uc.
Out_Level
This option defines the amount of extra information to be sent to the Fortran unit number defined by Punch Unit. The possible choices for i are the following:
i | Meaning
0 | No extra output.
1 | Updated solutions only. This is useful during long runs to observe progress.
2 | Successful start points only. This is useful to save the starting points that gave rise to the final solution.
3 | Both updated solutions and successful start points.
See [Optional Parameters] in e04uc for details of the other options.
The Warm Start option of e04uc is not a valid option for use with e05uc.

Inheritance Hierarchy

System..::..Object
NagLibrary..::..E05..::..e05ucOptions

See Also

E05..::..e05ucOptions Members
NagLibrary Namespace
NAG Library Overview
e05uc


E05.e05ucOptions Members

[image] [image]

NAG Library for .NET Release 2
E05..::..e05ucOptions Members
E05..::..e05ucOptions Class Constructors Methods Properties See Also Send Feedback

Global optimization involves finding the absolute maximum or minimum value of a function (the objective function) of several variables, possibly subject to restrictions (defined by a set of bounds or constraint functions) on the values of the variables. Such problems can be much harder to solve than local optimization problems (which are discussed in E04 class) because it is difficult to determine whether a potential optimum found is global, and because of the nonlocal methods required to avoid becoming trapped near local optima. Most optimization methods in the NAG Library are concerned with function minimization only, since the problem of maximizing a given objective function F is equivalent to minimizing -F. In e05jb, (E05SAF not in this release) and (E05SBF not in this release), you may specify whether you are solving a minimization or maximization problem; in the latter case, the required transformation of the objective function will be carried out automatically. In what follows we refer exclusively to minimization problems.
This introduction is a brief guide to the subject of global optimization, designed for the casual user. For further details you may find it beneficial to consult a more detailed text, such as Neumaier (2004). Furthermore, much of the material in the E04 class is relevant in this context also. In particular, it is strongly recommended that you read [] in the E04 class Chapter Introduction.

The E05..::..e05ucOptions type exposes the following members.

Constructors

Name | Description
E05..::..e05ucOptions | Constructor

Methods

Name | Description
Get | Overloaded.
Set | Overloaded.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e05uc.
Warning | Set the method used for logging any warning or error messages from e05uc.

See Also

E05..::..e05ucOptions Class


E05.e05ucOptions Constructor

[image]

NAG Library for .NET Release 2
E05..::..e05ucOptions Constructor
E05..::..e05ucOptions Class See Also Send Feedback
Constructor

Syntax

C#
public e05ucOptions()
Visual Basic
Public Sub New
Visual C++
public:
e05ucOptions()
F#
new : unit -> e05ucOptions

See Also

E05..::..e05ucOptions Class
E05..::..e05ucOptions Members


E05.e05ucOptions Methods

[image] [image]

NAG Library for .NET Release 2
E05..::..e05ucOptions Methods
E05..::..e05ucOptions Class See Also Send Feedback

Methods

Name | Description
Get | Overloaded.
Set | Overloaded.

See Also

E05..::..e05ucOptions Class


Get Method

[image] [image]

NAG Library for .NET Release 2
E05..::..e05ucOptions..::Get Method
E05..::..e05ucOptions Class See Also Send Feedback

Overload List

Name | Description
Get(String, Double) | Get an Option value for e05uc
Get(String, Int32%) | Get an Option value for e05uc
Get(String, String%) | Get an Option value for e05uc

See Also

E05..::..e05ucOptions Class
E05..::..e05ucOptions Members


Get Method (String, Double)

[image]

NAG Library for .NET Release 2
E05..::..e05ucOptions..::Get Method (String, Double)
E05..::..e05ucOptions Class See Also Send Feedback
Get an Option value for e05uc

Syntax

C#
public void Get(
    string optstr,
    double rvalue
)
Visual Basic
Public Sub Get ( _
    optstr As String, _
    rvalue As Double _
)
Visual C++
public:
void Get(
    String^ optstr,
    double rvalue
)
F#
member Get :
        optstr : string *
        rvalue : float -> unit

Parameters

optstr
Type: System..::..String
The name of an option.
rvalue
Type: System..::..Double
The option value.

See Also

E05..::..e05ucOptions Class
E05..::..e05ucOptions Members
Get Overload


Get Method (String, Int32)

[image]

NAG Library for .NET Release 2
E05..::..e05ucOptions..::Get Method (String, Int32%)
E05..::..e05ucOptions Class See Also Send Feedback
Get an Option value for e05uc

Syntax

C#
public void Get(
    string optstr,
    out int ivalue
)
Visual Basic
Public Sub Get ( _
    optstr As String, _
    <OutAttribute> ByRef ivalue As Integer _
)
Visual C++
public:
void Get(
    String^ optstr,
    [OutAttribute] int% ivalue
)
F#
member Get :
        optstr : string *
        ivalue : int byref -> unit

Parameters

optstr
Type: System..::..String
The name of an option.
ivalue
Type: System..::..Int32 %
The option value.

See Also

E05..::..e05ucOptions Class
E05..::..e05ucOptions Members
Get Overload


Get Method (String, String)

[image]

NAG Library for .NET Release 2
E05..::..e05ucOptions..::Get Method (String, String%)
E05..::..e05ucOptions Class See Also Send Feedback
Get an Option value for e05uc

Syntax

C#
public void Get(
    string optstr,
    ref string cvalue
)
Visual Basic
Public Sub Get ( _
    optstr As String, _
    ByRef cvalue As String _
)
Visual C++
public:
void Get(
    String^ optstr,
    String^% cvalue
)
F#
member Get :
        optstr : string *
        cvalue : string byref -> unit

Parameters

optstr
Type: System..::..String
The name of an option.
cvalue
Type: System..::..String %
The option value.

See Also

E05..::..e05ucOptions Class
E05..::..e05ucOptions Members
Get Overload


Set Method

[image] [image]

NAG Library for .NET Release 2
E05..::..e05ucOptions..::Set Method
E05..::..e05ucOptions Class See Also Send Feedback

Overload List

Name | Description
Set(String) | Set an Option for e05uc
Set(DataReader) | Set Options for from a DataReader Stream.

See Also

E05..::..e05ucOptions Class
E05..::..e05ucOptions Members


Set Method (String)

[image]

NAG Library for .NET Release 2
E05..::..e05ucOptions..::Set Method (String)
E05..::..e05ucOptions Class See Also Send Feedback
Set an Option for e05uc

Syntax

C#
public void Set(
    string optstr
)
Visual Basic
Public Sub Set ( _
    optstr As String _
)
Visual C++
public:
void Set(
    String^ optstr
)
F#
member Set :
        optstr : string -> unit

Parameters

optstr
Type: System..::..String
A string of the form option = value, or for boolean options, simply option.

See Also

E05..::..e05ucOptions Class
E05..::..e05ucOptions Members
Set Overload


Set Method (DataReader)

[image]

NAG Library for .NET Release 2
E05..::..e05ucOptions..::Set Method (DataReader)
E05..::..e05ucOptions Class See Also Send Feedback
Set Options for from a DataReader Stream.

Syntax

C#
public void Set(
    DataReader sr
)
Visual Basic
Public Sub Set ( _
    sr As DataReader _
)
Visual C++
public:
void Set(
    DataReader^ sr
)
F#
member Set :
        sr : DataReader -> unit

Parameters

sr
Type: NagLibrary..::..DataReader
A DataReader Stream, containing an option setting on each line.

See Also

E05..::..e05ucOptions Class
E05..::..e05ucOptions Members
Set Overload


E05.e05ucOptions Properties

[image] [image]

NAG Library for .NET Release 2
E05..::..e05ucOptions Properties
E05..::..e05ucOptions Class See Also Send Feedback

The E05..::..e05ucOptions type exposes the following members.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e05uc.
Warning | Set the method used for logging any warning or error messages from e05uc.

See Also

E05..::..e05ucOptions Class


Message Property

[image]

NAG Library for .NET Release 2
E05..::..e05ucOptions..::Message Property
E05..::..e05ucOptions Class See Also Send Feedback
Set the method used for logging any monitoring messages from e05uc.

Syntax

C#
public PrintManager..::..MessageLogger Message { get; set; }
Visual Basic
Public Property Message As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Message {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Message : PrintManager..::..MessageLogger with get, set

See Also

E05..::..e05ucOptions Class
E05..::..e05ucOptions Members


Warning Property

[image]

NAG Library for .NET Release 2
E05..::..e05ucOptions..::Warning Property
E05..::..e05ucOptions Class See Also Send Feedback
Set the method used for logging any warning or error messages from e05uc.

Syntax

C#
public PrintManager..::..MessageLogger Warning { get; set; }
Visual Basic
Public Property Warning As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Warning {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Warning : PrintManager..::..MessageLogger with get, set

See Also

E05..::..e05ucOptions Class
E05..::..e05ucOptions Members


E05.e05usOptions Class

[image]

NAG Library for .NET Release 2
E05..::..e05usOptions Class
E05 Class Members See Also Send Feedback
Options Class for e05us

Syntax

C#
public class e05usOptions
Visual Basic
Public Class e05usOptions
Visual C++
public ref class e05usOptions
F#
type e05usOptions =  class end

Inheritance Hierarchy

System..::..Object
NagLibrary..::..E05..::..e05usOptions

See Also

E05..::..e05usOptions Members
NagLibrary Namespace
NAG Library Overview
e05us


E05.e05usOptions Members

[image] [image]

NAG Library for .NET Release 2
E05..::..e05usOptions Members
E05..::..e05usOptions Class Constructors Methods Properties See Also Send Feedback

Global optimization involves finding the absolute maximum or minimum value of a function (the objective function) of several variables, possibly subject to restrictions (defined by a set of bounds or constraint functions) on the values of the variables. Such problems can be much harder to solve than local optimization problems (which are discussed in E04 class) because it is difficult to determine whether a potential optimum found is global, and because of the nonlocal methods required to avoid becoming trapped near local optima. Most optimization methods in the NAG Library are concerned with function minimization only, since the problem of maximizing a given objective function F is equivalent to minimizing -F. In e05jb, (E05SAF not in this release) and (E05SBF not in this release), you may specify whether you are solving a minimization or maximization problem; in the latter case, the required transformation of the objective function will be carried out automatically. In what follows we refer exclusively to minimization problems.
This introduction is a brief guide to the subject of global optimization, designed for the casual user. For further details you may find it beneficial to consult a more detailed text, such as Neumaier (2004). Furthermore, much of the material in the E04 class is relevant in this context also. In particular, it is strongly recommended that you read [] in the E04 class Chapter Introduction.

The E05..::..e05usOptions type exposes the following members.

Constructors

Name | Description
E05..::..e05usOptions | Constructor

Methods

Name | Description
Get | Overloaded.
Set | Overloaded.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e05us.
Warning | Set the method used for logging any warning or error messages from e05us.

See Also

E05..::..e05usOptions Class


E05.e05usOptions Constructor

[image]

NAG Library for .NET Release 2
E05..::..e05usOptions Constructor
E05..::..e05usOptions Class See Also Send Feedback
Constructor

Syntax

C#
public e05usOptions()
Visual Basic
Public Sub New
Visual C++
public:
e05usOptions()
F#
new : unit -> e05usOptions

See Also

E05..::..e05usOptions Class
E05..::..e05usOptions Members


E05.e05usOptions Methods

[image] [image]

NAG Library for .NET Release 2
E05..::..e05usOptions Methods
E05..::..e05usOptions Class See Also Send Feedback

Methods

Name | Description
Get | Overloaded.
Set | Overloaded.

See Also

E05..::..e05usOptions Class


Get Method

[image] [image]

NAG Library for .NET Release 2
E05..::..e05usOptions..::Get Method
E05..::..e05usOptions Class See Also Send Feedback

Overload List

Name | Description
Get(String, Double) | Get an Option value for e05us
Get(String, Int32%) | Get an Option value for e05us
Get(String, String%) | Get an Option value for e05us

See Also

E05..::..e05usOptions Class
E05..::..e05usOptions Members


Get Method (String, Double)

[image]

NAG Library for .NET Release 2
E05..::..e05usOptions..::Get Method (String, Double)
E05..::..e05usOptions Class See Also Send Feedback
Get an Option value for e05us

Syntax

C#
public void Get(
    string optstr,
    double rvalue
)
Visual Basic
Public Sub Get ( _
    optstr As String, _
    rvalue As Double _
)
Visual C++
public:
void Get(
    String^ optstr,
    double rvalue
)
F#
member Get :
        optstr : string *
        rvalue : float -> unit

Parameters

optstr
Type: System..::..String
The name of an option.
rvalue
Type: System..::..Double
The option value.

See Also

E05..::..e05usOptions Class
E05..::..e05usOptions Members
Get Overload


Get Method (String, Int32)

[image]

NAG Library for .NET Release 2
E05..::..e05usOptions..::Get Method (String, Int32%)
E05..::..e05usOptions Class See Also Send Feedback
Get an Option value for e05us

Syntax

C#
public void Get(
    string optstr,
    out int ivalue
)
Visual Basic
Public Sub Get ( _
    optstr As String, _
    <OutAttribute> ByRef ivalue As Integer _
)
Visual C++
public:
void Get(
    String^ optstr,
    [OutAttribute] int% ivalue
)
F#
member Get :
        optstr : string *
        ivalue : int byref -> unit

Parameters

optstr
Type: System..::..String
The name of an option.
ivalue
Type: System..::..Int32 %
The option value.

See Also

E05..::..e05usOptions Class
E05..::..e05usOptions Members
Get Overload


Get Method (String, String)

[image]

NAG Library for .NET Release 2
E05..::..e05usOptions..::Get Method (String, String%)
E05..::..e05usOptions Class See Also Send Feedback
Get an Option value for e05us

Syntax

C#
public void Get(
    string optstr,
    ref string cvalue
)
Visual Basic
Public Sub Get ( _
    optstr As String, _
    ByRef cvalue As String _
)
Visual C++
public:
void Get(
    String^ optstr,
    String^% cvalue
)
F#
member Get :
        optstr : string *
        cvalue : string byref -> unit

Parameters

optstr
Type: System..::..String
The name of an option.
cvalue
Type: System..::..String %
The option value.

See Also

E05..::..e05usOptions Class
E05..::..e05usOptions Members
Get Overload


Set Method

[image] [image]

NAG Library for .NET Release 2
E05..::..e05usOptions..::Set Method
E05..::..e05usOptions Class See Also Send Feedback

Overload List

Name | Description
Set(String) | Set an Option for e05us
Set(DataReader) | Set Options for from a DataReader Stream.

See Also

E05..::..e05usOptions Class
E05..::..e05usOptions Members


Set Method (String)

[image]

NAG Library for .NET Release 2
E05..::..e05usOptions..::Set Method (String)
E05..::..e05usOptions Class See Also Send Feedback
Set an Option for e05us

Syntax

C#
public void Set(
    string optstr
)
Visual Basic
Public Sub Set ( _
    optstr As String _
)
Visual C++
public:
void Set(
    String^ optstr
)
F#
member Set :
        optstr : string -> unit

Parameters

optstr
Type: System..::..String
A string of the form option = value, or for boolean options, simply option.

See Also

E05..::..e05usOptions Class
E05..::..e05usOptions Members
Set Overload


Set Method (DataReader)

[image]

NAG Library for .NET Release 2
E05..::..e05usOptions..::Set Method (DataReader)
E05..::..e05usOptions Class See Also Send Feedback
Set Options for from a DataReader Stream.

Syntax

C#
public void Set(
    DataReader sr
)
Visual Basic
Public Sub Set ( _
    sr As DataReader _
)
Visual C++
public:
void Set(
    DataReader^ sr
)
F#
member Set :
        sr : DataReader -> unit

Parameters

sr
Type: NagLibrary..::..DataReader
A DataReader Stream, containing an option setting on each line.

See Also

E05..::..e05usOptions Class
E05..::..e05usOptions Members
Set Overload


E05.e05usOptions Properties

[image] [image]

NAG Library for .NET Release 2
E05..::..e05usOptions Properties
E05..::..e05usOptions Class See Also Send Feedback

The E05..::..e05usOptions type exposes the following members.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from e05us.
Warning | Set the method used for logging any warning or error messages from e05us.

See Also

E05..::..e05usOptions Class


Message Property

[image]

NAG Library for .NET Release 2
E05..::..e05usOptions..::Message Property
E05..::..e05usOptions Class See Also Send Feedback
Set the method used for logging any monitoring messages from e05us.

Syntax

C#
public PrintManager..::..MessageLogger Message { get; set; }
Visual Basic
Public Property Message As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Message {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Message : PrintManager..::..MessageLogger with get, set

See Also

E05..::..e05usOptions Class
E05..::..e05usOptions Members


Warning Property

[image]

NAG Library for .NET Release 2
E05..::..e05usOptions..::Warning Property
E05..::..e05usOptions Class See Also Send Feedback
Set the method used for logging any warning or error messages from e05us.

Syntax

C#
public PrintManager..::..MessageLogger Warning { get; set; }
Visual Basic
Public Property Warning As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Warning {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Warning : PrintManager..::..MessageLogger with get, set

See Also

E05..::..e05usOptions Class
E05..::..e05usOptions Members


E05 Methods

[image] [image]

NAG Library for .NET Release 2
E05 Methods
E05 Class See Also Send Feedback

The E05 type exposes the following members.

Methods

Name | Description
e05jb | e05jb is designed to find the global minimum or maximum of an arbitrary function, subject to simple bound-constraints using a multi-level coordinate search method. Derivatives are not required, but convergence is only guaranteed if the objective function is continuous in a neighbourhood of a global optimum. It is not intended for large problems. The initialization method (E05JAF not in this release) must have been called before calling e05jb.
e05jbk | Auxiliary for use as a delegate parameter
e05uc | e05uc is designed to find the global minimum of an arbitrary smooth function subject to constraints (which may include simple bounds on the variables, linear constraints and smooth nonlinear constraints) by generating a number of different starting points and performing a local search from each using sequential quadratic programming.
e05ucz | Auxiliary for use as a delegate parameter
e05us | e05us is designed to find the global minimum of an arbitrary smooth sum of squares function subject to constraints (which may include simple bounds on the variables, linear constraints and smooth nonlinear constraints) by generating a number of different starting points and performing a local search from each using sequential quadratic programming.

See Also

E05 Class


e05jb Method

[image]

NAG Library for .NET Release 2
E05..::e05jb Method
E05 Class See Also Send Feedback
e05jb is designed to find the global minimum or maximum of an arbitrary function, subject to simple bound-constraints using a multi-level coordinate search method. Derivatives are not required, but convergence is only guaranteed if the objective function is continuous in a neighbourhood of a global optimum. It is not intended for large problems.
The initialization method (E05JAF not in this release) must have been called before calling e05jb.

Syntax

C#
public static void e05jb(
    int n,
    E05..::..E05JB_OBJFUN objfun,
    int ibound,
    int iinit,
    double[] bl,
    double[] bu,
    double[,] list,
    int[] numpts,
    int[] initpt,
    E05..::..E05JB_MONIT monit,
    double[] x,
    out double obj,
    E05..::..e05jbOptions options,
    out int ifail
)
Visual Basic
Public Shared Sub e05jb ( _
    n As Integer, _
    objfun As E05..::..E05JB_OBJFUN, _
    ibound As Integer, _
    iinit As Integer, _
    bl As Double(), _
    bu As Double(), _
    list As Double(,), _
    numpts As Integer(), _
    initpt As Integer(), _
    monit As E05..::..E05JB_MONIT, _
    x As Double(), _
    <OutAttribute> ByRef obj As Double, _
    options As E05..::..e05jbOptions, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e05jb(
    int n,
    E05..::..E05JB_OBJFUN^ objfun,
    int ibound,
    int iinit,
    array<double>^ bl,
    array<double>^ bu,
    array<double,2>^ list,
    array<int>^ numpts,
    array<int>^ initpt,
    E05..::..E05JB_MONIT^ monit,
    array<double>^ x,
    [OutAttribute] double% obj,
    E05..::..e05jbOptions^ options,
    [OutAttribute] int% ifail
)
F#
static member e05jb :
        n : int *
        objfun : E05..::..E05JB_OBJFUN *
        ibound : int *
        iinit : int *
        bl : float[] *
        bu : float[] *
        list : float[,] *
        numpts : int[] *
        initpt : int[] *
        monit : E05..::..E05JB_MONIT *
        x : float[] *
        obj : float byref *
        options : E05..::..e05jbOptions *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of variables.
Constraint: n>0.
objfun
Type: NagLibrary..::..E05..::..E05JB_OBJFUN
objfun must evaluate the objective function F x for a specified n-vector x.

A delegate of type E05JB_OBJFUN.

ibound
Type: System..::..Int32
On entry: indicates whether the facility for dealing with bounds of special forms is to be used. ibound must be set to one of the following values.
ibound=0
You will supply ℓ and u individually.
ibound=1
There are no bounds on x.
ibound=2
There are semi-infinite bounds 0≤x.
ibound=3
There are constant bounds ℓ=ℓ 1 and u=u 1.
Note that it only makes sense to fix any components of x when ibound=0.
Constraint: ibound=0, 1, 2 or 3.
iinit
Type: System..::..Int32
On entry: selects which initialization method to use.
iinit=0
Simple initialization (boundary and midpoint), with
numpts[i-1]=3, initpt[i-1]=2 and
list[i-1,j-1]=bl[i-1],bl[i-1]+bu[i-1]/2,bu[i-1],
for i=1,2,…,n and j=1,2,3.
iinit=1
Simple initialization (off-boundary and midpoint), with
numpts[i-1]=3, initpt[i-1]=2 and
list[i-1,j-1]=5 bl[i-1]+bu[i-1]/6,bl[i-1]+bu[i-1]/2,bl[i-1]+5 bu[i-1]/6,
for i=1,2,…,n and j=1,2,3.
iinit=2
Initialization using linesearches.
iinit=3
You are providing your own initialization list.
iinit=4
Generate a random initialization list.
For more information on methods iinit=2, 3 or 4 see [Initialization and Sweeps].
If ‘infinite’ values (as determined by the value of the optional parameter Infinite Bound Size) are detected by e05jb when you are using a simple initialization method (iinit=0 or 1), a safeguarded initialization procedure will be attempted, to avoid overflow.
Suggested value: iinit=0
Constraint: iinit=0, 1, 2, 3 or 4.
bl
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: bl is ℓ, the array of lower bounds. bu is u, the array of upper bounds.
If ibound=0, you must set bl[i-1] to ℓi and bu[i-1] to ui, for i=1,2,…,n. If a particular xi is to be unbounded below, the corresponding bl[i-1] should be set to -infbnd, where infbnd is the value of the optional parameter Infinite Bound Size. Similarly, if a particular xi is to be unbounded above, the corresponding bu[i-1] should be set to infbnd.
If ibound=1 or 2, arrays bl and bu need not be set on input.
If ibound=3, you must set bl[0] to ℓ1 and bu[0] to u1. The remaining elements of bl and bu will then be populated by these initial values.
On exit: unless ifail=1 or 2 on exit, bl and bu are the actual arrays of bounds used by e05jb.
Constraints:
  • if ibound=0, bl[i-1]≤bu[i-1], for i=1,2,…,n;
  • if ibound=3, bl[0]<bu[0].
bu
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: bl is ℓ, the array of lower bounds. bu is u, the array of upper bounds.
If ibound=0, you must set bl[i-1] to ℓi and bu[i-1] to ui, for i=1,2,…,n. If a particular xi is to be unbounded below, the corresponding bl[i-1] should be set to -infbnd, where infbnd is the value of the optional parameter Infinite Bound Size. Similarly, if a particular xi is to be unbounded above, the corresponding bu[i-1] should be set to infbnd.
If ibound=1 or 2, arrays bl and bu need not be set on input.
If ibound=3, you must set bl[0] to ℓ1 and bu[0] to u1. The remaining elements of bl and bu will then be populated by these initial values.
On exit: unless ifail=1 or 2 on exit, bl and bu are the actual arrays of bounds used by e05jb.
Constraints:
  • if ibound=0, bl[i-1]≤bu[i-1], for i=1,2,…,n;
  • if ibound=3, bl[0]<bu[0].
list
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [n, sdlist]
On entry: this parameter need not be set on entry if you wish to use one of the preset initialization methods (iinit≠3).
list is the ‘initialization list’: whenever a sub-box in the algorithm is split for the first time (either during the initialization procedure or later), for each non-fixed coordinate i the split is done at the values list[i-1,0:numpts[i-1]-1], as well as at some adaptively chosen intermediate points. The array sections list[i-1,0:numpts[i-1]-1], for i=1,2,…,n, must be in ascending order with each entry being distinct. In this context, ‘distinct’ should be taken to mean relative to the safe-range parameter (see x02am).
On exit: unless ifail=1, 2 or -999 on exit, the actual initialization data used by e05jb. If you wish to monitor the contents of list you are advised to do so solely through monit, not through the output value here.
Constraint: if x[i-1] is not fixed, list[i-1,0:numpts[i-1]-1] is in ascending order with each entry being distinct, for i=1,2,…,nbl[i-1]≤list[i-1,j-1]≤bu[i-1], for i=1,2,…,n and j=1,2,…,numpts[i-1].
numpts
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On entry: this parameter need not be set on entry if you wish to use one of the preset initialization methods (iinit≠3).
numpts encodes the number of splitting points in each non-fixed dimension.
On exit: unless ifail=1, 2 or -999 on exit, the actual initialization data used by e05jb.
Constraints:
  • if x[i-1] is not fixed, numpts[i-1]≤sdlist;
  • numpts[i-1]≥3, for i=1,2,…,n.
initpt
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On entry: this parameter need not be set on entry if you wish to use one of the preset initialization methods (iinit≠3).
You must designate a point stored in list that you wish e05jb to consider as an ‘initial point’ for the purposes of the splitting procedure. Call this initial point x*. The coordinates of x* correspond to a set of indices Ji, for i=1,2,…,n, such that xi* is stored in list[i-1,Ji-1], for i=1,2,…,n. You must set initpt[i-1]=Ji, for i=1,2,…,n.
On exit: unless ifail=1, 2 or -999 on exit, the actual initialization data used by e05jb.
Constraint: if x[i-1] is not fixed, 1≤initpt[i-1]≤sdlist, for i=1,2,…,n.
monit
Type: NagLibrary..::..E05..::..E05JB_MONIT
monit may be used to monitor the optimization process. It is invoked upon every successful completion of the procedure in which a sub-box is considered for splitting. It will also be called just before e05jb exits if that splitting procedure was not successful.
If no monitoring is required, monit may be the dummy monitoring method E05JBK supplied by the NAG Library.

A delegate of type E05JB_MONIT.

x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: if ifail=0, contains an estimate of the global optimum (see also [Accuracy]).
obj
Type: System..::..Double %
On exit: if ifail=0, contains the function value at x.
If you request early termination of e05jb using inform in objfun or the analogous inform in monit, there is no guarantee that the function value at x equals obj.
options
Type: NagLibrary..::..E05..::..e05jbOptions
An Object of type E05.e05jbOptions. Used to configure optional parameters to this method.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

e05jb is designed to solve modestly sized global optimization problems having simple bound-constraints only; it finds the global optimum of a nonlinear function subject to a set of bound constraints on the variables. Without loss of generality, the problem is assumed to be stated in the following form:
minimize x∈Rn F x  subject to  ℓ≤x≤u  and  ℓ≤u,
where F x (the objective function) is a nonlinear scalar function (assumed to be continuous in a neighbourhood of a global minimum), and the bound vectors are elements of R-n, where R- denotes the extended reals R∪-∞,∞. Relational operators between vectors are interpreted elementwise.
The optional parameter Maximize should be set if you wish to solve maximization, rather than minimization, problems.
If certain bounds are not present, the associated elements of ℓ or u can be set to special values that will be treated as -∞ or +∞. See the description of the optional parameter Infinite Bound Size. Phrases in this document containing terms like ‘unbounded values’ should be understood to be taken relative to this optional parameter.
Fixing variables (that is, setting li=ui for some i) is allowed in e05jb.
A typical excerpt from a method calling e05jb is: where (E05JDF not in this release) sets the optional parameter and value specified in optstr.
The initialization method (E05JAF not in this release) does not need to be called before each invocation of e05jb. You should be aware that a call to the initialization method will reset each optional parameter to its default value, and, if you are using repeatable randomized initialization lists (see the description of the parameter iinit), the random state stored in the array comm will be destroyed.
You must supply a method that evaluates F x; derivatives are not required.
The method used by e05jb is based on MCS, the Multi-level Coordinate Search method described in Huyer and Neumaier (1999), and the algorithm it uses is described in detail in [Algorithmic Details].

References

Huyer W and Neumaier A (1999) Global optimization by multi-level coordinate search Journal of Global Optimization 14 331–355

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
Initialization method (E05JAF not in this release) has not been called.
On entry, lcomm=value.
Constraint: lcomm≥100.
ifail=2
A value of Splits Limit (smax) smaller than nr+3 was set: smax=value, nr=value.
On entry, ibound=value.
Constraint: ibound=0, 1, 2 or 3.
On entry, ibound=0 or 3 and bl[i-1]=value, bu[i-1]=value and i=value.
Constraint: if ibound=0 then bl[i-1]≤bu[i-1], for i=1,2,…,n; if ibound=3 then bl[0]<bu[0].
On entry, ibound=3 and bl[0]=bu[0]=value.
Constraint: if ibound=3 then bl[0]<bu[0].
On entry, iinit=value.
Constraint: iinit=0, 1, 2, 3 or 4.
On entry, iinit=2 and sdlist=value.
Constraint: if iinit=2 then sdlist≥192.
On entry, iinit=value and sdlist=value.
Constraint: if iinit≠2 then sdlist≥3.
On entry, n=value.
Constraint: n>0.
On entry, user-supplied initpt[i-1]=value, i=value.
Constraint: if x[i-1] is not fixed then initpt[i-1]≥1, for i=1,2,…,n.
On entry, user-supplied initpt[i-1]=value, i=value and sdlist=value.
Constraint: if x[i-1] is not fixed then initpt[i-1]≤sdlist, for i=1,2,…,n.
On entry, user-supplied list[i-1,j-1]=value, i=value, j=value, and bl[i-1]=value.
Constraint: if x[i-1] is not fixed then list[i-1,j-1]≥bl[i-1], for i=1,2,…,n and j=1,2,…,numpts[i-1].
On entry, user-supplied list[i-1,j-1]=value, i=value, j=value, and bu[i-1]=value.
Constraint: if x[i-1] is not fixed then list[i-1,j-1]≤bu[i-1], for i=1,2,…,n and j=1,2,…,numpts[i-1].
On entry, user-supplied numpts[i-1]=value, i=value.
Constraint: if x[i-1] is not fixed then numpts[i-1]≥3, for i=1,2,…,n.
On entry, user-supplied numpts[i-1]=value, i=value and sdlist=value.
Constraint: if x[i-1] is not fixed then numpts[i-1]≤sdlist, for i=1,2,…,n.
On entry, user-supplied section list[i,1:numpts[i-1]] contained ndist distinct elements, and ndist<numpts[i-1]: ndist=value, numpts[i-1]=value, i=value.
On entry, user-supplied section list[i,1:numpts[i-1]] was not in ascending order: numpts[i-1]=value, i=value.
The number of non-fixed variables nr=0.
Constraint: nr>0.
ifail=3
A finite initialization list could not be computed internally. Consider reformulating the bounds on the problem, try providing your own initialization list, use the randomization option (iinit=4) or vary the value of Infinite Bound Size.
The user-supplied initialization list contained infinite values, as determined by the optional parameter Infinite Bound Size.
ifail=4
The division procedure completed but your target value could not be reached.
Despite every sub-box being processed Splits Limit times, the target value you provided in Target Objective Value could not be found to the tolerances given in Target Objective Error and Target Objective Safeguard. You could try reducing Splits Limit or the objective tolerances.
ifail=5
The function evaluations limit was exceeded.
Approximately Function Evaluations Limit function calls have been made without your chosen termination criterion being satisfied.
ifail=6
User-supplied monitoring method requested termination.
User-supplied objective function requested termination.
ifail=7
An error occurred during initialization. It is likely that points from the initialization list are very close together. Try relaxing the bounds on the variables or use a different initialization method.
An error occurred during linesearching. It is likely that your objective function is badly scaled: try rescaling it. Also, try relaxing the bounds or use a different initialization method. If the problem persists, please contact NAG quoting error code value.
ifail=-999
Dynamic memory allocation failed.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

If ifail=0 on exit, then the vector returned in the array x is an estimate of the solution x whose function value satisfies your termination criterion: the function value was static for Static Limit sweeps through levels, or
F x-objval≤max objerr×objval,objsfg,
where objval is the value of the optional parameter Target Objective Value, objerr is the value of the optional parameter Target Objective Error, and objsfg is the value of the optional parameter Target Objective Safeguard.

Parallelism and Performance

None.

Further Comments

For each invocation of e05jb, local workspace arrays of fixed length are allocated internally. The total size of these arrays amounts to 13 nr+smax-1 integer elements, where smax is the value of the optional parameter Splits Limit and nr is the number of non-fixed variables, and 2+nr sdlist+2 n+21 nr+3 nr 2+1 real elements. In addition, if you are using randomized initialization lists (see the description of the parameter iinit), a further 21 integer elements are allocated internally.
In order to keep track of the regions of the search space that have been visited while looking for a global optimum, e05jb internally allocates arrays of increasing sizes depending on the difficulty of the problem. Two of the main factors that govern the amount allocated are the number of sub-boxes (call this quantity nboxes) and the number of points in the ‘shopping basket’ (the parameter nbaskt on entry to monit). Safe, pessimistic upper bounds on these two quantities are so large as to be impractical. In fact, the worst-case number of sub-boxes for even the most simple initialization list (when ninit=3 on entry to monit) grows like nrnr. Thus e05jb does not attempt to estimate in advance the final values of nboxes or nbaskt for a given problem. There are a total of 5 integer arrays and 4+nr+ninit real arrays whose lengths depend on nboxes, and there are a total of 2 integer arrays and 3+n+nr real arrays whose lengths depend on nbaskt. e05jb makes a fixed initial guess that the maximum number of sub-boxes required will be 10000 and that the maximum number of points in the ‘shopping basket’ will be 1000. If ever a greater amount of sub-boxes or more room in the ‘shopping basket’ is required, e05jb performs reallocation, usually doubling the size of the inadequately-sized arrays. Clearly this process requires periods where the original array and its extension exist in memory simultaneously, so that the data within can be copied, which compounds the complexity of e05jb's memory usage. It is possible (although not likely) that if your problem is particularly difficult to solve, or of a large size (hundreds of variables), you may run out of memory.
One array that could be dynamically resized by e05jb is the ‘shopping basket’ (xbaskt on entry to monit). If the initial attempt to allocate 1000 nr reals for this array fails, monit will not be called on exit from e05jb.
e05jb performs better if your problem is well-scaled. It is worth trying (by guesswork perhaps) to rescale the problem if necessary, as sensible scaling will reduce the difficulty of the optimization problem, so that e05jb will take less computer time.

Example

This example finds the global minimum of the ‘peaks’ function in two dimensions
F x,y=3 1-x 2 exp-x 2-y+1 2-10 x 5-x 3-y 5 exp-x 2-y 2-13 exp-x+1 2-y 2
on the box -3,3×-3,3.
The function F has several local minima and one global minimum in the given box. The global minimum is approximately located at 0.23,-1.63, where the function value is approximately -6.55.
We use default values for all the optional parameters, and we instruct e05jb to use the simple initialization list corresponding to iinit=0. In particular, this will set for us the initial point 0,0 (see []).

Example program (C#): e05jbe.cs

Example program data: e05jbe.d

Example program results: e05jbe.r

Algorithmic Details

Here we summarise the main features of the MCS algorithm used in e05jb, and we introduce some terminology used in the description of the method and its arguments. We assume throughout that we will only do any work in coordinates i in which xi is free to vary. The MCS algorithm is fully described in Huyer and Neumaier (1999).

Initialization and Sweeps

Each sub-box is determined by a basepoint x and an opposite point y. We denote such a sub-box by B x,y. The basepoint is allowed to belong to more than one sub-box, is usually a boundary point, and is often a vertex.
An initialization procedure produces an initial set of sub-boxes. Whenever a sub-box is split along a coordinate i for the first time (in the initialization procedure or later), the splitting is done at three or more user-defined values xij j at which the objective function is sampled, and at some adaptively chosen intermediate points. At least four children are generated. More precisely, we assume that we are given
ℓi≤xi 1<xi 2<⋯<xi Li≤ui, Li≥3,  for ​i=1,2,…,n
and a vector p that, for each i, locates within xij j the ith coordinate of an initial point x 0; that is, if xi 0=xij for some j=1,2,…,Li, then pi=j. A good guess for the global optimum can be used as x 0.
The initialization points and the vectors ℓ and p are collectively called the initialization list (and sometimes we will refer to just the initialization points as ‘the initialization list’, whenever this causes no confusion). The initialization data may be input by you, or they can be set to sensible default values by e05jb: if you provide them yourself, list[i-1,j-1] should contain xij, numpts[i-1] should contain Li, and initpt[i-1] should contain pi, for i=1,2,…,n and j=1,2,…,Li; if you wish e05jb to use one of its preset initialization methods, you could choose one of two simple, three-point methods (see Figure 1). If the list generated by one of these methods contains infinite values, attempts are made to generate a safeguarded list using the function subint x,y (which is also used during the splitting procedure, and is described in [Splitting]). If infinite values persist, e05jb exits with ifail=3. There is also the option to generate an initialization list with the aid of linesearches (by setting iinit=2). Starting with the absolutely smallest point in the root box, linesearches are made along each coordinate. For each coordinate, the local minimizers found by the linesearches are put into the initialization list. If there were fewer than three minimizers, they are augmented by close-by values. The final preset initialization option (iinit=4) generates a randomized list, so that independent multiple runs may be made if you suspect a global optimum has not been found. Each call to the initialization method (E05JAF not in this release) resets the initial-state vector for the Wichmann–Hill base-generator that is used. Depending on whether you set the optional parameter Repeatability to ON or OFF, the random state is initialized to give a repeatable or non-repeatable sequence. Then, a random integer between 3 and sdlist is selected, which is then used to determine the number of points to be generated in each coordinate; that is, numpts becomes a constant vector, set to this value. The components of list are then generated, from a uniform distribution on the root box if the box is finite, or else in a safeguarded fashion if any bound is infinite. The array initpt is set to point to the best point in list.
Given an initialization list (preset or otherwise), e05jb evaluates F at x 0, and sets the initial estimate of the global minimum, x*, to x 0. Then, for i=1,2,…,n, the objective function F is evaluated at Li-1 points that agree with x* in all but the ith coordinate. We obtain pairs x^j,fij, for j=1,2,…,Li, with: x*=x^j 1, say; with, for j≠j 1,
x^kj=xk*if ​k≠i;xkjotherwise;
and with
fij=F x^j.
The point having the smallest function value is renamed x* and the procedure is repeated with the next coordinate.
Once e05jb has a full set of initialization points and function values, it can generate an initial set of sub-boxes. Recall that the root box is B x,y=ℓ,u, having basepoint x=x 0. The opposite point y is a corner of ℓ,u farthest away from x, in some sense. The point x need not be a vertex of ℓ,u, and y is entitled to have infinite coordinates. We loop over each coordinate i, splitting the current box along coordinate i into 2 Li-2, 2 Li-1 or 2 Li sub-intervals with exactly one of the x^ij as endpoints, depending on whether two, one or none of the x^ij are on the boundary. Thus, as well as splitting at x^ij, for j=1,2,…,Li, we split at additional points zij, for j=2,3,…,Li. These additional zij are such that
zij=x^i j-1+qm x^ij-x^i j-1,  j=2,…,Li,
where q is the golden-section ratio 5-1/2, and the exponent m takes the value 1 or 2, chosen so that the sub-box with the smaller function value gets the larger fraction of the interval. Each child sub-box gets as basepoint the point obtained from x* by changing xi* to the xij that is a boundary point of the corresponding ith coordinate interval; this new basepoint therefore has function value fij. The opposite point is derived from y by changing yi to the other end of that interval.
e05jb can now rank the coordinates based on an estimated variability of F. For each i we compute the union of the ranges of the quadratic interpolant through any three consecutive x^ij, taking the difference between the upper and lower bounds obtained as a measure of the variability of F in coordinate i. A vector π is populated in such a way that coordinate i has the πith highest estimated variability. For tiebreaks, when the x* obtained after splitting coordinate i belongs to two sub-boxes, the one that contains the minimizer of the quadratic models is designated the current sub-box for coordinate i+1.
Boxes are assigned levels in the following manner. The root box is given level 1. When a sub-box of level s is split, the child with the smaller fraction of the golden-section split receives level s+2; all other children receive level s+1. The box with the better function value is given the larger fraction of the splitting interval and the smaller level because then it is more likely to be split again more quickly. We see that after the initialization procedure the first level is empty and the non-split boxes have levels 2,…,nr+2, so it is meaningful to choose smax much larger than nr. Note that the internal structure of e05jb demands that smax be at least nr+3.
Examples of initializations in two dimensions are given in Figure 1. In both cases the initial point is x 0=ℓ+u/2; on the left the initialization points are
x 1=ℓ, x 2=ℓ+u/2, x 3=u,
while on the right the points are
x 1=5 ℓ+u/6, x 2=ℓ+u/2, x 3=ℓ+5 u/6.
In Figure 1, basepoints and levels after initialization are displayed. Note that these initialization lists correspond to iinit=0 and iinit=1, respectively.
Examples of the initialization procedure
Figure 1: Examples of the initialization procedure
After initialization, a series of sweeps through levels is begun. A sweep is defined by three steps:
(i) | scan the list of non-split sub-boxes. Fill a record list b according to bs=0 if there is no box at level s, and with bs pointing to a sub-box with the lowest function value among all sub-boxes with level s otherwise, for 0<s<smax;
(ii) | the sub-box with label bs is a candidate for splitting. If the sub-box is not to be split, according to the rules described in [Splitting], increase its level by 1 and update b s+1 if necessary. If the sub-box is split, mark it so, insert its children into the list of sub-boxes, and update b if any child with level s′ yields a strict improvement of F over those sub-boxes at level s′;
(iii) | increment s by 1. If s=smax then displaying monitoring information and start a new sweep; else if bs=0 then repeat this step; else display monitoring information and go to the previous step.
Clearly, each sweep ends after at most smax-1 visits of the third step.

Splitting

Each sub-box is stored by e05jb as a set of information about the history of the sub-box: the label of its parent, a label identifying which child of the parent it is, etc. Whenever a sub-box B x,y of level s<smax is a candidate for splitting, as described in [Initialization and Sweeps], we recover x, y, and the number, nj, of times coordinate j has been split in the history of B. Sub-box B could be split in one of two ways.
(i) | Splitting by rank If s>2 nr min nj+1, the box is always split. The splitting index is set to a coordinate i such that ni=min nj.
(ii) | Splitting by expected gain If s≤2 nr min nj+1, the sub-box could be split along a coordinate where a maximal gain in function value is expected. This gain is estimated according to a local separable quadratic model obtained by fitting to 2 nr+1 function values. If the expected gain is too small the sub-box is not split at all, and its level is increased by 1.
Eventually, a sub-box that is not eligible for splitting by expected gain will reach level 2 nr min nj+1+1 and then be split by rank, as long as smax is large enough. As smax→∞, the rule for splitting by rank ensures that each coordinate is split arbitrarily often.
Before describing the details of each splitting method, we introduce the procedure for correctly handling splitting at adaptive points and for dealing with unbounded intervals. Suppose we want to split the ith coordinate interval ▯xi,yi, where we define ▯xi,yi=min xi,yi,max xi,yi, for xi∈R and yi∈R-, and where x is the basepoint of the sub-box being considered. The descendants of the sub-box should shrink sufficiently fast, so we should not split too close to xi. Moreover, if yi is large we want the new splitting value to not be too large, so we force it to belong to some smaller interval ▯ξ′,ξ′′, determined by
ξ′′=subint xi,yi, ξ′=xi+ξ′′-xi/10,
where the function subint is defined by
subint x,y=sign yif ​1000 x<1​ and ​y>1000;10 sign yxif ​1000 x≥1​ and ​y>1000 x;yotherwise.

Splitting by rank

Consider a sub-box B with level s>2 nr min nj+1. Although the sub-box has reached a high level, there is at least one coordinate along which it has not been split very often. Among the i such that ni=min nj for B, select the splitting index to be the coordinate with the lowest πi (and hence highest variability rank). ‘Splitting by rank’ refers to the ranking of the coordinates by ni and πi.
If ni=0, so that B has never been split along coordinate i, the splitting is done according to the initialization list and the adaptively chosen golden-section split points, as described in [Initialization and Sweeps]. Also as covered there, new basepoints and opposite points are generated. The children having the smaller fraction of the golden-section split (that is, those with larger function values) are given level min s+2,smax. All other children are given level s+1.
Otherwise, B ranges between xi and yi in the ith coordinate direction. The splitting value is selected to be zi=xi+2 subint xi,yi-xi/3; we are not attempting to split based on a large reduction in function value, merely in order to reduce the size of a large interval, so zi may not be optimal. Sub-box B is split at zi and the golden-section split point, producing three parts and requiring only one additional function evaluation, at the point x′ obtained from x by changing the ith coordinate to zi. The child with the smaller fraction of the golden-section split is given level min s+2,smax, while the other two parts are given level s+1. Basepoints are assigned as follows: the basepoint of the first child is taken to be x, and the basepoint of the second and third children is the point x′. Opposite points are obtained by changing yi to the other end of the ith coordinate-interval of the corresponding child.

Splitting by expected gain

When a sub-box B has level s≤2 nr min nj+1, we compute the optimal splitting index and splitting value from a local separable quadratic used as a simple local approximation of the objective function. To fit this curve, for each coordinate we need two additional points and their function values. Such data may be recoverable from the history of B: whenever the ith coordinate was split in the history of B, we obtained values that can be used for the current quadratic interpolation in coordinate i.
We loop over i; for each coordinate we pursue the history of B back to the root box, and we take the first two points and function values we find, since these are expected to be closest to the current basepoint x. If the current coordinate has not yet been split we use the initialization list. Then we generate a local separable model e ξ for F ξ by interpolation at x and the 2 nr additional points just collected:
e ξ=F x+∑i=1 n ei ξi.
We define the expected gain e^i in function value when we evaluate at a new point obtained by changing coordinate i in the basepoint, for each i, based on two cases:
(i) ni=0. We compute the expected gain as
e^i=min 1≤j≤Li fij-fi pi.
Again, we split according to the initialization list, with the new basepoints and opposite points being as before.
(ii) ni>0. Now, the ith component of our sub-box ranges from xi to yi. Using the quadratic partial correction function
ei ξi=αi ξi-xi+βi ξi-xi 2
we can approximate the maximal gain expected when changing xi only. We will choose the splitting value from ▯ξ′,ξ′′. We compute
e^i=min ξi∈▯ξ′,ξ′′ei ξi
and call zi the minimizer in ▯ξ′,ξ′′.
If the expected best function value fexp satisfies
fexp=F x+min 1≤i≤n e^i<fbest, (1)
where fbest is the current best function value (including those function values obtained by local optimization), we expect the sub-box to contain a better point and so we split it, using as splitting index the component with minimal e^i. Equation (1) prevents wasting function calls by avoiding splitting sub-boxes whose basepoints have bad function values. These sub-boxes will eventually be split by rank anyway.
We now have a splitting index and a splitting value zi. The sub-box is split at zi as long as zi≠yi, and at the golden-section split point; two or three children are produced. The larger fraction of the golden-section split receives level s+1, while the smaller fraction receives level min s+2,smax. If it is the case that zi≠yi and the third child is larger than the smaller of the two children from the golden-section split, the third child receives level s+1. Otherwise it is given the level min s+2,smax. The basepoint of the first child is set to x, and the basepoint of the second (and third if it exists) is obtained by changing the ith coordinate of x to zi. The opposite points are again derived by changing yi to the other end of the ith coordinate interval of B.
If equation (1) does not hold, we expect no improvement. We do not split, and we increase the level of B by 1.

Local Search

The local optimization algorithm used by e05jb uses linesearches along directions that are determined by minimizing quadratic models, all subject to bound constraints. Triples of vectors are computed using coordinate searches based on linesearches. These triples are used in triple search procedures to build local quadratic models for F. A trust-region-type approach to minimize these models is then carried out, and more information about the coordinate search and the triple search can be found in Huyer and Neumaier (1999).
The local search starts by looking for better points without being too local, by making a triple search using points found by a coordinate search. This yields a new point and function value, an approximation of the gradient of the objective, and an approximation of the Hessian of the objective. Then the quadratic model for F is minimized over a small box, with the solution to that minimization problem then being used as a linesearch direction to minimize the objective. A measure r is computed to quantify the predictive quality of the quadratic model.
The third stage is the checking of termination criteria. The local search will stop if more than loclim visits to this part of the local search have occurred, where loclim is the value of the optional parameter Local Searches Limit. If that is not the case, it will stop if the limit on function calls has been exceeded (see the description of the optional parameter Function Evaluations Limit). The final criterion checks if no improvement can be made to the function value, or whether the approximated gradient g is small, in the sense that
g T max x,xold<loctol f 0-f.
The vector xold is the best point at the start of the current loop in this iterative local-search procedure, the constant loctol is the value of the optional parameter Local Searches Tolerance, f is the objective value at x, and f 0 is the smallest function value found by the initialization procedure.
Next, e05jb attempts to move away from the boundary, if any components of the current point lie there, using linesearches along the offending coordinates. Local searches are terminated if no improvement could be made.
The fifth stage carries out another triple search, but this time it does not use points from a coordinate search, rather points lying within the trust-region box are taken.
The final stage modifies the trust-region box to be bigger or smaller, depending on the quality of the quadratic model, minimizes the new quadratic model on that box, and does a linesearch in the direction of the minimizer. The value of r is updated using the new data, and then we go back to the third stage (checking of termination criteria).
The Hessians of the quadratic models generated by the local search may not be positive definite, so e05jb uses the general nonlinear optimizer e04vh to minimize the models.

See Also

E05 Class
E05 Members


e05jbk Method

[image]

NAG Library for .NET Release 2
E05..::e05jbk Method
E05 Class See Also Send Feedback
Auxiliary for use as a delegate parameter

Syntax

C#
public static void e05jbk(
    int n,
    int ncall,
    double[] xbest,
    int[] icount,
    double[,] list,
    int[] numpts,
    int[] initpt,
    int nbaskt,
    double[,] xbaskt,
    double[] boxl,
    double[] boxu,
    int nstate,
    out int inform
)
Visual Basic
Public Shared Sub e05jbk ( _
    n As Integer, _
    ncall As Integer, _
    xbest As Double(), _
    icount As Integer(), _
    list As Double(,), _
    numpts As Integer(), _
    initpt As Integer(), _
    nbaskt As Integer, _
    xbaskt As Double(,), _
    boxl As Double(), _
    boxu As Double(), _
    nstate As Integer, _
    <OutAttribute> ByRef inform As Integer _
)
Visual C++
public:
static void e05jbk(
    int n,
    int ncall,
    array<double>^ xbest,
    array<int>^ icount,
    array<double,2>^ list,
    array<int>^ numpts,
    array<int>^ initpt,
    int nbaskt,
    array<double,2>^ xbaskt,
    array<double>^ boxl,
    array<double>^ boxu,
    int nstate,
    [OutAttribute] int% inform
)
F#
static member e05jbk :
        n : int *
        ncall : int *
        xbest : float[] *
        icount : int[] *
        list : float[,] *
        numpts : int[] *
        initpt : int[] *
        nbaskt : int *
        xbaskt : float[,] *
        boxl : float[] *
        boxu : float[] *
        nstate : int *
        inform : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of variables.
ncall
Type: System..::..Int32
On entry: the cumulative number of calls to _objfun.
xbest
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the current best point.
icount
Type: array< System..::..Int32 >[]()[][]
An array of size [6]
On entry: an array of counters.
icount[0]
nboxes, the current number of sub-boxes.
icount[1]
ncloc, the cumulative number of calls to _objfun made in local searches.
icount[2]
nloc, the cumulative number of points used as start points for local searches.
icount[3]
nsweep, the cumulative number of sweeps through levels.
icount[4]
m, the cumulative number of splits by initialization list.
icount[5]
s, the current lowest level containing non-split boxes.
list
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [n, ninit]
On entry: the initialization list.
numpts
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On entry: the number of points in each coordinate at which to split according to the initialization list list.
initpt
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On entry: a pointer to the ‘initial point’ in list. Element initpt[i-1] is the column index in list of the ith coordinate of the initial point.
nbaskt
Type: System..::..Int32
On entry: the number of points in the ‘shopping basket’ xbaskt.
xbaskt
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [n, nbaskt]
On entry: the ‘shopping basket’ of candidate minima.
boxl
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the array of lower bounds of the current search box.
boxu
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the array of upper bounds of the current search box.
nstate
Type: System..::..Int32
On entry: is set by e05jb to indicate at what stage of the minimization _monit was called.
nstate=1
This is the first time that _monit has been called.
nstate=-1
This is the last time _monit will be called.
nstate=0
This is the first and last time _monit will be called.
inform
Type: System..::..Int32 %
On exit: must be set to a value describing the action to be taken by the solver on return from _monit: if the value is negative the solution of the current problem will terminate immediately; otherwise, computations will continue.

Description

Auxiliary for use as a delegate parameter

References

None.

Error Indicators and Warnings

None.

Accuracy

Not applicable.

Further Comments

None.

Example

None.

See Also

E05 Class
E05 Members


e05uc Method

[image]

NAG Library for .NET Release 2
E05..::e05uc Method
E05 Class See Also Send Feedback
e05uc is designed to find the global minimum of an arbitrary smooth function subject to constraints (which may include simple bounds on the variables, linear constraints and smooth nonlinear constraints) by generating a number of different starting points and performing a local search from each using sequential quadratic programming.

Syntax

C#
public static void e05uc(
    int n,
    int nclin,
    int ncnln,
    double[,] a,
    double[] bl,
    double[] bu,
    E05..::..E05UC_CONFUN confun,
    E05..::..E05UC_OBJFUN objfun,
    int npts,
    double[,] x,
    E05..::..E05UC_START start,
    bool repeat,
    int nb,
    double[] objf,
    double[,] objgrd,
    int[] iter,
    double[,] c,
    double[,,] cjac,
    int sdcjac,
    double[,,] r,
    int sdr,
    double[,] clamda,
    int[,] istate,
    E05..::..e05ucOptions options,
    int[] info,
    out int ifail
)
Visual Basic
Public Shared Sub e05uc ( _
    n As Integer, _
    nclin As Integer, _
    ncnln As Integer, _
    a As Double(,), _
    bl As Double(), _
    bu As Double(), _
    confun As E05..::..E05UC_CONFUN, _
    objfun As E05..::..E05UC_OBJFUN, _
    npts As Integer, _
    x As Double(,), _
    start As E05..::..E05UC_START, _
    repeat As Boolean, _
    nb As Integer, _
    objf As Double(), _
    objgrd As Double(,), _
    iter As Integer(), _
    c As Double(,), _
    cjac As Double(,,), _
    sdcjac As Integer, _
    r As Double(,,), _
    sdr As Integer, _
    clamda As Double(,), _
    istate As Integer(,), _
    options As E05..::..e05ucOptions, _
    info As Integer(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e05uc(
    int n,
    int nclin,
    int ncnln,
    array<double,2>^ a,
    array<double>^ bl,
    array<double>^ bu,
    E05..::..E05UC_CONFUN^ confun,
    E05..::..E05UC_OBJFUN^ objfun,
    int npts,
    array<double,2>^ x,
    E05..::..E05UC_START^ start,
    bool repeat,
    int nb,
    array<double>^ objf,
    array<double,2>^ objgrd,
    array<int>^ iter,
    array<double,2>^ c,
    array<double,3>^ cjac,
    int sdcjac,
    array<double,3>^ r,
    int sdr,
    array<double,2>^ clamda,
    array<int,2>^ istate,
    E05..::..e05ucOptions^ options,
    array<int>^ info,
    [OutAttribute] int% ifail
)
F#
static member e05uc :
        n : int *
        nclin : int *
        ncnln : int *
        a : float[,] *
        bl : float[] *
        bu : float[] *
        confun : E05..::..E05UC_CONFUN *
        objfun : E05..::..E05UC_OBJFUN *
        npts : int *
        x : float[,] *
        start : E05..::..E05UC_START *
        repeat : bool *
        nb : int *
        objf : float[] *
        objgrd : float[,] *
        iter : int[] *
        c : float[,] *
        cjac : float[,,] *
        sdcjac : int *
        r : float[,,] *
        sdr : int *
        clamda : float[,] *
        istate : int[,] *
        options : E05..::..e05ucOptions *
        info : int[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of variables.
Constraint: n>0.
nclin
Type: System..::..Int32
On entry: nL, the number of general linear constraints.
Constraint: nclin≥0.
ncnln
Type: System..::..Int32
On entry: nN, the number of nonlinear constraints.
Constraint: ncnln≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥nclin
Note: the second dimension of the array a must be at least n if nclin>0, and at least 1 otherwise.
On entry: the matrix AL of general linear constraints in (1). That is, the ith row contains the coefficients of the ith general linear constraint, for i=1,2,…,nclin.
If nclin=0, the array a is not referenced.
bl
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin+ncnln]
On entry: bl must contain the lower bounds and bu the upper bounds for all the constraints in the following order. The first n elements of each array must contain the bounds on the variables, the next nL elements the bounds for the general linear constraints (if any) and the next nN elements the bounds for the general nonlinear constraints (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j-1]≤-bigbnd, and to specify a nonexistent upper bound (i.e., uj=+∞), set bu[j-1]≥bigbnd; the default value of bigbnd is 1020, but this may be changed by the optional parameter Infinite Bound Size. To specify the jth constraint as an equality, set bl[j-1]=bu[j-1]=β, say, where β<bigbnd.
Constraints:
  • bl[j-1]≤bu[j-1], for j=1,2,…,n+nclin+ncnln;
  • if bl[j-1]=bu[j-1]=β, β<bigbnd.
bu
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin+ncnln]
On entry: bl must contain the lower bounds and bu the upper bounds for all the constraints in the following order. The first n elements of each array must contain the bounds on the variables, the next nL elements the bounds for the general linear constraints (if any) and the next nN elements the bounds for the general nonlinear constraints (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j-1]≤-bigbnd, and to specify a nonexistent upper bound (i.e., uj=+∞), set bu[j-1]≥bigbnd; the default value of bigbnd is 1020, but this may be changed by the optional parameter Infinite Bound Size. To specify the jth constraint as an equality, set bl[j-1]=bu[j-1]=β, say, where β<bigbnd.
Constraints:
  • bl[j-1]≤bu[j-1], for j=1,2,…,n+nclin+ncnln;
  • if bl[j-1]=bu[j-1]=β, β<bigbnd.
confun
Type: NagLibrary..::..E05..::..E05UC_CONFUN
confun must calculate the vector c x of nonlinear constraint functions and (optionally) its Jacobian (=∂c∂x) for a specified n-element vector x. If there are no nonlinear constraints (i.e., ncnln=0), confun will never be called by e05uc and confun may be the dummy method E04UDM. (E04UDM is included in the NAG Library.) If there are nonlinear constraints, the first call to confun will occur before the first call to objfun.

A delegate of type E05UC_CONFUN.

confun should be tested separately before being used in conjunction with e05uc. See also the description of the optional parameter Verify.
objfun
Type: NagLibrary..::..E05..::..E05UC_OBJFUN
objfun must calculate the objective function F x and (optionally) its gradient g x=∂F∂x for a specified n-vector x.

A delegate of type E05UC_OBJFUN.

objfun should be tested separately before being used in conjunction with e05uc. See also the description of the optional parameter Verify.
npts
Type: System..::..Int32
On entry: the number of different starting points to be generated and used. The more points used, the more likely that the best returned solution will be a global minimum.
Constraint: 1≤nb≤npts.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nb]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: x[j-1,i-1] contains the final estimate of the ith solution, for j=1,2,…,n.
start
Type: NagLibrary..::..E05..::..E05UC_START
start must calculate the npts starting points to be used by the local optimizer. If you do not wish to write a method specific to your problem then E05UCZ may be used as the actual argument. E05UCZ is supplied in the NAG Library and uses the NAG quasi-random number generators to distribute starting points uniformly across the domain. It is affected by the value of repeat.

A delegate of type E05UC_START.

repeat
Type: System..::..Boolean
On entry: is passed as an argument to start and may be used to initialize a random number generator to a repeatable, or non-repeatable, sequence.
nb
Type: System..::..Int32
On entry: the number of solutions to be returned. The method saves up to nb local minima ordered by increasing value of the final objective function. If the defining criterion for ‘best solution’ is only that the value of the objective function is as small as possible then nb should be set to 1. However, if you want to look at other solutions that may have desirable properties then setting nb>1 will produce nb local minima, ordered by increasing value of their objective functions at the minima.
Constraint: 1≤nb≤npts.
objf
Type: array< System..::..Double >[]()[][]
An array of size [nb]
On exit: objf[i-1] contains the value of the objective function at the final iterate for the ith solution.
objgrd
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nb]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: objgrd[j-1,i-1] contains the gradient of the objective function for the ith solution at the final iterate (or its finite difference approximation), for j=1,2,…,n.
iter
Type: array< System..::..Int32 >[]()[][]
An array of size [nb]
On exit: iter[i-1] contains the number of major iterations performed to obtain the ith solution. If less than nb solutions are returned then iter[nb-1] contains the number of starting points that have resulted in a converged solution. If this is close to npts then this might be indicative that fewer than nb local minima exist.
c
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nb]
Note: dim1 must satisfy the constraint: dim1≥ncnln
On exit: if ncnln>0, c[j-1,i-1] contains the value of the jth nonlinear constraint function cj at the final iterate, for the ith solution, for j=1,2,…,ncnln.
If ncnln=0, the array c is not referenced.
cjac
Type: array< System..::..Double ,3>[,](,)[,][,]
An array of size [dim1, sdcjac, nb]
Note: dim1 must satisfy the constraint: dim1≥ncnln
On exit: if ncnln>0, cjac contains the Jacobian matrices of the nonlinear constraint functions at the final iterate for each of the returned solutions, i.e., cjac[k-1,j-1,i-1] contains the partial derivative of the kth constraint function with respect to the jth variable, for k=1,2,…,ncnln and j=1,2,…,n, for the ith solution. (See the discussion of parameter cjsl under confun.)
If ncnln=0, the array cjac is not referenced.
sdcjac
Type: System..::..Int32
the second dimension of the array cjac.
On entry: the second dimension of the array cjac as declared in the (sub)program from which e05uc is called.
Constraint: if ncnln>0, sdcjac≥n.
r
Type: array< System..::..Double ,3>[,](,)[,][,]
An array of size [dim1, sdr, nb]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: for each of the nb solutions r will contain a form of the Hessian; for the ith returned solution r[ldr,sdr,i] contains the Hessian that would be returned from the local minimizer. If Hessian=NO, the default, each r[ldr,sdr,i] contains the upper triangular Cholesky factor R of QT HQ, an estimate of the transformed and reordered Hessian of the Lagrangian at x. If Hessian=YES, r[ldr,sdr,i] contains the upper triangular Cholesky factor R of H, the approximate (untransformed) Hessian of the Lagrangian, with the variables in the natural order.
sdr
Type: System..::..Int32
the second dimension of the array r.
On entry: the second dimension of the array r as declared in the (sub)program from which e05uc is called.
Constraint: sdr≥n.
clamda
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nb]
Note: dim1 must satisfy the constraint: dim1≥n+nclin+ncnln
On exit: the values of the QP multipliers from the last QP subproblem solved for the ith solution. clamda[j-1,i-1] should be non-negative if istate[j-1,i-1]=1 and non-positive if istate[j-1,i-1]=2.
istate
Type: array< System..::..Int32 ,2>[,](,)[,][,]
An array of size [dim1, nb]
Note: dim1 must satisfy the constraint: dim1≥n+nclin+ncnln
On exit: istate[j-1,i-1] contains the status of the constraints in the QP working set for the ith solution. The significance of each possible value of istate[j-1,i-1] is as follows:
istate[j-1,i-1] | Meaning
-0 | The constraint is satisfied to within the feasibility tolerance, but is not in the QP working set.
-1 | This inequality constraint is included in the QP working set at its lower bound.
-2 | This inequality constraint is included in the QP working set at its upper bound.
-3 | This constraint is included in the QP working set as an equality. This value of istate can occur only when bl[j-1]=bu[j-1].
options
Type: NagLibrary..::..E05..::..e05ucOptions
An Object of type E05.e05ucOptions. Used to configure optional parameters to this method.
info
Type: array< System..::..Int32 >[]()[][]
An array of size [nb]
On exit: info[i-1] contains one of 0, 1 or 6. Please see the description of each corresponding value of ifail on exit from e04uc for detailed explanations of these exit values. As usual 0 denotes success.
If ifail=8 on exit, then not all nb solutions have been found, and info[nb-1] contains the number of solutions actually found.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The problem is assumed to be stated in the following form:
minimize x∈Rn​ ​F x  subject to  l≤xAL xc x≤u, (1)
where F x (the objective function) is a nonlinear function, AL is an nL by n linear constraint matrix, and c x is an nN element vector of nonlinear constraint functions. (The matrix AL and the vector c x may be empty.) The objective function and the constraint functions are assumed to be smooth, i.e., at least twice-continuously differentiable. (This method will usually solve (1) if there are only isolated discontinuities away from the solution.)
e05uc solves a user-specified number of local optimization problems with different starting points. You may specify the starting points via the method start. If a random number generator is used to generate the starting points then the parameter repeat allows you to specify whether a repeatable set of points are generated or whether different starting points are generated on different calls. The resulting local minima are ordered and the best nb results returned in order of ascending values of the resulting objective function values at the minima. Thus the value returned in position 1 will be the best result obtained. If a sufficient number of different points are chosen then this is likely to be be the global minimum. Please note that the default version of start uses a random number generator to generate the starting points.

References

Dennis J E Jr and Moré J J (1977) Quasi-Newton methods, motivation and theory SIAM Rev. 19 46–89
Dennis J E Jr and Schnabel R B (1981) A new derivation of symmetric positive-definite secant updates nonlinear programming (eds O L Mangasarian, R R Meyer and S M Robinson) 4 167–199 Academic Press
Dennis J E Jr and Schnabel R B (1983) Numerical Methods for Unconstrained Optimization and Nonlinear Equations Prentice–Hall
Fletcher R (1987) Practical Methods of Optimization (2nd Edition) Wiley
Gill P E, Hammarling S, Murray W, Saunders M A and Wright M H (1986) Users' guide for LSSOL (Version 1.0) Report SOL 86-1 Department of Operations Research, Stanford University
Gill P E, Murray W, Saunders M A and Wright M H (1984) Users' guide for SOL/QPSOL version 3.2 Report SOL 84–5 Department of Operations Research, Stanford University
Gill P E, Murray W, Saunders M A and Wright M H (1986a) Some theoretical properties of an augmented Lagrangian merit function Report SOL 86–6R Department of Operations Research, Stanford University
Gill P E, Murray W, Saunders M A and Wright M H (1986b) Users' guide for NPSOL (Version 4.0): a Fortran package for nonlinear programming Report SOL 86-2 Department of Operations Research, Stanford University
Gill P E, Murray W and Wright M H (1981) Practical Optimization Academic Press
Powell M J D (1974) Introduction to constrained optimization Numerical Methods for Constrained Optimization (eds P E Gill and W Murray) 1–28 Academic Press
Powell M J D (1983) Variable metric methods in constrained optimization Mathematical Programming: the State of the Art (eds A Bachem, M Grötschel and B Korte) 288–311 Springer–Verlag

Error Indicators and Warnings

Note: e05uc may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA, LDX, LDOBJD, LDC, LDCJAC, LDR, LDCLDA, LISTAT) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
An input value is incorrect. One, or more, of the following requirements are violated:
  • n≥1;
  • nclin≥0;
  • ncnln≥0;
  • lda≥nclin;
  • bl[i-1]≤bu[i-1] for some i;
  • ldx≥n;
  • 1≤nb≤npts;
  • ldobjd≥n;
  • ldc≥ncnln;
  • ldcjac≥ncnln;
  • sdcjac≥n if ncnln>0
  • ldr≥n;
  • sdr≥n;
  • ldclda≥n+nclin+ncnln;
  • listat≥n+nclin+ncnln.
ifail=2
e05uc has terminated without finding any solutions. The majority of calls to the local optimizer have failed to find a feasible point for the linear constraints and bounds, which means that either no feasible point exists for the given value of the optional parameter Linear Feasibility Tolerance (default value ε, where ε is the machine precision), or no feasible point could be found in the number of iterations specified by the optional parameter Minor Iteration Limit. You should check that there are no constraint redundancies. If the data for the constraints are accurate only to an absolute precision σ, you should ensure that the value of the optional parameter Linear Feasibility Tolerance is greater than σ. For example, if all elements of AL are of order unity and are accurate to only three decimal places, Linear Feasibility Tolerance should be at least 10-3.
ifail=3
e05uc has failed to find any solutions. The majority of local optimizations could not find a feasible point for the nonlinear constraints. The problem may have no feasible solution. This behaviour will occur if there is no feasible point for the nonlinear constraints. (However, there is no general test that can determine whether a feasible point exists for a set of nonlinear constraints.)
ifail=4
e05uc has failed to find any solutions. The majority of local optimizations have failed because the limiting number of iterations have been reached. The Iteration Limit may be changed using (E05ZKF not in this release)
ifail=5
ifail=6
Not used by this method.
ifail=7
The user-supplied derivatives of the objective function and/or nonlinear constraints appear to be incorrect.
Large errors were found in the derivatives of the objective function and/or nonlinear constraints. This value of ifail will occur if the verification process indicated that at least one gradient or Jacobian element had no correct figures. You should refer to or enable the printed output to determine which elements are suspected to be in error.
As a first-step, you should check that the code for the objective and constraint values is correct – for example, by computing the function at a point where the correct value is known. However, care should be taken that the chosen point fully tests the evaluation of the function. It is remarkable how often the values x=0 or x=1 are used to test function evaluation procedures, and how often the special properties of these numbers make the test meaningless.
Special care should be used in this test if computation of the objective function involves subsidiary data communicated in storage, including iuser and ruser in a multithreaded environment. Although the first evaluation of the function may be correct, subsequent calculations may be in error because some of the subsidiary data has accidentally been overwritten.
Gradient checking will be ineffective if the objective function uses information computed by the constraints, since they are not necessarily computed before each function evaluation.
Errors in programming the function may be quite subtle in that the function value is almost correct. For example, the function may not be accurate to full precision because of the inaccurate calculation of a subsidiary quantity, or the limited accuracy of data upon which the function depends. A common error on machines where numerical calculations are usually performed in double precision is to include even one single precision constant in the calculation of the function; since some compilers do not convert such constants to double precision, half the correct figures may be lost by such a seemingly trivial error.
ifail=8
Not all nb solutions have been found. info[nb-1] contains the number actually found.
ifail=9
You terminated the computation by setting mode<0 in start.
If E05UCZ has been used as the actual argument for start then the message displayed, when ifail=0 or -1 on entry to e05uc, will have the following meaning:
-998 | – failure to allocate space, a smaller value of npts should be tried;
-997 | – an internal error has occurred. Please contact NAG for assistance.
ifail=10
Failed to initialize optional parameter arrays.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

If ifail=0 on exit and the value of info[i-1]=0, then the vector returned in the array x for solution i is an estimate of the solution to an accuracy of approximately Optimality Tolerance.

Parallelism and Performance

None.

Further Comments

You should be wary of requesting much intermediate output from the local optimizer, since large volumes may be produced if npts is large.
The auxiliary routine E05UCZ makes use of the NAG quasi-random Sobol generator (g05yl and g05ym). If E05UCZ is used as an argument for start (see the description of start) and repeat=false then a randomly chosen value for iskip is used, otherwise iskip is set to 100. If repeat is set to false and the program is executed several times, each time producing the same best answer, then there is increased probability that this answer is a global minimum. However, if it is important that identical results be obtained on successive runs, then repeat should be set to true.

Description of the Printed Output

See [Description of the Printed Output] in e04uc.

Example

This example finds the global minimum of the two-dimensional Schwefel function:
minimize x∈R 2 f=∑j=1 2 xj sin xj
subject to the constraints:
-10000<3.0 x 1-2.0 x 2<10.0,-1.0<x 12-x 22+3.0 x 1x 2<500000.0,-0.9<cos x 1/200 2+x 2/100<0.9,-500≤x 1≤500,-500≤x 2≤500.

Example program (C#): e05uce.cs

Example program data: e05uce.d

Example program results: e05uce.r

Algorithmic Details

See [Algorithmic Details] in e04uc.

Description of Monitoring Information

See [Description of Monitoring Information] in e04uc.

See Also

E05 Class
E05 Members


e05ucz Method

[image]

NAG Library for .NET Release 2
E05..::e05ucz Method
E05 Class See Also Send Feedback
Auxiliary for use as a delegate parameter

Syntax

C#
public static void e05ucz(
    int npts,
    double[,] quas,
    int n,
    bool repeat,
    double[] bl,
    double[] bu,
    ref int mode
)
Visual Basic
Public Shared Sub e05ucz ( _
    npts As Integer, _
    quas As Double(,), _
    n As Integer, _
    repeat As Boolean, _
    bl As Double(), _
    bu As Double(), _
    ByRef mode As Integer _
)
Visual C++
public:
static void e05ucz(
    int npts,
    array<double,2>^ quas,
    int n,
    bool repeat,
    array<double>^ bl,
    array<double>^ bu,
    int% mode
)
F#
static member e05ucz :
        npts : int *
        quas : float[,] *
        n : int *
        repeat : bool *
        bl : float[] *
        bu : float[] *
        mode : int byref -> unit

Parameters

npts
Type: System..::..Int32
On entry: indicates the number of starting points.
quas
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [n, npts]
On entry: elements of quas will have been set to zero.
On exit: quas[j-1,i-1] must contain the starting points for the npts local minimizations, i.e., quas[j-1,i-1] must contain the jth component of the ith starting point.
n
Type: System..::..Int32
On entry: the number of variables.
repeat
Type: System..::..Boolean
On entry: specifies whther a repeatable or non-repeatable sequence of points are to be generated.
bl
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the lower bounds on the variables. These may be used to ensure that the starting points generated in some sense ‘cover’ the region, but there is no requirement that a starting point be feasible.
bu
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the upper bounds on the variables. (See bl.)
mode
Type: System..::..Int32 %
On entry: mode will contain 0.
On exit: if you set mode to a negative value then e05uc will terminate immediately with ifail=9. The error message, produced when ifail=0 or -1 on entry to e05uc, will contain this value of mode.

Description

Auxiliary for use as a delegate parameter

References

None.

Error Indicators and Warnings

ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Further Comments

None.

Example

None.

See Also

E05 Class
E05 Members


e05us Method

[image]

NAG Library for .NET Release 2
E05..::e05us Method
E05 Class See Also Send Feedback
e05us is designed to find the global minimum of an arbitrary smooth sum of squares function subject to constraints (which may include simple bounds on the variables, linear constraints and smooth nonlinear constraints) by generating a number of different starting points and performing a local search from each using sequential quadratic programming.

Syntax

C#
public static void e05us(
    int m,
    int n,
    int nclin,
    int ncnln,
    double[,] a,
    double[] bl,
    double[] bu,
    double[] y,
    E05..::..E05US_CONFUN confun,
    E05..::..E05US_OBJFUN objfun,
    int npts,
    double[,] x,
    E05..::..E05US_START start,
    bool repeat1,
    int nb,
    double[] objf,
    double[,] f,
    double[,,] fjac,
    int sdfjac,
    int[] iter,
    double[,] c,
    double[,,] cjac,
    int sdcjac,
    double[,] clamda,
    int[,] istate,
    E05..::..e05usOptions options,
    int[] info,
    out int ifail
)
Visual Basic
Public Shared Sub e05us ( _
    m As Integer, _
    n As Integer, _
    nclin As Integer, _
    ncnln As Integer, _
    a As Double(,), _
    bl As Double(), _
    bu As Double(), _
    y As Double(), _
    confun As E05..::..E05US_CONFUN, _
    objfun As E05..::..E05US_OBJFUN, _
    npts As Integer, _
    x As Double(,), _
    start As E05..::..E05US_START, _
    repeat1 As Boolean, _
    nb As Integer, _
    objf As Double(), _
    f As Double(,), _
    fjac As Double(,,), _
    sdfjac As Integer, _
    iter As Integer(), _
    c As Double(,), _
    cjac As Double(,,), _
    sdcjac As Integer, _
    clamda As Double(,), _
    istate As Integer(,), _
    options As E05..::..e05usOptions, _
    info As Integer(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void e05us(
    int m,
    int n,
    int nclin,
    int ncnln,
    array<double,2>^ a,
    array<double>^ bl,
    array<double>^ bu,
    array<double>^ y,
    E05..::..E05US_CONFUN^ confun,
    E05..::..E05US_OBJFUN^ objfun,
    int npts,
    array<double,2>^ x,
    E05..::..E05US_START^ start,
    bool repeat1,
    int nb,
    array<double>^ objf,
    array<double,2>^ f,
    array<double,3>^ fjac,
    int sdfjac,
    array<int>^ iter,
    array<double,2>^ c,
    array<double,3>^ cjac,
    int sdcjac,
    array<double,2>^ clamda,
    array<int,2>^ istate,
    E05..::..e05usOptions^ options,
    array<int>^ info,
    [OutAttribute] int% ifail
)
F#
static member e05us :
        m : int *
        n : int *
        nclin : int *
        ncnln : int *
        a : float[,] *
        bl : float[] *
        bu : float[] *
        y : float[] *
        confun : E05..::..E05US_CONFUN *
        objfun : E05..::..E05US_OBJFUN *
        npts : int *
        x : float[,] *
        start : E05..::..E05US_START *
        repeat1 : bool *
        nb : int *
        objf : float[] *
        f : float[,] *
        fjac : float[,,] *
        sdfjac : int *
        iter : int[] *
        c : float[,] *
        cjac : float[,,] *
        sdcjac : int *
        clamda : float[,] *
        istate : int[,] *
        options : E05..::..e05usOptions *
        info : int[] *
        ifail : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: m, the number of subfunctions associated with F x.
Constraint: m>0.
n
Type: System..::..Int32
On entry: n, the number of variables.
Constraint: n>0.
nclin
Type: System..::..Int32
On entry: nL, the number of general linear constraints.
Constraint: nclin≥0.
ncnln
Type: System..::..Int32
On entry: nN, the number of nonlinear constraints.
Constraint: ncnln≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥nclin
Note: the second dimension of the array a must be at least n if nclin>0, and at least 1 otherwise.
On entry: the matrix AL of general linear constraints in (1). That is, the ith row contains the coefficients of the ith general linear constraint, for i=1,2,…,nclin.
If nclin=0, the array a is not referenced.
bl
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin+ncnln]
On entry: bl must contain the lower bounds and bu the upper bounds for all the constraints in the following order. The first n elements of each array must contain the bounds on the variables, the next nL elements the bounds for the general linear constraints (if any) and the next nN elements the bounds for the general nonlinear constraints (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j-1]≤-bigbnd, and to specify a nonexistent upper bound (i.e., uj=+∞), set bu[j-1]≥bigbnd; the default value of bigbnd is 1020, but this may be changed by the optional parameter Infinite Bound Size. To specify the jth constraint as an equality, set bl[j-1]=bu[j-1]=β, say, where β<bigbnd.
Constraints:
  • bl[j-1]≤bu[j-1], for j=1,2,…,n+nclin+ncnln;
  • if bl[j-1]=bu[j-1]=β, β<bigbnd.
bu
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin+ncnln]
On entry: bl must contain the lower bounds and bu the upper bounds for all the constraints in the following order. The first n elements of each array must contain the bounds on the variables, the next nL elements the bounds for the general linear constraints (if any) and the next nN elements the bounds for the general nonlinear constraints (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j-1]≤-bigbnd, and to specify a nonexistent upper bound (i.e., uj=+∞), set bu[j-1]≥bigbnd; the default value of bigbnd is 1020, but this may be changed by the optional parameter Infinite Bound Size. To specify the jth constraint as an equality, set bl[j-1]=bu[j-1]=β, say, where β<bigbnd.
Constraints:
  • bl[j-1]≤bu[j-1], for j=1,2,…,n+nclin+ncnln;
  • if bl[j-1]=bu[j-1]=β, β<bigbnd.
y
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: the coefficients of the constant vector y of the objective function.
confun
Type: NagLibrary..::..E05..::..E05US_CONFUN
confun must calculate the vector c x of nonlinear constraint functions and (optionally) its Jacobian (=∂c∂x) for a specified n-element vector x. If there are no nonlinear constraints (i.e., ncnln=0), confun will never be called by e05us and confun may be the dummy method E04UDM. (E04UDM is included in the NAG Library.) If there are nonlinear constraints, the first call to confun will occur before the first call to objfun.

A delegate of type E05US_CONFUN.

confun should be tested separately before being used in conjunction with e05us. See also the description of the optional parameter Verify.
objfun
Type: NagLibrary..::..E05..::..E05US_OBJFUN
objfun must calculate either the ith element of the vector f x=f 1 x,f 2 x,…,fm x T or all m elements of f x and (optionally) its Jacobian (=∂f∂x) for a specified n-element vector x.

A delegate of type E05US_OBJFUN.

objfun should be tested separately before being used in conjunction with e05us. See also the description of the optional parameter Verify.
npts
Type: System..::..Int32
On entry: the number of different starting points to be generated and used. The more points used, the more likely that the best returned solution will be a global minimum.
Constraint: 1≤nb≤npts.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥n
Note: the second dimension of the array x must be at least nb.
On exit: x[j-1,i-1] contains the final estimate of the ith solution, for j=1,2,…,n.
start
Type: NagLibrary..::..E05..::..E05US_START
start must calculate the npts starting points to be used by the local optimizer. If you do not wish to write a method specific to your problem then E05UCZ may be used as the actual argument. E05UCZ is supplied in the NAG Library and uses the NAG quasi-random number generators to distribute starting points uniformly across the domain. It is affected by the value of repeat1.

A delegate of type E05US_START.

repeat1
Type: System..::..Boolean
On entry: is passed as an argument to start and may be used to initialize a random number generator to a repeatable, or non-repeatable, sequence. See [Further Comments] for more detail.
nb
Type: System..::..Int32
On entry: the number of solutions to be returned. The method saves up to nb local minima ordered by increasing value of the final objective function. If the defining criterion for ‘best solution’ is only that the value of the objective function is as small as possible then nb should be set to 1. However, if you want to look at other solutions that may have desirable properties then setting nb>1 will produce nb local minima, ordered by increasing value of their objective functions at the minima.
Constraint: 1≤nb≤npts.
objf
Type: array< System..::..Double >[]()[][]
An array of size [nb]
On exit: objf[i-1] contains the value of the objective function at the final iterate for the ith solution.
f
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [m, dim2]
Note: the second dimension of the array f must be at least nb.
On exit: f[j-1,i-1] contains the value of the jth function fj at the final iterate, for j=1,2,…,m, for the ith solution, for i=1,2,…,nb.
fjac
Type: array< System..::..Double ,3>[,](,)[,][,]
An array of size [dim1, sdfjac, dim3]
Note: dim1 must satisfy the constraint: dim1≥m
Note: the last dimension of the array fjac must be at least nb.
On exit: for the ith returned solution, the Jacobian matrix of the functions f 1,f 2,…,fm at the final iterate, i.e., fjac[k-1,j-1,i-1] contains the partial derivative of the kth function with respect to the jth variable, for k=1,2,…,m, j=1,2,…,n and i=1,2,…,nb. (See also the discussion of parameter fjsl under objfun.)
sdfjac
Type: System..::..Int32
the second dimension of the array fjac.
On entry: the second dimension of the array fjac as declared in the (sub)program from which e05us is called.
Constraint: sdfjac≥n.
iter
Type: array< System..::..Int32 >[]()[][]
An array of size [nb]
On exit: iter[i-1] contains the number of major iterations performed to obtain the ith solution. If less than nb solutions are returned then iter[nb-1] contains the number of starting points that have resulted in a converged solution. If this is close to npts then this might be indicative that fewer than nb local minima exist.
c
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥ncnln
Note: the second dimension of the array c must be at least nb.
On exit: if ncnln>0, c[j-1,i-1] contains the value of the jth nonlinear constraint function cj at the final iterate, for the ith solution, for j=1,2,…,ncnln.
If ncnln=0, the array c is not referenced.
cjac
Type: array< System..::..Double ,3>[,](,)[,][,]
An array of size [dim1, sdcjac, dim3]
Note: dim1 must satisfy the constraint: dim1≥ncnln
Note: the last dimension of the array cjac must be at least nb.
On exit: if ncnln>0, cjac contains the Jacobian matrices of the nonlinear constraint functions at the final iterate for each of the returned solutions, i.e., cjac[k-1,j-1,i-1] contains the partial derivative of the kth constraint function with respect to the jth variable, for k=1,2,…,ncnln and j=1,2,…,n, for the ith solution. (See the discussion of parameter cjsl under confun.)
If ncnln=0, the array cjac is not referenced.
sdcjac
Type: System..::..Int32
the second dimension of the array cjac.
On entry: the second dimension of the array cjac as declared in the (sub)program from which e05us is called.
Constraint: if ncnln>0, sdcjac≥n.
clamda
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥n+nclin+ncnln
Note: the second dimension of the array clamda must be at least nb.
On exit: the values of the QP multipliers from the last QP subproblem solved for the ith solution. clamda[j-1,i-1] should be non-negative if istate[j-1,i-1]=1 and non-positive if istate[j-1,i-1]=2.
istate
Type: array< System..::..Int32 ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥n+nclin+ncnln
Note: the second dimension of the array istate must be at least nb.
On exit: istate[j-1,i-1] contains the status of the constraints in the QP working set for the ith solution. The significance of each possible value of istate[j-1,i-1] is as follows:
istate[j-1,i-1] | Meaning
-0 | The constraint is satisfied to within the feasibility tolerance, but is not in the QP working set.
-1 | This inequality constraint is included in the QP working set at its lower bound.
-2 | This inequality constraint is included in the QP working set at its upper bound.
-3 | This constraint is included in the QP working set as an equality. This value of istate can occur only when bl[j-1]=bu[j-1].
options
Type: NagLibrary..::..E05..::..e05usOptions
An Object of type E05.e05usOptions. Used to configure optional parameters to this method.
info
Type: array< System..::..Int32 >[]()[][]
An array of size [nb]
On exit: if ifail=0, info[i-1] does not contain an error value returned by e04us .
If ifail=8 on exit, then not all nb solutions have been found, and info[nb-1] contains the number of solutions actually found.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The local minimization method is (E04USA not in this release). The problem is assumed to be stated in the following form:
minimize x∈Rn​ ​F x=12∑i=1 m yi-fi x 2  subject to  l≤xAL xc x≤u, (1)
where F x (the objective function) is a nonlinear function which can be represented as the sum of squares of m subfunctions y 1-f 1 x,y 2-f 2 x,…,ym-fm x, the yi are constant, AL is an nL by n constant linear constraint matrix, and c x is an nN element vector of nonlinear constraint functions. (The matrix AL and the vector c x may be empty.) The objective function and the constraint functions are assumed to be smooth, i.e., at least twice-continuously differentiable. (This method will usually solve (1) if any isolated discontinuities are away from the solution.)
e05us solves a user-specified number of local optimization problems with different starting points. You may specify the starting points via the method start. If a random number generator is used to generate the starting points then the parameter repeat1 allows you to specify whether a repeatable set of points are generated or whether different starting points are generated on different calls. The resulting local minima are ordered and the best nb results returned in order of ascending values of the resulting objective function values at the minima. Thus the value returned in position 1 will be the best result obtained. If a sufficiently high number of different points are chosen then this is likely to be the global minimum.

References

Gill P E, Murray W and Wright M H (1981) Practical Optimization Academic Press
Hock W and Schittkowski K (1981) Test Examples for Nonlinear Programming Codes. Lecture Notes in Economics and Mathematical Systems 187 Springer–Verlag

Error Indicators and Warnings

Note: e05us may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA, LDX, LDFJAC, LDC, LDCJAC, LDCLDA, LISTAT) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
An input value is incorrect. One, or more, of the following requirements are violated:
  • listat≥n+nclin+ncnln;
  • ldc≥ncnln;
  • sdcjac≥n and ncnln>0;
  • ldx≥n;
  • m>0;
  • sdcjac≥1 and ncnln=0;
  • ldclda≥n+nclin+ncnln;
  • _ldr≥n;
  • _sdr≥n;
  • n>0;
  • nclin≥0;
  • ncnln≥0;
  • lda≥nclin;
  • ldcjac≥ncnln;
  • ldfjac≥m;
  • bl[i-1]≤bu[i-1] for all i;
  • sdfjac≥n;
  • nb<1;
  • nb>npts.
Set ifail=-1 and re-enter e05us for more detailed information.
ifail=2
e05us has terminated without finding any solutions. The majority of calls to the local optimizer have failed to find a feasible point for the linear constraints and bounds, which means that either no feasible point exists for the given value of the optional parameter Linear Feasibility Tolerance (default value x02aj, the square root of the machine precision, or no feasible point could be found in the number of iterations specified by the optional parameter Minor Iteration Limit. You should check that there are no constraint redundancies. If the data for the constraints are accurate only to an absolute precision σ, you should ensure that the value of the optional parameter Linear Feasibility Tolerance is greater than σ. For example, if all elements of AL are of order unity and are accurate to only three decimal places, Linear Feasibility Tolerance should be at least 10-3.
ifail=3
e05us has failed to find any solutions. The majority of local optimizations could not find a feasible point for the nonlinear constraints. The problem may have no feasible solution. This behaviour will occur if there is no feasible point for the nonlinear constraints. (However, there is no general test that can determine whether a feasible point exists for a set of nonlinear constraints.)
ifail=4
e05us has failed to find any solutions. The majority of local optimizations have failed because the limiting number of iterations have been reached.
ifail=5
This should not occur. Please contact NAG.
ifail=7
The user-supplied derivatives of the objective function and/or nonlinear constraints appear to be incorrect.
Large errors were found in the derivatives of the objective function and/or nonlinear constraints. This value of ifail will occur if the verification process indicated that at least one gradient or Jacobian element had no correct figures. You should refer to or enable the printed output to determine which elements are suspected to be in error.
As a first-step, you should check that the code for the objective and constraint values is correct – for example, by computing the function at a point where the correct value is known. However, care should be taken that the chosen point fully tests the evaluation of the function. It is remarkable how often the values x=0 or x=1 are used to test function evaluation procedures, and how often the special properties of these numbers make the test meaningless.
Special care should be used in this test if computation of the objective function involves subsidiary data communicated in storage, including iuser and ruser in a multithreaded environment. Although the first evaluation of the function may be correct, subsequent calculations may be in error because some of the subsidiary data has accidentally been overwritten.
Gradient checking will be ineffective if the objective function uses information computed by the constraints, since they are not necessarily computed before each function evaluation.
Errors in programming the function may be quite subtle in that the function value is almost correct. For example, the function may not be accurate to full precision because of the inaccurate calculation of a subsidiary quantity, or the limited accuracy of data upon which the function depends. A common error on machines where numerical calculations are usually performed in double precision is to include even one single precision constant in the calculation of the function; since some compilers do not convert such constants to double precision, half the correct figures may be lost by such a seemingly trivial error.
ifail=8
Not all nb solutions have been found. info[nb-1] contains the number actually found.
ifail=9
You terminated the computation by setting mode<0 in start.
If E05UCZ has been used as the actual argument for start then the message displayed, when ifail=0 or -1 on entry to e05us, will have the following meaning:
-998 | – failure to allocate space, a smaller value of npts should be tried;
-997 | – an internal error has occurred. Please contact NAG for assistance.
ifail=10
Failed to initialize optional parameter arrays.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

If ifail=0 on exit and the value of info[i-1]=0, then the vector returned in the array x for solution i is an estimate of the solution to an accuracy of approximately Optimality Tolerance.

Parallelism and Performance

None.

Further Comments

You should be wary of requesting much intermediate output from the local optimizer, since large volumes may be produced if npts is large.
The auxiliary routine E05UCZ makes use of the NAG quasi-random Sobol generator (g05yl and g05ym). If E05UCZ is used as the actual argument for start and repeat1=false then a randomly chosen value for iskip is used, otherwise iskip is set to 100. If repeat1 is set to false and the program is executed several times, each time producing the same best answer, then there is increased probability that this answer is a global minimum. However, if it is important that identical results be obtained on successive runs, then repeat1 should be set to true.

Description of the Printed Output

See [Description of the Printed Output] in e04us.

Example

This example is based on Problem 57 in Hock and Schittkowski (1981) and involves the minimization of the sum of squares function
F x=12∑i=1 44 yi-fi x 2,
where
fi x=x 1+0.49-x 1 e-x 2 ai-8
and
iyiaiiyiai10.498230.412220.498240.402230.4810250.422440.4710260.402450.4810270.402460.4710280.412670.4612290.402680.4612300.412690.4512310.4128100.4312320.4028110.4514330.4030120.4314340.4030130.4314350.3830140.4416360.4132150.4316370.4032160.4316380.4034170.4618390.4136180.4518400.3836190.4220410.4038200.4220420.4038210.4320430.3940220.4122440.3942
subject to the bounds
x 1≥-0.4x 2≥-4.0
to the general linear constraint
x 1+x 2≥1.0
and to the nonlinear constraint
0.49 x 2-x 1x 2≥0.09.
The optimal solution (to five figures) is
x*=0.41995,1.28484 T,
and F x*=0.01423. The nonlinear constraint is active at the solution.

Example program (C#): e05use.cs

Example program data: e05use.d

Example program results: e05use.r

Algorithmic Details

See [Algorithmic Details] in e04us.

Description of Monitoring Information

See [Description of Monitoring Information] in e04us.

See Also

E05 Class
E05 Members


F01 Class

[image]

NAG Library for .NET Release 2
F01 Class
Members See Also Send Feedback
This chapter provides facilities for four types of problem:
(i) | Matrix Inversion
(ii) | Matrix Factorizations
(iii) | Matrix Arithmetic and Manipulation
(iv) | Matrix Functions
These problems are discussed separately in [Matrix Inversion], [Matrix Factorizations], [Matrix Arithmetic and Manipulation] and [Matrix Functions].

Syntax

C#
public static class F01
Visual Basic
Public NotInheritable Class F01
Visual C++
public ref class F01 abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type F01 =  class end

Background to the Problems

Matrix Inversion

(i) Nonsingular square matrices of order n.
If A, a square matrix of order n, is nonsingular (has rank n), then its inverse X exists and satisfies the equations AX=XA=I (the identity or unit matrix).
It is worth noting that if AX-I=R, so that R is the ‘residual’ matrix, then a bound on the relative error is given by R, i.e.,
X-A-1A-1≤R.
(ii) General real rectangular matrices.
A real matrix A has no inverse if it is square (n by n) and singular (has rank <n), or if it is of shape (m by n) with m≠n, but there is a Generalized or Pseudo-inverse A+ which satisfies the equations
A A+A=A,  A+A A+=A+,  A A+T=A A+,  A+A T=A+A
(which of course are also satisfied by the inverse X of A if A is square and nonsingular).
(a) if m≥n and rank A=n then A can be factorized using a QR factorization, given by
A=Q R0,
where Q is an m by m orthogonal matrix and R is an n by n, nonsingular, upper triangular matrix. The pseudo-inverse of A is then given by
A+=R-1Q~T,
where Q~ consists of the first n columns of Q.
(b) if m≤n and rank A=m then A can be factorized using an RQ factorization, given by
A=R 0 QT
where Q is an n by n orthogonal matrix and R is an m by m, nonsingular, upper triangular matrix. The pseudo-inverse of A is then given by
A+=Q~R-1,
where Q~ consists of the first m columns of Q.
(c) if m≥n and rank A=r≤n then A can be factorized using a QR factorization, with column interchanges, as
A=Q R0 PT,
where Q is an m by m orthogonal matrix, R is an r by n upper trapezoidal matrix and P is an n by n permutation matrix. The pseudo-inverse of A is then given by
A+=P RTR RT-1Q~T,
where Q~ consists of the first r columns of Q.
(d) if rank A=r≤k=min m,n, then A can be factorized as the singular value decomposition
A=UΣ VT,
where U is an m by m orthogonal matrix, V is an n by n orthogonal matrix and Σ is an m by n diagonal matrix with non-negative diagonal elements σ. The first k columns of U and V are the left- and right-hand singular vectors of A respectively and the k diagonal elements of Σ are the singular values of A. Σ may be chosen so that
σ 1≥σ 2≥⋯≥σk≥0
and in this case if rank A=r then
σ 1≥σ 2≥⋯≥σr>0,  σ r+1=⋯=σk=0.
If U~ and V~ consist of the first r columns of U and V respectively and Σ~ is an r by r diagonal matrix with diagonal elements σ 1,σ 2,…,σr then A is given by
A=U~Σ~V~T
and the pseudo-inverse of A is given by
A+=V~Σ~-1U~T.
Notice that
AT A=V ΣT Σ VT
which is the classical eigenvalue (spectral) factorization of AT A.
(e) if A is complex then the above relationships are still true if we use ‘unitary’ in place of ‘orthogonal’ and conjugate transpose in place of transpose. For example, the singular value decomposition of A is
A=UΣ VH,
where U and V are unitary, VH the conjugate transpose of V and Σ is as in (d) above.

Matrix Factorizations

The methods in this section perform matrix factorizations which are required for the solution of systems of linear equations with various special structures. A few methods which perform associated computations are also included.
Other methods for matrix factorizations are to be found in F07 class F08 class (F11 not in this release).
This section also contains a few methods associated with eigenvalue problems (see (F02 not in this release)). (Historical note: this section used to contain many more such methods, but they have now been superseded by methods in F08 class.)

Matrix Arithmetic and Manipulation

The intention of methods in this section (sub-chapters F01C, F01V and F01Z) is to cater for some of the commonly occurring operations in matrix manipulation, e.g., transposing a matrix or adding part of one matrix to another, and for conversion between different storage formats, e.g., conversion between rectangular band matrix storage and packed band matrix storage. For vector or matrix-vector or matrix-matrix operations refer to F06 class (F16 not in this release).

Matrix Functions

Given a square matrix A, the matrix function f A is a matrix with the same dimensions as A which provides a generalization of the scalar function f.
If A has a full set of eigenvectors V then A can be factorized as
A=VD V-1,
where D is the diagonal matrix whose diagonal elements, di, are the eigenvalues of A. f A is given by
f A=Vf D V-1,
where f D is the diagonal matrix whose ith diagonal element is f di.
In general, A may not have a full set of eigenvectors. The matrix function can then be defined via a Cauchy integral. For A∈ℂ n×n,
f A=1 2 πi∫Γ f z zI-A-1 dz,
where Γ is a closed contour surrounding the eigenvalues of A, and f is analytic within Γ.
Some matrix functions are defined implicitly. A matrix logarithm is a solution X to the equation
eX=A.
In general X is not unique, but if A has no eigenvalues on the closed negative real line then a unique principal logarithm exists whose eigenvalues have imaginary part between π and -π. Similarly, a matrix square root is a solution X to the equation
X 2=A.
If A has no eigenvalues on the closed negative real line then a unique principal square root exists with eigenvalues in the right half-plane. If A has a vanishing eigenvalue then log A cannot be computed. If the vanishing eigenvalue is defective (its algebraic multiplicity exceeds its geometric multiplicity, or equivalently it occurs in a Jordan block of size greater than 1) then the square root cannot be computed. If the vanishing eigenvalue is semisimple (its algebraic and geometric multiplicities are equal, or equivalently it occurs only in Jordan blocks of size 1) then a square root can be computed.
Algorithms for computing matrix functions are usually tailored to a specific function. Currently F01 class contains routines for calculating the exponential, logarithm, sine, cosine, sinh, cosh, square root and general real power of both real and complex matrices. In addition there are routines to compute a general function of real symmetric and complex Hermitian matrices and a general function of general real and complex matrices.
The Fréchet derivative of a matrix function f A in the direction of the matrix E is the linear function mapping E to Lf A,E such that
f A+E-f A-Lf A,E=O E.
The Fréchet derivative measures the first-order effect on f A of perturbations in A. F01 class contains methods for calculating the Fréchet derivative of the exponential, logarithm and real powers of both real and complex matrices.
The condition number of a matrix function is a measure of its sensitivity to perturbations in the data. The absolute condition number measures these perturbations in an absolute sense, and is defined by
condabs f,A:=lim ε→0sup E→0 f A+E-f A ε.
The relative condition number, which is usually of more interest, measures these perturbations in a relative sense, and is defined by
condrel f,A=condabs f,A Af A.
The absolute and relative condition numbers can be expressed in terms of the norm of the Fréchet derivative by
condabs f,A=max E≠0 L A,EE,
condrel f,A=Af A max E≠0 L A,EE.
F01 class contains routines for calculating the condition number of the matrix exponential, logarithm, sine, cosine, sinh, cosh, square root and general real power of both real and complex matrices. It also contains routines for estimating the condition number of a general function of a real or complex matrix.

Recommendations on Choice and Use of Available Methods

Matrix Inversion

Note: before using any method for matrix inversion, consider carefully whether it is really needed.
Although the solution of a set of linear equations Ax=b can be written as x=A-1 b, the solution should never be computed by first inverting A and then computing A-1 b; the methods in (F04 not in this release) F07 class should always be used to solve such sets of equations directly; they are faster in execution, and numerically more stable and accurate. Similar remarks apply to the solution of least squares problems which again should be solved by using the methods in (F04 not in this release) F08 class rather than by computing a pseudo-inverse.
(a) Nonsingular square matrices of order n
This chapter describes techniques for inverting a general real matrix A and matrices which are positive definite (have all eigenvalues positive) and are either real and symmetric or complex and Hermitian. It is wasteful and uneconomical not to use the appropriate method when a matrix is known to have one of these special forms. A general method must be used when the matrix is not known to be positive definite. In most methods the inverse is computed by solving the linear equations A xi=ei, for i=1,2,…,n, where ei is the ith column of the identity matrix.
Methods are given for calculating the approximate inverse, that is solving the linear equations just once, and also for obtaining the accurate inverse by successive iterative corrections of this first approximation. The latter, of course, are more costly in terms of time and storage, since each correction involves the solution of n sets of linear equations and since the original A and its LU decomposition must be stored together with the first and successively corrected approximations to the inverse. In practice the storage requirements for the ‘corrected’ inverse methods are about double those of the ‘approximate’ inverse methods, though the extra computer time is not prohibitive since the same matrix and the same LU decomposition is used in every linear equation solution.
Despite the extra work of the ‘corrected’ inverse methods they are superior to the ‘approximate’ inverse methods. A correction provides a means of estimating the number of accurate figures in the inverse or the number of ‘meaningful’ figures relating to the degree of uncertainty in the coefficients of the matrix.
The residual matrix R=AX-I, where X is a computed inverse of A, conveys useful information. Firstly R is a bound on the relative error in X and secondly R<12 guarantees the convergence of the iterative process in the ‘corrected’ inverse methods.
The decision trees for inversion show which methods in (F04 not in this release) and F07 class should be used for the inversion of other special types of matrices not treated in the chapter.
(b) General real rectangular matrices
For real matrices (F08AEF not in this release) and (F01QJF not in this release) return QR and RQ factorizations of A respectively and f08bf returns the QR factorization with column interchanges. The corresponding complex methods are (F08ASF not in this release), (F01RJF not in this release) and (F08BTF not in this release) respectively. Methods are also provided to form the orthogonal matrices and transform by the orthogonal matrices following the use of the above methods. (F01QGF not in this release) (F01RGF not in this release) form the RQ factorization of an upper trapezoidal matrix for the real and complex cases respectively.
(F01BLF not in this release) uses the QR factorization as described in [Matrix Inversion](ii)(a) and is the only method that explicitly returns a pseudo-inverse. If m≥n, then the method will calculate the pseudo-inverse A+ of the matrix A. If m<n, then the n by m matrix AT should be used. The method will calculate the pseudo-inverse Z=AT+=A+T of AT and the required pseudo-inverse will be ZT. The method also attempts to calculate the rank, r, of the matrix given a tolerance to decide when elements can be regarded as zero. However, should this method fail due to an incorrect determination of the rank, the singular value decomposition method (described below) should be used.
f08kb and f08kp compute the singular value decomposition as described in [Background to the Problems] for real and complex matrices respectively. If A has rank r≤k=min m,n then the k-r smallest singular values will be negligible and the pseudo-inverse of A can be obtained as A+=V Σ-1UT as described in [Background to the Problems]. If the rank of A is not known in advance it can be estimated from the singular values (see [Matrix Functions] in the F04 class Chapter Introduction). In the real case with m≥n, (F02WDF not in this release) provides details of the QR factorization or the singular value decomposition depending on whether or not A is of full rank and for some problems provides an attractive alternative to f08kb. For large sparse matrices, leading terms in the singular value decomposition can be computed using methods from (F12 not in this release).

Matrix Factorizations

Each of these methods serves a special purpose required for the solution of sets of simultaneous linear equations or the eigenvalue problem. For further details you should consult [Recommendations on Choice and Use of Available Methods] or [Decision Trees] in the F02 class Chapter Introduction or [Recommendations on Choice and Use of Available Methods] or [Decision Trees] in the F04 class Chapter Introduction.
(F01BRF not in this release) (F01BSF not in this release) are provided for factorizing general real sparse matrices. A more recent algorithm for the same problem is available through (F11MEF not in this release). For factorizing real symmetric positive definite sparse matrices, see (F11JAF not in this release). These methods should be used only when A is not banded and when the total number of nonzero elements is less than 10% of the total number of elements. In all other cases either the band methods or the general methods should be used.

Matrix Arithmetic and Manipulation

The methods in the F01C section are designed for the general handling of m by n matrices. Emphasis has been placed on flexibility in the parameter specifications and on avoiding, where possible, the use of internally declared arrays. They are therefore suited for use with large matrices of variable row and column dimensions. Methods are included for the addition and subtraction of sub-matrices of larger matrices, as well as the standard manipulations of full matrices. Those methods involving matrix multiplication may use additional-precision arithmetic for the accumulation of inner products. See also F06 class.
The methods in the F01V (LAPACK) and F01Z section are designed to allow conversion between full storage format and one of the packed storage schemes required by some of the methods in (F02 not in this release) (F04 not in this release) F06 class F07 class F08 class.

NAG Names and LAPACK Names

Methods with NAG name beginning F01V may be called either by their NAG names or by their LAPACK names. When using the NAG Library, the double precision form of the LAPACK name must be used (beginning with D- or Z-).
References to F01 class methods in the manual normally include the LAPACK double precision names, for example, f01ve.
The LAPACK method names follow a simple scheme (which is similar to that used for the BLAS in F06 class). Most names have the structure XYYTZZ, where the components have the following meanings:
– the initial letter, X, indicates the data type (real or complex) and precision:
  • S – real, single precision (in Fortran, 4 byte length REAL)
  • D – real, double precision (in Fortran, 8 byte length REAL)
  • C – complex, single precision (in Fortran, 8 byte length COMPLEX)
  • Z – complex, double precision (in Fortran, 16 byte length COMPLEX)
– the fourth letter, T, indicates that the method is performing a storage scheme transformation (conversion)
– the letters YY indicate the original storage scheme used to store a triangular part of the matrix A, while the letters ZZ indicate the target storage scheme of the conversion (YY cannot equal ZZ since this would do nothing):
  • TF – Rectangular Full Packed Format (RFP)
  • TP – Packed Format
  • TR – Full Format

Matrix Functions

(F01ECF not in this release) f01fc compute the matrix exponential, eA, of a real and complex square matrix A respectively. If estimates of the condition number of the matrix exponential are required then (F01JGF not in this release) (F01KGF not in this release) should be used. If Fréchet derivatives are required then (F01JHF not in this release) (F01KHF not in this release) should be used.
f01ed and f01fd compute the matrix exponential, eA, of a real symmetric and complex Hermitian matrix respectively. If the matrix is real symmetric, or complex Hermitian then it is recommended that f01ed, or f01fd be used as they are more efficient and, in general, more accurate than (F01ECF not in this release) f01fc.
(F01EJF not in this release) (F01FJF not in this release) compute the principal matrix logarithm, log A, of a real and complex square matrix A respectively. If estimates of the condition number of the matrix logarithm are required then (F01JJF not in this release) (F01KJF not in this release) should be used. If Fréchet derivatives are required then (F01JKF not in this release) (F01KKF not in this release) should be used.
(F01EKF not in this release) (F01FKF not in this release) compute the matrix exponential, sine, cosine, sinh or cosh of a real and complex square matrix A respectively. If the matrix exponential is required then it is recommended that (F01ECF not in this release) f01fc be used as they are, in general, more accurate than (F01EKF not in this release) (F01FKF not in this release). If estimates of the condition number of the matrix function are required then (F01JAF not in this release) (F01KAF not in this release) should be used.
(F01ELF not in this release) (F01EMF not in this release) compute the matrix function, f A, of a real square matrix. (F01FLF not in this release) (F01FMF not in this release) compute the matrix function of a complex square matrix. The derivatives of f are required for these computations. (F01ELF not in this release) (F01FLF not in this release) use numerical differentiation to obtain the derivatives of f. (F01EMF not in this release) (F01FMF not in this release) use derivatives you have supplied. If estimates of the condition number are required but you are not supplying derivatives then (F01JBF not in this release) (F01KBF not in this release) should be used. If estimates of the condition number of the matrix function are required and you are supplying derivatives of f, then (F01JCF not in this release) (F01KCF not in this release) should be used.
If the matrix A is real symmetric or complex Hermitian then it is recommended that to compute the matrix function, f A, f01ef and f01ff are used respectively as they are more efficient and, in general, more accurate than (F01ELF not in this release) (F01EMF not in this release) (F01FLF not in this release) (F01FMF not in this release).
(F01GAF not in this release) (F01HAF not in this release) compute the matrix function e tA B for explicitly stored dense real and complex matrices A and B respectively while (F01GBF not in this release) (F01HBF not in this release) compute the same using reverse communication. In the latter case, control is returned to you. You should calculate any required matrix-matrix products and then call the method again.
(F01ENF not in this release) (F01FNF not in this release) compute the principal square root A 1/2 of a real and complex square matrix A respectively. If A is complex and upper triangular then (F01FPF not in this release) should be used. If A is real and upper quasi-triangular then (F01EPF not in this release) should be used. If estimates of the condition number of the matrix square root are required then (F01JDF not in this release) (F01KDF not in this release) should be used.
(F01EQF not in this release) (F01FQF not in this release) compute the matrix power Ap, where p∈ℝ, of real and complex matrices respectively. If estimates of the condition number of the matrix power are required then (F01JEF not in this release) (F01KEF not in this release) should be used. If Fréchet derivatives are required then (F01JFF not in this release) (F01KFF not in this release) should be used.

Decision Trees

The decision trees show the methods in this chapter and in (F04 not in this release), F07 class and F08 class that should be used for inverting matrices of various types. They also show which method should be used to calculate various matrix functions.
(i) Matrix Inversion:

Tree 1

Is A an n by n matrix of rank n? | _ yes | Is A a real matrix? | _ yes | see Tree 2
| |  | no | |
| |  | see Tree 3
no | |
see Tree 4

Tree 2: Inverse of a real n by n matrix of full rank

Is A a band matrix? | _ yes | See Note 1.
no | |
Is A symmetric? | _ yes | Is A positive definite? | _ yes | Do you want guaranteed accuracy? (See Note 2) | _ yes | (F01ABF not in this release)
| |  | | |  | no | |
| |  | | |  | Is one triangle of A stored as a linear array? | _ yes | (F07GDF not in this release) (F07GJF not in this release)
| |  | | |  | no | |
| |  | | |  | (F01ADF not in this release) or (F07FDF not in this release) (F07FJF not in this release)
| |  | no | |
| |  | Is one triangle of A stored as a linear array? | _ yes | (F07PDF not in this release) (F07PJF not in this release)
| |  | no | |
| |  | (F07MDF not in this release) (F07MJF not in this release)
no | |
Is A triangular? | _ yes | Is A stored as a linear array? | _ yes | (F07UJF not in this release)
| |  | no | |
| |  | f07tj
no | |
Do you want guaranteed accuracy? (See Note 2) | _ yes | (F04AEF not in this release)
no | |
(F07ADF not in this release) (F07AJF not in this release)

Tree 3: Inverse of a complex n by n matrix of full rank

Is A a band matrix? | _ yes | See Note 1.
no | |
Is A Hermitian? | _ yes | Is A positive definite? | _ yes | Is one triangle of A stored as a linear array? | _ yes | (F07GRF not in this release) (F07GWF not in this release)
| |  | | |  | no | |
| |  | | |  | (F07FRF not in this release) (F07FWF not in this release)
| |  | no | |
| |  | Is one triangle A stored as a linear array? | _ yes | (F07PRF not in this release) (F07PWF not in this release)
| |  | no | |
| |  | (F07MRF not in this release) (F07MWF not in this release)
no | |
Is A symmetric? | _ yes | Is one triangle of A stored as a linear array? | _ yes | (F07QRF not in this release) (F07QWF not in this release)
| |  | no | |
| |  | (F07NRF not in this release) (F07NWF not in this release)
no | |
Is A triangular? | _ yes | Is A stored as a linear array? | _ yes | (F07UWF not in this release)
| |  | no | |
| |  | (F07TWF not in this release)
no | |
(F07ANF not in this release) or f07ar (F07AWF not in this release)

Tree 4: Pseudo-inverses

Is A a complex matrix? | _ yes | Is A of full rank? | _ yes | Is A an m by n matrix with m<n? | _ yes | (F01RJF not in this release) and (F01RKF not in this release)
| |  | | |  | no | |
| |  | | |  | (F08ASF not in this release) (F08AUF not in this release) or (F08ATF not in this release)
| |  | no | |
| |  | f08kp
no | |
Is A of full rank? | _ yes | Is A an m by n matrix with m<n? | _ yes | (F01QJF not in this release) and (F01QKF not in this release)
| |  | no | |
| |  | (F08AEF not in this release) f08ag or (F08AFF not in this release)
no | |
Is A an m by n matrix with m<n? | _ yes | f08kb
no | |
Is reliability more important than efficiency? | _ yes | f08kb
no | |
(F01BLF not in this release)
Note 1: the inverse of a band matrix A does not in general have the same shape as A, and no methods are provided specifically for finding such an inverse. The matrix must either be treated as a full matrix, or the equations AX=B must be solved, where B has been initialized to the identity matrix I. In the latter case, see the decision trees in [Decision Trees] in the F04 class Chapter Introduction.
Note 2: by ‘guaranteed accuracy’ we mean that the accuracy of the inverse is improved by use of the iterative refinement technique using additional precision.
(ii) Matrix Factorizations: see the decision trees in Section in the F02 class and F04 class.
(iii) Matrix Arithmetic and Manipulation: not appropriate.
(iv) Matrix Functions:

Tree 5: Matrix functions f A of an n by n real matrix A

Is e tA B required? | _ yes | Is A stored in dense format? | _ yes | (F01GAF not in this release)
| |  | no | |
| |  | (F01GBF not in this release)
no | |
Is A real symmetric? | _ yes | Is e A required? | _ yes | f01ed
| |  | no | |
| |  | f01ef
no | |
Is cos A or cosh A or sin A or sinh A required? | _ yes | Is the condition number of the matrix function required? | _ yes | (F01JAF not in this release)
| |  | no | |
| |  | (F01EKF not in this release)
no | |
Is log A required? | _ yes | Is the condition number of the matrix logarithm required? | _ yes | (F01JJF not in this release)
| |  | no | |
| |  | Is the Fréchet derivative of the matrix logarithm required? | _ yes | (F01JKF not in this release)
| |  | no | |
| |  | (F01EJF not in this release)
no | |
Is exp A required? | _ yes | Is the condition number of the matrix exponential required? | _ yes | (F01JGF not in this release)
| |  | no | |
| |  | Is the Fréchet derivative of the matrix exponential required? | _ yes | (F01JHF not in this release)
| |  | no | |
| |  | (F01ECF not in this release)
no | |
Is A 1/2 required? | _ yes | Is the condition number of the matrix square root required? | _ yes | (F01JDF not in this release)
| |  | no | |
| |  | Is the matrix upper quasi-triangular? | _ yes | (F01EPF not in this release)
| |  | no | |
| |  | (F01ENF not in this release)
no | |
Is Ap required? | _ yes | Is the condition number of the matrix power required? | _ yes | (F01JEF not in this release)
| |  | no | |
| |  | Is the Fréchet derivative of the matrix power required? | _ yes | (F01JFF not in this release)
| |  | no | |
| |  | (F01EQF not in this release)
no | |
f A will be computed. Will derivatives of f be supplied by the user? | _ yes | Is the condition number of the matrix function required? | _ yes | (F01JCF not in this release)
| |  | no | |
| |  | (F01EMF not in this release)
no | |
Is the condition number of the matrix function required? | _ yes | (F01JBF not in this release)
no | |
(F01ELF not in this release)

Tree 6: Matrix functions f A of an n by n complex matrix A

Is e tA B required? | _ yes | Is A stored in dense format? | _ yes | (F01HAF not in this release)
| |  | no | |
| |  | (F01HBF not in this release)
no | |
Is A complex Hermitian? | _ yes | Is e A required? | _ yes | f01fd
| |  | no | |
| |  | f01ff
no | |
Is cos A or cosh A or sin A or sinh A required? | _ yes | Is the condition number of the matrix function required? | _ yes | (F01KAF not in this release)
| |  | no | |
| |  | (F01FKF not in this release)
no | |
Is log A required? | _ yes | Is the condition number of the matrix logarithm required? | _ yes | (F01KJF not in this release)
| |  | no | |
| |  | Is the Fréchet derivative of the matrix logarithm required? | _ yes | (F01KKF not in this release)
| |  | no | |
| |  | (F01FJF not in this release)
no | |
Is exp A required? | _ yes | Is the condition number of the matrix exponential required? | _ yes | (F01KGF not in this release)
| |  | no | |
| |  | Is the Fréchet derivative of the matrix exponential required? | _ yes | (F01KHF not in this release)
| |  | no | |
| |  | f01fc
no | |
Is A 1/2 required? | _ yes | Is the condition number of the matrix square root required? | _ yes | (F01KDF not in this release)
| |  | no | |
| |  | Is the matrix upper triangular? | _ yes | (F01FPF not in this release)
| |  | no | |
| |  | (F01FNF not in this release)
no | |
Is Ap required? | _ yes | Is the condition number of the matrix power required? | _ yes | (F01KEF not in this release)
| |  | no | |
| |  | Is the Fréchet derivative of the matrix power required? | _ yes | (F01KFF not in this release)
| |  | no | |
| |  | (F01FQF not in this release)
no | |
f A will be computed. Will derivatives of f be supplied by the user? | _ yes | Is the condition number of the matrix function required? | _ yes | (F01KCF not in this release)
| |  | no | |
| |  | (F01FMF not in this release)
no | |
Is the condition number of the matrix function required? | _ yes | (F01KBF not in this release)
no | |
(F01FLF not in this release)

References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Higham N J (2008) Functions of Matrices: Theory and Computation SIAM, Philadelphia, PA, USA
Wilkinson J H (1965) The Algebraic Eigenvalue Problem Oxford University Press, Oxford
Wilkinson J H (1977) Some recent advances in numerical linear algebra The State of the Art in Numerical Analysis (ed D A H Jacobs) Academic Press
Wilkinson J H and Reinsch C (1971) Handbook for Automatic Computation II, Linear Algebra Springer–Verlag

Inheritance Hierarchy

System..::..Object
NagLibrary..::..F01

See Also

F01 Members


F01 Members

[image] [image]

NAG Library for .NET Release 2
F01 Members
F01 Class Methods See Also Send Feedback

The F01 type exposes the following members.

Methods

Name | Description
f01ed | f01ed computes the matrix exponential, eA, of a real symmetric n by n matrix A.
f01ef | f01ef computes the matrix function, f A, of a real symmetric n by n matrix A. f A must also be a real symmetric matrix.
f01fc | f01fc computes the matrix exponential, eA, of a complex n by n matrix A.
f01fd | f01fd computes the matrix exponential, eA, of a complex Hermitian n by n matrix A.
f01ff | f01ff computes the matrix function, f A, of a complex Hermitian n by n matrix A. f A must also be a complex Hermitian matrix.
f01va | f01va copies a real triangular matrix stored in full format in a two-dimensional array to a standard packed format in a one-dimensional array. Packed storage format is described in [] in the F07 class Chapter Introduction.
f01vb | f01vb copies a complex triangular matrix stored in full format in a two-dimensional array to packed format in a one-dimensional array. Packed storage format is described in [] in the F07 class Chapter Introduction.
f01vc | f01vc unpacks a real triangular matrix, stored in packed format in a one-dimensional array, to full format in a two-dimensional array. Packed storage format is described in [] in the F07 class Chapter Introduction.
f01vd | f01vd unpacks a complex triangular matrix, stored in packed format in a one-dimensional array, to full format in a two-dimensional array. Packed storage format is described in [] in the F07 class Chapter Introduction.
f01ve | f01ve copies a real triangular matrix stored in full format in a two-dimensional array to Rectangular Full Packed (RFP) format. The RFP storage format is described in [] in the F07 class Chapter Introduction.
f01vf | f01vf copies a complex triangular matrix stored full format in a two-dimensional array to Rectangular Full Packed (RFP) format. The RFP storage format is described in [] in the F07 class Chapter Introduction.
f01vg | f01vg unpacks a real triangular matrix stored in Rectangular Full Packed (RFP) format to full format in a two-dimensional array. The RFP storage format is described in [] in the F07 class Chapter Introduction.
f01vh | f01vh unpacks a complex triangular matrix stored in Rectangular Full Packed (RFP) format to full format in a two-dimensional array. The RFP storage format is described in [] in the F07 class Chapter Introduction.
f01vj | f01vj copies a real triangular matrix stored in packed format to Rectangular Full Packed (RFP) format. The RFP storage format is described in [] in the F07 class Chapter Introduction and the packed storage format is described in [] in the F07 class Chapter Introduction.
f01vk | f01vk copies a complex triangular matrix stored in packed format to Rectangular Full Packed (RFP) format. The RFP storage format is described in [] in the F07 class Chapter Introduction and the packed storage format is described in [] in the F07 class Chapter Introduction.
f01vl | f01vl copies a real triangular matrix stored in a Rectangular Full Packed (RFP) format to packed format. The RFP storage format is described in [] in the F07 class Chapter Introduction and the packed storage format is described in [] in the F07 class Chapter Introduction.
f01vm | f01vm copies a complex triangular matrix stored in a Rectangular Full Packed (RFP) format to packed format. The RFP storage format is described in [] in the F07 class Chapter Introduction and the packed storage format is described in [] in the F07 class Chapter Introduction.

See Also

F01 Class


F01 Delegates

[image]

NAG Library for .NET Release 2
F01 Delegates

F01 Delegate Types

  • F01.F01EF_F Delegate
  • F01.F01FF_F Delegate


F01.F01EF_F Delegate

[image]

NAG Library for .NET Release 2
F01..::..F01EF_F Delegate
F01 Class See Also Send Feedback
The method f evaluates f zi at a number of points zi.

Syntax

C#
public delegate void F01EF_F(
    ref int iflag,
    int n,
    double[] x,
    double[] fx
)
Visual Basic
Public Delegate Sub F01EF_F ( _
    ByRef iflag As Integer, _
    n As Integer, _
    x As Double(), _
    fx As Double() _
)
Visual C++
public delegate void F01EF_F(
    int% iflag,
    int n,
    array<double>^ x,
    array<double>^ fx
)
F#
type F01EF_F =
    delegate of
        iflag : int byref *
        n : int *
        x : float[] *
        fx : float[] -> unit

Parameters

iflag
Type: System..::..Int32 %
On entry: iflag will be zero.
On exit: iflag should either be unchanged from its entry value of zero, or may be set nonzero to indicate that there is a problem in evaluating the function f x; for instance f x may not be defined, or may be complex. If iflag is returned as nonzero then f01ef will terminate the computation, with ifail=-6.
n
Type: System..::..Int32
On entry: n, the number of function values required.
x
Type: array< System..::..Double >[]()[][]
On entry: the n points x 1,x 2,…,xn at which the function f is to be evaluated.
fx
Type: array< System..::..Double >[]()[][]
On exit: the n function values. fx[i-1] should return the value f xi, for i=1,2,…,n.

See Also

NagLibrary Namespace
NAG Library Overview
f01ef


F01.F01FF_F Delegate

[image]

NAG Library for .NET Release 2
F01..::..F01FF_F Delegate
F01 Class See Also Send Feedback
The method f evaluates f zi at a number of points zi.

Syntax

C#
public delegate void F01FF_F(
    ref int iflag,
    int n,
    double[] x,
    double[] fx
)
Visual Basic
Public Delegate Sub F01FF_F ( _
    ByRef iflag As Integer, _
    n As Integer, _
    x As Double(), _
    fx As Double() _
)
Visual C++
public delegate void F01FF_F(
    int% iflag,
    int n,
    array<double>^ x,
    array<double>^ fx
)
F#
type F01FF_F =
    delegate of
        iflag : int byref *
        n : int *
        x : float[] *
        fx : float[] -> unit

Parameters

iflag
Type: System..::..Int32 %
On entry: iflag will be zero.
On exit: iflag should either be unchanged from its entry value of zero, or may be set nonzero to indicate that there is a problem in evaluating the function f x; for instance f x may not be defined, or may be complex. If iflag is returned as nonzero then f01ff will terminate the computation, with ifail=-6.
n
Type: System..::..Int32
On entry: n, the number of function values required.
x
Type: array< System..::..Double >[]()[][]
On entry: the n points x 1,x 2,…,xn at which the function f is to be evaluated.
fx
Type: array< System..::..Double >[]()[][]
On exit: the n function values. fx[i-1] should return the value f xi, for i=1,2,…,n.

See Also

NagLibrary Namespace
NAG Library Overview
f01ff


F01 Methods

[image] [image]

NAG Library for .NET Release 2
F01 Methods
F01 Class See Also Send Feedback

The F01 type exposes the following members.

Methods

Name | Description
f01ed | f01ed computes the matrix exponential, eA, of a real symmetric n by n matrix A.
f01ef | f01ef computes the matrix function, f A, of a real symmetric n by n matrix A. f A must also be a real symmetric matrix.
f01fc | f01fc computes the matrix exponential, eA, of a complex n by n matrix A.
f01fd | f01fd computes the matrix exponential, eA, of a complex Hermitian n by n matrix A.
f01ff | f01ff computes the matrix function, f A, of a complex Hermitian n by n matrix A. f A must also be a complex Hermitian matrix.
f01va | f01va copies a real triangular matrix stored in full format in a two-dimensional array to a standard packed format in a one-dimensional array. Packed storage format is described in [] in the F07 class Chapter Introduction.
f01vb | f01vb copies a complex triangular matrix stored in full format in a two-dimensional array to packed format in a one-dimensional array. Packed storage format is described in [] in the F07 class Chapter Introduction.
f01vc | f01vc unpacks a real triangular matrix, stored in packed format in a one-dimensional array, to full format in a two-dimensional array. Packed storage format is described in [] in the F07 class Chapter Introduction.
f01vd | f01vd unpacks a complex triangular matrix, stored in packed format in a one-dimensional array, to full format in a two-dimensional array. Packed storage format is described in [] in the F07 class Chapter Introduction.
f01ve | f01ve copies a real triangular matrix stored in full format in a two-dimensional array to Rectangular Full Packed (RFP) format. The RFP storage format is described in [] in the F07 class Chapter Introduction.
f01vf | f01vf copies a complex triangular matrix stored full format in a two-dimensional array to Rectangular Full Packed (RFP) format. The RFP storage format is described in [] in the F07 class Chapter Introduction.
f01vg | f01vg unpacks a real triangular matrix stored in Rectangular Full Packed (RFP) format to full format in a two-dimensional array. The RFP storage format is described in [] in the F07 class Chapter Introduction.
f01vh | f01vh unpacks a complex triangular matrix stored in Rectangular Full Packed (RFP) format to full format in a two-dimensional array. The RFP storage format is described in [] in the F07 class Chapter Introduction.
f01vj | f01vj copies a real triangular matrix stored in packed format to Rectangular Full Packed (RFP) format. The RFP storage format is described in [] in the F07 class Chapter Introduction and the packed storage format is described in [] in the F07 class Chapter Introduction.
f01vk | f01vk copies a complex triangular matrix stored in packed format to Rectangular Full Packed (RFP) format. The RFP storage format is described in [] in the F07 class Chapter Introduction and the packed storage format is described in [] in the F07 class Chapter Introduction.
f01vl | f01vl copies a real triangular matrix stored in a Rectangular Full Packed (RFP) format to packed format. The RFP storage format is described in [] in the F07 class Chapter Introduction and the packed storage format is described in [] in the F07 class Chapter Introduction.
f01vm | f01vm copies a complex triangular matrix stored in a Rectangular Full Packed (RFP) format to packed format. The RFP storage format is described in [] in the F07 class Chapter Introduction and the packed storage format is described in [] in the F07 class Chapter Introduction.

See Also

F01 Class


f01ed Method

[image]

NAG Library for .NET Release 2
F01..::f01ed Method
F01 Class See Also Send Feedback
f01ed computes the matrix exponential, eA, of a real symmetric n by n matrix A.

Syntax

C#
public static void f01ed(
    string uplo,
    int n,
    double[,] a,
    out int ifail
)
Visual Basic
Public Shared Sub f01ed ( _
    uplo As String, _
    n As Integer, _
    a As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void f01ed(
    String^ uplo,
    int n,
    array<double,2>^ a,
    [OutAttribute] int% ifail
)
F#
static member f01ed :
        uplo : string *
        n : int *
        a : float[,] *
        ifail : int byref -> unit

Parameters

uplo
Type: System..::..String
On entry: indicates whether the upper or lower triangular part of A is stored.
uplo="U"
The upper triangular part of A is stored.
uplo="L"
The lower triangular part of A is stored.
Constraint: uplo="U" or "L".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least n.
On entry: the n by n symmetric matrix A.
  • If uplo="U", the upper triangular part of A must be stored and the elements of the array below the diagonal are not referenced.
  • If uplo="L", the lower triangular part of A must be stored and the elements of the array above the diagonal are not referenced.
On exit: if ifail=0, the upper or lower triangular part of the n by n matrix exponential, eA.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

eA is computed using a spectral factorization of A
A=QD QT,
where D is the diagonal matrix whose diagonal elements, di, are the eigenvalues of A, and Q is an orthogonal matrix whose columns are the eigenvectors of A. eA is then given by
eA=Q eDQT,
where eD is the diagonal matrix whose ith diagonal element is e di. See for example Section 4.5 of Higham (2008).

References

Higham N J (2008) Functions of Matrices: Theory and Computation SIAM, Philadelphia, PA, USA
Moler C B and Van Loan C F (2003) Nineteen dubious ways to compute the exponential of a matrix, twenty-five years later SIAM Rev. 45 3–49

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=-1
On entry, uplo≠"L" or "U".
ifail=-2
On entry, n<0.
ifail=-3
An unexpected internal error occurred when computing the spectral factorization. Please contact NAG.
ifail=-4
On entry, lda<n.
ifail=-999
Allocation of memory failed. The integer allocatable memory required is n, and the real allocatable memory required is approximately n+nb+4×n, where nb is the block size required by f08fa.
ifail=i and ifail>0
The algorithm to compute the spectral factorization failed to converge; i off-diagonal elements of an intermediate tridiagonal form did not converge to zero (see f08fa).
Note: this failure is unlikely to occur.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

For a symmetric matrix A, the matrix eA, has the relative condition number
κ A=A 2,
which is the minimum possible for the matrix exponential and so the computed matrix exponential is guaranteed to be close to the exact matrix. See Section 10.2 of Higham (2008) for details and further discussion.

Parallelism and Performance

None.

Further Comments

The cost of the algorithm is O n 3.
As well as the excellent book cited above, the classic reference for the computation of the matrix exponential is Moler and Van Loan (2003).

Example

This example finds the matrix exponential of the symmetric matrix
A=1234212332124321

Example program (C#): f01ede.cs

Example program data: f01ede.d

Example program results: f01ede.r

See Also

F01 Class
F01 Members


f01ef Method

[image]

NAG Library for .NET Release 2
F01..::f01ef Method
F01 Class See Also Send Feedback
f01ef computes the matrix function, f A, of a real symmetric n by n matrix A. f A must also be a real symmetric matrix.

Syntax

C#
public static void f01ef(
    string uplo,
    int n,
    double[,] a,
    F01..::..F01EF_F f,
    out int iflag,
    out int ifail
)
Visual Basic
Public Shared Sub f01ef ( _
    uplo As String, _
    n As Integer, _
    a As Double(,), _
    f As F01..::..F01EF_F, _
    <OutAttribute> ByRef iflag As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void f01ef(
    String^ uplo,
    int n,
    array<double,2>^ a,
    F01..::..F01EF_F^ f,
    [OutAttribute] int% iflag,
    [OutAttribute] int% ifail
)
F#
static member f01ef :
        uplo : string *
        n : int *
        a : float[,] *
        f : F01..::..F01EF_F *
        iflag : int byref *
        ifail : int byref -> unit

Parameters

uplo
Type: System..::..String
On entry: if uplo="U", the upper triangle of the matrix A is stored.
If uplo="L", the lower triangle of the matrix A is stored.
Constraint: uplo="U" or "L".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least n.
On entry: the n by n symmetric matrix A.
  • If uplo="U", the upper triangular part of A must be stored and the elements of the array below the diagonal are not referenced.
  • If uplo="L", the lower triangular part of A must be stored and the elements of the array above the diagonal are not referenced.
On exit: if ifail=0, the upper or lower triangular part of the n by n matrix function, f A.
f
Type: NagLibrary..::..F01..::..F01EF_F
The method f evaluates f zi at a number of points zi.

A delegate of type F01EF_F.

iflag
Type: System..::..Int32 %
On exit: iflag=0, unless you have set iflag nonzero inside f, in which case iflag will be the value you set and ifail will be set to ifail=-6.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

f A is computed using a spectral factorization of A
A=QD QT,
where D is the diagonal matrix whose diagonal elements, di, are the eigenvalues of A, and Q is an orthogonal matrix whose columns are the eigenvectors of A. f A is then given by
f A=Qf D QT,
where f D is the diagonal matrix whose ith diagonal element is f di. See for example Section 4.5 of Higham (2008). f di is assumed to be real.

References

Higham N J (2008) Functions of Matrices: Theory and Computation SIAM, Philadelphia, PA, USA

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail<0 and ifail≠-999  or  -6
If ifail=-i, the ith argument had an illegal value.
ifail=-6
iflag has been set nonzero by the user.
ifail=-999
Internal memory allocation failed.
The integer allocatable memory required is n, and the real allocatable memory required is approximately n+nb+4×n, where nb is the block size required by f08fa.
ifail=i and ifail>0
The algorithm to compute the spectral factorization failed to converge; i off-diagonal elements of an intermediate tridiagonal form did not converge to zero (see f08fa).
Note: this failure is unlikely to occur.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Provided that f D can be computed accurately then the computed matrix function will be close to the exact matrix function. See Section 10.2 of Higham (2008) for details and further discussion.

Parallelism and Performance

None.

Further Comments

The cost of the algorithm is O n 3 plus the cost of evaluating f D. If λ^i is the ith computed eigenvalue of A, then the user-supplied method f will be asked to evaluate the function f at f λ^i, i=1,2,…,n.
For further information on matrix functions, see Higham (2008).
f01ff can be used to find the matrix function f A for a complex Hermitian matrix A.

Example

This example finds the matrix cosine, cos A, of the symmetric matrix
A=1234212332124321.

Example program (C#): f01efe.cs

Example program data: f01efe.d

Example program results: f01efe.r

See Also

F01 Class
F01 Members


f01fc Method

[image]

NAG Library for .NET Release 2
F01..::f01fc Method
F01 Class See Also Send Feedback
f01fc computes the matrix exponential, eA, of a complex n by n matrix A.

Syntax

C#
public static void f01fc(
    int n,
    Complex[,] a,
    out int ifail
)
Visual Basic
Public Shared Sub f01fc ( _
    n As Integer, _
    a As Complex(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void f01fc(
    int n,
    array<Complex,2>^ a,
    [OutAttribute] int% ifail
)
F#
static member f01fc :
        n : int *
        a : Complex[,] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
a
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥n
Note: the second dimension of the array a must be at least n.
On entry: the n by n matrix A.
On exit: with ifail=0, the n by n matrix exponential eA.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

eA is computed using a Padé approximant and the scaling and squaring method described in Al–Mohy and Higham (2009).

References

Al–Mohy A H and Higham N J (2009) A new scaling and squaring algorithm for the matrix exponential SIAM J. Matrix Anal. 31(3) 970–989
Higham N J (2005) The scaling and squaring method for the matrix exponential revisited SIAM J. Matrix Anal. Appl. 26(4) 1179–1193
Higham N J (2008) Functions of Matrices: Theory and Computation SIAM, Philadelphia, PA, USA
Moler C B and Van Loan C F (2003) Nineteen dubious ways to compute the exponential of a matrix, twenty-five years later SIAM Rev. 45 3–49

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
The linear equations to be solved for the Padé approximant are singular; it is likely that this method has been called incorrectly.
ifail=2
The linear equations to be solved are nearly singular and the Padé approximant probably has no correct figures; it is likely that this method has been called incorrectly.
ifail=3
eA has been computed using an IEEE double precision Padé approximant, although the arithmetic precision is higher than IEEE double precision.
ifail=4
An unexpected internal error has occurred. Please contact NAG.
ifail=-1
On entry, n=value.
Constraint: n≥0.
ifail=-3
On entry, lda=value and n=value.
Constraint: lda≥n.
ifail=-999
Dynamic memory allocation failed.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

For a normal matrix A (for which AH A=A AH) the computed matrix, eA, is guaranteed to be close to the exact matrix, that is, the method is forward stable. No such guarantee can be given for non-normal matrices. See Al–Mohy and Higham (2009) and Section 10.3 of Higham (2008) for details and further discussion.
If estimates of the condition number of the matrix exponential are required then (F01KGF not in this release) should be used.

Parallelism and Performance

None.

Further Comments

The cost of the algorithm is O n 3; see Section 5 of Al–Mohy and Higham (2009). The complex allocatable memory required is approximately 6×n 2.
If the Fréchet derivative of the matrix exponential is required then (F01KHF not in this release) should be used.
As well as the excellent book cited above, the classic reference for the computation of the matrix exponential is Moler and Van Loan (2003).

Example

This example finds the matrix exponential of the matrix
A=1+2 i2+2 i2+2 i2+i3+2 i112+i3+2 i2+2 i12+i3+2 i3+2 i3+2 i1+i.

Example program (C#): f01fce.cs

Example program data: f01fce.d

Example program results: f01fce.r

See Also

F01 Class
F01 Members


f01fd Method

[image]

NAG Library for .NET Release 2
F01..::f01fd Method
F01 Class See Also Send Feedback
f01fd computes the matrix exponential, eA, of a complex Hermitian n by n matrix A.

Syntax

C#
public static void f01fd(
    string uplo,
    int n,
    Complex[,] a,
    out int ifail
)
Visual Basic
Public Shared Sub f01fd ( _
    uplo As String, _
    n As Integer, _
    a As Complex(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void f01fd(
    String^ uplo,
    int n,
    array<Complex,2>^ a,
    [OutAttribute] int% ifail
)
F#
static member f01fd :
        uplo : string *
        n : int *
        a : Complex[,] *
        ifail : int byref -> unit

Parameters

uplo
Type: System..::..String
On entry: if uplo="U", the upper triangle of the matrix A is stored.
If uplo="L", the lower triangle of the matrix A is stored.
Constraint: uplo="U" or "L".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
a
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥n
Note: the second dimension of the array a must be at least n.
On entry: the n by n Hermitian matrix A.
  • If uplo="U", the upper triangular part of A must be stored and the elements of the array below the diagonal are not referenced.
  • If uplo="L", the lower triangular part of A must be stored and the elements of the array above the diagonal are not referenced.
On exit: if ifail=0, the upper or lower triangular part of the n by n matrix exponential, eA.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

eA is computed using a spectral factorization of A
A=QD QH,
where D is the diagonal matrix whose diagonal elements, di, are the eigenvalues of A, and Q is a unitary matrix whose columns are the eigenvectors of A. eA is then given by
eA=Q eDQH,
where eD is the diagonal matrix whose ith diagonal element is e di. See for example Section 4.5 of Higham (2008).

References

Higham N J (2005) The scaling and squaring method for the matrix exponential revisited SIAM J. Matrix Anal. Appl. 26(4) 1179–1193
Higham N J (2008) Functions of Matrices: Theory and Computation SIAM, Philadelphia, PA, USA
Moler C B and Van Loan C F (2003) Nineteen dubious ways to compute the exponential of a matrix, twenty-five years later SIAM Rev. 45 3–49

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail<0 and ifail≠-999
If ifail=-i, the ith argument had an illegal value.
ifail=-999
Allocation of memory failed. The INTEGER allocatable memory required is n, the real allocatable memory required is n and the complex allocatable memory required is approximately n+nb+1×n, where nb is the block size required by f08fn.
ifail=i and ifail>0
The algorithm to compute the spectral factorization failed to converge; i off-diagonal elements of an intermediate tridiagonal form did not converge to zero (see f08fn).
Note: this failure is unlikely to occur.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

For an Hermitian matrix A, the matrix eA, has the relative condition number
κ A=A 2,
which is the minimal possible for the matrix exponential and so the computed matrix exponential is guaranteed to be close to the exact matrix. See Section 10.2 of Higham (2008) for details and further discussion.

Parallelism and Performance

None.

Further Comments

The cost of the algorithm is O n 3.
As well as the excellent book cited above, the classic reference for the computation of the matrix exponential is Moler and Van Loan (2003).

Example

This example finds the matrix exponential of the Hermitian matrix
A=12+2 i3+2 i4+3 i2-2 i12+2 i3+2 i3-2 i2-2 i12+2 i4-3 i3-2 i2-2 i1.

Example program (C#): f01fde.cs

Example program data: f01fde.d

Example program results: f01fde.r

See Also

F01 Class
F01 Members


f01ff Method

[image]

NAG Library for .NET Release 2
F01..::f01ff Method
F01 Class See Also Send Feedback
f01ff computes the matrix function, f A, of a complex Hermitian n by n matrix A. f A must also be a complex Hermitian matrix.

Syntax

C#
public static void f01ff(
    string uplo,
    int n,
    Complex[,] a,
    F01..::..F01FF_F f,
    out int iflag,
    out int ifail
)
Visual Basic
Public Shared Sub f01ff ( _
    uplo As String, _
    n As Integer, _
    a As Complex(,), _
    f As F01..::..F01FF_F, _
    <OutAttribute> ByRef iflag As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void f01ff(
    String^ uplo,
    int n,
    array<Complex,2>^ a,
    F01..::..F01FF_F^ f,
    [OutAttribute] int% iflag,
    [OutAttribute] int% ifail
)
F#
static member f01ff :
        uplo : string *
        n : int *
        a : Complex[,] *
        f : F01..::..F01FF_F *
        iflag : int byref *
        ifail : int byref -> unit

Parameters

uplo
Type: System..::..String
On entry: if uplo="U", the upper triangle of the matrix A is stored.
If uplo="L", the lower triangle of the matrix A is stored.
Constraint: uplo="U" or "L".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
a
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least n.
On entry: the n by n Hermitian matrix A.
  • If uplo="U", the upper triangular part of A must be stored and the elements of the array below the diagonal are not referenced.
  • If uplo="L", the lower triangular part of A must be stored and the elements of the array above the diagonal are not referenced.
On exit: if ifail=0, the upper or lower triangular part of the n by n matrix function, f A.
f
Type: NagLibrary..::..F01..::..F01FF_F
The method f evaluates f zi at a number of points zi.

A delegate of type F01FF_F.

iflag
Type: System..::..Int32 %
On exit: iflag=0, unless you have set iflag nonzero inside f, in which case iflag will be the value you set and ifail will be set to ifail=-6.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

f A is computed using a spectral factorization of A
A=QD QH,
where D is the real diagonal matrix whose diagonal elements, di, are the eigenvalues of A, Q is a unitary matrix whose columns are the eigenvectors of A and QH is the conjugate transpose of Q. f A is then given by
f A=Qf D QH,
where f D is the diagonal matrix whose ith diagonal element is f di. See for example Section 4.5 of Higham (2008). f di is assumed to be real.

References

Higham N J (2008) Functions of Matrices: Theory and Computation SIAM, Philadelphia, PA, USA

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail<0 and ifail≠-999  or  -6
If ifail=-i, the ith argument had an illegal value.
ifail=-6
iflag has been set nonzero by the user.
ifail=-999
Internal memory allocation failed.
The integer allocatable memory required is n, the real allocatable memory required is 4×n-2 and the complex allocatable memory required is approximately n+nb+1×n, where nb is the block size required by f08fn.
ifail=i and ifail>0
The algorithm to compute the spectral factorization failed to converge; i off-diagonal elements of an intermediate tridiagonal form did not converge to zero (see f08fn).
Note: this failure is unlikely to occur.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Provided that f D can be computed accurately then the computed matrix function will be close to the exact matrix function. See Section 10.2 of Higham (2008) for details and further discussion.

Parallelism and Performance

None.

Further Comments

The cost of the algorithm is O n 3 plus the cost of evaluating f D. If λ^i is the ith computed eigenvalue of A, then the user-supplied method f will be asked to evaluate the function f at f λ^i, for i=1,2,…,n.
For further information on matrix functions, see Higham (2008).
f01ef can be used to find the matrix function f A for a real symmetric matrix A.

Example

This example finds the matrix cosine, cos A, of the Hermitian matrix
A=12+i3+2 i4+3 i2-i12+i3+2 i3-2 i2-i12+i4-3 i3-2 i2-i1.

Example program (C#): f01ffe.cs

Example program data: f01ffe.d

Example program results: f01ffe.r

See Also

F01 Class
F01 Members


f01va Method

[image]

NAG Library for .NET Release 2
F01..::f01va Method
F01 Class See Also Send Feedback
f01va copies a real triangular matrix stored in full format in a two-dimensional array to a standard packed format in a one-dimensional array. Packed storage format is described in [] in the F07 class Chapter Introduction.

Syntax

C#
public static void f01va(
    string uplo,
    int n,
    double[,] a,
    double[] ap,
    out int info
)
Visual Basic
Public Shared Sub f01va ( _
    uplo As String, _
    n As Integer, _
    a As Double(,), _
    ap As Double(), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f01va(
    String^ uplo,
    int n,
    array<double,2>^ a,
    array<double>^ ap,
    [OutAttribute] int% info
)
F#
static member f01va :
        uplo : string *
        n : int *
        a : float[,] *
        ap : float[] *
        info : int byref -> unit

Parameters

uplo
Type: System..::..String
On entry: specifies whether A is upper or lower triangular.
uplo="U"
A is upper triangular.
uplo="L"
A is lower triangular.
Constraint: uplo="U" or "L".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥1.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least n.
On entry: the triangular matrix A.
  • If uplo="U", A is upper triangular and the elements of the array below the diagonal are not referenced.
  • If uplo="L", A is lower triangular and the elements of the array above the diagonal are not referenced.
ap
Type: array< System..::..Double >[]()[][]
An array of size [n×n+1/2]
On exit: the n by n triangular matrix A, packed by columns.
More precisely,
  • if uplo="U", the upper triangle of A is stored with element Aij in ap[i+j j-1/2] for i≤j;
  • if uplo="L", the lower triangle of A is stored with element Aij in ap[i+2 n-jj-1/2] for i≥j.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f01va packs a real n by n triangular matrix A, stored conventionally in a two-dimensional array, into a one-dimensional array of length n n+1/2. The matrix is packed by columns. This method is intended for possible use in conjunction with methods from F06 class F07 class F08 class where some methods use triangular matrices stored in the packed form.

References

None.

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads in a triangular matrix and copies it to packed format.

Example program (C#): f01vae.cs

Example program data: f01vae.d

Example program results: f01vae.r

See Also

F01 Class
F01 Members


f01vb Method

[image]

NAG Library for .NET Release 2
F01..::f01vb Method
F01 Class See Also Send Feedback
f01vb copies a complex triangular matrix stored in full format in a two-dimensional array to packed format in a one-dimensional array. Packed storage format is described in [] in the F07 class Chapter Introduction.

Syntax

C#
public static void f01vb(
    string uplo,
    int n,
    Complex[,] a,
    Complex[] ap,
    out int info
)
Visual Basic
Public Shared Sub f01vb ( _
    uplo As String, _
    n As Integer, _
    a As Complex(,), _
    ap As Complex(), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f01vb(
    String^ uplo,
    int n,
    array<Complex,2>^ a,
    array<Complex>^ ap,
    [OutAttribute] int% info
)
F#
static member f01vb :
        uplo : string *
        n : int *
        a : Complex[,] *
        ap : Complex[] *
        info : int byref -> unit

Parameters

uplo
Type: System..::..String
On entry: specifies whether A is upper or lower triangular.
uplo="U"
A is upper triangular.
uplo="L"
A is lower triangular.
Constraint: uplo="U" or "L".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥1.
a
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least n.
On entry: the triangular matrix A.
  • If uplo="U", A is upper triangular and the elements of the array below the diagonal are not referenced.
  • If uplo="L", A is lower triangular and the elements of the array above the diagonal are not referenced.
ap
Type: array< NagLibrary..::..Complex >[]()[][]
An array of size [n×n+1/2]
On exit: the n by n triangular matrix A, packed by columns.
More precisely,
  • if uplo="U", the upper triangle of A is stored with element Aij in ap[i+j j-1/2] for i≤j;
  • if uplo="L", the lower triangle of A is stored with element Aij in ap[i+2 n-jj-1/2] for i≥j.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f01vb packs a complex n by n triangular matrix A, stored conventionally in a two-dimensional array into a one-dimensional array of length n n+1/2. The matrix is packed by columns. This method is intended for possible use in conjunction with methods from F06 class F07 class F08 class where some methods use triangular matrices stored in the packed form.

References

None.

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads in a triangular matrix and copies it to packed format.

Example program (C#): f01vbe.cs

Example program data: f01vbe.d

Example program results: f01vbe.r

See Also

F01 Class
F01 Members


f01vc Method

[image]

NAG Library for .NET Release 2
F01..::f01vc Method
F01 Class See Also Send Feedback
f01vc unpacks a real triangular matrix, stored in packed format in a one-dimensional array, to full format in a two-dimensional array. Packed storage format is described in [] in the F07 class Chapter Introduction.

Syntax

C#
public static void f01vc(
    string uplo,
    int n,
    double[] ap,
    double[,] a,
    out int info
)
Visual Basic
Public Shared Sub f01vc ( _
    uplo As String, _
    n As Integer, _
    ap As Double(), _
    a As Double(,), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f01vc(
    String^ uplo,
    int n,
    array<double>^ ap,
    array<double,2>^ a,
    [OutAttribute] int% info
)
F#
static member f01vc :
        uplo : string *
        n : int *
        ap : float[] *
        a : float[,] *
        info : int byref -> unit

Parameters

uplo
Type: System..::..String
On entry: specifies whether A is upper or lower triangular.
uplo="U"
A is upper triangular.
uplo="L"
A is lower triangular.
Constraint: uplo="U" or "L".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥1.
ap
Type: array< System..::..Double >[]()[][]
An array of size [n×n+1/2]
On entry: the n by n triangular matrix A, packed by columns.
More precisely,
  • if uplo="U", the upper triangle of A must be stored with element Aij in ap[i+j j-1/2] for i≤j;
  • if uplo="L", the lower triangle of A must be stored with element Aij in ap[i+2 n-jj-1/2] for i≥j.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least n.
On exit: the triangular matrix A.
  • If uplo="U", A is upper triangular and the elements of the array below the diagonal are not referenced.
  • If uplo="L", A is lower triangular and the elements of the array above the diagonal are not referenced.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f01vc unpacks a real n by n triangular matrix A, stored in a one-dimensional array of length n n+1/2 to conventional storage in a two-dimensional array. This method is intended for possible use in conjunction with methods from F06 class F07 class F08 class where some methods use triangular matrices stored in the packed form.

References

None.

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads in a triangular matrix packed by columns and unpacks it to full format.

Example program (C#): f01vce.cs

Example program data: f01vce.d

Example program results: f01vce.r

See Also

F01 Class
F01 Members


f01vd Method

[image]

NAG Library for .NET Release 2
F01..::f01vd Method
F01 Class See Also Send Feedback
f01vd unpacks a complex triangular matrix, stored in packed format in a one-dimensional array, to full format in a two-dimensional array. Packed storage format is described in [] in the F07 class Chapter Introduction.

Syntax

C#
public static void f01vd(
    string uplo,
    int n,
    Complex[] ap,
    Complex[,] a,
    out int info
)
Visual Basic
Public Shared Sub f01vd ( _
    uplo As String, _
    n As Integer, _
    ap As Complex(), _
    a As Complex(,), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f01vd(
    String^ uplo,
    int n,
    array<Complex>^ ap,
    array<Complex,2>^ a,
    [OutAttribute] int% info
)
F#
static member f01vd :
        uplo : string *
        n : int *
        ap : Complex[] *
        a : Complex[,] *
        info : int byref -> unit

Parameters

uplo
Type: System..::..String
On entry: specifies whether A is upper or lower triangular.
uplo="U"
A is upper triangular.
uplo="L"
A is lower triangular.
Constraint: uplo="U" or "L".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥1.
ap
Type: array< NagLibrary..::..Complex >[]()[][]
An array of size [n×n+1/2]
On entry: the n by n triangular matrix A, packed by columns.
More precisely,
  • if uplo="U", the upper triangle of A must be stored with element Aij in ap[i+j j-1/2] for i≤j;
  • if uplo="L", the lower triangle of A must be stored with element Aij in ap[i+2 n-jj-1/2] for i≥j.
a
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least n.
On exit: the triangular matrix A.
  • If uplo="U", A is upper triangular and the elements of the array below the diagonal are not referenced.
  • If uplo="L", A is lower triangular and the elements of the array above the diagonal are not referenced.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f01vd unpacks a complex n by n triangular matrix A, stored in a one-dimensional array of length n n+1/2 to conventional storage in a two-dimensional array. This method is intended for possible use in conjunction with methods from F06 class F07 class F08 class where some methods use triangular matrices stored in the packed form.

References

None.

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads in a triangular matrix packed by columns and unpacks it to full format.

Example program (C#): f01vde.cs

Example program data: f01vde.d

Example program results: f01vde.r

See Also

F01 Class
F01 Members


f01ve Method

[image]

NAG Library for .NET Release 2
F01..::f01ve Method
F01 Class See Also Send Feedback
f01ve copies a real triangular matrix stored in full format in a two-dimensional array to Rectangular Full Packed (RFP) format. The RFP storage format is described in [] in the F07 class Chapter Introduction.

Syntax

C#
public static void f01ve(
    string transr,
    string uplo,
    int n,
    double[,] a,
    double[] arf,
    out int info
)
Visual Basic
Public Shared Sub f01ve ( _
    transr As String, _
    uplo As String, _
    n As Integer, _
    a As Double(,), _
    arf As Double(), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f01ve(
    String^ transr,
    String^ uplo,
    int n,
    array<double,2>^ a,
    array<double>^ arf,
    [OutAttribute] int% info
)
F#
static member f01ve :
        transr : string *
        uplo : string *
        n : int *
        a : float[,] *
        arf : float[] *
        info : int byref -> unit

Parameters

transr
Type: System..::..String
On entry: specifies whether the RFP representation of A is normal or transposed.
transr="N"
The matrix A is stored in normal RFP format.
transr="T"
The matrix A is stored in transposed RFP format.
Constraint: transr="N" or "T".
uplo
Type: System..::..String
On entry: specifies whether A is upper or lower triangular.
uplo="U"
A is upper triangular.
uplo="L"
A is lower triangular.
Constraint: uplo="U" or "L".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least n.
On entry: the triangular matrix A.
  • If uplo="U", A is upper triangular and the elements of the array below the diagonal are not referenced.
  • If uplo="L", A is lower triangular and the elements of the array above the diagonal are not referenced.
arf
Type: array< System..::..Double >[]()[][]
An array of size [n×n+1/2]
On exit: the triangular matrix A in RFP format, as described in [] in the F07 class Chapter Introduction.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f01ve packs a real n by n triangular matrix A, stored conventionally in a two-dimensional array into RFP format. This method is intended for possible use in conjunction with methods from F06 class F07 class where some methods that use triangular matrices store them in RFP format.

References

None.

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads in a triangular matrix and copies it to RFP format.

Example program (C#): f01vee.cs

Example program data: f01vee.d

Example program results: f01vee.r

See Also

F01 Class
F01 Members


f01vf Method

[image]

NAG Library for .NET Release 2
F01..::f01vf Method
F01 Class See Also Send Feedback
f01vf copies a complex triangular matrix stored full format in a two-dimensional array to Rectangular Full Packed (RFP) format. The RFP storage format is described in [] in the F07 class Chapter Introduction.

Syntax

C#
public static void f01vf(
    string transr,
    string uplo,
    int n,
    Complex[,] a,
    Complex[] arf,
    out int info
)
Visual Basic
Public Shared Sub f01vf ( _
    transr As String, _
    uplo As String, _
    n As Integer, _
    a As Complex(,), _
    arf As Complex(), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f01vf(
    String^ transr,
    String^ uplo,
    int n,
    array<Complex,2>^ a,
    array<Complex>^ arf,
    [OutAttribute] int% info
)
F#
static member f01vf :
        transr : string *
        uplo : string *
        n : int *
        a : Complex[,] *
        arf : Complex[] *
        info : int byref -> unit

Parameters

transr
Type: System..::..String
On entry: specifies whether the normal RFP representation of A or its conjugate transpose is stored.
transr="N"
The matrix A is stored in normal RFP format.
transr="C"
The conjugate transpose of the RFP representation of the matrix A is stored.
Constraint: transr="N" or "C".
uplo
Type: System..::..String
On entry: specifies whether A is upper or lower triangular.
uplo="U"
A is upper triangular.
uplo="L"
A is lower triangular.
Constraint: uplo="U" or "L".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
a
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least n.
On entry: the triangular matrix A.
  • If uplo="U", A is upper triangular and the elements of the array below the diagonal are not referenced.
  • If uplo="L", A is lower triangular and the elements of the array above the diagonal are not referenced.
arf
Type: array< NagLibrary..::..Complex >[]()[][]
An array of size [n×n+1/2]
On exit: the triangular matrix A in RFP format, as described in [] in the F07 class Chapter Introduction.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f01vf packs a complex n by n triangular matrix A, stored conventionally in a two-dimensional array into RFP format. This method is intended for possible use in conjunction with methods from F06 class F07 class where some methods that use triangular matrices store them in RFP format.

References

None.

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads in a triangular matrix and copies it to RFP format.

Example program (C#): f01vfe.cs

Example program data: f01vfe.d

Example program results: f01vfe.r

See Also

F01 Class
F01 Members


f01vg Method

[image]

NAG Library for .NET Release 2
F01..::f01vg Method
F01 Class See Also Send Feedback
f01vg unpacks a real triangular matrix stored in Rectangular Full Packed (RFP) format to full format in a two-dimensional array. The RFP storage format is described in [] in the F07 class Chapter Introduction.

Syntax

C#
public static void f01vg(
    string transr,
    string uplo,
    int n,
    double[] arf,
    double[,] a,
    out int info
)
Visual Basic
Public Shared Sub f01vg ( _
    transr As String, _
    uplo As String, _
    n As Integer, _
    arf As Double(), _
    a As Double(,), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f01vg(
    String^ transr,
    String^ uplo,
    int n,
    array<double>^ arf,
    array<double,2>^ a,
    [OutAttribute] int% info
)
F#
static member f01vg :
        transr : string *
        uplo : string *
        n : int *
        arf : float[] *
        a : float[,] *
        info : int byref -> unit

Parameters

transr
Type: System..::..String
On entry: specifies whether the RFP representation of A is normal or transposed.
transr="N"
The matrix A is stored in normal RFP format.
transr="T"
The matrix A is stored in transposed RFP format.
Constraint: transr="N" or "T".
uplo
Type: System..::..String
On entry: specifies whether A is upper or lower triangular.
uplo="U"
A is upper triangular.
uplo="L"
A is lower triangular.
Constraint: uplo="U" or "L".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
arf
Type: array< System..::..Double >[]()[][]
An array of size [n×n+1/2]
On entry: the n by n triangular matrix A in RFP format, as described in [] in the F07 class Chapter Introduction.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least n.
On exit: the triangular matrix A.
  • If uplo="U", A is upper triangular and the elements of the array below the diagonal are not referenced.
  • If uplo="L", A is lower triangular and the elements of the array above the diagonal are not referenced.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f01vg unpacks a real n by n triangular matrix A, stored in RFP format to conventional storage in a two-dimensional array. This method is intended for possible use in conjunction with methods from F06 class F07 class where some methods that use triangular matrices store them in RFP format.

References

None.

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads in a triangular matrix in RFP format and unpacks it to full format.

Example program (C#): f01vge.cs

Example program data: f01vge.d

Example program results: f01vge.r

See Also

F01 Class
F01 Members


f01vh Method

[image]

NAG Library for .NET Release 2
F01..::f01vh Method
F01 Class See Also Send Feedback
f01vh unpacks a complex triangular matrix stored in Rectangular Full Packed (RFP) format to full format in a two-dimensional array. The RFP storage format is described in [] in the F07 class Chapter Introduction.

Syntax

C#
public static void f01vh(
    string transr,
    string uplo,
    int n,
    Complex[] arf,
    Complex[,] a,
    out int info
)
Visual Basic
Public Shared Sub f01vh ( _
    transr As String, _
    uplo As String, _
    n As Integer, _
    arf As Complex(), _
    a As Complex(,), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f01vh(
    String^ transr,
    String^ uplo,
    int n,
    array<Complex>^ arf,
    array<Complex,2>^ a,
    [OutAttribute] int% info
)
F#
static member f01vh :
        transr : string *
        uplo : string *
        n : int *
        arf : Complex[] *
        a : Complex[,] *
        info : int byref -> unit

Parameters

transr
Type: System..::..String
On entry: specifies whether the normal RFP representation of A or its conjugate transpose is stored.
transr="N"
The matrix A is stored in normal RFP format.
transr="C"
The conjugate transpose of the RFP representation of the matrix A is stored.
Constraint: transr="N" or "C".
uplo
Type: System..::..String
On entry: specifies whether A is upper or lower triangular.
uplo="U"
A is upper triangular.
uplo="L"
A is lower triangular.
Constraint: uplo="U" or "L".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
arf
Type: array< NagLibrary..::..Complex >[]()[][]
An array of size [n×n+1/2]
On entry: the n by n triangular matrix A in RFP format, as described in [] in the F07 class Chapter Introduction.
a
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least n.
On exit: the triangular matrix A.
  • If uplo="U", A is upper triangular and the elements of the array below the diagonal are not referenced.
  • If uplo="L", A is lower triangular and the elements of the array above the diagonal are not referenced.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f01vh unpacks a complex n by n triangular matrix A, stored in RFP format to conventional storage in a two-dimensional array. This method is intended for possible use in conjunction with methods from F06 class F07 class where some methods that use triangular matrices store them in RFP format.

References

None.

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads in a triangular matrix in RFP format and unpacks it to full format.

Example program (C#): f01vhe.cs

Example program data: f01vhe.d

Example program results: f01vhe.r

See Also

F01 Class
F01 Members


f01vj Method

[image]

NAG Library for .NET Release 2
F01..::f01vj Method
F01 Class See Also Send Feedback
f01vj copies a real triangular matrix stored in packed format to Rectangular Full Packed (RFP) format. The RFP storage format is described in [] in the F07 class Chapter Introduction and the packed storage format is described in [] in the F07 class Chapter Introduction.

Syntax

C#
public static void f01vj(
    string transr,
    string uplo,
    int n,
    double[] ap,
    double[] arf,
    out int info
)
Visual Basic
Public Shared Sub f01vj ( _
    transr As String, _
    uplo As String, _
    n As Integer, _
    ap As Double(), _
    arf As Double(), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f01vj(
    String^ transr,
    String^ uplo,
    int n,
    array<double>^ ap,
    array<double>^ arf,
    [OutAttribute] int% info
)
F#
static member f01vj :
        transr : string *
        uplo : string *
        n : int *
        ap : float[] *
        arf : float[] *
        info : int byref -> unit

Parameters

transr
Type: System..::..String
On entry: specifies whether the RFP representation of A is normal or transposed.
transr="N"
The matrix A is stored in normal RFP format.
transr="T"
The matrix A is stored in transposed RFP format.
Constraint: transr="N" or "T".
uplo
Type: System..::..String
On entry: specifies whether A is upper or lower triangular.
uplo="U"
A is upper triangular.
uplo="L"
A is lower triangular.
Constraint: uplo="U" or "L".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
ap
Type: array< System..::..Double >[]()[][]
An array of size [n×n+1/2]
On entry: the n by n triangular matrix A, packed by columns.
More precisely,
  • if uplo="U", the upper triangle of A must be stored with element Aij in ap[i+j j-1/2] for i≤j;
  • if uplo="L", the lower triangle of A must be stored with element Aij in ap[i+2 n-jj-1/2] for i≥j.
arf
Type: array< System..::..Double >[]()[][]
An array of size [n×n+1/2]
On exit: the triangular matrix A in RFP format, as described in [] in the F07 class Chapter Introduction.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f01vj copies a real n by n triangular matrix, A, stored packed format, to RFP format. This method is intended for possible use in conjunction with methods from F06 class F07 class where some methods that use triangular matrices store them in RFP format.

References

None.

Error Indicators and Warnings

info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads in a triangular matrix in packed format and copies it to RFP format.

Example program (C#): f01vje.cs

Example program data: f01vje.d

Example program results: f01vje.r

See Also

F01 Class
F01 Members


f01vk Method

[image]

NAG Library for .NET Release 2
F01..::f01vk Method
F01 Class See Also Send Feedback
f01vk copies a complex triangular matrix stored in packed format to Rectangular Full Packed (RFP) format. The RFP storage format is described in [] in the F07 class Chapter Introduction and the packed storage format is described in [] in the F07 class Chapter Introduction.

Syntax

C#
public static void f01vk(
    string transr,
    string uplo,
    int n,
    Complex[] ap,
    Complex[] arf,
    out int info
)
Visual Basic
Public Shared Sub f01vk ( _
    transr As String, _
    uplo As String, _
    n As Integer, _
    ap As Complex(), _
    arf As Complex(), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f01vk(
    String^ transr,
    String^ uplo,
    int n,
    array<Complex>^ ap,
    array<Complex>^ arf,
    [OutAttribute] int% info
)
F#
static member f01vk :
        transr : string *
        uplo : string *
        n : int *
        ap : Complex[] *
        arf : Complex[] *
        info : int byref -> unit

Parameters

transr
Type: System..::..String
On entry: specifies whether the normal RFP representation of A or its conjugate transpose is stored.
transr="N"
The matrix A is stored in normal RFP format.
transr="C"
The conjugate transpose of the RFP representation of the matrix A is stored.
Constraint: transr="N" or "C".
uplo
Type: System..::..String
On entry: specifies whether A is upper or lower triangular.
uplo="U"
A is upper triangular.
uplo="L"
A is lower triangular.
Constraint: uplo="U" or "L".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
ap
Type: array< NagLibrary..::..Complex >[]()[][]
An array of size [n×n+1/2]
On entry: the n by n triangular matrix A, packed by columns.
More precisely,
  • if uplo="U", the upper triangle of A must be stored with element Aij in ap[i+j j-1/2] for i≤j;
  • if uplo="L", the lower triangle of A must be stored with element Aij in ap[i+2 n-jj-1/2] for i≥j.
arf
Type: array< NagLibrary..::..Complex >[]()[][]
An array of size [n×n+1/2]
On exit: the triangular matrix A in RFP format, as described in [] in the F07 class Chapter Introduction.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f01vk copies a complex n by n triangular matrix, A, stored packed format, to RFP format. This method is intended for possible use in conjunction with methods from F06 class F07 class where some methods that use triangular matrices store them in RFP format.

References

None.

Error Indicators and Warnings

info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads in a triangular matrix in packed format and copies it to RFP format.

Example program (C#): f01vke.cs

Example program data: f01vke.d

Example program results: f01vke.r

See Also

F01 Class
F01 Members


f01vl Method

[image]

NAG Library for .NET Release 2
F01..::f01vl Method
F01 Class See Also Send Feedback
f01vl copies a real triangular matrix stored in a Rectangular Full Packed (RFP) format to packed format. The RFP storage format is described in [] in the F07 class Chapter Introduction and the packed storage format is described in [] in the F07 class Chapter Introduction.

Syntax

C#
public static void f01vl(
    string transr,
    string uplo,
    int n,
    double[] arf,
    double[] ap,
    out int info
)
Visual Basic
Public Shared Sub f01vl ( _
    transr As String, _
    uplo As String, _
    n As Integer, _
    arf As Double(), _
    ap As Double(), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f01vl(
    String^ transr,
    String^ uplo,
    int n,
    array<double>^ arf,
    array<double>^ ap,
    [OutAttribute] int% info
)
F#
static member f01vl :
        transr : string *
        uplo : string *
        n : int *
        arf : float[] *
        ap : float[] *
        info : int byref -> unit

Parameters

transr
Type: System..::..String
On entry: specifies whether the RFP representation of A is normal or transposed.
transr="N"
The matrix A is stored in normal RFP format.
transr="T"
The matrix A is stored in transposed RFP format.
Constraint: transr="N" or "T".
uplo
Type: System..::..String
On entry: specifies whether A is upper or lower triangular.
uplo="U"
A is upper triangular.
uplo="L"
A is lower triangular.
Constraint: uplo="U" or "L".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
arf
Type: array< System..::..Double >[]()[][]
An array of size [n×n+1/2]
On entry: the triangular matrix A in RFP format, as described in [] in the F07 class Chapter Introduction.
ap
Type: array< System..::..Double >[]()[][]
An array of size [n×n+1/2]
On exit: the n by n triangular matrix A, packed by columns.
More precisely,
  • if uplo="U", the upper triangle of A is stored with element Aij in ap[i+j j-1/2] for i≤j;
  • if uplo="L", the lower triangle of A is stored with element Aij in ap[i+2 n-jj-1/2] for i≥j.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f01vl packs a real n by n triangular matrix A stored in RFP format to packed format. This method is intended for possible use in conjunction with methods from F06 class F07 class where some methods that use triangular matrices store them in RFP format.

References

None.

Error Indicators and Warnings

info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads in a triangular matrix in RFP format and copies it to packed format.

Example program (C#): f01vle.cs

Example program data: f01vle.d

Example program results: f01vle.r

See Also

F01 Class
F01 Members


f01vm Method

[image]

NAG Library for .NET Release 2
F01..::f01vm Method
F01 Class See Also Send Feedback
f01vm copies a complex triangular matrix stored in a Rectangular Full Packed (RFP) format to packed format. The RFP storage format is described in [] in the F07 class Chapter Introduction and the packed storage format is described in [] in the F07 class Chapter Introduction.

Syntax

C#
public static void f01vm(
    string transr,
    string uplo,
    int n,
    Complex[] arf,
    Complex[] ap,
    out int info
)
Visual Basic
Public Shared Sub f01vm ( _
    transr As String, _
    uplo As String, _
    n As Integer, _
    arf As Complex(), _
    ap As Complex(), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f01vm(
    String^ transr,
    String^ uplo,
    int n,
    array<Complex>^ arf,
    array<Complex>^ ap,
    [OutAttribute] int% info
)
F#
static member f01vm :
        transr : string *
        uplo : string *
        n : int *
        arf : Complex[] *
        ap : Complex[] *
        info : int byref -> unit

Parameters

transr
Type: System..::..String
On entry: specifies whether the normal RFP representation of A or its conjugate transpose is stored.
transr="N"
The matrix A is stored in normal RFP format.
transr="C"
The conjugate transpose of the RFP representation of the matrix A is stored.
Constraint: transr="N" or "C".
uplo
Type: System..::..String
On entry: specifies whether A is upper or lower triangular.
uplo="U"
A is upper triangular.
uplo="L"
A is lower triangular.
Constraint: uplo="U" or "L".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
arf
Type: array< NagLibrary..::..Complex >[]()[][]
An array of size [n×n+1/2]
On entry: the triangular matrix A in RFP format, as described in [] in the F07 class Chapter Introduction.
ap
Type: array< NagLibrary..::..Complex >[]()[][]
An array of size [n×n+1/2]
On exit: the n by n triangular matrix A, packed by columns.
More precisely,
  • if uplo="U", the upper triangle of A is stored with element Aij in ap[i+j j-1/2] for i≤j;
  • if uplo="L", the lower triangle of A is stored with element Aij in ap[i+2 n-jj-1/2] for i≥j.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f01vm packs a complex n by n triangular matrix A stored in RFP format to packed format. This method is intended for possible use in conjunction with methods from F06 class F07 class where some methods that use triangular matrices store them in RFP format.

References

None.

Error Indicators and Warnings

info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads in a triangular matrix in RFP format and copies it to packed format.

Example program (C#): f01vme.cs

Example program data: f01vme.d

Example program results: f01vme.r

See Also

F01 Class
F01 Members


F06 Class

[image]

NAG Library for .NET Release 2
F06 Class
Members See Also Send Feedback
This chapter is concerned with basic linear algebra methods which perform elementary algebraic operations involving scalars, vectors and matrices. It includes methods which conform to the specifications of the BLAS (Basic Linear Algebra Subprograms).

Syntax

C#
public static class F06
Visual Basic
Public NotInheritable Class F06
Visual C++
public ref class F06 abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type F06 =  class end

Background to the Problems

A number of the methods in this chapter meet the specification of the Basic Linear Algebra Subprograms (BLAS) as described in Lawson et al. (1979), Dodson et al. (1991), Dongarra et al. (1988) and Dongarra et al. (1990). The first reference describes a set of methods concerned with operations on scalars and vectors: these will be referred to here as the Level-0 and the Level-1 BLAS; the second reference describes a set of methods concerned with operations on sparse vectors: these will be referred to here as the Level-1 Sparse BLAS; the third reference describes a set of methods concerned with matrix-vector operations: these will be referred to here as the Level-2 BLAS; and the fourth reference describes a set of methods concerned with matrix-matrix operations: these will be referred to here as the Level-3 BLAS.
More generally we refer to the scalar methods in the chapter as Level-0 methods, to the vector methods as Level-1 methods, to the matrix-vector and matrix methods as Level-2 methods, and to the matrix-matrix methods as Level-3 methods. The terminology reflects the number of operations involved. For example, a Level-2 method involves O n 2 operations for an n×n matrix.

The Use of BLAS Names

Many of the methods in other chapters of the Library call the methods in this chapter, and in particular a number of the BLAS are called. These methods are usually called by the BLAS name and so, for correct operation of the Library, it is essential that you do not attempt to link your own versions of these methods. If you are in any doubt about how to avoid this, please consult your computer centre or the NAG Response Centre.
The BLAS names are used in order to make use of efficient implementations of the methods when these exist. Such implementations are stringently tested before being used, to ensure that they correctly meet the specification of the BLAS, and that they return the desired accuracy (see, for example, Dodson et al. (1991), Dongarra et al. (1988) and Dongarra et al. (1990)).

Background Information

Most of the methods in this chapter implement straightforward scalar, vector and matrix operations that need no further explanation beyond a statement of the purpose of the method. In this section we give some additional background information to those few cases where additional explanation may be necessary. A sub-section is devoted to each topic.

Real plane rotations

There are a number of methods in the chapter concerned with setting up and applying plane rotations. This section discusses the real case and the next section looks at the complex case. For further background information see Golub and Van Loan (1996).
A plane rotation matrix for the i,j plane, R ij, is an orthogonal matrix that is different from the unit matrix only in the elements r ii, r jj, r ij and r ji. If we put
R=r iir ijr jir jj, (1)
then, in the real case, it is usual to choose R ij so that
R=-cs-sc,  c=cos θ,  s=sin θ.
An exception is method (F06FPF not in this release) which applies the so-called symmetric rotation for which
R=c-ss-c. (2)
The application of plane rotations is straightforward and needs no further elaboration, so further comment is made only on the construction of plane rotations.
The most common use of plane rotations is to choose c and s so that for given a and b,
-cs-sc ab=d0. (3)
In such an application the matrix R is often termed a Givens rotation matrix. There are two approaches to the construction of real Givens rotations in F06 class.
The BLAS method (F06AAF not in this release), see Lawson et al. (1979) and Dodson and Grimes (1982), computes c, s and d as
d=σ a 2+b 2 1/2,
c=a/d,d≠0,1,d=0,   s=b/d,d≠0,0,d=0, (4)
where σ=sign a,a>bsign b,a≤b.
The value z defined as
z=s,s<c  or  c=01/c,0<c≤s (5)
is also computed and this enables c and s to be reconstructed from the single value z as
c=0,z=11-z 2 1/2,z<11/z,z>1   s=1,z=1z,z<11-c 2 1/2,z>1.
The other F06 class methods for constructing Givens rotations are based on the computation of the tangent, t=tan θ. t is computed as
t=0,b=0b/a,b≤a.flmax,b≠0sign b/a.flmax,b>a.flmaxsign b.flmax,b≠0,a=0 (6)
where flmax=1/flmin and flmin is the small positive value returned by x02am. The values of c and s are then computed or reconstructed via t as
c=1/1+t 2 1/2,eps≤t≤1/eps1,t<eps1/t,t>1/eps   s=c.t,eps≤t≤1/epst,t<epssign t,t>1/eps (7)
where eps is the machine precision. Note that c is always non-negative in this scheme and that the same expressions are used in the initial computation of c and s from a and b as in any subsequent recovery of c and s via t. This is the approach used by many of the NAG Library methods that require plane rotations. d is computed simply as
d=c.a+s.b.
You need not be too concerned with the above detail, since methods are provided for setting up, recovering and applying such rotations.
Another use of plane rotations is to choose c and s so that for given x, y and z
-cs-sc xyyz c-ss-c=a00b. (8)
In such an application the matrix R is often termed a Jacobi rotation matrix. The method that generates a Jacobi rotation ( (F06BEF not in this release)) first computes the tangent t and then computes c and s via t as described above for the Givens rotation.

Complex plane rotations

In the complex case a plane rotation matrix for the i,j plane, R ij is a unitary matrix and, analogously to the real case, it is usual to choose R ij so that
R=-c-s--sc,  c 2+s 2=1, (9)
where a- denotes the complex conjugate of a.
The BLAS (see Lawson et al. (1979)) do not contain a method for the generation of complex rotations, and so the methods in F06 class are all based upon computing c and s via t=b/a in an analogous manner to the real case. R can be chosen to have either c real, or s real and there are methods for both cases.
When c is real then it is non-negative and the transformation
-cs--sc ab=d0 (10)
is such that if a is real then d is also real.
When s is real then the transformation
-c-s-sc ab=d0 (11)
is such that if b is real then d is also real.

Elementary real (Householder) reflections

There are a number of methods in the chapter concerned with setting up and applying Householder transformations. This section discusses the real case and the next section looks at the complex case. For further background information see Golub and Van Loan (1996).
A real elementary reflector, P, is a matrix of the form
P=I-μu uT,  μ uT u=2, (12)
where μ is a scalar and u is a vector, and P is both symmetric and orthogonal. In the methods in F06 class, u is expressed in the form
u=ζz,  ζ​ a scalar (13)
because in many applications ζ and z are not contiguous elements. The usual use of elementary reflectors is to choose μ and u so that for given α and x
P αx=β0,  α​ and ​β​ scalars. (14)
Such a transformation is often termed a Householder transformation. There are two choices of μ and u available in F06 class.
The first form of the Householder transformation is compatible with that used by LINPACK (see Dongarra et al. (1979)) and has
μ=1/ζ. (15)
This choice makes ζ satisfy
1≤ζ≤2.
The second form, and the form used by many of the NAG Library methods, has
μ=1 (16)
which makes
1≤ζ≤2.
In both cases the special setting
ζ=0 (17)
is used by the methods to flag the case where P=I.
Note that while there are methods to apply an elementary reflector to a vector, there are no methods available in F06 class to apply an elementary reflector to a matrix. This is because such transformations can readily and efficiently be achieved by calls to the matrix-vector Level 2 BLAS methods. For example, to form PA for a given matrix
PA=I-μu uT A=A-μu uT A=A-μu bT,  b=AT u, (18)
and so we can call a matrix-vector product method to form b=AT u and then call a rank-one update method to form A-μu bT. Of course, we must skip the transformation when ζ has been set to zero.

Elementary complex (Householder) reflections

A complex elementary reflector, P, is a matrix of the form
P=I-μu uH,  μ uH u=2,  μ​ real,
where uH denotes the complex conjugate of uT, and P is both Hermitian and unitary. For convenience in a number of applications this definition can be generalized slightly by allowing μ to be complex and so defining the generalized elementary reflector as
P=I-μu uH,  μ 2uH u=μ+μ- (19)
for which P is still unitary, but is no longer Hermitian.
The F06 class methods choose μ and ζ so that
Re μ=1,  Im ζ=0 (20)
and this reduces to (12) with the choice (16) when μ and u are real. This choice is used because μ and u can now be chosen so that in the Householder transformation (14) we can make
Im β=0
and, as in the real case,
1≤ζ≤2.
Rather than returning μ and ζ as separate parameters the F06 class methods return the single complex value θ defined as
θ=ζ+i.Im μ,  i=-1.
Obviously ζ and μ can be recovered as
ζ=Re θ,  μ=1+i.Im θ.
The special setting
θ=0
is used to flag the case where P=I, and
Re θ≤0,  Im θ≠0
is used to flag the case where
P=γ00I,  γ​ a scalar (21)
and in this case θ actually contains the value of γ. Notice that with both (18) and (21) we merely have to supply θ- rather than θ in order to represent PH.

References

Dodson D S and Grimes R G (1982) Remark on Algorithm 539 ACM Trans. Math. Software 8 403–404
Dodson D S, Grimes R G and Lewis J G (1991) Sparse extensions to the Fortran basic linear algebra subprograms ACM Trans. Math. Software 17 253–263
Dongarra J J, Du Croz J J, Duff I S and Hammarling S (1990) A set of Level 3 basic linear algebra subprograms ACM Trans. Math. Software 16 1–28
Dongarra J J, Du Croz J J, Hammarling S and Hanson R J (1988) An extended set of FORTRAN basic linear algebra subprograms ACM Trans. Math. Software 14 1–32
Dongarra J J, Moler C B, Bunch J R and Stewart G W (1979) LINPACK Users' Guide SIAM, Philadelphia
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Lawson C L, Hanson R J, Kincaid D R and Krogh F T (1979) Basic linear algebra supbrograms for Fortran usage ACM Trans. Math. Software 5 308–325

Inheritance Hierarchy

System..::..Object
NagLibrary..::..F06

See Also

F06 Members


F06 Members

[image] [image]

NAG Library for .NET Release 2
F06 Members
F06 Class Methods See Also Send Feedback

The F06 type exposes the following members.

Methods

Name Description
f06bn
f06bn returns the value a 2+b 2.
f06db
f06db broadcasts an integer scalar into an integer vector.
f06ea
f06ea computes the scalar product of two real vectors.
f06ef
f06ef makes a copy of a real vector .
f06ej
f06ej returns the Euclidean norm of the n-element real vector x.
f06fd
f06fd multiplies a real vector by a scalar, preserving the input vector.
f06jj
f06jj computes the Euclidean norm of a complex vector.
f06pa
f06pa computes the matrix-vector product for a real general matrix or its transpose.
f06pj
f06pj solves a real triangular system of equations with a single right hand side.
f06qf
f06qf performs the matrix-copy operation
B←A
where A and B are m by n real general or trapezoidal matrices.
f06qh
f06qh forms the real m by n rectangular or trapezoidal matrix A given by
a ij=diagif i=jconstif i≠j.
f06ya
f06ya performs one of the matrix-matrix operations
C←αAB+βC,C←α AT B+βC,C←αA BT+βC  orC←α ATBT+βC,
where A, B and C are real matrices, and α and β are real scalars; C is always m by n.
f06yj
f06yj performs one of the matrix-matrix operations
B←α A-1 B,B←α A-T B,B←αB A-1  orB←αB A-T,
where A is a real triangular matrix, B is an m by n real matrix, and α is a real scalar. A-T denotes AT-1 or equivalently A-1 T.
No test for singularity or near-singularity of A is included in this method. Such tests must be performed before calling this method.

See Also

F06 Class


F06 Methods

[image] [image]

NAG Library for .NET Release 2
F06 Methods
F06 Class See Also Send Feedback

The F06 type exposes the following members.

Methods

Name Description
f06bn
f06bn returns the value a 2+b 2.
f06db
f06db broadcasts an integer scalar into an integer vector.
f06ea
f06ea computes the scalar product of two real vectors.
f06ef
f06ef makes a copy of a real vector .
f06ej
f06ej returns the Euclidean norm of the n-element real vector x.
f06fd
f06fd multiplies a real vector by a scalar, preserving the input vector.
f06jj
f06jj computes the Euclidean norm of a complex vector.
f06pa
f06pa computes the matrix-vector product for a real general matrix or its transpose.
f06pj
f06pj solves a real triangular system of equations with a single right hand side.
f06qf
f06qf performs the matrix-copy operation
B←A
where A and B are m by n real general or trapezoidal matrices.
f06qh
f06qh forms the real m by n rectangular or trapezoidal matrix A given by
a ij=diagif i=jconstif i≠j.
f06ya
f06ya performs one of the matrix-matrix operations
C←αAB+βC,C←α AT B+βC,C←αA BT+βC  orC←α ATBT+βC,
where A, B and C are real matrices, and α and β are real scalars; C is always m by n.
f06yj
f06yj performs one of the matrix-matrix operations
B←α A-1 B,B←α A-T B,B←αB A-1  orB←αB A-T,
where A is a real triangular matrix, B is an m by n real matrix, and α is a real scalar. A-T denotes AT-1 or equivalently A-1 T.
No test for singularity or near-singularity of A is included in this method. Such tests must be performed before calling this method.

See Also

F06 Class


f06bn Method

[image]

NAG Library for .NET Release 2
F06..::f06bn Method
F06 Class See Also Send Feedback
f06bn returns the value a 2+b 2.

Syntax

C#
public static double f06bn(
    double a,
    double b
)
Visual Basic
Public Shared Function f06bn ( _
    a As Double, _
    b As Double _
) As Double
Visual C++
public:
static double f06bn(
    double a,
    double b
)
F#
static member f06bn :
        a : float *
        b : float -> float

Parameters

a
Type: System..::..Double
On entry: the value a.
b
Type: System..::..Double
On entry: the value b.

Return Value

f06bn returns the value a 2+b 2.

Description

None.

References

None.

Error Indicators and Warnings

None.

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): f06bne.cs

Example program results: f06bne.r

See Also

F06 Class
F06 Members


f06db Method

[image]

NAG Library for .NET Release 2
F06..::f06db Method
F06 Class See Also Send Feedback
f06db broadcasts an integer scalar into an integer vector.

Syntax

C#
public static void f06db(
    int n,
    int con,
    int[] x,
    int incx,
    out int ifail
)
Visual Basic
Public Shared Sub f06db ( _
    n As Integer, _
    con As Integer, _
    x As Integer(), _
    incx As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void f06db(
    int n,
    int con,
    array<int>^ x,
    int incx,
    [OutAttribute] int% ifail
)
F#
static member f06db :
        n : int *
        con : int *
        x : int[] *
        incx : int *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of elements in x.
con
Type: System..::..Int32
On entry: the scalar α.
x
Type: array< System..::..Int32 >[]()[][]
An array of size [dim1]
Note: the dimension of the array x must be at least max 1,1+n-1×incx.
On exit: the vector x. xi will be stored in x[1+i-1×incx], for i=1,2,…,n.
Intermediate elements of x are unchanged.
incx
Type: System..::..Int32
On entry: the increment in the subscripts of x between successive elements of x.
Constraint: incx>0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f06db performs the operation
x←α,α,…,α T,
where x is an n-element integer vector scattered with stride incx.

References

None.

Error Indicators and Warnings

ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): f06dbe.cs

Example program results: f06dbe.r

See Also

F06 Class
F06 Members


f06ea Method

[image]

NAG Library for .NET Release 2
F06..::f06ea Method
F06 Class See Also Send Feedback
f06ea computes the scalar product of two real vectors.

Syntax

C#
public static double f06ea(
    int n,
    double[] x,
    int incx,
    double[] y,
    int incy,
    out int ifail
)
Visual Basic
Public Shared Function f06ea ( _
    n As Integer, _
    x As Double(), _
    incx As Integer, _
    y As Double(), _
    incy As Integer, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double f06ea(
    int n,
    array<double>^ x,
    int incx,
    array<double>^ y,
    int incy,
    [OutAttribute] int% ifail
)
F#
static member f06ea :
        n : int *
        x : float[] *
        incx : int *
        y : float[] *
        incy : int *
        ifail : int byref -> float

Parameters

n
Type: System..::..Int32
On entry: n, the number of elements in x and y.
x
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array x must be at least max 1,1+n-1×incx.
On entry: the n-element vector x.
If incx>0, xi must be stored in x[1+i-1×incx], for i=1,2,…,n.
If incx<0, xi must be stored in x[1-n-i×incx], for i=1,2,…,n.
Intermediate elements of x are not referenced.
incx
Type: System..::..Int32
On entry: the increment in the subscripts of x between successive elements of x.
y
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array y must be at least max 1,1+n-1×incy.
On entry: the n-element vector y.
If incy>0, yi must be stored in y[1+i-1×incy], for i=1,2,…,n.
If incy<0, yi must be stored in y[1-n-i×incy], for i=1,2,…,n.
Intermediate elements of y are not referenced.
incy
Type: System..::..Int32
On entry: the increment in the subscripts of y between successive elements of y.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error (see [Error Indicators and Warnings]).

Return Value

f06ea computes the scalar product of two real vectors.

Description

f06ea returns the value of the scalar product
xT y
where x and y are n-element real vectors scattered with stride incx and incy respectively.

References

Lawson C L, Hanson R J, Kincaid D R and Krogh F T (1979) Basic linear algebra supbrograms for Fortran usage ACM Trans. Math. Software 5 308–325

Error Indicators and Warnings

ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): f06eae.cs

Example program results: f06eae.r

See Also

F06 Class
F06 Members


f06ef Method

[image]

NAG Library for .NET Release 2
F06..::f06ef Method
F06 Class See Also Send Feedback
f06ef makes a copy of a real vector .

Syntax

C#
public static void f06ef(
    int n,
    double[] x,
    int incx,
    double[] y,
    int incy,
    out int ifail
)
Visual Basic
Public Shared Sub f06ef ( _
    n As Integer, _
    x As Double(), _
    incx As Integer, _
    y As Double(), _
    incy As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void f06ef(
    int n,
    array<double>^ x,
    int incx,
    array<double>^ y,
    int incy,
    [OutAttribute] int% ifail
)
F#
static member f06ef :
        n : int *
        x : float[] *
        incx : int *
        y : float[] *
        incy : int *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of elements in x and y.
x
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array x must be at least max 1,1+n-1×incx.
On entry: the n-element vector x.
If incx>0, xi must be stored in x[1+i-1×incx], for i=1,2,…,n.
If incx<0, xi must be stored in x[1-n-i×incx], for i=1,2,…,n.
Intermediate elements of x are not referenced.
incx
Type: System..::..Int32
On entry: the increment in the subscripts of x between successive elements of x.
y
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array y must be at least max 1,1+n-1×incy.
On exit: the vector y.
If incy>0, yi will be stored in y[1+i-1×incy], for i=1,2,…,n.
If incy<0, yi will be stored in y[1-n-i×incy], for i=1,2,…,n.
Intermediate elements of y are unchanged.
incy
Type: System..::..Int32
On entry: the increment in the subscripts of y between successive elements of y.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f06ef performs the operation
y←x
where x and y are n-element real vectors scattered with stride incx and incy respectively.

References

Lawson C L, Hanson R J, Kincaid D R and Krogh F T (1979) Basic linear algebra supbrograms for Fortran usage ACM Trans. Math. Software 5 308–325

Error Indicators and Warnings

ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): f06efe.cs

Example program results: f06efe.r

See Also

F06 Class
F06 Members


f06ej Method

[image]

NAG Library for .NET Release 2
F06..::f06ej Method
F06 Class See Also Send Feedback
f06ej returns the Euclidean norm of the n-element real vector x.

Syntax

C#
public static double f06ej(
    int n,
    double[] x,
    int incx,
    out int ifail
)
Visual Basic
Public Shared Function f06ej ( _
    n As Integer, _
    x As Double(), _
    incx As Integer, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double f06ej(
    int n,
    array<double>^ x,
    int incx,
    [OutAttribute] int% ifail
)
F#
static member f06ej :
        n : int *
        x : float[] *
        incx : int *
        ifail : int byref -> float

Parameters

n
Type: System..::..Int32
On entry: n, the number of elements in x.
x
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array x must be at least max 1,1+n-1×incx.
On entry: the n-element vector x. xi must be stored in x[1+i-1×incx], for i=1,2,…,n.
Intermediate elements of x are not referenced.
incx
Type: System..::..Int32
On entry: the increment in the subscripts of x between successive elements of x.
Constraint: incx>0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error (see [Error Indicators and Warnings]).

Return Value

f06ej returns the Euclidean norm of the n-element real vector x.

Description

f06ej returns the Euclidean norm
x 2=xT x
of the n-element real vector x scattered with stride incx.

References

Lawson C L, Hanson R J, Kincaid D R and Krogh F T (1979) Basic linear algebra supbrograms for Fortran usage ACM Trans. Math. Software 5 308–325

Error Indicators and Warnings

ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): f06eje.cs

Example program results: f06eje.r

See Also

F06 Class
F06 Members


f06fd Method

[image]

NAG Library for .NET Release 2
F06..::f06fd Method
F06 Class See Also Send Feedback
f06fd multiplies a real vector by a scalar, preserving the input vector.

Syntax

C#
public static void f06fd(
    int n,
    double alpha,
    double[] x,
    int incx,
    double[] y,
    int incy,
    out int ifail
)
Visual Basic
Public Shared Sub f06fd ( _
    n As Integer, _
    alpha As Double, _
    x As Double(), _
    incx As Integer, _
    y As Double(), _
    incy As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void f06fd(
    int n,
    double alpha,
    array<double>^ x,
    int incx,
    array<double>^ y,
    int incy,
    [OutAttribute] int% ifail
)
F#
static member f06fd :
        n : int *
        alpha : float *
        x : float[] *
        incx : int *
        y : float[] *
        incy : int *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of elements in x and y.
alpha
Type: System..::..Double
On entry: the scalar α.
x
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array x must be at least max 1,1+n-1×incx.
On entry: the n-element vector x.
If incx>0, xi must be stored in x[1+i-1×incx], for i=1,2,…,n.
If incx<0, xi must be stored in x[1-n-i×incx], for i=1,2,…,n.
Intermediate elements of x are not referenced.
incx
Type: System..::..Int32
On entry: the increment in the subscripts of x between successive elements of x.
y
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array y must be at least max 1,1+n-1×incy.
On exit: the vector y.
If incy>0, yi will be stored in y[1+i-1×incy], for i=1,2,…,n.
If incy<0, yi will be stored in y[1-n-i×incy], for i=1,2,…,n.
Intermediate elements of y are unchanged.
incy
Type: System..::..Int32
On entry: the increment in the subscripts of y between successive elements of y.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f06fd performs the operation
y←αx
where x and y are n-element real vectors scattered with stride incx and incy respectively, and α is a real scalar.

References

None.

Error Indicators and Warnings

ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): f06fde.cs

Example program results: f06fde.r

See Also

F06 Class
F06 Members


f06jj Method

[image]

NAG Library for .NET Release 2
F06..::f06jj Method
F06 Class See Also Send Feedback
f06jj computes the Euclidean norm of a complex vector.

Syntax

C#
public static double f06jj(
    int n,
    Complex[] x,
    int incx,
    out int ifail
)
Visual Basic
Public Shared Function f06jj ( _
    n As Integer, _
    x As Complex(), _
    incx As Integer, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double f06jj(
    int n,
    array<Complex>^ x,
    int incx,
    [OutAttribute] int% ifail
)
F#
static member f06jj :
        n : int *
        x : Complex[] *
        incx : int *
        ifail : int byref -> float

Parameters

n
Type: System..::..Int32
On entry: n, the number of elements in x.
x
Type: array< NagLibrary..::..Complex >[]()[][]
An array of size [dim1]
Note: the dimension of the array x must be at least max 1,1+n-1×incx.
On entry: the n-element vector x. xi must be stored in x[1+i-1×incx], for i=1,2,…,n.
Intermediate elements of x are not referenced.
incx
Type: System..::..Int32
On entry: the increment in the subscripts of x between successive elements of x.
Constraint: incx>0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error (see [Error Indicators and Warnings]).

Return Value

f06jj computes the Euclidean norm of a complex vector.

Description

f06jj returns the Euclidean norm
x 2=xH x
of the n-element complex vector x scattered with stride incx.

References

Lawson C L, Hanson R J, Kincaid D R and Krogh F T (1979) Basic linear algebra supbrograms for Fortran usage ACM Trans. Math. Software 5 308–325

Error Indicators and Warnings

ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): f06jje.cs

Example program results: f06jje.r

See Also

F06 Class
F06 Members


f06pa Method

[image]

NAG Library for .NET Release 2
F06..::f06pa Method
F06 Class See Also Send Feedback
f06pa computes the matrix-vector product for a real general matrix or its transpose.

Syntax

C#
public static void f06pa(
    string trans,
    int m,
    int n,
    double alpha,
    double[,] a,
    double[] x,
    int incx,
    double beta,
    double[] y,
    int incy,
    out int ifail
)
Visual Basic
Public Shared Sub f06pa ( _
    trans As String, _
    m As Integer, _
    n As Integer, _
    alpha As Double, _
    a As Double(,), _
    x As Double(), _
    incx As Integer, _
    beta As Double, _
    y As Double(), _
    incy As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void f06pa(
    String^ trans,
    int m,
    int n,
    double alpha,
    array<double,2>^ a,
    array<double>^ x,
    int incx,
    double beta,
    array<double>^ y,
    int incy,
    [OutAttribute] int% ifail
)
F#
static member f06pa :
        trans : string *
        m : int *
        n : int *
        alpha : float *
        a : float[,] *
        x : float[] *
        incx : int *
        beta : float *
        y : float[] *
        incy : int *
        ifail : int byref -> unit

Parameters

trans
Type: System..::..String
On entry: specifies the operation to be performed.
trans="N"
y←αAx+βy.
trans="T" or "C"
y←α AT x+βy.
Constraint: trans="N", "T" or "C".
m
Type: System..::..Int32
On entry: m, the number of rows of the matrix A.
Constraint: m≥0.
n
Type: System..::..Int32
On entry: n, the number of columns of the matrix A.
Constraint: n≥0.
alpha
Type: System..::..Double
On entry: the scalar α.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,m
Note: the second dimension of the array a must be at least n.
On entry: the m by n matrix A.
x
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array x must be at least max 1,1+n-1×incx if trans="N" and at least max 1,1+m-1×incx if trans="T" or "C".
On entry: the vector x.
If trans="N",
  • if incx>0, xi must be stored in x[1+i-1×incx-1], for i=1,2,…,n;
  • if incx<0, xi must be stored in x[1-n-i×incx-1], for i=1,2,…,n.
If trans="T" or "C",
  • if incx>0, xi must be stored in x[1+i-1×incx-1], for i=1,2,…,m;
  • if incx<0, xi must be stored in x[1-m-i×incx-1], for i=1,2,…,m.
incx
Type: System..::..Int32
On entry: the increment in the subscripts of x between successive elements of x.
Constraint: incx≠0.
beta
Type: System..::..Double
On entry: the scalar β.
y
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array y must be at least max 1,1+m-1×incy if trans="N" and at least max 1,1+n-1×incy if trans="T" or "C".
On entry: the vector y, if beta=0.0, y need not be set.
If trans="N",
  • if incy>0, yi must be stored in y[1+i-1×incy-1], for i=1,2,…,m;
  • if incy<0, yi must be stored in y[1-m-i×incy-1], for i=1,2,…,m.
If trans="T" or "C",
  • if incy>0, yi must be stored in y[1+i-1×incy-1], for i=1,2,…,n;
  • if incy<0, yi must be stored in y[1-n-i×incy-1], for i=1,2,…,n.
On exit: the updated vector y stored in the array elements used to supply the original vector y.
incy
Type: System..::..Int32
On entry: the increment in the subscripts of y between successive elements of y.
Constraint: incy≠0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f06pa performs one of the matrix-vector operations
y←αAx+βy,   or  y←α AT x+βy,
where A is an m by n real matrix, x and y are real vectors, and α and β are real scalars.
If m=0 or n=0, no operation is performed.

References

None.

Error Indicators and Warnings

ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): f06pae.cs

Example program results: f06pae.r

See Also

F06 Class
F06 Members


f06pj Method

[image]

NAG Library for .NET Release 2
F06..::f06pj Method
F06 Class See Also Send Feedback
f06pj solves a real triangular system of equations with a single right hand side.

Syntax

C#
public static void f06pj(
    string uplo,
    string trans,
    string diag,
    int n,
    double[,] a,
    double[] x,
    int incx,
    out int ifail
)
Visual Basic
Public Shared Sub f06pj ( _
    uplo As String, _
    trans As String, _
    diag As String, _
    n As Integer, _
    a As Double(,), _
    x As Double(), _
    incx As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void f06pj(
    String^ uplo,
    String^ trans,
    String^ diag,
    int n,
    array<double,2>^ a,
    array<double>^ x,
    int incx,
    [OutAttribute] int% ifail
)
F#
static member f06pj :
        uplo : string *
        trans : string *
        diag : string *
        n : int *
        a : float[,] *
        x : float[] *
        incx : int *
        ifail : int byref -> unit

Parameters

uplo
Type: System..::..String
On entry: specifies whether A is upper or lower triangular.
uplo="U"
A is upper triangular.
uplo="L"
A is lower triangular.
Constraint: uplo="U" or "L".
trans
Type: System..::..String
On entry: specifies the operation to be performed.
trans="N"
x←A-1 x.
trans="T" or "C"
x←A-T x.
Constraint: trans="N", "T" or "C".
diag
Type: System..::..String
On entry: specifies whether A has nonunit or unit diagonal elements.
diag="N"
The diagonal elements are stored explicitly.
diag="U"
The diagonal elements are assumed to be 1, and are not referenced.
Constraint: diag="N" or "U".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least n.
On entry: the n by n triangular matrix A.
  • If uplo="U", A is upper triangular and the elements of the array below the diagonal are not referenced.
  • If uplo="L", A is lower triangular and the elements of the array above the diagonal are not referenced.
  • If diag="U", the diagonal elements of A are assumed to be 1, and are not referenced.
x
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array x must be at least max 1,1+n-1×incx.
On entry: the n-element vector x.
If incx>0, xi must be stored in x[1+i–1×incx-1], for i=1,2,…,n.
If incx<0, xi must be stored in x[1–n–i×incx-1], for i=1,2,…,n.
On exit: the updated vector x stored in the array elements used to supply the original vector x.
incx
Type: System..::..Int32
On entry: the increment in the subscripts of x between successive elements of x.
Constraint: incx≠0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f06pj performs one of the matrix-vector operations
x←A-1 x  or  x←A-T x,
where A is an n by n real triangular matrix, and x is an n-element real vector. A-T denotes AT-1 or equivalently A-1 T.
No test for singularity or near-singularity of A is included in this method. Such tests must be performed before calling this method.

References

None.

Error Indicators and Warnings

ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): f06pje.cs

Example program results: f06pje.r

See Also

F06 Class
F06 Members


f06qf Method

[image]

NAG Library for .NET Release 2
F06..::f06qf Method
F06 Class See Also Send Feedback
f06qf performs the matrix-copy operation
B←A
where A and B are m by n real general or trapezoidal matrices.

Syntax

C#
public static void f06qf(
    string matrix,
    int m,
    int n,
    double[,] a,
    double[,] b,
    out int ifail
)
Visual Basic
Public Shared Sub f06qf ( _
    matrix As String, _
    m As Integer, _
    n As Integer, _
    a As Double(,), _
    b As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void f06qf(
    String^ matrix,
    int m,
    int n,
    array<double,2>^ a,
    array<double,2>^ b,
    [OutAttribute] int% ifail
)
F#
static member f06qf :
        matrix : string *
        m : int *
        n : int *
        a : float[,] *
        b : float[,] *
        ifail : int byref -> unit

Parameters

matrix
Type: System..::..String
On entry: the matrix type.
matrix="G"
General matrix.
matrix="U"
Upper trapezoidal matrix (upper triangular if m=n).
matrix="L"
Lower trapezoidal matrix (lower triangular if m=n).
Constraint: matrix="G", "U" or "L".
m
Type: System..::..Int32
On entry: m, the number of rows of the matrices A and B.
Constraint: m≥0.
n
Type: System..::..Int32
On entry: n, the number of columns of the matrices A and B.
Constraint: n≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,m
Note: the second dimension of the array a must be at least n.
On entry: the m by n general or trapezoidal matrix A.
  • If matrix="U", A is upper trapezoidal and the elements of the array below the diagonal are not referenced.
  • If matrix="L", A is lower trapezoidal and the elements of the array above the diagonal are not referenced.
b
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,m
Note: the second dimension of the array b must be at least n.
On exit: the m by n general or trapezoidal matrix B.
  • If matrix="U", B is upper trapezoidal and the elements of the array below the diagonal are not referenced.
  • If matrix="L", B is lower trapezoidal and the elements of the array above the diagonal are not referenced.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

None.

References

None.

Error Indicators and Warnings

ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): f06qfe.cs

Example program results: f06qfe.r

See Also

F06 Class
F06 Members


f06qh Method

[image]

NAG Library for .NET Release 2
F06..::f06qh Method
F06 Class See Also Send Feedback
f06qh forms the real m by n rectangular or trapezoidal matrix A given by
a ij=diagif i=jconstif i≠j.

Syntax

C#
public static void f06qh(
    string matrix,
    int m,
    int n,
    double con,
    double diag,
    double[,] a,
    out int ifail
)
Visual Basic
Public Shared Sub f06qh ( _
    matrix As String, _
    m As Integer, _
    n As Integer, _
    con As Double, _
    diag As Double, _
    a As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void f06qh(
    String^ matrix,
    int m,
    int n,
    double con,
    double diag,
    array<double,2>^ a,
    [OutAttribute] int% ifail
)
F#
static member f06qh :
        matrix : string *
        m : int *
        n : int *
        con : float *
        diag : float *
        a : float[,] *
        ifail : int byref -> unit

Parameters

matrix
Type: System..::..String
On entry: the matrix type.
matrix="G"
General matrix.
matrix="U"
Upper trapezoidal matrix (upper triangular if m=n).
matrix="L"
Lower trapezoidal matrix (lower triangular if m=n).
Constraint: matrix="G", "U" or "L".
m
Type: System..::..Int32
On entry: m, the number of rows of the matrix A.
Constraint: m≥0.
n
Type: System..::..Int32
On entry: n, the number of columns of the matrix A.
Constraint: n≥0.
con
Type: System..::..Double
On entry: the value to be assigned to the off-diagonal elements of A.
diag
Type: System..::..Double
On entry: the value to be assigned to the diagonal elements of A.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,m
Note: the second dimension of the array a must be at least n.
On exit: the m by n general or trapezoidal matrix A.
  • If matrix="U", A is upper trapezoidal and the elements of the array below the diagonal are not referenced.
  • If matrix="L", A is lower trapezoidal and the elements of the array above the diagonal are not referenced.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

None.

References

None.

Error Indicators and Warnings

ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): f06qhe.cs

Example program results: f06qhe.r

See Also

F06 Class
F06 Members


f06ya Method

[image]

NAG Library for .NET Release 2
F06..::f06ya Method
F06 Class See Also Send Feedback
f06ya performs one of the matrix-matrix operations
C←αAB+βC,C←α AT B+βC,C←αA BT+βC  orC←α ATBT+βC,
where A, B and C are real matrices, and α and β are real scalars; C is always m by n.

Syntax

C#
public static void f06ya(
    string transa,
    string transb,
    int m,
    int n,
    int k,
    double alpha,
    double[,] a,
    double[,] b,
    double beta,
    double[,] c,
    out int ifail
)
Visual Basic
Public Shared Sub f06ya ( _
    transa As String, _
    transb As String, _
    m As Integer, _
    n As Integer, _
    k As Integer, _
    alpha As Double, _
    a As Double(,), _
    b As Double(,), _
    beta As Double, _
    c As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void f06ya(
    String^ transa,
    String^ transb,
    int m,
    int n,
    int k,
    double alpha,
    array<double,2>^ a,
    array<double,2>^ b,
    double beta,
    array<double,2>^ c,
    [OutAttribute] int% ifail
)
F#
static member f06ya :
        transa : string *
        transb : string *
        m : int *
        n : int *
        k : int *
        alpha : float *
        a : float[,] *
        b : float[,] *
        beta : float *
        c : float[,] *
        ifail : int byref -> unit

Parameters

transa
Type: System..::..String
On entry: specifies whether the operation involves A or AT.
transa="N"
The operation involves A.
transa="T" or "C"
The operation involves AT.
Constraint: transa="N", "T" or "C".
transb
Type: System..::..String
On entry: specifies whether the operation involves B or BT.
transb="N"
The operation involves B.
transb="T" or "C"
The operation involves BT.
Constraint: transb="N", "T" or "C".
m
Type: System..::..Int32
On entry: m, the number of rows of the matrix C; the number of rows of A if transa="N", or the number of columns of A if transa="T" or "C".
Constraint: m≥0.
n
Type: System..::..Int32
On entry: n, the number of columns of the matrix C; the number of columns of B if transb="N", or the number of rows of B if transb="T" or "C".
Constraint: n≥0.
k
Type: System..::..Int32
On entry: k, the number of columns of A if transa="N", or the number of rows of A if transa="T" or "C"; the number of rows of B if transb="N", or the number of columns of B if transb="T" or "C".
Constraint: k≥0.
alpha
Type: System..::..Double
On entry: the scalar α.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint:
  • if transa="N", dim1≥max 1,m;
  • if transa="T" or "C", dim1≥max 1,k.
Note: the second dimension of the array a must be at least max 1,k if transa="N" and at least max 1,m if transa="T" or "C".
On entry: the matrix A; A is m by k if transa="N", or k by m if transa="T" or "C".
b
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint:
  • if transb="N", dim1≥max 1,k;
  • if transb="T" or "C", dim1≥max 1,n.
Note: the second dimension of the array b must be at least max 1,n if transb="N" and at least max 1,k if transb="T" or "C".
On entry: the matrix B; B is k by n if transb="N", or n by k if transb="T" or "C".
beta
Type: System..::..Double
On entry: the scalar β.
c
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,m
Note: the second dimension of the array c must be at least max 1,n.
On entry: the m by n matrix C.
If beta=0, c need not be set.
On exit: the updated matrix C.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

None.

References

None.

Error Indicators and Warnings

ifail=-6000
Invalid Parameters . Check Documentation

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): f06yae.cs

Example program results: f06yae.r

See Also

F06 Class
F06 Members


f06yj Method

[image]

NAG Library for .NET Release 2
F06..::f06yj Method
F06 Class See Also Send Feedback
f06yj performs one of the matrix-matrix operations
B←α A-1 B,B←α A-T B,B←αB A-1  orB←αB A-T,
where A is a real triangular matrix, B is an m by n real matrix, and α is a real scalar. A-T denotes AT-1 or equivalently A-1 T.
No test for singularity or near-singularity of A is included in this method. Such tests must be performed before calling this method.

Syntax

C#
public static void f06yj(
    string side,
    string uplo,
    string transa,
    string diag,
    int m,
    int n,
    double alpha,
    double[,] a,
    double[,] b,
    out int ifail
)
Visual Basic
Public Shared Sub f06yj ( _
    side As String, _
    uplo As String, _
    transa As String, _
    diag As String, _
    m As Integer, _
    n As Integer, _
    alpha As Double, _
    a As Double(,), _
    b As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void f06yj(
    String^ side,
    String^ uplo,
    String^ transa,
    String^ diag,
    int m,
    int n,
    double alpha,
    array<double,2>^ a,
    array<double,2>^ b,
    [OutAttribute] int% ifail
)
F#
static member f06yj :
        side : string *
        uplo : string *
        transa : string *
        diag : string *
        m : int *
        n : int *
        alpha : float *
        a : float[,] *
        b : float[,] *
        ifail : int byref -> unit

Parameters

side
Type: System..::..String
On entry: specifies whether B is operated on from the left or the right.
side="L"
B is pre-multiplied from the left.
side="R"
B is post-multiplied from the right.
Constraint: side="L" or "R".
uplo
Type: System..::..String
On entry: specifies whether A is upper or lower triangular.
uplo="U"
A is upper triangular.
uplo="L"
A is lower triangular.
Constraint: uplo="U" or "L".
transa
Type: System..::..String
On entry: specifies whether the operation involves A-1 or A-T.
transa="N"
The operation involves A-1.
transa="T" or "C"
The operation involves A-T.
Constraint: transa="N", "T" or "C".
diag
Type: System..::..String
On entry: specifies whether A has nonunit or unit diagonal elements.
diag="N"
The diagonal elements are stored explicitly.
diag="U"
The diagonal elements are assumed to be 1, and are not referenced.
Constraint: diag="N" or "U".
m
Type: System..::..Int32
On entry: m, the number of rows of the matrix B; the order of A if side="L".
Constraint: m≥0.
n
Type: System..::..Int32
On entry: n, the number of columns of the matrix B; the order of A if side="R".
Constraint: n≥0.
alpha
Type: System..::..Double
On entry: the scalar α.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint:
  • if side="L", dim1≥max 1,m;
  • if side="R", dim1≥max 1,n.
Note: the second dimension of the array a must be at least max 1,m if side="L" and at least max 1,n if side="R".
On entry: the triangular matrix A; A is m by m if side="L", or n by n if side="R".
  • If uplo="U", A is upper triangular and the elements of the array below the diagonal are not referenced.
  • If uplo="L", A is lower triangular and the elements of the array above the diagonal are not referenced.
  • If diag="U", the diagonal elements of A are assumed to be 1, and are not referenced.
b
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,m
Note: the second dimension of the array b must be at least max 1,n.
On entry: the m by n matrix B.
If alpha=0, b need not be set.
On exit: the updated matrix B.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

None.

References

None.

Error Indicators and Warnings

ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): f06yje.cs

Example program results: f06yje.r

See Also

F06 Class
F06 Members


F07 Class

[image]

NAG Library for .NET Release 2
F07 Class
Members See Also Send Feedback
This chapter provides methods for the solution of systems of simultaneous linear equations, and associated computations. It provides methods for
  • – matrix factorizations;
  • – solution of linear equations;
  • – estimating matrix condition numbers;
  • – computing error bounds for the solution of linear equations;
  • – matrix inversion;
  • – computing scaling factors to equilibrate a matrix.
Methods are provided for both real and complex data.
For a general introduction to the solution of systems of linear equations, you should turn first to (F04 not in this release). The decision trees, in [Decision Trees] in the F04 class Chapter Introduction, direct you to the most appropriate methods in (F04 not in this release) F07 class for solving your particular problem. In particular, (F04 not in this release) F07 class contain Black Box (or driver) methods which enable some standard types of problem to be solved by a call to a single method. Where possible, methods in (F04 not in this release) call F07 class methods to perform the necessary computational tasks.
There are two types of driver methods in this chapter: simple drivers which just return the solution to the linear equations; and expert drivers which also return condition and error estimates and, in many cases, also allow equilibration. The simple drivers for real matrices have names of the form and for complex matrices have names of the form The expert drivers for real matrices have names of the form and for complex matrices have names of the form
The methods in this chapter ( F07 class) handle only dense and band matrices (not matrices with more specialised structures, or general sparse matrices).
The methods in this chapter have all been derived from the LAPACK project (see Anderson et al. (1999)). They have been designed to be efficient on a wide range of high-performance computers, without compromising efficiency on conventional serial machines.

Syntax

C#
public static class F07
Visual Basic
Public NotInheritable Class F07
Visual C++
public ref class F07 abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type F07 =  class end

Background to the Problems

This section is only a brief introduction to the numerical solution of systems of linear equations. Consult a standard textbook, for example Golub and Van Loan (1996) for a more thorough discussion.

Notation

We use the standard notation for a system of simultaneous linear equations:
Ax=b (1)
where A is the coefficient matrix, b is the right-hand side, and x is the solution. A is assumed to be a square matrix of order n.
If there are several right-hand sides, we write
AX=B (2)
where the columns of B are the individual right-hand sides, and the columns of X are the corresponding solutions.
We also use the following notation, both here and in the method documents:
x^ | a computed solution to Ax=b, (which usually differs from the exact solution x because of round-off error)
r=b-A x^ | the residual corresponding to the computed solution x^
x∞=maxi xi | the ∞-norm of the vector x
x 1=∑j=1 n xj | the 1-norm of the vector x
A∞=maxi∑j a ij | the ∞-norm of the matrix A
A 1=maxj∑i=1 n a ij | the 1-norm of the matrix A
x | the vector with elements xi
A | the matrix with elements a ij
Inequalities of the form A≤B are interpreted component-wise, that is a ij≤b ij for all i,j.

Matrix Factorizations

If A is upper or lower triangular, Ax=b can be solved by a straightforward process of backward or forward substitution.
Otherwise, the solution is obtained after first factorizing A, as follows.
General matrices (LU factorization with partial pivoting)
A=PLU
where P is a permutation matrix, L is lower-triangular with diagonal elements equal to 1, and U is upper-triangular; the permutation matrix P (which represents row interchanges) is needed to ensure numerical stability.
Symmetric positive definite matrices (Cholesky factorization)
A=UT U  or  A=L LT
where U is upper triangular and L is lower triangular.
Symmetric positive semidefinite matrices (pivoted Cholesky factorization)
A=P UT U PT or A=PL LTPT
where P is a permutation matrix, U is upper triangular and L is lower triangular. The permutation matrix P (which represents row-and-column interchanges) is needed to ensure numerical stability and to reveal the numerical rank of A.
Symmetric indefinite matrices (Bunch–Kaufman factorization)
A=PUD UTPT  or  A=PLD LTPT
where P is a permutation matrix, U is upper triangular, L is lower triangular, and D is a block diagonal matrix with diagonal blocks of order 1 or 2; U and L have diagonal elements equal to 1, and have 2 by 2 unit matrices on the diagonal corresponding to the 2 by 2 blocks of D. The permutation matrix P (which represents symmetric row-and-column interchanges) and the 2 by 2 blocks in D are needed to ensure numerical stability. If A is in fact positive definite, no interchanges are needed and the factorization reduces to A=UD UT or A=LD LT with diagonal D, which is simply a variant form of the Cholesky factorization.

Solution of Systems of Equations

Given one of the above matrix factorizations, it is straightforward to compute a solution to Ax=b by solving two subproblems, as shown below, first for y and then for x. Each subproblem consists essentially of solving a triangular system of equations by forward or backward substitution; the permutation matrix P and the block diagonal matrix D introduce only a little extra complication:
General matrices ( LU factorization)
Ly=PT bUx=y
Symmetric positive definite matrices (Cholesky factorization)
UT y=bUx=y  or  Ly=bLT x=y
Symmetric indefinite matrices (Bunch–Kaufman factorization)
PUDy=bUTPT x=y  or  PLDy=bLTPT x=y

Sensitivity and Error Analysis

Normwise error bounds

Frequently, in practical problems the data A and b are not known exactly, and it is then important to understand how uncertainties or perturbations in the data can affect the solution.
If x is the exact solution to Ax=b, and x+δx is the exact solution to a perturbed problem A+δAx+δx=b+δb, then
δxx≤κ AδAA+δbb+⋯second-order terms
where κ A is the condition number of A defined by
κ A=A.A-1. (3)
In other words, relative errors in A or b may be amplified in x by a factor κ A. [Estimating condition numbers] discusses how to compute or estimate κ A.
Similar considerations apply when we study the effects of rounding errors introduced by computation in finite precision. The effects of rounding errors can be shown to be equivalent to perturbations in the original data, such that δAA and δbb are usually at most p n ε, where ε is the machine precision and p n is an increasing function of n which is seldom larger than 10 n (although in theory it can be as large as 2 n-1).
In other words, the computed solution x^ is the exact solution of a linear system A+δA x^=b+δb which is close to the original system in a normwise sense.

Estimating condition numbers

The previous section has emphasized the usefulness of the quantity κ A in understanding the sensitivity of the solution of Ax=b. To compute the value of κ A from equation (3) is more expensive than solving Ax=b in the first place. Hence it is standard practice to estimate κ A, in either the 1-norm or the ∞-norm, by a method which only requires O n 2 additional operations, assuming that a suitable factorization of A is available.
The method used in this chapter is Higham's modification of Hager's method (see Higham (1988)). It yields an estimate which is never larger than the true value, but which seldom falls short by more than a factor of 3 (although artificial examples can be constructed where it is much smaller). This is acceptable since it is the order of magnitude of κ A which is important rather than its precise value.
Because κ A is infinite if A is singular, the methods in this chapter actually return the reciprocal of κ A.

Scaling and Equilibration

The condition of a matrix and hence the accuracy of the computed solution, may be improved by scaling; thus if D 1 and D 2 are diagonal matrices with positive diagonal elements, then
B=D 1 A D 2
is the scaled matrix. A general matrix is said to be equilibrated if it is scaled so that the lengths of its rows and columns have approximately equal magnitude. Similarly a general matrix is said to be row-equilibrated (column-equilibrated) if it is scaled so that the lengths of its rows (columns) have approximately equal magnitude. Note that row scaling can affect the choice of pivot when partial pivoting is used in the factorization of A.
A symmetric or Hermitian positive definite matrix is said to be equilibrated if the diagonal elements are all approximately equal to unity.
For further information on scaling and equilibration see Section 3.5.2 of Golub and Van Loan (1996), Section 7.2, 7.3 and 9.8 of Higham (1988) and Section 5 of Chapter 4 of Wilkinson (1965).
Methods are provided to return the scaling factors that equilibrate a matrix for general, general band, symmetric and Hermitian positive definite and symmetric and Hermitian positive definite band matrices.

Componentwise error bounds

A disadvantage of normwise error bounds is that they do not reflect any special structure in the data A and b – that is, a pattern of elements which are known to be zero – and the bounds are dominated by the largest elements in the data.
Componentwise error bounds overcome these limitations. Instead of the normwise relative error, we can bound the relative error in each component of A and b:
max ijk δ a ija ij,δ bkbk≤ω
where the component-wise backward error bound ω is given by
ω=maxi riA.x^+b i.
Methods are provided in this chapter which compute ω, and also compute a forward error bound which is sometimes much sharper than the normwise bound given earlier:
x-x^∞x∞≤A-1.r∞x∞.
Care is taken when computing this bound to allow for rounding errors in computing r. The norm A-1.r∞ is estimated cheaply (without computing A-1) by a modification of the method used to estimate κ A.

Iterative refinement of the solution

If x^ is an approximate computed solution to Ax=b, and r is the corresponding residual, then a procedure for iterative refinement of x^ can be defined as follows, starting with x 0=x^:
  • for i=0,1,…, until convergence
    compute | ri=b-A xi
    solve | A di=ri
    compute | x i+1=xi+di
In (F04 not in this release), methods are provided which perform this procedure using additional precision to compute r, and are thus able to reduce the forward error to the level of machine precision.
The methods in this chapter do not use additional precision to compute r, and cannot guarantee a small forward error, but can guarantee a small backward error (except in rare cases when A is very ill-conditioned, or when A and x are sparse in such a way that A.x has a zero or very small component). The iterations continue until the backward error has been reduced as much as possible; usually only one iteration is needed.

Matrix Inversion

It is seldom necessary to compute an explicit inverse of a matrix. In particular, do not attempt to solve Ax=b by first computing A-1 and then forming the matrix-vector product x=A-1 b; the procedure described in [Solution of Systems of Equations] is more efficient and more accurate.
However, methods are provided for the rare occasions when an inverse is needed, using one of the factorizations described in [Matrix Factorizations].

Packed Storage Formats

Methods which handle symmetric matrices are usually designed so that they use either the upper or lower triangle of the matrix; it is not necessary to store the whole matrix. If the upper or lower triangle is stored conventionally in the upper or lower triangle of a two-dimensional array, the remaining elements of the array can be used to store other useful data.
However, that is not always convenient, and if it is important to economize on storage, the upper or lower triangle can be stored in a one-dimensional array of length n n+1/2 or a two-dimensional array with n n+1/2 elements; in other words, the storage is almost halved.
The one-dimensional array storage format is referred to as packed storage; it is described in [Packed storage]. The two-dimensional array storage format is referred to as Rectangular Full Packed (RFP) format; it is described in [Rectangular Full Packed (RFP) Storage]. They may also be used for triangular matrices.
Methods designed for these packed storage formats perform the same number of arithmetic operations as methods which use conventional storage. Those using a packed one-dimensional array are usually less efficient, especially on high-performance computers, so there is then a trade-off between storage and efficiency. The RFP methods are as efficient as for conventional storage, although only a small subset of methods use this format.

Band and Tridiagonal Matrices

A band matrix is one whose nonzero elements are confined to a relatively small number of subdiagonals or superdiagonals on either side of the main diagonal. A tridiagonal matrix is a special case of a band matrix with just one subdiagonal and one superdiagonal. Algorithms can take advantage of bandedness to reduce the amount of work and storage required. The storage scheme used for band matrices is described in [Band storage].
The LU factorization for general matrices, and the Cholesky factorization for symmetric and Hermitian positive definite matrices both preserve bandedness. Hence methods are provided which take advantage of the band structure when solving systems of linear equations.
The Cholesky factorization preserves bandedness in a very precise sense: the factor U or L has the same number of superdiagonals or subdiagonals as the original matrix. In the LU factorization, the row-interchanges modify the band structure: if A has kl subdiagonals and ku superdiagonals, then L is not a band matrix but still has at most kl nonzero elements below the diagonal in each column; and U has at most kl+ku superdiagonals.
The Bunch–Kaufman factorization does not preserve bandedness, because of the need for symmetric row-and-column permutations; hence no methods are provided for symmetric indefinite band matrices.
The inverse of a band matrix does not in general have a band structure, so no methods are provided for computing inverses of band matrices.

Block Partitioned Algorithms

Many of the methods in this chapter use what is termed a block partitioned algorithm. This means that at each major step of the algorithm a block of rows or columns is updated, and most of the computation is performed by matrix-matrix operations on these blocks. The matrix-matrix operations are performed by calls to the Level 3 BLAS (see F06 class), which are the key to achieving high performance on many modern computers. See Golub and Van Loan (1996) or Anderson et al. (1999) for more about block partitioned algorithms.
The performance of a block partitioned algorithm varies to some extent with the block size – that is, the number of rows or columns per block. This is a machine-dependent parameter, which is set to a suitable value when the library is implemented on each range of machines. You do not normally need to be aware of what value is being used. Different block sizes may be used for different methods. Values in the range 16 to 64 are typical.
On some machines there may be no advantage from using a block partitioned algorithm, and then the methods use an unblocked algorithm (effectively a block size of 1), relying solely on calls to the Level 2 BLAS (see F06 class again).
The only situation in which you need some awareness of the block size is when it affects the amount of workspace to be supplied to a particular method. This is discussed in [Length of work arrays].

Mixed Precision LAPACK Routines

Some LAPACK routines use mixed precision arithmetic in an effort to solve problems more efficiently on modern hardware. They work by converting a double precision problem into an equivalent single precision problem, solving it and then using iterative refinement in double precision to find a full precision solution to the original problem. The method may fail if the problem is too ill-conditioned to allow the initial single precision solution, in which case the methods fall back to solve the original problem entirely in double precision. The vast majority of problems are not so ill-conditioned, and in those cases the technique can lead to significant gains in speed without loss of accuracy. This is particularly true on machines where double precision arithmetic is significantly slower than single precision.

References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Higham N J (1988) Algorithm 674: Fortran codes for estimating the one-norm of a real or complex matrix, with applications to condition estimation ACM Trans. Math. Software 14 381–396
Wilkinson J H (1965) The Algebraic Eigenvalue Problem Oxford University Press, Oxford

Inheritance Hierarchy

System..::..Object
NagLibrary..::..F07

See Also

F07 Members


F07 Members

[image] [image]

NAG Library for .NET Release 2
F07 Members
F07 Class Methods See Also Send Feedback

The F07 type exposes the following members.

Methods

Name Description
f07ab
f07ab uses the LU factorization to compute the solution to a real system of linear equations
AX=B  or  AT X=B,
where A is an n by n matrix and X and B are n by r matrices. Error bounds on the solution and a condition estimate are also provided.
f07ap
f07ap uses the LU factorization to compute the solution to a complex system of linear equations
AX=B  or  AT X=B  or  AH X=B,
where A is an n by n matrix and X and B are n by r matrices. Error bounds on the solution and a condition estimate are also provided.
f07ar
f07ar computes the LU factorization of a complex m by n matrix.
f07as
f07as solves a complex system of linear equations with multiple right-hand sides,
AX=B, AT X=B  or  AH X=B,
where A has been factorized by f07ar.
f07fb
f07fb uses the Cholesky factorization
A=UT U  or  A=L LT
to compute the solution to a real system of linear equations
AX=B,
where A is an n by n symmetric positive definite matrix and X and B are n by r matrices. Error bounds on the solution and a condition estimate are also provided.
f07fp
f07fp uses the Cholesky factorization
A=UH U  or  A=L LH
to compute the solution to a complex system of linear equations
AX=B,
where A is an n by n Hermitian positive definite matrix and X and B are n by r matrices. Error bounds on the solution and a condition estimate are also provided.
f07hd
f07hd computes the Cholesky factorization of a real symmetric positive definite band matrix.
f07he
f07he solves a real symmetric positive definite band system of linear equations with multiple right-hand sides,
AX=B,
where A has been factorized by f07hd.
f07te
f07te solves a real triangular system of linear equations with multiple right-hand sides, AX=B or AT X=B.
f07th
f07th returns error bounds for the solution of a real triangular system of linear equations with multiple right-hand sides, AX=B or AT X=B.
f07tj
f07tj computes the inverse of a real triangular matrix.

See Also

F07 Class


F07 Methods

[image] [image]

NAG Library for .NET Release 2
F07 Methods
F07 Class See Also Send Feedback

The F07 type exposes the following members.

Methods

Name Description
f07ab
f07ab uses the LU factorization to compute the solution to a real system of linear equations
AX=B  or  AT X=B,
where A is an n by n matrix and X and B are n by r matrices. Error bounds on the solution and a condition estimate are also provided.
f07ap
f07ap uses the LU factorization to compute the solution to a complex system of linear equations
AX=B  or  AT X=B  or  AH X=B,
where A is an n by n matrix and X and B are n by r matrices. Error bounds on the solution and a condition estimate are also provided.
f07ar
f07ar computes the LU factorization of a complex m by n matrix.
f07as
f07as solves a complex system of linear equations with multiple right-hand sides,
AX=B, AT X=B  or  AH X=B,
where A has been factorized by f07ar.
f07fb
f07fb uses the Cholesky factorization
A=UT U  or  A=L LT
to compute the solution to a real system of linear equations
AX=B,
where A is an n by n symmetric positive definite matrix and X and B are n by r matrices. Error bounds on the solution and a condition estimate are also provided.
f07fp
f07fp uses the Cholesky factorization
A=UH U  or  A=L LH
to compute the solution to a complex system of linear equations
AX=B,
where A is an n by n Hermitian positive definite matrix and X and B are n by r matrices. Error bounds on the solution and a condition estimate are also provided.
f07hd
f07hd computes the Cholesky factorization of a real symmetric positive definite band matrix.
f07he
f07he solves a real symmetric positive definite band system of linear equations with multiple right-hand sides,
AX=B,
where A has been factorized by f07hd.
f07te
f07te solves a real triangular system of linear equations with multiple right-hand sides, AX=B or AT X=B.
f07th
f07th returns error bounds for the solution of a real triangular system of linear equations with multiple right-hand sides, AX=B or AT X=B.
f07tj
f07tj computes the inverse of a real triangular matrix.

See Also

F07 Class


f07ab Method

[image]

NAG Library for .NET Release 2
F07..::f07ab Method
F07 Class See Also Send Feedback
f07ab uses the LU factorization to compute the solution to a real system of linear equations
AX=B  or  AT X=B,
where A is an n by n matrix and X and B are n by r matrices. Error bounds on the solution and a condition estimate are also provided.

Syntax

C#
public static void f07ab(
    string fact,
    string trans,
    int n,
    int nrhs,
    double[,] a,
    double[,] af,
    int[] ipiv,
    ref string equed,
    double[] r,
    double[] c,
    double[,] b,
    double[,] x,
    out double rcond,
    double[] ferr,
    double[] berr,
    out double rgf,
    out int info
)
Visual Basic
Public Shared Sub f07ab ( _
    fact As String, _
    trans As String, _
    n As Integer, _
    nrhs As Integer, _
    a As Double(,), _
    af As Double(,), _
    ipiv As Integer(), _
    ByRef equed As String, _
    r As Double(), _
    c As Double(), _
    b As Double(,), _
    x As Double(,), _
    <OutAttribute> ByRef rcond As Double, _
    ferr As Double(), _
    berr As Double(), _
    <OutAttribute> ByRef rgf As Double, _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f07ab(
    String^ fact,
    String^ trans,
    int n,
    int nrhs,
    array<double,2>^ a,
    array<double,2>^ af,
    array<int>^ ipiv,
    String^% equed,
    array<double>^ r,
    array<double>^ c,
    array<double,2>^ b,
    array<double,2>^ x,
    [OutAttribute] double% rcond,
    array<double>^ ferr,
    array<double>^ berr,
    [OutAttribute] double% rgf,
    [OutAttribute] int% info
)
F#
static member f07ab :
        fact : string *
        trans : string *
        n : int *
        nrhs : int *
        a : float[,] *
        af : float[,] *
        ipiv : int[] *
        equed : string byref *
        r : float[] *
        c : float[] *
        b : float[,] *
        x : float[,] *
        rcond : float byref *
        ferr : float[] *
        berr : float[] *
        rgf : float byref *
        info : int byref -> unit

Parameters

fact
Type: System..::..String
On entry: specifies whether or not the factorized form of the matrix A is supplied on entry, and if not, whether the matrix A should be equilibrated before it is factorized.
fact="F"
af and ipiv contain the factorized form of A. If equed≠"N", the matrix A has been equilibrated with scaling factors given by r and c. a, af and ipiv are not modified.
fact="N"
The matrix A will be copied to af and factorized.
fact="E"
The matrix A will be equilibrated if necessary, then copied to af and factorized.
Constraint: fact="F", "N" or "E".
trans
Type: System..::..String
On entry: specifies the form of the system of equations.
trans="N"
AX=B (No transpose).
trans="T" or "C"
AT X=B (Transpose).
Constraint: trans="N", "T" or "C".
n
Type: System..::..Int32
On entry: n, the number of linear equations, i.e., the order of the matrix A.
Constraint: n≥0.
nrhs
Type: System..::..Int32
On entry: r, the number of right-hand sides, i.e., the number of columns of the matrix B.
Constraint: nrhs≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least max 1,n.
On entry: the n by n matrix A.
If fact="F" and equed≠"N", a must have been equilibrated by the scaling factors in r and/or c.
On exit: if fact="F" or "N", or if fact="E" and equed="N", a is not modified.
If fact="E" or equed≠"N", A is scaled as follows:
  • if equed="R", A=DR A;
  • if equed="C", A=A DC;
  • if equed="B", A=DR A DC.
af
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array af must be at least max 1,n.
On entry: if fact="F", af contains the factors L and U from the factorization A=PLU as computed by f07ad. If equed≠"N", af is the factorized form of the equilibrated matrix A.
If fact="N" or "E", af need not be set.
On exit: if fact="N", af returns the factors L and U from the factorization A=PLU of the original matrix A.
If fact="E", af returns the factors L and U from the factorization A=PLU of the equilibrated matrix A (see the description of a for the form of the equilibrated matrix).
If fact="F", af is unchanged from entry.
ipiv
Type: array< System..::..Int32 >[]()[][]
An array of size [dim1]
Note: the dimension of the array ipiv must be at least max 1,n.
On entry: if fact="F", ipiv contains the pivot indices from the factorization A=PLU as computed by f07ad; at the ith step row i of the matrix was interchanged with row ipiv[i-1]. ipiv[i-1]=i indicates a row interchange was not required.
If fact="N" or "E", ipiv need not be set.
On exit: if fact="N", ipiv contains the pivot indices from the factorization A=PLU of the original matrix A.
If fact="E", ipiv contains the pivot indices from the factorization A=PLU of the equilibrated matrix A.
If fact="F", ipiv is unchanged from entry.
equed
Type: System..::..String %
On entry: if fact="N" or "E", equed need not be set.
If fact="F", equed must specify the form of the equilibration that was performed as follows:
  • if equed="N", no equilibration;
  • if equed="R", row equilibration, i.e., A has been premultiplied by DR;
  • if equed="C", column equilibration, i.e., A has been postmultiplied by DC;
  • if equed="B", both row and column equilibration, i.e., A has been replaced by DR A DC.
On exit: if fact="F", equed is unchanged from entry.
Otherwise, if no constraints are violated, equed specifies the form of equilibration that was performed as specified above.
Constraint: if fact="F", equed="N", "R", "C" or "B".
r
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array r must be at least max 1,n.
On entry: if fact="N" or "E", r need not be set.
If fact="F" and equed="R" or "B", r must contain the row scale factors for A, DR; each element of r must be positive.
On exit: if fact="F", r is unchanged from entry.
Otherwise, if no constraints are violated and equed="R" or "B", r contains the row scale factors for A, DR, such that A is multiplied on the left by DR; each element of r is positive.
c
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array c must be at least max 1,n.
On entry: if fact="N" or "E", c need not be set.
If fact="F" or equed="C" or "B", c must contain the column scale factors for A, DC; each element of c must be positive.
On exit: if fact="F", c is unchanged from entry.
Otherwise, if no constraints are violated and equed="C" or "B", c contains the row scale factors for A, DC; each element of c is positive.
b
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array b must be at least max 1,nrhs.
On entry: the n by r right-hand side matrix B.
On exit: if equed="N", b is not modified.
If trans="N" and equed="R" or "B", b is overwritten by DR B.
If trans="T" or "C" and equed="C" or "B", b is overwritten by DC B.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array x must be at least max 1,nrhs.
On exit: if info=0 or n+1, the n by r solution matrix X to the original system of equations. Note that the arrays A and B are modified on exit if equed≠"N", and the solution to the equilibrated system is DC-1 X if trans="N" and equed="C" or "B", or DR-1 X if trans="T" or "C" and equed="R" or "B".
rcond
Type: System..::..Double %
On exit: if no constraints are violated, an estimate of the reciprocal condition number of the matrix A (after equilibration if that is performed), computed as rcond=1.0/A 1A-1 1.
ferr
Type: array< System..::..Double >[]()[][]
An array of size [nrhs]
On exit: if info=0 or n+1, an estimate of the forward error bound for each computed solution vector, such that x^j-xj∞/xj∞≤ferr[j-1] where x^j is the jth column of the computed solution returned in the array x and xj is the corresponding column of the exact solution X. The estimate is as reliable as the estimate for rcond, and is almost always a slight overestimate of the true error.
berr
Type: array< System..::..Double >[]()[][]
An array of size [nrhs]
On exit: if info=0 or n+1, an estimate of the component-wise relative backward error of each computed solution vector x^j (i.e., the smallest relative change in any element of A or B that makes x^j an exact solution).
rgf
Type: System..::..Double %
On exit: if info=0, the reciprocal pivot growth factor A/U, where . denotes the maximum absolute element norm. If rgf≪1, the stability of the LU factorization of A could be poor. This also means that the solution x, condition estimate rcond, and forward error bound ferr could be unreliable. If the factorization fails with info>0 and info≤n, then rgf contains the reciprocal pivot growth factor for the leading info columns of A.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f07ab performs the following steps:
1. Equilibration
The linear system to be solved may be badly scaled. However, the system can be equilibrated as a first stage by setting fact="E". In this case, real scaling factors are computed and these factors then determine whether the system is to be equilibrated. Equilibrated forms of the systems AX=B and AT X=B are
DR A DCDC-1 X=DR B
and
DR A DC T DR-1 X=DC B,
respectively, where DR and DC are diagonal matrices, with positive diagonal elements, formed from the computed scaling factors.
When equilibration is used, A will be overwritten by DR A DC and B will be overwritten by DR B (or DC B when the solution of AT X=B is sought).
2. Factorization
The matrix A, or its scaled form, is copied and factored using the LU decomposition
A=PLU,
where P is a permutation matrix, L is a unit lower triangular matrix, and U is upper triangular.
This stage can be by-passed when a factored matrix (with scaled matrices and scaling factors) are supplied; for example, as provided by a previous call to f07ab with the same matrix A.
3. Condition Number Estimation
The LU factorization of A determines whether a solution to the linear system exists. If some diagonal element of U is zero, then U is exactly singular, no solution exists and the method returns with a failure. Otherwise the factorized form of A is used to estimate the condition number of the matrix A. If the reciprocal of the condition number is less than machine precision then a warning code is returned on final exit.
4. Solution
The (equilibrated) system is solved for X (DC-1 X or DR-1 X) using the factored form of A (DR A DC).
5. Iterative Refinement
Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for the computed solution.
6. Construct Solution Matrix X
If equilibration was used, the matrix X is premultiplied by DC (if trans="N") or DR (if trans="T" or "C") so that it solves the original system before equilibration.

References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Higham N J (2002) Accuracy and Stability of Numerical Algorithms (2nd Edition) SIAM, Philadelphia

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA, LDAF, LDB, LDX, WORK) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
info>0 and info≤n
Element value of the diagonal is exactly zero. The factorization has been completed, but the factor U is exactly singular, so the solution and error bounds could not be computed. rcond=0.0 is returned.
info=n+1
U is nonsingular, but rcond is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of rcond would suggest.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

For each right-hand side vector b, the computed solution x^ is the exact solution of a perturbed system of equations A+E x^=b, where
E≤c n εP LU,
c n is a modest linear function of n, and ε is the machine precision. See Section 9.3 of Higham (2002) for further details.
If x is the true solution, then the computed solution x^ satisfies a forward error bound of the form
x-x^∞x^∞≤wc cond A,x^,b
where cond A,x^,b=A-1Ax^+b∞/x^∞≤cond A=A-1A∞≤κ∞A. If x^ is the jth column of X, then wc is returned in berr[j-1] and a bound on x-x^∞/x^∞ is returned in ferr[j-1]. See Section 4.4 of Anderson et al. (1999) for further details.

Parallelism and Performance

None.

Further Comments

The factorization of A requires approximately 23 n 3 floating-point operations.
Estimating the forward error involves solving a number of systems of linear equations of the form Ax=b or AT x=b; the number is usually 4 or 5 and never more than 11. Each solution involves approximately 2⁢n 2 operations.
In practice the condition number estimator is very reliable, but it can underestimate the true condition number; see Section 15.3 of Higham (2002) for further details.
The complex analogue of this method is f07ap.

Example

This example solves the equations
AX=B,
where A is the general matrix
A=1.802.882.05-0.89525.00-295.00-95.00-380.001.58-2.69-2.90-1.04-1.11-0.66-0.59-0.80
and
B=9.5218.472435.00225.000.77-13.28-6.22-6.21.
Error estimates for the solutions, information on scaling, an estimate of the reciprocal of the condition number of the scaled matrix A and an estimate of the reciprocal of the pivot growth factor for the factorization of A are also output.

Example program (C#): f07abe.cs

Example program data: f07abe.d

Example program results: f07abe.r

See Also

F07 Class
F07 Members


f07ap Method

[image]

NAG Library for .NET Release 2
F07..::f07ap Method
F07 Class See Also Send Feedback
f07ap uses the LU factorization to compute the solution to a complex system of linear equations
AX=B  or  AT X=B  or  AH X=B,
where A is an n by n matrix and X and B are n by r matrices. Error bounds on the solution and a condition estimate are also provided.

Syntax

C#
public static void f07ap(
    string fact,
    string trans,
    int n,
    int nrhs,
    Complex[,] a,
    Complex[,] af,
    int[] ipiv,
    ref string equed,
    double[] r,
    double[] c,
    Complex[,] b,
    Complex[,] x,
    out double rcond,
    double[] ferr,
    double[] berr,
    out double rgf,
    out int info
)
Visual Basic
Public Shared Sub f07ap ( _
    fact As String, _
    trans As String, _
    n As Integer, _
    nrhs As Integer, _
    a As Complex(,), _
    af As Complex(,), _
    ipiv As Integer(), _
    ByRef equed As String, _
    r As Double(), _
    c As Double(), _
    b As Complex(,), _
    x As Complex(,), _
    <OutAttribute> ByRef rcond As Double, _
    ferr As Double(), _
    berr As Double(), _
    <OutAttribute> ByRef rgf As Double, _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f07ap(
    String^ fact,
    String^ trans,
    int n,
    int nrhs,
    array<Complex,2>^ a,
    array<Complex,2>^ af,
    array<int>^ ipiv,
    String^% equed,
    array<double>^ r,
    array<double>^ c,
    array<Complex,2>^ b,
    array<Complex,2>^ x,
    [OutAttribute] double% rcond,
    array<double>^ ferr,
    array<double>^ berr,
    [OutAttribute] double% rgf,
    [OutAttribute] int% info
)
F#
static member f07ap :
        fact : string *
        trans : string *
        n : int *
        nrhs : int *
        a : Complex[,] *
        af : Complex[,] *
        ipiv : int[] *
        equed : string byref *
        r : float[] *
        c : float[] *
        b : Complex[,] *
        x : Complex[,] *
        rcond : float byref *
        ferr : float[] *
        berr : float[] *
        rgf : float byref *
        info : int byref -> unit

Parameters

fact
Type: System..::..String
On entry: specifies whether or not the factorized form of the matrix A is supplied on entry, and if not, whether the matrix A should be equilibrated before it is factorized.
fact="F"
af and ipiv contain the factorized form of A. If equed≠"N", the matrix A has been equilibrated with scaling factors given by r and c. a, af and ipiv are not modified.
fact="N"
The matrix A will be copied to af and factorized.
fact="E"
The matrix A will be equilibrated if necessary, then copied to af and factorized.
Constraint: fact="F", "N" or "E".
trans
Type: System..::..String
On entry: specifies the form of the system of equations.
trans="N"
AX=B (No transpose).
trans="T"
AT X=B (Transpose).
trans="C"
AH X=B (Conjugate transpose).
Constraint: trans="N", "T" or "C".
n
Type: System..::..Int32
On entry: n, the number of linear equations, i.e., the order of the matrix A.
Constraint: n≥0.
nrhs
Type: System..::..Int32
On entry: r, the number of right-hand sides, i.e., the number of columns of the matrix B.
Constraint: nrhs≥0.
a
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least max 1,n.
On entry: the n by n matrix A.
If fact="F" and equed≠"N", a must have been equilibrated by the scaling factors in r and/or c.
On exit: if fact="F" or "N", or if fact="E" and equed="N", a is not modified.
If fact="E" or equed≠"N", A is scaled as follows:
  • if equed="R", A=DR A;
  • if equed="C", A=A DC;
  • if equed="B", A=DR A DC.
af
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array af must be at least max 1,n.
On entry: if fact="F", af contains the factors L and U from the factorization A=PLU as computed by f07ar. If equed≠"N", af is the factorized form of the equilibrated matrix A.
If fact="N" or "E", af need not be set.
On exit: if fact="N", af returns the factors L and U from the factorization A=PLU of the original matrix A.
If fact="E", af returns the factors L and U from the factorization A=PLU of the equilibrated matrix A (see the description of a for the form of the equilibrated matrix).
If fact="F", af is unchanged from entry.
ipiv
Type: array< System..::..Int32 >[]()[][]
An array of size [dim1]
Note: the dimension of the array ipiv must be at least max 1,n.
On entry: if fact="F", ipiv contains the pivot indices from the factorization A=PLU as computed by f07ar; at the ith step row i of the matrix was interchanged with row ipiv[i-1]. ipiv[i-1]=i indicates a row interchange was not required.
If fact="N" or "E", ipiv need not be set.
On exit: if fact="N", ipiv contains the pivot indices from the factorization A=PLU of the original matrix A.
If fact="E", ipiv contains the pivot indices from the factorization A=PLU of the equilibrated matrix A.
If fact="F", ipiv is unchanged from entry.
equed
Type: System..::..String %
On entry: if fact="N" or "E", equed need not be set.
If fact="F", equed must specify the form of the equilibration that was performed as follows:
  • if equed="N", no equilibration;
  • if equed="R", row equilibration, i.e., A has been premultiplied by DR;
  • if equed="C", column equilibration, i.e., A has been postmultiplied by DC;
  • if equed="B", both row and column equilibration, i.e., A has been replaced by DR A DC.
On exit: if fact="F", equed is unchanged from entry.
Otherwise, if no constraints are violated, equed specifies the form of equilibration that was performed as specified above.
Constraint: if fact="F", equed="N", "R", "C" or "B".
r
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array r must be at least max 1,n.
On entry: if fact="N" or "E", r need not be set.
If fact="F" and equed="R" or "B", r must contain the row scale factors for A, DR; each element of r must be positive.
On exit: if fact="F", r is unchanged from entry.
Otherwise, if no constraints are violated and equed="R" or "B", r contains the row scale factors for A, DR, such that A is multiplied on the left by DR; each element of r is positive.
c
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array c must be at least max 1,n.
On entry: if fact="N" or "E", c need not be set.
If fact="F" or equed="C" or "B", c must contain the column scale factors for A, DC; each element of c must be positive.
On exit: if fact="F", c is unchanged from entry.
Otherwise, if no constraints are violated and equed="C" or "B", c contains the row scale factors for A, DC; each element of c is positive.
b
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array b must be at least max 1,nrhs.
On entry: the n by r right-hand side matrix B.
On exit: if equed="N", b is not modified.
If trans="N" and equed="R" or "B", b is overwritten by DR B.
If trans="T" or "C" and equed="C" or "B", b is overwritten by DC B.
x
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array x must be at least max 1,nrhs.
On exit: if info=0 or n+1, the n by r solution matrix X to the original system of equations. Note that the arrays A and B are modified on exit if equed≠"N", and the solution to the equilibrated system is DC-1 X if trans="N" and equed="C" or "B", or DR-1 X if trans="T" or "C" and equed="R" or "B".
rcond
Type: System..::..Double %
On exit: if no constraints are violated, an estimate of the reciprocal condition number of the matrix A (after equilibration if that is performed), computed as rcond=1.0/A 1A-1 1.
ferr
Type: array< System..::..Double >[]()[][]
An array of size [nrhs]
On exit: if info=0 or n+1, an estimate of the forward error bound for each computed solution vector, such that x^j-xj∞/xj∞≤ferr[j-1] where x^j is the jth column of the computed solution returned in the array x and xj is the corresponding column of the exact solution X. The estimate is as reliable as the estimate for rcond, and is almost always a slight overestimate of the true error.
berr
Type: array< System..::..Double >[]()[][]
An array of size [nrhs]
On exit: if info=0 or n+1, an estimate of the component-wise relative backward error of each computed solution vector x^j (i.e., the smallest relative change in any element of A or B that makes x^j an exact solution).
rgf
Type: System..::..Double %
On exit: if info=0, the reciprocal pivot growth factor A/U, where . denotes the maximum absolute element norm. If rgf≪1, the stability of the LU factorization of A could be poor. This also means that the solution x, condition estimate rcond, and forward error bound ferr could be unreliable. If the factorization fails with info>0 and info≤n, then rgf contains the reciprocal pivot growth factor for the leading info columns of A.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f07ap performs the following steps:
1. Equilibration
The linear system to be solved may be badly scaled. However, the system can be equilibrated as a first stage by setting fact="E". In this case, real scaling factors are computed and these factors then determine whether the system is to be equilibrated. Equilibrated forms of the systems AX=B, AT X=B and AH X=B are
DR A DCDC-1 X=DR B,
DR A DC T DR-1 X=DC B,
and
DR A DC H DR-1 X=DC B,
respectively, where DR and DC are diagonal matrices, with positive diagonal elements, formed from the computed scaling factors.
When equilibration is used, A will be overwritten by DR A DC and B will be overwritten by DR B (or DC B when the solution of AT X=B or AH X=B is sought).
2. Factorization
The matrix A, or its scaled form, is copied and factored using the LU decomposition
A=PLU,
where P is a permutation matrix, L is a unit lower triangular matrix, and U is upper triangular.
This stage can be by-passed when a factored matrix (with scaled matrices and scaling factors) are supplied; for example, as provided by a previous call to f07ap with the same matrix A.
3. Condition Number Estimation
The LU factorization of A determines whether a solution to the linear system exists. If some diagonal element of U is zero, then U is exactly singular, no solution exists and the method returns with a failure. Otherwise the factorized form of A is used to estimate the condition number of the matrix A. If the reciprocal of the condition number is less than machine precision then a warning code is returned on final exit.
4. Solution
The (equilibrated) system is solved for X (DC-1 X or DR-1 X) using the factored form of A (DR A DC).
5. Iterative Refinement
Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for the computed solution.
6. Construct Solution Matrix X
If equilibration was used, the matrix X is premultiplied by DC (if trans="N") or DR (if trans="T" or "C") so that it solves the original system before equilibration.

References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Higham N J (2002) Accuracy and Stability of Numerical Algorithms (2nd Edition) SIAM, Philadelphia

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA, LDAF, LDB, LDX, RWORK) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
info>0 and info≤n
Element value of the diagonal is exactly zero. The factorization has been completed, but the factor U is exactly singular, so the solution and error bounds could not be computed. rcond=0.0 is returned.
info=n+1
U is nonsingular, but rcond is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of rcond would suggest.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

For each right-hand side vector b, the computed solution x^ is the exact solution of a perturbed system of equations A+E x^=b, where
E≤c n εP LU,
c n is a modest linear function of n, and ε is the machine precision. See Section 9.3 of Higham (2002) for further details.
If x is the true solution, then the computed solution x^ satisfies a forward error bound of the form
x-x^∞x^∞≤wc cond A,x^,b
where cond A,x^,b=A-1Ax^+b∞/x^∞≤cond A=A-1A∞≤κ∞A. If x^ is the jth column of X, then wc is returned in berr[j-1] and a bound on x-x^∞/x^∞ is returned in ferr[j-1]. See Section 4.4 of Anderson et al. (1999) for further details.

Parallelism and Performance

None.

Further Comments

The factorization of A requires approximately 83 n 3 floating-point operations.
Estimating the forward error involves solving a number of systems of linear equations of the form Ax=b or AT x=b; the number is usually 4 or 5 and never more than 11. Each solution involves approximately 8⁢n 2 operations.
In practice the condition number estimator is very reliable, but it can underestimate the true condition number; see Section 15.3 of Higham (2002) for further details.
The real analogue of this method is f07ab.

Example

This example solves the equations
AX=B,
where A is the general matrix
A= -1.34+0 2.55 i 0.28+3.17 i -6.39-0 2.20 i 0.72-0 0.92 i -1.70-14.10 i 33.10-1.50 i -1.50+13.40 i 12.90+13.80 i -3.29-0 2.39 i -1.91+4.42 i -0.14-0 1.35 i 1.72+0 1.35 i 2.41+0 0.39 i -0.56+1.47 i -0.83-0 0.69 i -1.96+0 0.67 i
and
B= 26.26+51.78 i 31.32-0 6.70 i 64.30-86.80 i 158.60-14.20 i -5.75+25.31 i -2.15+30.19 i 1.16+0 2.57 i -2.56+0 7.55 i .
Error estimates for the solutions, information on scaling, an estimate of the reciprocal of the condition number of the scaled matrix A and an estimate of the reciprocal of the pivot growth factor for the factorization of A are also output.

Example program (C#): f07ape.cs

Example program data: f07ape.d

Example program results: f07ape.r

See Also

F07 Class
F07 Members


f07ar Method

[image]

NAG Library for .NET Release 2
F07..::f07ar Method
F07 Class See Also Send Feedback
f07ar computes the LU factorization of a complex m by n matrix.

Syntax

C#
public static void f07ar(
    int m,
    int n,
    Complex[,] a,
    int[] ipiv,
    out int info
)
Visual Basic
Public Shared Sub f07ar ( _
    m As Integer, _
    n As Integer, _
    a As Complex(,), _
    ipiv As Integer(), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f07ar(
    int m,
    int n,
    array<Complex,2>^ a,
    array<int>^ ipiv,
    [OutAttribute] int% info
)
F#
static member f07ar :
        m : int *
        n : int *
        a : Complex[,] *
        ipiv : int[] *
        info : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: m, the number of rows of the matrix A.
Constraint: m≥0.
n
Type: System..::..Int32
On entry: n, the number of columns of the matrix A.
Constraint: n≥0.
a
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,m
Note: the second dimension of the array a must be at least max 1,n.
On entry: the m by n matrix A.
On exit: the factors L and U from the factorization A=PLU; the unit diagonal elements of L are not stored.
ipiv
Type: array< System..::..Int32 >[]()[][]
An array of size [min m,n]
On exit: the pivot indices that define the permutation matrix. At the ith step, if ipiv[i-1]>i then row i of the matrix A was interchanged with row ipiv[i-1], for i=1,2,…,min m,n. ipiv[i-1]≤i indicates that, at the ith step, a row interchange was not required.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f07ar forms the LU factorization of a complex m by n matrix A as A=PLU, where P is a permutation matrix, L is lower triangular with unit diagonal elements (lower trapezoidal if m>n) and U is upper triangular (upper trapezoidal if m<n). Usually A is square m=n, and both L and U are triangular. The method uses partial pivoting, with row interchanges.

References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
info>0
Element value of the diagonal is exactly zero. The factorization has been completed, but the factor U is exactly singular, and division by zero will occur if it is used to solve a system of equations.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

The computed factors L and U are the exact factors of a perturbed matrix A+E, where
E≤c min m,n εP LU,
c n is a modest linear function of n, and ε is the machine precision.

Parallelism and Performance

None.

Further Comments

The total number of real floating-point operations is approximately 83 n 3 if m=n (the usual case), 43 n 2 3 m-n if m>n and 43 m 2 3 n-m if m<n.
A call to this method with m=n may be followed by calls to the methods:
  • f07as to solve AX=B, AT X=B or AH X=B;
  • (F07AUF not in this release) to estimate the condition number of A;
  • (F07AWF not in this release) to compute the inverse of A.
The real analogue of this method is (F07ADF not in this release).

Example

This example computes the LU factorization of the matrix A, where
A= -1.34+2.55 i 0.28+3.17 i -6.39-2.20 i 0.72-0.92 i -0.17-1.41 i 3.31-0.15 i -0.15+1.34 i 1.29+1.38 i -3.29-2.39 i -1.91+4.42 i -0.14-1.35 i 1.72+1.35 i 2.41+0.39 i -0.56+1.47 i -0.83-0.69 i -1.96+0.67 i .

Example program (C#): f07are.cs

Example program data: f07are.d

Example program results: f07are.r

See Also

F07 Class
F07 Members


f07as Method

[image]

NAG Library for .NET Release 2
F07..::f07as Method
F07 Class See Also Send Feedback
f07as solves a complex system of linear equations with multiple right-hand sides,
AX=B, AT X=B  or  AH X=B,
where A has been factorized by f07ar.

Syntax

C#
public static void f07as(
    string trans,
    int n,
    int nrhs,
    Complex[,] a,
    int[] ipiv,
    Complex[,] b,
    out int info
)
Visual Basic
Public Shared Sub f07as ( _
    trans As String, _
    n As Integer, _
    nrhs As Integer, _
    a As Complex(,), _
    ipiv As Integer(), _
    b As Complex(,), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f07as(
    String^ trans,
    int n,
    int nrhs,
    array<Complex,2>^ a,
    array<int>^ ipiv,
    array<Complex,2>^ b,
    [OutAttribute] int% info
)
F#
static member f07as :
        trans : string *
        n : int *
        nrhs : int *
        a : Complex[,] *
        ipiv : int[] *
        b : Complex[,] *
        info : int byref -> unit

Parameters

trans
Type: System..::..String
On entry: indicates the form of the equations.
trans="N"
AX=B is solved for X.
trans="T"
AT X=B is solved for X.
trans="C"
AH X=B is solved for X.
Constraint: trans="N", "T" or "C".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
nrhs
Type: System..::..Int32
On entry: r, the number of right-hand sides.
Constraint: nrhs≥0.
a
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least max 1,n.
On entry: the LU factorization of A, as returned by f07ar.
ipiv
Type: array< System..::..Int32 >[]()[][]
An array of size [dim1]
Note: the dimension of the array ipiv must be at least max 1,n.
On entry: the pivot indices, as returned by f07ar.
b
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array b must be at least max 1,nrhs.
On entry: the n by r right-hand side matrix B.
On exit: the n by r solution matrix X.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f07as is used to solve a complex system of linear equations AX=B, AT X=B or AH X=B, the method must be preceded by a call to f07ar which computes the LU factorization of A as A=PLU. The solution is computed by forward and backward substitution.
If trans="N", the solution is computed by solving PLY=B and then UX=Y.
If trans="T", the solution is computed by solving UT Y=B and then LTPT X=Y.
If trans="C", the solution is computed by solving UH Y=B and then LHPT X=Y.

References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA, LDB) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

For each right-hand side vector b, the computed solution x is the exact solution of a perturbed system of equations A+E x=b, where
E≤c n εP LU,
c n is a modest linear function of n, and ε is the machine precision.
If x^ is the true solution, then the computed solution x satisfies a forward error bound of the form
x-x^∞x∞≤c n cond A,x ε
where cond A,x=A-1Ax∞/x∞≤cond A=A-1A∞≤κ∞A.
Note that cond A,x can be much smaller than cond A, and cond AH (which is the same as cond AT) can be much larger (or smaller) than cond A.
Forward and backward error bounds can be computed by calling (F07AVF not in this release), and an estimate for κ∞A can be obtained by calling (F07AUF not in this release) with norm="I".

Parallelism and Performance

None.

Further Comments

The total number of real floating-point operations is approximately 8⁢n 2 r.
This method may be followed by a call to (F07AVF not in this release) to refine the solution and return an error estimate.
The real analogue of this method is (F07AEF not in this release).

Example

Example program (C#): f07ase.cs

Example program data: f07ase.d

Example program results: f07ase.r

See Also

F07 Class
F07 Members


f07fb Method

[image]

NAG Library for .NET Release 2
F07..::f07fb Method
F07 Class See Also Send Feedback
f07fb uses the Cholesky factorization
A=UT U  or  A=L LT
to compute the solution to a real system of linear equations
AX=B,
where A is an n by n symmetric positive definite matrix and X and B are n by r matrices. Error bounds on the solution and a condition estimate are also provided.

Syntax

C#
public static void f07fb(
    string fact,
    string uplo,
    int n,
    int nrhs,
    double[,] a,
    double[,] af,
    ref string equed,
    double[] s,
    double[,] b,
    double[,] x,
    out double rcond,
    double[] ferr,
    double[] berr,
    out int info
)
Visual Basic
Public Shared Sub f07fb ( _
    fact As String, _
    uplo As String, _
    n As Integer, _
    nrhs As Integer, _
    a As Double(,), _
    af As Double(,), _
    ByRef equed As String, _
    s As Double(), _
    b As Double(,), _
    x As Double(,), _
    <OutAttribute> ByRef rcond As Double, _
    ferr As Double(), _
    berr As Double(), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f07fb(
    String^ fact,
    String^ uplo,
    int n,
    int nrhs,
    array<double,2>^ a,
    array<double,2>^ af,
    String^% equed,
    array<double>^ s,
    array<double,2>^ b,
    array<double,2>^ x,
    [OutAttribute] double% rcond,
    array<double>^ ferr,
    array<double>^ berr,
    [OutAttribute] int% info
)
F#
static member f07fb :
        fact : string *
        uplo : string *
        n : int *
        nrhs : int *
        a : float[,] *
        af : float[,] *
        equed : string byref *
        s : float[] *
        b : float[,] *
        x : float[,] *
        rcond : float byref *
        ferr : float[] *
        berr : float[] *
        info : int byref -> unit

Parameters

fact
Type: System..::..String
On entry: specifies whether or not the factorized form of the matrix A is supplied on entry, and if not, whether the matrix A should be equilibrated before it is factorized.
fact="F"
af contains the factorized form of A. If equed="Y", the matrix A has been equilibrated with scaling factors given by s. a and af will not be modified.
fact="N"
The matrix A will be copied to af and factorized.
fact="E"
The matrix A will be equilibrated if necessary, then copied to af and factorized.
Constraint: fact="F", "N" or "E".
uplo
Type: System..::..String
On entry: if uplo="U", the upper triangle of A is stored.
If uplo="L", the lower triangle of A is stored.
Constraint: uplo="U" or "L".
n
Type: System..::..Int32
On entry: n, the number of linear equations, i.e., the order of the matrix A.
Constraint: n≥0.
nrhs
Type: System..::..Int32
On entry: r, the number of right-hand sides, i.e., the number of columns of the matrix B.
Constraint: nrhs≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least max 1,n.
On entry: the n by n symmetric matrix A.
If fact="F" and equed="Y", a must have been equilibrated by the scaling factor in s as DS A DS.
  • If uplo="U", the upper triangular part of A must be stored and the elements of the array below the diagonal are not referenced.
  • If uplo="L", the lower triangular part of A must be stored and the elements of the array above the diagonal are not referenced.
On exit: if fact="F" or "N", or if fact="E" and equed="N", a is not modified.
If fact="E" and equed="Y", a is overwritten by DS A DS.
af
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array af must be at least max 1,n.
On entry: if fact="F", af contains the triangular factor U or L from the Cholesky factorization A=UT U or A=L LT, in the same storage format as a. If equed≠"N", af is the factorized form of the equilibrated matrix DS A DS.
On exit: if fact="N", af returns the triangular factor U or L from the Cholesky factorization A=UT U or A=L LT of the original matrix A.
If fact="E", af returns the triangular factor U or L from the Cholesky factorization A=UT U or A=L LT of the equilibrated matrix A (see the description of a for the form of the equilibrated matrix).
equed
Type: System..::..String %
On entry: if fact="N" or "E", equed need not be set.
If fact="F", equed must specify the form of the equilibration that was performed as follows:
  • if equed="N", no equilibration;
  • if equed="Y", equilibration was performed, i.e., A has been replaced by DS A DS.
On exit: if fact="F", equed is unchanged from entry.
Otherwise, if no constraints are violated, equed specifies the form of the equilibration that was performed as specified above.
Constraint: if fact="F", equed="N" or "Y".
s
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array s must be at least max 1,n.
On entry: if fact="N" or "E", s need not be set.
If fact="F" and equed="Y", s must contain the scale factors, DS, for A; each element of s must be positive.
On exit: if fact="F", s is unchanged from entry.
Otherwise, if no constraints are violated and equed="Y", s contains the scale factors, DS, for A; each element of s is positive.
b
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array b must be at least max 1,nrhs.
On entry: the n by r right-hand side matrix B.
On exit: if equed="N", b is not modified.
If equed="Y", b is overwritten by DS B.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array x must be at least max 1,nrhs.
On exit: if info=0 or n+1, the n by r solution matrix X to the original system of equations. Note that the arrays A and B are modified on exit if equed="Y", and the solution to the equilibrated system is DS-1 X.
rcond
Type: System..::..Double %
On exit: if no constraints are violated, an estimate of the reciprocal condition number of the matrix A (after equilibration if that is performed), computed as rcond=1.0/A 1A-1 1.
ferr
Type: array< System..::..Double >[]()[][]
An array of size [nrhs]
On exit: if info=0 or n+1, an estimate of the forward error bound for each computed solution vector, such that x^j-xj∞/xj∞≤ferr[j-1] where x^j is the jth column of the computed solution returned in the array x and xj is the corresponding column of the exact solution X. The estimate is as reliable as the estimate for rcond, and is almost always a slight overestimate of the true error.
berr
Type: array< System..::..Double >[]()[][]
An array of size [nrhs]
On exit: if info=0 or n+1, an estimate of the component-wise relative backward error of each computed solution vector x^j (i.e., the smallest relative change in any element of A or B that makes x^j an exact solution).
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f07fb performs the following steps:
1. If fact="E", real diagonal scaling factors, DS, are computed to equilibrate the system:
DS A DSDS-1 X=DS B.
Whether or not the system will be equilibrated depends on the scaling of the matrix A, but if equilibration is used, A is overwritten by DS A DS and B by DS B.
2. | If fact="N" or "E", the Cholesky decomposition is used to factor the matrix A (after equilibration if fact="E") as A=UT U if uplo="U" or A=L LT if uplo="L", where U is an upper triangular matrix and L is a lower triangular matrix.
3. | If the leading i by i principal minor of A is not positive definite, then the method returns with info=i. Otherwise, the factored form of A is used to estimate the condition number of the matrix A. If the reciprocal of the condition number is less than machine precision, info=n+1 is returned as a warning, but the method still goes on to solve for X and compute error bounds as described below.
4. | The system of equations is solved for X using the factored form of A.
5. | Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it.
6. | If equilibration was used, the matrix X is premultiplied by DS so that it solves the original system before equilibration.

References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Higham N J (2002) Accuracy and Stability of Numerical Algorithms (2nd Edition) SIAM, Philadelphia

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA, LDAF, LDB, LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
info>0 and info≤n
The leading minor of order value of A is not positive definite, so the factorization could not be completed, and the solution has not been computed. rcond=0.0 is returned.
info=n+1
U (or L) is nonsingular, but rcond is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of rcond would suggest.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

For each right-hand side vector b, the computed solution x is the exact solution of a perturbed system of equations A+E x=b, where
  • if uplo="U", E≤c n ε UTU;
  • if uplo="L", E≤c n ε LLT,
c n is a modest linear function of n, and ε is the machine precision. See Section 10.1 of Higham (2002) for further details.
If x^ is the true solution, then the computed solution x satisfies a forward error bound of the form
x-x^∞x^∞≤wc cond A,x^,b
where cond A,x^,b=A-1Ax^+b∞/x^∞≤cond A=A-1A∞≤κ∞A. If x^ is the jth column of X, then wc is returned in berr[j-1] and a bound on x-x^∞/x^∞ is returned in ferr[j-1]. See Section 4.4 of Anderson et al. (1999) for further details.

Parallelism and Performance

None.

Further Comments

The factorization of A requires approximately 13 n 3 floating-point operations.
For each right-hand side, computation of the backward error involves a minimum of 4⁢n 2 floating-point operations. Each step of iterative refinement involves an additional 6⁢n 2 operations. At most five steps of iterative refinement are performed, but usually only one or two steps are required. Estimating the forward error involves solving a number of systems of equations of the form Ax=b; the number is usually 4 or 5 and never more than 11. Each solution involves approximately 2⁢n 2 operations.
The complex analogue of this method is f07fp.

Example

This example solves the equations
AX=B,
where A is the symmetric positive definite matrix
A=4.16-3.120.56-0.10-3.125.03-0.831.180.56-0.830.760.34-0.101.180.341.18
and
B=8.708.30-13.352.131.891.61-4.145.00.
Error estimates for the solutions, information on equilibration and an estimate of the reciprocal of the condition number of the scaled matrix A are also output.

Example program (C#): f07fbe.cs

Example program data: f07fbe.d

Example program results: f07fbe.r

See Also

F07 Class
F07 Members


f07fp Method

[image]

NAG Library for .NET Release 2
F07..::f07fp Method
F07 Class See Also Send Feedback
f07fp uses the Cholesky factorization
A=UH U  or  A=L LH
to compute the solution to a complex system of linear equations
AX=B,
where A is an n by n Hermitian positive definite matrix and X and B are n by r matrices. Error bounds on the solution and a condition estimate are also provided.

Syntax

C#
public static void f07fp(
    string fact,
    string uplo,
    int n,
    int nrhs,
    Complex[,] a,
    Complex[,] af,
    ref string equed,
    double[] s,
    Complex[,] b,
    Complex[,] x,
    out double rcond,
    double[] ferr,
    double[] berr,
    out int info
)
Visual Basic
Public Shared Sub f07fp ( _
    fact As String, _
    uplo As String, _
    n As Integer, _
    nrhs As Integer, _
    a As Complex(,), _
    af As Complex(,), _
    ByRef equed As String, _
    s As Double(), _
    b As Complex(,), _
    x As Complex(,), _
    <OutAttribute> ByRef rcond As Double, _
    ferr As Double(), _
    berr As Double(), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f07fp(
    String^ fact,
    String^ uplo,
    int n,
    int nrhs,
    array<Complex,2>^ a,
    array<Complex,2>^ af,
    String^% equed,
    array<double>^ s,
    array<Complex,2>^ b,
    array<Complex,2>^ x,
    [OutAttribute] double% rcond,
    array<double>^ ferr,
    array<double>^ berr,
    [OutAttribute] int% info
)
F#
static member f07fp :
        fact : string *
        uplo : string *
        n : int *
        nrhs : int *
        a : Complex[,] *
        af : Complex[,] *
        equed : string byref *
        s : float[] *
        b : Complex[,] *
        x : Complex[,] *
        rcond : float byref *
        ferr : float[] *
        berr : float[] *
        info : int byref -> unit

Parameters

fact
Type: System..::..String
On entry: specifies whether or not the factorized form of the matrix A is supplied on entry, and if not, whether the matrix A should be equilibrated before it is factorized.
fact="F"
af contains the factorized form of A. If equed="Y", the matrix A has been equilibrated with scaling factors given by s. a and af will not be modified.
fact="N"
The matrix A will be copied to af and factorized.
fact="E"
The matrix A will be equilibrated if necessary, then copied to af and factorized.
Constraint: fact="F", "N" or "E".
uplo
Type: System..::..String
On entry: if uplo="U", the upper triangle of A is stored.
If uplo="L", the lower triangle of A is stored.
Constraint: uplo="U" or "L".
n
Type: System..::..Int32
On entry: n, the number of linear equations, i.e., the order of the matrix A.
Constraint: n≥0.
nrhs
Type: System..::..Int32
On entry: r, the number of right-hand sides, i.e., the number of columns of the matrix B.
Constraint: nrhs≥0.
a
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least max 1,n.
On entry: the n by n Hermitian matrix A.
If fact="F" and equed="Y", a must have been equilibrated by the scaling factor in s as DS A DS.
  • If uplo="U", the upper triangular part of A must be stored and the elements of the array below the diagonal are not referenced.
  • If uplo="L", the lower triangular part of A must be stored and the elements of the array above the diagonal are not referenced.
On exit: if fact="F" or "N", or if fact="E" and equed="N", a is not modified.
If fact="E" and equed="Y", a is overwritten by DS A DS.
af
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array af must be at least max 1,n.
On entry: if fact="F", af contains the triangular factor U or L from the Cholesky factorization A=UH U or A=L LH, in the same storage format as a. If equed≠"N", af is the factorized form of the equilibrated matrix DS A DS.
On exit: if fact="N", af returns the triangular factor U or L from the Cholesky factorization A=UH U or A=L LH of the original matrix A.
If fact="E", af returns the triangular factor U or L from the Cholesky factorization A=UH U or A=L LH of the equilibrated matrix A (see the description of a for the form of the equilibrated matrix).
equed
Type: System..::..String %
On entry: if fact="N" or "E", equed need not be set.
If fact="F", equed must specify the form of the equilibration that was performed as follows:
  • if equed="N", no equilibration;
  • if equed="Y", equilibration was performed, i.e., A has been replaced by DS A DS.
On exit: if fact="F", equed is unchanged from entry.
Otherwise, if no constraints are violated, equed specifies the form of the equilibration that was performed as specified above.
Constraint: if fact="F", equed="N" or "Y".
s
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array s must be at least max 1,n.
On entry: if fact="N" or "E", s need not be set.
If fact="F" and equed="Y", s must contain the scale factors, DS, for A; each element of s must be positive.
On exit: if fact="F", s is unchanged from entry.
Otherwise, if no constraints are violated and equed="Y", s contains the scale factors, DS, for A; each element of s is positive.
b
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array b must be at least max 1,nrhs.
On entry: the n by r right-hand side matrix B.
On exit: if equed="N", b is not modified.
If equed="Y", b is overwritten by DS B.
x
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array x must be at least max 1,nrhs.
On exit: if info=0 or n+1, the n by r solution matrix X to the original system of equations. Note that the arrays A and B are modified on exit if equed="Y", and the solution to the equilibrated system is DS-1 X.
rcond
Type: System..::..Double %
On exit: if no constraints are violated, an estimate of the reciprocal condition number of the matrix A (after equilibration if that is performed), computed as rcond=1.0/A 1A-1 1.
ferr
Type: array< System..::..Double >[]()[][]
An array of size [nrhs]
On exit: if info=0 or n+1, an estimate of the forward error bound for each computed solution vector, such that x^j-xj∞/xj∞≤ferr[j-1] where x^j is the jth column of the computed solution returned in the array x and xj is the corresponding column of the exact solution X. The estimate is as reliable as the estimate for rcond, and is almost always a slight overestimate of the true error.
berr
Type: array< System..::..Double >[]()[][]
An array of size [nrhs]
On exit: if info=0 or n+1, an estimate of the component-wise relative backward error of each computed solution vector x^j (i.e., the smallest relative change in any element of A or B that makes x^j an exact solution).
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f07fp performs the following steps:
1. If fact="E", real diagonal scaling factors, DS, are computed to equilibrate the system:
DS A DSDS-1 X=DS B.
Whether or not the system will be equilibrated depends on the scaling of the matrix A, but if equilibration is used, A is overwritten by DS A DS and B by DS B.
2. | If fact="N" or "E", the Cholesky decomposition is used to factor the matrix A (after equilibration if fact="E") as A=UH U if uplo="U" or A=L LH if uplo="L", where U is an upper triangular matrix and L is a lower triangular matrix.
3. | If the leading i by i principal minor of A is not positive definite, then the method returns with info=i. Otherwise, the factored form of A is used to estimate the condition number of the matrix A. If the reciprocal of the condition number is less than machine precision, info=n+1 is returned as a warning, but the method still goes on to solve for X and compute error bounds as described below.
4. | The system of equations is solved for X using the factored form of A.
5. | Iterative refinement is applied to improve the computed solution matrix and to calculate error bounds and backward error estimates for it.
6. | If equilibration was used, the matrix X is premultiplied by DS so that it solves the original system before equilibration.

References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Higham N J (2002) Accuracy and Stability of Numerical Algorithms (2nd Edition) SIAM, Philadelphia

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA, LDAF, LDB, LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
info>0 and info≤n
The leading minor of order value of A is not positive definite, so the factorization could not be completed, and the solution has not been computed. rcond=0.0 is returned.
info=n+1
U (or L) is nonsingular, but rcond is less than machine precision, meaning that the matrix is singular to working precision. Nevertheless, the solution and error bounds are computed because there are a number of situations where the computed solution can be more accurate than the value of rcond would suggest.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

For each right-hand side vector b, the computed solution x is the exact solution of a perturbed system of equations A+E x=b, where
  • if uplo="U", E≤c n ε UHU;
  • if uplo="L", E≤c n ε LLH,
c n is a modest linear function of n, and ε is the machine precision. See Section 10.1 of Higham (2002) for further details.
If x^ is the true solution, then the computed solution x satisfies a forward error bound of the form
x-x^∞x^∞≤wc cond A,x^,b
where cond A,x^,b=A-1Ax^+b∞/x^∞≤cond A=A-1A∞≤κ∞A. If x^ is the jth column of X, then wc is returned in berr[j-1] and a bound on x-x^∞/x^∞ is returned in ferr[j-1]. See Section 4.4 of Anderson et al. (1999) for further details.

Parallelism and Performance

None.

Further Comments

The factorization of A requires approximately 43 n 3 floating-point operations.
For each right-hand side, computation of the backward error involves a minimum of 16⁢n 2 floating-point operations. Each step of iterative refinement involves an additional 24⁢n 2 operations. At most five steps of iterative refinement are performed, but usually only one or two steps are required. Estimating the forward error involves solving a number of systems of equations of the form Ax=b; the number is usually 4 or 5 and never more than 11. Each solution involves approximately 8⁢n 2 operations.
The real analogue of this method is f07fb.

Example

This example solves the equations
AX=B,
where A is the Hermitian positive definite matrix
A= 3.23 i+0.00 1.51-1.92 i 1.90+0.84 i 0.42+2.50 i 1.51+1.92 i 3.58 i+0.00 -0.23+1.11 i -1.18+1.37 i 1.90-0.84 i -0.23-1.11 i 4.09 i+0.00 2.33-0.14 i 0.42-2.50 i -1.18-1.37 i 2.33+0.14 i 4.29 i+0.00
and
B= 3.93-0 6.14 i 1.48+0 6.58 i 6.17+0 9.42 i 4.64-0 4.75 i -7.17-21.83 i -4.91+0 2.29 i 1.99-14.38 i 7.64-10.79 i .
Error estimates for the solutions, information on equilibration and an estimate of the reciprocal of the condition number of the scaled matrix A are also output.

Example program (C#): f07fpe.cs

Example program data: f07fpe.d

Example program results: f07fpe.r

See Also

F07 Class
F07 Members


f07hd Method

[image]

NAG Library for .NET Release 2
F07..::f07hd Method
F07 Class See Also Send Feedback
f07hd computes the Cholesky factorization of a real symmetric positive definite band matrix.

Syntax

C#
public static void f07hd(
    string uplo,
    int n,
    int kd,
    double[,] ab,
    out int info
)
Visual Basic
Public Shared Sub f07hd ( _
    uplo As String, _
    n As Integer, _
    kd As Integer, _
    ab As Double(,), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f07hd(
    String^ uplo,
    int n,
    int kd,
    array<double,2>^ ab,
    [OutAttribute] int% info
)
F#
static member f07hd :
        uplo : string *
        n : int *
        kd : int *
        ab : float[,] *
        info : int byref -> unit

Parameters

uplo
Type: System..::..String
On entry: specifies whether the upper or lower triangular part of A is stored and how A is to be factorized.
uplo="U"
The upper triangular part of A is stored and A is factorized as UT U, where U is upper triangular.
uplo="L"
The lower triangular part of A is stored and A is factorized as L LT, where L is lower triangular.
Constraint: uplo="U" or "L".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
kd
Type: System..::..Int32
On entry: kd, the number of superdiagonals or subdiagonals of the matrix A.
Constraint: kd≥0.
ab
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥kd+1
Note: the second dimension of the array ab must be at least max 1,n.
On entry: the n by n symmetric positive definite band matrix A.
The matrix is stored in rows 1 to kd+1, more precisely,
  • if uplo="U", the elements of the upper triangle of A within the band must be stored with element Aij in ab[kd+1+i-j,j]​ for ​max 1,j-kd≤i≤j;
  • if uplo="L", the elements of the lower triangle of A within the band must be stored with element Aij in ab[1+i-j,j]​ for ​j≤i≤min n,j+kd.
On exit: the upper or lower triangle of A is overwritten by the Cholesky factor U or L as specified by uplo, using the same storage format as described above.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f07hd forms the Cholesky factorization of a real symmetric positive definite band matrix A either as A=UT U if uplo="U" or A=L LT if uplo="L", where U (or L) is an upper (or lower) triangular band matrix with the same number of superdiagonals (or subdiagonals) as A.

References

Demmel J W (1989) On floating-point errors in Cholesky LAPACK Working Note No. 14 University of Tennessee, Knoxville
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDAB) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
info>0
The leading minor of order value is not positive definite and the factorization could not be completed. Hence A itself is not positive definite. This may indicate an error in forming the matrix A. There is no method specifically designed to factorize a symmetric band matrix which is not positive definite; the matrix must be treated either as a nonsymmetric band matrix, by calling f07bd or as a full symmetric matrix, by calling f07md.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

If uplo="U", the computed factor U is the exact factor of a perturbed matrix A+E, where
E≤c k+1 ε UTU,
c k+1 is a modest linear function of k+1, and ε is the machine precision.
If uplo="L", a similar statement holds for the computed factor L. It follows that e ij≤c k+1 ε⁢a iia jj.

Parallelism and Performance

None.

Further Comments

The total number of floating-point operations is approximately n k+1 2, assuming n≫k.
A call to f07hd may be followed by calls to the methods:
  • f07he to solve AX=B;
  • (F07HGF not in this release) to estimate the condition number of A.
The complex analogue of this method is (F07HRF not in this release).

Example

This example computes the Cholesky factorization of the matrix A, where
A=5.492.680.000.002.685.63-2.390.000.00-2.392.60-2.220.000.00-2.225.17.

Example program (C#): f07hde.cs

Example program data: f07hde.d

Example program results: f07hde.r

See Also

F07 Class
F07 Members


f07he Method

[image]

NAG Library for .NET Release 2
F07..::f07he Method
F07 Class See Also Send Feedback
f07he solves a real symmetric positive definite band system of linear equations with multiple right-hand sides,
AX=B,
where A has been factorized by f07hd.

Syntax

C#
public static void f07he(
    string uplo,
    int n,
    int kd,
    int nrhs,
    double[,] ab,
    double[,] b,
    out int info
)
Visual Basic
Public Shared Sub f07he ( _
    uplo As String, _
    n As Integer, _
    kd As Integer, _
    nrhs As Integer, _
    ab As Double(,), _
    b As Double(,), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f07he(
    String^ uplo,
    int n,
    int kd,
    int nrhs,
    array<double,2>^ ab,
    array<double,2>^ b,
    [OutAttribute] int% info
)
F#
static member f07he :
        uplo : string *
        n : int *
        kd : int *
        nrhs : int *
        ab : float[,] *
        b : float[,] *
        info : int byref -> unit

Parameters

uplo
Type: System..::..String
On entry: specifies how A has been factorized.
uplo="U"
A=UT U, where U is upper triangular.
uplo="L"
A=L LT, where L is lower triangular.
Constraint: uplo="U" or "L".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
kd
Type: System..::..Int32
On entry: kd, the number of superdiagonals or subdiagonals of the matrix A.
Constraint: kd≥0.
nrhs
Type: System..::..Int32
On entry: r, the number of right-hand sides.
Constraint: nrhs≥0.
ab
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥kd+1
Note: the second dimension of the array ab must be at least max 1,n.
On entry: the Cholesky factor of A, as returned by f07hd.
b
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array b must be at least max 1,nrhs.
On entry: the n by r right-hand side matrix B.
On exit: the n by r solution matrix X.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f07he is used to solve a real symmetric positive definite band system of linear equations AX=B, the method must be preceded by a call to f07hd which computes the Cholesky factorization of A. The solution X is computed by forward and backward substitution.
If uplo="U", A=UT U, where U is upper triangular; the solution X is computed by solving UT Y=B and then UX=Y.
If uplo="L", A=L LT, where L is lower triangular; the solution X is computed by solving LY=B and then LT X=Y.

References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDAB, LDB) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

For each right-hand side vector b, the computed solution x is the exact solution of a perturbed system of equations A+E x=b, where
  • if uplo="U", E≤c k+1 ε UTU;
  • if uplo="L", E≤c k+1 ε LLT,
c k+1 is a modest linear function of k+1, and ε is the machine precision.
If x^ is the true solution, then the computed solution x satisfies a forward error bound of the form
x-x^∞x∞≤c k+1 cond A,x ε
where cond A,x=A-1Ax∞/x∞≤cond A=A-1A∞≤κ∞A. Note that cond A,x can be much smaller than cond A.
Forward and backward error bounds can be computed by calling (F07HHF not in this release), and an estimate for κ∞A (=κ 1 A) can be obtained by calling (F07HGF not in this release).

Parallelism and Performance

None.

Further Comments

The total number of floating-point operations is approximately 4 nkr, assuming n≫k.
This method may be followed by a call to (F07HHF not in this release) to refine the solution and return an error estimate.
The complex analogue of this method is (F07HSF not in this release).

Example

Example program (C#): f07hee.cs

Example program data: f07hee.d

Example program results: f07hee.r

See Also

F07 Class
F07 Members


f07te Method

[image]

NAG Library for .NET Release 2
F07..::f07te Method
F07 Class See Also Send Feedback
f07te solves a real triangular system of linear equations with multiple right-hand sides, AX=B or AT X=B.

Syntax

C#
public static void f07te(
    string uplo,
    string trans,
    string diag,
    int n,
    int nrhs,
    double[,] a,
    double[,] b,
    out int info
)
Visual Basic
Public Shared Sub f07te ( _
    uplo As String, _
    trans As String, _
    diag As String, _
    n As Integer, _
    nrhs As Integer, _
    a As Double(,), _
    b As Double(,), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f07te(
    String^ uplo,
    String^ trans,
    String^ diag,
    int n,
    int nrhs,
    array<double,2>^ a,
    array<double,2>^ b,
    [OutAttribute] int% info
)
F#
static member f07te :
        uplo : string *
        trans : string *
        diag : string *
        n : int *
        nrhs : int *
        a : float[,] *
        b : float[,] *
        info : int byref -> unit

Parameters

uplo
Type: System..::..String
On entry: specifies whether A is upper or lower triangular.
uplo="U"
A is upper triangular.
uplo="L"
A is lower triangular.
Constraint: uplo="U" or "L".
trans
Type: System..::..String
On entry: indicates the form of the equations.
trans="N"
The equations are of the form AX=B.
trans="T" or "C"
The equations are of the form AT X=B.
Constraint: trans="N", "T" or "C".
diag
Type: System..::..String
On entry: indicates whether A is a nonunit or unit triangular matrix.
diag="N"
A is a nonunit triangular matrix.
diag="U"
A is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be 1.
Constraint: diag="N" or "U".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
nrhs
Type: System..::..Int32
On entry: r, the number of right-hand sides.
Constraint: nrhs≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least max 1,n.
On entry: the n by n triangular matrix A.
  • If uplo="U", A is upper triangular and the elements of the array below the diagonal are not referenced.
  • If uplo="L", A is lower triangular and the elements of the array above the diagonal are not referenced.
  • If diag="U", the diagonal elements of A are assumed to be 1, and are not referenced.
b
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array b must be at least max 1,nrhs.
On entry: the n by r right-hand side matrix B.
On exit: the n by r solution matrix X.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f07te solves a real triangular system of linear equations AX=B or AT X=B.

References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Higham N J (1989) The accuracy of solutions to triangular systems SIAM J. Numer. Anal. 26 1252–1265

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA, LDB) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
info>0
Element value of the diagonal is exactly zero. A is singular and the solution has not been computed.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

The solutions of triangular systems of equations are usually computed to high accuracy. See Higham (1989).
For each right-hand side vector b, the computed solution x is the exact solution of a perturbed system of equations A+E x=b, where
E≤c n ε A,
c n is a modest linear function of n, and ε is the machine precision.
If x^ is the true solution, then the computed solution x satisfies a forward error bound of the form
x-x^∞x∞≤c n cond A,x ε,   provided  c n cond A,x ε<1,
where cond A,x=A-1Ax∞/x∞.
Note that cond A,x≤cond A=A-1A∞≤κ∞A; cond A,x can be much smaller than cond A and it is also possible for cond AT to be much larger (or smaller) than cond A.
Forward and backward error bounds can be computed by calling f07th, and an estimate for κ∞A can be obtained by calling (F07TGF not in this release) with norm="I".

Parallelism and Performance

None.

Further Comments

The total number of floating-point operations is approximately n 2 r.
The complex analogue of this method is (F07TSF not in this release).

Example

This example solves the system of equations AX=B, where
A=4.300.000.000.00-3.96-4.870.000.000.400.31-8.020.00-0.270.07-5.950.12  and  B=-12.90-21.5016.7514.93-17.556.33-11.048.09.

Example program (C#): f07tee.cs

Example program data: f07tee.d

Example program results: f07tee.r

See Also

F07 Class
F07 Members


f07th Method

[image]

NAG Library for .NET Release 2
F07..::f07th Method
F07 Class See Also Send Feedback
f07th returns error bounds for the solution of a real triangular system of linear equations with multiple right-hand sides, AX=B or AT X=B.

Syntax

C#
public static void f07th(
    string uplo,
    string trans,
    string diag,
    int n,
    int nrhs,
    double[,] a,
    double[,] b,
    double[,] x,
    double[] ferr,
    double[] berr,
    out int info
)
Visual Basic
Public Shared Sub f07th ( _
    uplo As String, _
    trans As String, _
    diag As String, _
    n As Integer, _
    nrhs As Integer, _
    a As Double(,), _
    b As Double(,), _
    x As Double(,), _
    ferr As Double(), _
    berr As Double(), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f07th(
    String^ uplo,
    String^ trans,
    String^ diag,
    int n,
    int nrhs,
    array<double,2>^ a,
    array<double,2>^ b,
    array<double,2>^ x,
    array<double>^ ferr,
    array<double>^ berr,
    [OutAttribute] int% info
)
F#
static member f07th :
        uplo : string *
        trans : string *
        diag : string *
        n : int *
        nrhs : int *
        a : float[,] *
        b : float[,] *
        x : float[,] *
        ferr : float[] *
        berr : float[] *
        info : int byref -> unit

Parameters

uplo
Type: System..::..String
On entry: specifies whether A is upper or lower triangular.
uplo="U"
A is upper triangular.
uplo="L"
A is lower triangular.
Constraint: uplo="U" or "L".
trans
Type: System..::..String
On entry: indicates the form of the equations.
trans="N"
The equations are of the form AX=B.
trans="T" or "C"
The equations are of the form AT X=B.
Constraint: trans="N", "T" or "C".
diag
Type: System..::..String
On entry: indicates whether A is a nonunit or unit triangular matrix.
diag="N"
A is a nonunit triangular matrix.
diag="U"
A is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be 1.
Constraint: diag="N" or "U".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
nrhs
Type: System..::..Int32
On entry: r, the number of right-hand sides.
Constraint: nrhs≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least max 1,n.
On entry: the n by n triangular matrix A.
  • If uplo="U", A is upper triangular and the elements of the array below the diagonal are not referenced.
  • If uplo="L", A is lower triangular and the elements of the array above the diagonal are not referenced.
  • If diag="U", the diagonal elements of A are assumed to be 1, and are not referenced.
b
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array b must be at least max 1,nrhs.
On entry: the n by r right-hand side matrix B.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array x must be at least max 1,nrhs.
On entry: the n by r solution matrix X, as returned by f07te.
ferr
Type: array< System..::..Double >[]()[][]
An array of size [nrhs]
On exit: ferr[j-1] contains an estimated error bound for the jth solution vector, that is, the jth column of X, for j=1,2,…,r.
berr
Type: array< System..::..Double >[]()[][]
An array of size [nrhs]
On exit: berr[j-1] contains the component-wise backward error bound β for the jth solution vector, that is, the jth column of X, for j=1,2,…,r.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f07th returns the backward errors and estimated bounds on the forward errors for the solution of a real triangular system of linear equations with multiple right-hand sides AX=B or AT X=B. The method handles each right-hand side vector (stored as a column of the matrix B) independently, so we describe the function of f07th in terms of a single right-hand side b and solution x.
Given a computed solution x, the method computes the component-wise backward error β. This is the size of the smallest relative perturbation in each element of A and b such that x is the exact solution of a perturbed system
A+δA x=b+δbδ a ij≤β a ij  and  δ bi≤β bi.
Then the method estimates a bound for the component-wise forward error in the computed solution, defined by:
maxi xi-x^i/maxi xi
where x^ is the true solution.
For details of the method, see the F07 class.

References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA, LDB, LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

The bounds returned in ferr are not rigorous, because they are estimated, not computed exactly; but in practice they almost always overestimate the actual error.

Parallelism and Performance

None.

Further Comments

A call to f07th, for each right-hand side, involves solving a number of systems of linear equations of the form Ax=b or AT x=b; the number is usually 4 or 5 and never more than 11. Each solution involves approximately n 2 floating-point operations.
The complex analogue of this method is (F07TVF not in this release).

Example

This example solves the system of equations AX=B and to compute forward and backward error bounds, where
A=4.300.000.000.00-3.96-4.870.000.000.400.31-8.020.00-0.270.07-5.950.12  and  B=-12.90-21.5016.7514.93-17.556.33-11.048.09.

Example program (C#): f07the.cs

Example program data: f07the.d

Example program results: f07the.r

See Also

F07 Class
F07 Members


f07tj Method

[image]

NAG Library for .NET Release 2
F07..::f07tj Method
F07 Class See Also Send Feedback
f07tj computes the inverse of a real triangular matrix.

Syntax

C#
public static void f07tj(
    string uplo,
    string diag,
    int n,
    double[,] a,
    out int info
)
Visual Basic
Public Shared Sub f07tj ( _
    uplo As String, _
    diag As String, _
    n As Integer, _
    a As Double(,), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f07tj(
    String^ uplo,
    String^ diag,
    int n,
    array<double,2>^ a,
    [OutAttribute] int% info
)
F#
static member f07tj :
        uplo : string *
        diag : string *
        n : int *
        a : float[,] *
        info : int byref -> unit

Parameters

uplo
Type: System..::..String
On entry: specifies whether A is upper or lower triangular.
uplo="U"
A is upper triangular.
uplo="L"
A is lower triangular.
Constraint: uplo="U" or "L".
diag
Type: System..::..String
On entry: indicates whether A is a nonunit or unit triangular matrix.
diag="N"
A is a nonunit triangular matrix.
diag="U"
A is a unit triangular matrix; the diagonal elements are not referenced and are assumed to be 1.
Constraint: diag="N" or "U".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least max 1,n.
On entry: the n by n triangular matrix A.
  • If uplo="U", A is upper triangular and the elements of the array below the diagonal are not referenced.
  • If uplo="L", A is lower triangular and the elements of the array above the diagonal are not referenced.
  • If diag="U", the diagonal elements of A are assumed to be 1, and are not referenced.
On exit: A is overwritten by A-1, using the same storage format as described above.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f07tj forms the inverse of a real triangular matrix A. Note that the inverse of an upper (lower) triangular matrix is also upper (lower) triangular.

References

Du Croz J J and Higham N J (1992) Stability of methods for matrix inversion IMA J. Numer. Anal. 12 1–19

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
info>0
Element value of the diagonal is exactly zero. A is singular its inverse cannot be computed.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

The computed inverse X satisfies
XA-I≤c n ε XA,
where c n is a modest linear function of n, and ε is the machine precision.
Note that a similar bound for AX-I cannot be guaranteed, although it is almost always satisfied.
The computed inverse satisfies the forward error bound
X-A-1≤c n ε A-1AX.
See Du Croz and Higham (1992).

Parallelism and Performance

None.

Further Comments

The total number of floating-point operations is approximately 13 n 3.
The complex analogue of this method is (F07TWF not in this release).

Example

This example computes the inverse of the matrix A, where
A=4.300.000.000.00-3.96-4.870.000.000.400.31-8.020.00-0.270.07-5.950.12.

Example program (C#): f07tje.cs

Example program data: f07tje.d

Example program results: f07tje.r

See Also

F07 Class
F07 Members


F08 Class

[image]

NAG Library for .NET Release 2
F08 Class
Members See Also Send Feedback
This chapter provides methods for the solution of linear least squares problems, eigenvalue problems and singular value problems, as well as associated computations. It provides methods for:
  • – solution of linear least squares problems
  • – solution of symmetric eigenvalue problems
  • – solution of nonsymmetric eigenvalue problems
  • – solution of singular value problems
  • – solution of generalized linear least squares problems
  • – solution of generalized symmetric-definite eigenvalue problems
  • – solution of generalized nonsymmetric eigenvalue problems
  • – solution of generalized singular value problems
  • – matrix factorizations associated with the above problems
  • – estimating condition numbers of eigenvalue and eigenvector problems
  • – estimating the numerical rank of a matrix
  • – solution of the Sylvester matrix equation
Methods are provided for both real and complex data.
For a general introduction to the solution of linear least squares problems, you should turn first to (F04 not in this release). The decision trees, at the end of (F04 not in this release), direct you to the most appropriate methods in (F04 not in this release) F08 class. (F04 not in this release) F08 class contain Black Box (or driver) methods which enable standard linear least squares problems to be solved by a call to a single method.
For a general introduction to eigenvalue and singular value problems, you should turn first to (F02 not in this release). The decision trees, at the end of (F02 not in this release), direct you to the most appropriate methods in (F02 not in this release) F08 class. (F02 not in this release) F08 class contain Black Box (or driver) methods which enable standard types of problem to be solved by a call to a single method. Often methods in (F02 not in this release) call F08 class methods to perform the necessary computational tasks.
The methods in this chapter ( F08 class) handle only dense, band, tridiagonal and Hessenberg matrices (not matrices with more specialised structures, or general sparse matrices). The tables in [Recommendations on Choice and Use of Available Methods] and the decision trees in [Decision Trees] direct you to the most appropriate methods in F08 class.
The methods in this chapter have all been derived from the LAPACK project (see Anderson et al. (1999)). They have been designed to be efficient on a wide range of high-performance computers, without compromising efficiency on conventional serial machines.
It is not expected that you will need to read all of the following sections, but rather you will pick out those sections relevant to your particular problem.

Syntax

C#
public static class F08
Visual Basic
Public NotInheritable Class F08
Visual C++
public ref class F08 abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type F08 =  class end

Background to the Problems

This section is only a brief introduction to the numerical solution of linear least squares problems, eigenvalue and singular value problems. Consult a standard textbook for a more thorough discussion, for example Golub and Van Loan (2012).

Linear Least Squares Problems

The linear least squares problem is
minimizex b-Ax 2, (1)
where A is an m by n matrix, b is a given m element vector and x is an n-element solution vector.
In the most usual case m≥n and rank A=n, so that A has full rank and in this case the solution to problem (1) is unique; the problem is also referred to as finding a least squares solution to an overdetermined system of linear equations.
When m<n and rank A=m, there are an infinite number of solutions x which exactly satisfy b-Ax=0. In this case it is often useful to find the unique solution x which minimizes x 2, and the problem is referred to as finding a minimum norm solution to an underdetermined system of linear equations.
In the general case when we may have rank A<min m,n – in other words, A may be rank-deficient – we seek the minimum norm least squares solution x which minimizes both x 2 and b-Ax 2.
This chapter ( F08 class) contains driver methods to solve these problems with a single call, as well as computational methods that can be combined with methods in F07 class to solve these linear least squares problems. (F04 not in this release) also contains Black Box methods to solve these linear least squares problems in standard cases. The next two sections discuss the factorizations that can be used in the solution of linear least squares problems.

Orthogonal Factorizations and Least Squares Problems

A number of methods are provided for factorizing a general rectangular m by n matrix A, as the product of an orthogonal matrix (unitary if complex) and a triangular (or possibly trapezoidal) matrix.
A real matrix Q is orthogonal if QT Q=I; a complex matrix Q is unitary if QH Q=I. Orthogonal or unitary matrices have the important property that they leave the 2-norm of a vector invariant, so that
x 2=Qx 2,
if Q is orthogonal or unitary. They usually help to maintain numerical stability because they do not amplify rounding errors.
Orthogonal factorizations are used in the solution of linear least squares problems. They may also be used to perform preliminary steps in the solution of eigenvalue or singular value problems, and are useful tools in the solution of a number of other problems.

QR factorization

The most common, and best known, of the factorizations is the QR factorization given by
A=Q R0,   if ​m≥n,
where R is an n by n upper triangular matrix and Q is an m by m orthogonal (or unitary) matrix. If A is of full rank n, then R is nonsingular. It is sometimes convenient to write the factorization as
A=Q 1Q 2R0
which reduces to
A=Q 1 R,
where Q 1 consists of the first n columns of Q, and Q 2 the remaining m-n columns.
If m<n, R is trapezoidal, and the factorization can be written
A=Q R 1R 2,   if ​m<n,
where R 1 is upper triangular and R 2 is rectangular.
The QR factorization can be used to solve the linear least squares problem (1) when m≥n and A is of full rank, since
b-Ax 2=QT b-QT Ax 2=c 1-Rxc 2 2,
where
c≡c 1c 2=Q 1 T bQ 2 T b=QT b;
and c 1 is an n-element vector. Then x is the solution of the upper triangular system
Rx=c 1.
The residual vector r is given by
r=b-Ax=Q 0c 2.
The residual sum of squares r 2 2 may be computed without forming r explicitly, since
r 2=b-Ax 2=c 2 2.

LQ factorization

The LQ factorization is given by
A=L 0 Q=L 0Q 1Q 2=L Q 1,   if ​m≤n,
where L is m by m lower triangular, Q is n by n orthogonal (or unitary), Q 1 consists of the first m rows of Q, and Q 2 the remaining n-m rows.
The LQ factorization of A is essentially the same as the QR factorization of AT (AH if A is complex), since
A=L 0 Q⇔AT=QT LT0.
The LQ factorization may be used to find a minimum norm solution of an underdetermined system of linear equations Ax=b where A is m by n with m<n and has rank m. The solution is given by
x=QT L-1 b0.

QR factorization with column pivoting

To solve a linear least squares problem (1) when A is not of full rank, or the rank of A is in doubt, we can perform either a QR factorization with column pivoting or a singular value decomposition.
The QR factorization with column pivoting is given by
A=Q R0 PT,  m≥n,
where Q and R are as before and P is a (real) permutation matrix, chosen (in general) so that
r 11≥r 22≥⋯≥r nn
and moreover, for each k,
r kk≥R k:j,j 2,  j=k+1,…,n.
If we put
R=R 11R 120R 22
where R 11 is the leading k by k upper triangular sub-matrix of R then, in exact arithmetic, if rank A=k, the whole of the sub-matrix R 22 in rows and columns k+1 to n would be zero. In numerical computation, the aim must be to determine an index k, such that the leading sub-matrix R 11 is well-conditioned, and R 22 is negligible, so that
R=R 11R 120R 22≃R 11R 1200.
Then k is the effective rank of A. See Golub and Van Loan (2012) for a further discussion of numerical rank determination.
The so-called basic solution to the linear least squares problem (1) can be obtained from this factorization as
x=P R 11-1 c^10,
where c^1 consists of just the first k elements of c=QT b.

Complete orthogonal factorization

The QR factorization with column pivoting does not enable us to compute a minimum norm solution to a rank-deficient linear least squares problem, unless R 12=0. However, by applying for further orthogonal (or unitary) transformations from the right to the upper trapezoidal matrix R 11R 12, R 12 can be eliminated:
R 11R 12 Z=T 110.
This gives the complete orthogonal factorization
AP=Q T 11000 ZT
from which the minimum norm solution can be obtained as
x=PZ T 11-1c^10.

Updating a QR factorization

[QR factorization] gave the forms of the QR factorization of an m by n matrix A for the two cases m≥n and m<n. Taking first the case m≥n, the least squares solution of
Ax=b=n(b 1)m-nb 2
is the solution of
Rx=Q 1 T b.
If the original system is now augmented by the addition of p rows so that we require the solution of
AB x=m(b)pb 3
where B is p by n, then this is equivalent to finding the least squares solution of
A^x=nn(R)pB x=Q 1 T bb 3=b^.
This now requires the QR factorization of the n+p by n triangular-rectangular matrix A^.
For the case m<n≤m+p, the least squares solution of the augmented system reduces to
A^x=BR 1R 2 x=b 3QT b=b^,
where A^ is pentagonal.
In both cases A^ can be written as a special case of a triangular-pentagonal matrix consisting of an upper triangular part on top of a rectangular part which is itself on top of a trapezoidal part. In the first case there is no trapezoidal part, in the second case a zero upper triangular part can be added, and more generally the two cases can be combined.

Other factorizations

The QL and RQ factorizations are given by
A=Q 0L,  if ​m≥n,
and
A=0R Q,  if ​m≤n.
The factorizations are less commonly used than either the QR or LQ factorizations described above, but have applications in, for example, the computation of generalized QR factorizations.

The Singular Value Decomposition

The singular value decomposition (SVD) of an m by n matrix A is given by
A=UΣ VT,  A=UΣ VH in the complex case
where U and V are orthogonal (unitary) and Σ is an m by n diagonal matrix with real diagonal elements, σi, such that
σ 1≥σ 2≥⋯≥σ min m,n≥0.
The σi are the singular values of A and the first min m,n columns of U and V are the left and right singular vectors of A. The singular values and singular vectors satisfy
A vi=σiui  and  AT ui=σivi or ​AH ui=σivi
where ui and vi are the ith columns of U and V respectively.
The computation proceeds in the following stages.
1. | The matrix A is reduced to bidiagonal form A=U 1 B V 1 T if A is real (A=U 1 B V 1 H if A is complex), where U 1 and V 1 are orthogonal (unitary if A is complex), and B is real and upper bidiagonal when m≥n and lower bidiagonal when m<n, so that B is nonzero only on the main diagonal and either on the first superdiagonal (if m≥n) or the first subdiagonal (if m<n).
2. | The SVD of the bidiagonal matrix B is computed as B=U 2 Σ V 2 T, where U 2 and V 2 are orthogonal and Σ is diagonal as described above. The singular vectors of A are then U=U 1U 2 and V=V 1V 2.
If m≫n, it may be more efficient to first perform a QR factorization of A, and then compute the SVD of the n by n matrix R, since if A=QR and R=UΣ VT, then the SVD of A is given by A=QU Σ VT.
Similarly, if m≪n, it may be more efficient to first perform an LQ factorization of A.
This chapter supports two primary algorithms for computing the SVD of a bidiagonal matrix. They are:
(i) | the divide and conquer algorithm;
(ii) | the QR algorithm.
The divide and conquer algorithm is much faster than the QR algorithm if singular vectors of large matrices are required.

The Singular Value Decomposition and Least Squares Problems

The SVD may be used to find a minimum norm solution to a (possibly) rank-deficient linear least squares problem (1). The effective rank, k, of A can be determined as the number of singular values which exceed a suitable threshold. Let Σ^ be the leading k by k sub-matrix of Σ, and V^ be the matrix consisting of the first k columns of V. Then the solution is given by
x=V^Σ^-1 c^1,
where c^1 consists of the first k elements of c=UT b=U 2 TU 1 T b.

Generalized Linear Least Squares Problems

The simple type of linear least squares problem described in [Linear Least Squares Problems] can be generalized in various ways.
1. Linear least squares problems with equality constraints:
find ​x​ to minimize ​S=c-Ax 2 2  subject to  Bx=d,
where A is m by n and B is p by n, with p≤n≤m+p. The equations Bx=d may be regarded as a set of equality constraints on the problem of minimizing S. Alternatively the problem may be regarded as solving an overdetermined system of equations
AB x=cd,
where some of the equations (those involving B) are to be solved exactly, and the others (those involving A) are to be solved in a least squares sense. The problem has a unique solution on the assumptions that B has full row rank p and the matrix AB has full column rank n. (For linear least squares problems with inequality constraints, refer to E04 class.)
2. General Gauss–Markov linear model problems:
minimize ​y 2  subject to  d=Ax+By,
where A is m by n and B is m by p, with n≤m≤n+p. When B=I, the problem reduces to an ordinary linear least squares problem. When B is square and nonsingular, it is equivalent to a weighted linear least squares problem:
find ​x​ to minimize ​B-1 d-Ax 2.
The problem has a unique solution on the assumptions that A has full column rank n, and the matrix A,B has full row rank m. Unless B is diagonal, for numerical stability it is generally preferable to solve a weighted linear least squares problem as a general Gauss–Markov linear model problem.

Generalized Orthogonal Factorization and Generalized Linear Least Squares Problems

Generalized QR Factorization

The generalized QR (GQR) factorization of an n by m matrix A and an n by p matrix B is given by the pair of factorizations
A=QR  and  B=QTZ,
where Q and Z are respectively n by n and p by p orthogonal matrices (or unitary matrices if A and B are complex). R has the form
R=mm(R 11)n-m0, if ​n≥m,
or
R=nm-nn(R 11R 12), if ​n<m,
where R 11 is upper triangular. T has the form
T=p-nnn(0T 12), if ​n≤p,
or
T=pn-p(T 11)pT 21, if ​n>p,
where T 12 or T 21 is upper triangular.
Note that if B is square and nonsingular, the GQR factorization of A and B implicitly gives the QR factorization of the matrix B-1 A:
B-1 A=ZT T-1 R
without explicitly computing the matrix inverse B-1 or the product B-1 A (remembering that the inverse of an invertible upper triangular matrix and the product of two upper triangular matrices is an upper triangular matrix).
The GQR factorization can be used to solve the general (Gauss–Markov) linear model problem (GLM) (see [Generalized Linear Least Squares Problems], but note that A and B are dimensioned differently there as m by n and p by n respectively). Using the GQR factorization of A and B, we rewrite the equation d=Ax+By as
QT d=QT Ax+QT By=Rx+TZy.
We partition this as
d 1d 2=mm(R 11)n-m0 x+p-n+mn-mm(T 11T 12)n-m0T 22 y 1y 2
where
d 1d 2≡QT d,  and  y 1y 2≡Zy.
The GLM problem is solved by setting
y 1=0  and  y 2=T 22-1 d 2
from which we obtain the desired solutions
x=R 11-1 d 1-T 12y 2  and  y=ZT 0y 2.

Generalized RQ Factorization

The generalized RQ (GRQ) factorization of an m by n matrix A and a p by n matrix B is given by the pair of factorizations
A=RQ,  B=ZTQ
where Q and Z are respectively n by n and p by p orthogonal matrices (or unitary matrices if A and B are complex). R has the form
R=n-mmm(0R 12),  if ​m≤n,
or
R=nm-n(R 11)nR 21,  if ​m>n,
where R 12 or R 21 is upper triangular. T has the form
T=nn(T 11)p-n0,   if ​p≥n,
or
T=pn-pp(T 11T 12),   if ​p<n,
where T 11 is upper triangular.
Note that if B is square and nonsingular, the GRQ factorization of A and B implicitly gives the RQ factorization of the matrix A B-1:
A B-1=R T-1 ZT
without explicitly computing the matrix B-1 or the product A B-1 (remembering that the inverse of an invertible upper triangular matrix and the product of two upper triangular matrices is an upper triangular matrix).
The GRQ factorization can be used to solve the linear equality-constrained least squares problem (LSE) (see [Generalized Linear Least Squares Problems]). We use the GRQ factorization of B and A (note that B and A have swapped roles), written as
B=TQ  and  A=ZRQ.
We write the linear equality constraints Bx=d as
TQx=d,
which we partition as:
n-ppp(0T 12)x 1x 2=d  where  x 1x 2≡Qx.
Therefore x 2 is the solution of the upper triangular system
T 12x 2=d.
Furthermore,
Ax-c 2=ZT Ax-ZT c 2=RQx-ZT c 2.
We partition this expression as:
n-ppn-p(R 11R 12)p+m-n0R 22 x 1x 2-c 1c 2,
where c 1c 2≡ZT c.
To solve the LSE problem, we set
R 11x 1+R 12x 2-c 1=0
which gives x 1 as the solution of the upper triangular system
R 11x 1=c 1-R 12x 2.
Finally, the desired solution is given by
x=QT x 1x 2.

Generalized Singular Value Decomposition (GSVD)

The generalized (or quotient) singular value decomposition of an m by n matrix A and a p by n matrix B is given by the pair of factorizations
A=U Σ 1 0,R QT  and  B=V Σ 2 0,R QT.
The matrices in these factorizations have the following properties:
– | U is m by m, V is p by p, Q is n by n, and all three matrices are orthogonal. If A and B are complex, these matrices are unitary instead of orthogonal, and QT should be replaced by QH in the pair of factorizations.
– | R is r by r, upper triangular and nonsingular. 0,R is r by n (in other words, the 0 is an r by n-r zero matrix). The integer r is the rank of AB, and satisfies r≤n.
– | Σ 1 is m by r, Σ 2 is p by r, both are real, non-negative and diagonal, and Σ 1 T Σ 1+Σ 2 T Σ 2=I. Write Σ 1 T Σ 1=diag α 12,…,αr 2 and Σ 2 T Σ 2=diag β 12,…,βr 2, where αi and βi lie in the interval from 0 to 1. The ratios α 1/β 1,…,αr/βr are called the generalized singular values of the pair A, B. If βi=0, then the generalized singular value αi/βi is infinite.
Σ 1 and Σ 2 have the following detailed structures, depending on whether m≥r or m<r. In the first case, m≥r, then
Σ 1=klk(I0)l0Cm-k-l00  and  Σ 2=kll(0S)p-l00.
Here l is the rank of B, k=r-l, C and S are diagonal matrices satisfying C 2+S 2=I, and S is nonsingular. We may also identify α 1=⋯=αk=1, α k+i=c ii, for i=1,2,…,l, β 1=⋯=βk=0, and β k+i=s ii, for i=1,2,…,l. Thus, the first k generalized singular values α 1/β 1,…,αk/βk are infinite, and the remaining l generalized singular values are finite.
In the second case, when m<r,
Σ 1=km-kk+l-mk(I00)m-k0C0
and
Σ 2=km-kk+l-mm-k(0S0)k+l-m00Ip-l000.
Again, l is the rank of B, k=r-l, C and S are diagonal matrices satisfying C 2+S 2=I, and S is nonsingular, and we may identify α 1=⋯=αk=1, α k+i=c ii, for i=1,2,…,m-k, α m+1=⋯=αr=0, β 1=⋯=βk=0, β k+i=s ii, for i=1,2,…,m-k and β m+1=⋯=βr=1. Thus, the first k generalized singular values α 1/β 1,…,αk/βk are infinite, and the remaining l generalized singular values are finite.
Here are some important special cases of the generalized singular value decomposition. First, if B is square and nonsingular, then r=n and the generalized singular value decomposition of A and B is equivalent to the singular value decomposition of A B-1, where the singular values of A B-1 are equal to the generalized singular values of the pair A, B:
A B-1=U Σ 1 R QT V Σ 2 R QT-1=U Σ 1 Σ 2-1 VT.
Second, for the matrix C, where
C≡AB
if the columns of C are orthonormal, then r=n, R=I and the generalized singular value decomposition of A and B is equivalent to the CS (Cosine–Sine) decomposition of C:
AB=U00VΣ 1Σ 2 QT.
Third, the generalized eigenvalues and eigenvectors of AT A-λ BT B can be expressed in terms of the generalized singular value decomposition: Let
X=Q I00R-1.
Then
XTAT AX=000Σ 1 T Σ 1  and  XTBT BX=000Σ 2 T Σ 2.
Therefore, the columns of X are the eigenvectors of AT A-λ BT B, and ‘nontrivial’ eigenvalues are the squares of the generalized singular values (see also [Generalized Symmetric-definite Eigenvalue Problems]). ‘Trivial’ eigenvalues are those corresponding to the leading n-r columns of X, which span the common null space of AT A and BT B. The ‘trivial eigenvalues’ are not well defined.

The Full CS Decomposition of Orthogonal Matrices

In [Generalized Singular Value Decomposition (GSVD)] the CS (Cosine-Sine) decomposition of an orthogonal matrix partitioned into two submatrices A and B was given by
AB=U00VΣ 1Σ 2 QT.
The full CS decomposition of an m by m orthogonal matrix X partitions X into four submatrices and factorizes as
X 11X 12X 21X 22=U 100U 2Σ 11-Σ 12Σ 21Σ 22 V 100V 2 T
where, X 11 is a p by q submatrix (which implies the dimensions of X 12, X 21 and X 22); U 1, U 2, V 1 and V 2 are orthogonal matrices of dimensions p, m-p, q and m-q respectively; Σ 11 is the p by q single-diagonal matrix
Σ 11=k 11-rrq-k 11k 11-r(I00)r0C0p-k 1100, k 11=min p,q
Σ 12 is the p by m-q single-diagonal matrix
Σ 12=m-q-k 12rk 12-rp-k 12(00)r0S0k 12-r00I, k 12=min p,m-q,
Σ 21 is the m-p by q single-diagonal matrix
Σ 21=q-k 21rk 21-rm-p-k 21(00)r0S0k 21-r00I, k 21=min m-p,q,
and, Σ 21 is the m-p by q single-diagonal matrix
Σ 22=k 22-rrm-q-k 22k 22-r(I00)r0C0m-p-k 2200, k 22=min m-p,m-q
where r=min p,m-p,q,m-q and the missing zeros remind us that either the column or the row is missing. The r by r diagonal matrices C and S are such that C 2+S 2=I.
This is equivalent to the simultaneous singular value decomposition of the four submatrices X 11, X 12, X 21 and X 22.

Symmetric Eigenvalue Problems

The symmetric eigenvalue problem is to find the eigenvalues, λ, and corresponding eigenvectors, z≠0, such that
Az=λz,  A=AT,   where ​A​ is real.
For the Hermitian eigenvalue problem we have
Az=λz,  A=AH,   where ​A​ is complex.
For both problems the eigenvalues λ are real.
When all eigenvalues and eigenvectors have been computed, we write
A=ZΛ ZT or ​A=ZΛ ZH​ if complex,
where Λ is a diagonal matrix whose diagonal elements are the eigenvalues, and Z is an orthogonal (or unitary) matrix whose columns are the eigenvectors. This is the classical spectral factorization of A.
The basic task of the symmetric eigenproblem methods is to compute values of λ and, optionally, corresponding vectors z for a given matrix A. This computation proceeds in the following stages.
1. | The real symmetric or complex Hermitian matrix A is reduced to real tridiagonal form T. If A is real symmetric this decomposition is A=QT QT with Q orthogonal and T symmetric tridiagonal. If A is complex Hermitian, the decomposition is A=QT QH with Q unitary and T, as before, real symmetric tridiagonal.
2. | Eigenvalues and eigenvectors of the real symmetric tridiagonal matrix T are computed. If all eigenvalues and eigenvectors are computed, this is equivalent to factorizing T as T=SΛ ST, where S is orthogonal and Λ is diagonal. The diagonal entries of Λ are the eigenvalues of T, which are also the eigenvalues of A, and the columns of S are the eigenvectors of T; the eigenvectors of A are the columns of Z=QS, so that A=ZΛ ZT (ZΛ ZH when A is complex Hermitian).
This chapter supports four primary algorithms for computing eigenvalues and eigenvectors of real symmetric matrices and complex Hermitian matrices. They are:
(i) | the divide-and-conquer algorithm;
(ii) | the QR algorithm;
(iii) | bisection followed by inverse iteration;
(iv) | the Relatively Robust Representation (RRR).
The divide-and-conquer algorithm is generally more efficient than the traditional QR algorithm for computing all eigenvalues and eigenvectors, but the RRR algorithm tends to be fastest of all. For further information and references see Anderson et al. (1999).

Generalized Symmetric-definite Eigenvalue Problems

This section is concerned with the solution of the generalized eigenvalue problems Az=λBz, ABz=λz, and BAz=λz, where A and B are real symmetric or complex Hermitian and B is positive definite. Each of these problems can be reduced to a standard symmetric eigenvalue problem, using a Cholesky factorization of B as either B=L LT or B=UT U (L LH or UH U in the Hermitian case).
With B=L LT, we have
Az=λBz⇒L-1 A L-TLT z=λ LT z.
Hence the eigenvalues of Az=λBz are those of Cy=λy, where C is the symmetric matrix C=L-1 A L-T and y=LT z. In the complex case C is Hermitian with C=L-1 A L-H and y=LH z.
Table 1 summarises how each of the three types of problem may be reduced to standard form Cy=λy, and how the eigenvectors z of the original problem may be recovered from the eigenvectors y of the reduced problem. The table applies to real problems; for complex problems, transposed matrices must be replaced by conjugate-transposes.
 | Type of problem | Factorization of B | Reduction | Recovery of eigenvectors
1. | Az=λBz | B=L LT, B=UT U | C=L-1 A L-T, C=U-T A U-1 | z=L-T y, z=U-1 y
2. | ABz=λz | B=L LT, B=UT U | C=LT AL, C=UA UT | z=L-T y, z=U-1 y
3. | BAz=λz | B=L LT, B=UT U | C=LT AL, C=UA UT | z=Ly, z=UT y
Table 1
Reduction of generalized symmetric-definite eigenproblems to standard problems
When the generalized symmetric-definite problem has been reduced to the corresponding standard problem Cy=λy, this may then be solved using the methods described in the previous section. No special methods are needed to recover the eigenvectors z of the generalized problem from the eigenvectors y of the standard problem, because these computations are simple applications of Level 2 or Level 3 BLAS (see F06 class).

Packed Storage for Symmetric Matrices

Methods which handle symmetric matrices are usually designed so that they use either the upper or lower triangle of the matrix; it is not necessary to store the whole matrix. If either the upper or lower triangle is stored conventionally in the upper or lower triangle of a two-dimensional array, the remaining elements of the array can be used to store other useful data. However, that is not always convenient, and if it is important to economize on storage, the upper or lower triangle can be stored in a one-dimensional array of length n n+1/2; that is, the storage is almost halved.
This storage format is referred to as packed storage; it is described in [Packed storage] in the F07 class Chapter Introduction.
Methods designed for packed storage are usually less efficient, especially on high-performance computers, so there is a trade-off between storage and efficiency.

Band Matrices

A band matrix is one whose elements are confined to a relatively small number of subdiagonals or superdiagonals on either side of the main diagonal. Algorithms can take advantage of bandedness to reduce the amount of work and storage required. The storage scheme for band matrices is described in [Band storage] in the F07 class Chapter Introduction.
If the problem is the generalized symmetric definite eigenvalue problem Az=λBz and the matrices A and B are additionally banded, the matrix C as defined in [Generalized Symmetric-definite Eigenvalue Problems] is, in general, full. We can reduce the problem to a banded standard problem by modifying the definition of C thus:
C=XT AX,   where  X=U-1 Q  or ​L-T Q,
where Q is an orthogonal matrix chosen to ensure that C has bandwidth no greater than that of A.
A further refinement is possible when A and B are banded, which halves the amount of work required to form C. Instead of the standard Cholesky factorization of B as UT U or L LT, we use a split Cholesky factorization B=ST S, where
S=U 11M 21L 22
with U 11 upper triangular and L 22 lower triangular of order approximately n/2; S has the same bandwidth as B.

Nonsymmetric Eigenvalue Problems

The nonsymmetric eigenvalue problem is to find the eigenvalues, λ, and corresponding eigenvectors, v≠0, such that
Av=λv.
More precisely, a vector v as just defined is called a right eigenvector of A, and a vector u≠0 satisfying
uT A=λ uT uH A=λ uH  when ​u​ is complex
is called a left eigenvector of A.
A real matrix A may have complex eigenvalues, occurring as complex conjugate pairs.
This problem can be solved via the Schur factorization of A, defined in the real case as
A=ZT ZT,
where Z is an orthogonal matrix and T is an upper quasi-triangular matrix with 1 by 1 and 2 by 2 diagonal blocks, the 2 by 2 blocks corresponding to complex conjugate pairs of eigenvalues of A. In the complex case, the Schur factorization is
A=ZT ZH,
where Z is unitary and T is a complex upper triangular matrix.
The columns of Z are called the Schur vectors. For each k (1≤k≤n), the first k columns of Z form an orthonormal basis for the invariant subspace corresponding to the first k eigenvalues on the diagonal of T. Because this basis is orthonormal, it is preferable in many applications to compute Schur vectors rather than eigenvectors. It is possible to order the Schur factorization so that any desired set of k eigenvalues occupy the k leading positions on the diagonal of T.
The two basic tasks of the nonsymmetric eigenvalue methods are to compute, for a given matrix A, all n values of λ and, if desired, their associated right eigenvectors v and/or left eigenvectors u, and the Schur factorization.
These two basic tasks can be performed in the following stages.
1. | A general matrix A is reduced to upper Hessenberg form H which is zero below the first subdiagonal. The reduction may be written A=QH QT with Q orthogonal if A is real, or A=QH QH with Q unitary if A is complex.
2. | The upper Hessenberg matrix H is reduced to Schur form T, giving the Schur factorization H=ST ST (for H real) or H=ST SH (for H complex). The matrix S (the Schur vectors of H) may optionally be computed as well. Alternatively S may be postmultiplied into the matrix Q determined in stage 1, to give the matrix Z=QS, the Schur vectors of A. The eigenvalues are obtained from the diagonal elements or diagonal blocks of T.
3. | Given the eigenvalues, the eigenvectors may be computed in two different ways. Inverse iteration can be performed on H to compute the eigenvectors of H, and then the eigenvectors can be multiplied by the matrix Q in order to transform them to eigenvectors of A. Alternatively the eigenvectors of T can be computed, and optionally transformed to those of H or A if the matrix S or Z is supplied.
The accuracy with which eigenvalues can be obtained can often be improved by balancing a matrix. This is discussed further in [Balancing and condition for the nonsymmetric eigenproblem] below.

Generalized Nonsymmetric Eigenvalue Problem

The generalized nonsymmetric eigenvalue problem is to find the eigenvalues, λ, and corresponding eigenvectors, v≠0, such that
Av=λBv.
More precisely, a vector v as just defined is called a right eigenvector of the matrix pair A,B, and a vector u≠0 satisfying
uT A=λ uT B uH A=λ uH B​ when ​u​ is complex
is called a left eigenvector of the matrix pair A,B.
If B is singular then the problem has one or more infinite eigenvalues λ=∞, corresponding to Bv=0. Note that if A is nonsingular, then the equivalent problem μAv=Bv is perfectly well defined and an infinite eigenvalue corresponds to μ=0. To deal with both finite (including zero) and infinite eigenvalues, the methods in this chapter do not compute λ explicitly, but rather return a pair of numbers α,β such that if β≠0
λ=α/β
and if α≠0 and β=0 then λ=∞. β is always returned as real and non-negative. Of course, computationally an infinite eigenvalue may correspond to a small β rather than an exact zero.
For a given pair A,B the set of all the matrices of the form A-λB is called a matrix pencil and λ and v are said to be an eigenvalue and eigenvector of the pencil A-λB. If A and B are both singular and share a common null space then
det A-λB≡0
so that the pencil A-λB is singular for all λ. In other words any λ can be regarded as an eigenvalue. In exact arithmetic a singular pencil will have α=β=0 for some α,β. Computationally if some pair α,β is small then the pencil is singular, or nearly singular, and no reliance can be placed on any of the computed eigenvalues. Singular pencils can also manifest themselves in other ways; see, in particular, Sections 2.3.5.2 and 4.11.1.4 of Anderson et al. (1999) for further details.
The generalized eigenvalue problem can be solved via the generalized Schur factorization of the pair A,B defined in the real case as
A=QS ZT,  B=QT ZT,
where Q and Z are orthogonal, T is upper triangular with non-negative diagonal elements and S is upper quasi-triangular with 1 by 1 and 2 by 2 diagonal blocks, the 2 by 2 blocks corresponding to complex conjugate pairs of eigenvalues. In the complex case, the generalized Schur factorization is
A=QS ZH,  B=QT ZH,
where Q and Z are unitary and S and T are upper triangular, with T having real non-negative diagonal elements. The columns of Q and Z are called respectively the left and right generalized Schur vectors and span pairs of deflating subspaces of A and B, which are a generalization of invariant subspaces.
It is possible to order the generalized Schur factorization so that any desired set of k eigenvalues correspond to the k leading positions on the diagonals of the pair S,T.
The two basic tasks of the generalized nonsymmetric eigenvalue methods are to compute, for a given pair A,B, all n values of λ and, if desired, their associated right eigenvectors v and/or left eigenvectors u, and the generalized Schur factorization.
These two basic tasks can be performed in the following stages.
1. | The matrix pair A,B is reduced to generalized upper Hessenberg form H,R, where H is upper Hessenberg (zero below the first subdiagonal) and R is upper triangular. The reduction may be written as A=Q 1 H Z 1 T,B=Q 1 R Z 1 T in the real case with Q 1 and Z 1 orthogonal, and A=Q 1 H Z 1 H,B=Q 1 R Z 1 H in the complex case with Q 1 and Z 1 unitary.
2. | The generalized upper Hessenberg form H,R is reduced to the generalized Schur form S,T using the generalized Schur factorization H=Q 2 S Z 2 T, R=Q 2 T Z 2 T in the real case with Q 2 and Z 2 orthogonal, and H=Q 2 S Z 2 H,R=Q 2 T Z 2 H in the complex case. The generalized Schur vectors of A,B are given by Q=Q 1Q 2, Z=Z 1Z 2. The eigenvalues are obtained from the diagonal elements (or blocks) of the pair S,T.
3. | Given the eigenvalues, the eigenvectors of the pair S,T can be computed, and optionally transformed to those of H,R or A,B.
The accuracy with which eigenvalues can be obtained can often be improved by balancing a matrix pair. This is discussed further in [Balancing the generalized eigenvalue problem] below.

The Sylvester Equation and the Generalized Sylvester Equation

The Sylvester equation is a matrix equation of the form
AX+XB=C,
where A, B, and C are given matrices with A being m by m, B an n by n matrix and C, and the solution matrix X, m by n matrices. The solution of a special case of this equation occurs in the computation of the condition number for an invariant subspace, but a combination of methods in this chapter allows the solution of the general Sylvester equation.
Methods are also provided for solving a special case of the generalized Sylvester equations
AR-LB=C, DR-LE=F,
where A,D, B,E and C,F are given matrix pairs, and R and L are the solution matrices.

Error and Perturbation Bounds and Condition Numbers

In this section we discuss the effects of rounding errors in the solution process and the effects of uncertainties in the data, on the solution to the problem. A number of the methods in this chapter return information, such as condition numbers, that allow these effects to be assessed. First we discuss some notation used in the error bounds of later sections.
The bounds usually contain the factor p n (or p m,n), which grows as a function of the matrix dimension n (or matrix dimensions m and n). It measures how errors can grow as a function of the matrix dimension, and represents a potentially different function for each problem. In practice, it usually grows just linearly; p n≤10 n is often true, although generally only much weaker bounds can be actually proved. We normally describe p n as a ‘modestly growing’ function of n. For detailed derivations of various p n, see Golub and Van Loan (2012) and Wilkinson (1965).
For linear equation (see F07 class) and least squares solvers, we consider bounds on the relative error x-x^/x in the computed solution x^, where x is the true solution. For eigenvalue problems we consider bounds on the error λi-λ^i in the ith computed eigenvalue λ^i, where λi is the true ith eigenvalue. For singular value problems we similarly consider bounds σi-σ^i.
Bounding the error in computed eigenvectors and singular vectors v^i is more subtle because these vectors are not unique: even though we restrict v^i 2=1 and vi 2=1, we may still multiply them by arbitrary constants of absolute value 1. So to avoid ambiguity we bound the angular difference between v^i and the true vector vi, so that
θ vi,v^i=acute angle between ​vi​ and ​v^i=arccos viH v^i. (2)
Here arccos θ is in the standard range: 0≤arccos θ<π. When θ vi,v^i is small, we can choose a constant α with absolute value 1 so that α vi-v^i 2≈θ vi,v^i.
In addition to bounds for individual eigenvectors, bounds can be obtained for the spaces spanned by collections of eigenvectors. These may be much more accurately determined than the individual eigenvectors which span them. These spaces are called invariant subspaces in the case of eigenvectors, because if v is any vector in the space, Av is also in the space, where A is the matrix. Again, we will use angle to measure the difference between a computed space S^ and the true space S:
θ S,S^=acute angle between ​S​ and ​S^=max s∈Ss≠0 min s^∈S^s^≠0 θ s,s^  or  max s^∈S^s^≠0 min s∈Ss≠0 θ s,s^ (3)
θ S,S^ may be computed as follows. Let S be a matrix whose columns are orthonormal and span S. Similarly let S^ be an orthonormal matrix with columns spanning S^. Then
θ S,S^=arccos σmin SH S^.
Finally, we remark on the accuracy of the bounds when they are large. Relative errors like x^-x/x and angular errors like θ v^i,vi are only of interest when they are much less than 1. Some stated bounds are not strictly true when they are close to 1, but rigorous bounds are much more complicated and supply little extra information in the interesting case of small errors. These bounds are indicated by using the symbol ≲, or ‘approximately less than’, instead of the usual ≤. Thus, when these bounds are close to 1 or greater, they indicate that the computed answer may have no significant digits at all, but do not otherwise bound the error.
A number of methods in this chapter return error estimates and/or condition number estimates directly. In other cases Anderson et al. (1999) gives code fragments to illustrate the computation of these estimates, and a number of the F08 class example programs, for the driver methods, implement these code fragments.

Least squares problems

The conventional error analysis of linear least squares problems goes as follows. The problem is to find the x minimizing Ax-b 2. Let x^ be the solution computed using one of the methods described above. We discuss the most common case, where A is overdetermined (i.e., has more rows than columns) and has full rank.
Then the computed solution x^ has a small normwise backward error. In other words x^ minimizes A+E x^-b+f 2, where
max E 2A 2,f 2b 2≤p n ε
and p n is a modestly growing function of n and ε is the machine precision. Let κ 2 A=σmax A/σmin A, ρ=Ax-b 2, and sin θ=ρ/b 2. Then if p n ε is small enough, the error x^-x is bounded by
x-x^2x 2≲p n ε 2 κ 2 Acos θ+tan θ κ 22 A.
If A is rank-deficient, the problem can be regularized by treating all singular values less than a user-specified threshold as exactly zero. See Golub and Van Loan (2012) for error bounds in this case, as well as for the underdetermined case.
The solution of the overdetermined, full-rank problem may also be characterised as the solution of the linear system of equations
IAAT0rx=b0.
By solving this linear system (see F07 class) component-wise error bounds can also be obtained (see Arioli et al. (1989)).

The singular value decomposition

The usual error analysis of the SVD algorithm is as follows (see Golub and Van Loan (2012)).
The computed SVD, U^Σ^V^T, is nearly the exact SVD of A+E, i.e., A+E=U^+δ U^Σ^V^+δ V^ is the true SVD, so that U^+δ U^ and V^+δ V^ are both orthogonal, where E 2/A 2≤p m,n ε, δ U^≤p m,n ε, and δ V^≤p m,n ε. Here p m,n is a modestly growing function of m and n and ε is the machine precision. Each computed singular value σ^i differs from the true σi by an amount satisfying the bound
σ^i-σi≤p m,n ε σ 1.
Thus large singular values (those near σ 1) are computed to high relative accuracy and small ones may not be.
The angular difference between the computed left singular vector u^i and the true ui satisfies the approximate bound
θ u^i,ui≲p m,n ε A 2 gapi
where
gapi=min j≠i σi-σj
is the absolute gap between σi and the nearest other singular value. Thus, if σi is close to other singular values, its corresponding singular vector ui may be inaccurate. The same bound applies to the computed right singular vector v^i and the true vector vi. The gaps may be easily obtained from the computed singular values.
Let S^ be the space spanned by a collection of computed left singular vectors u^i,i∈I, where I is a subset of the integers from 1 to n. Let S be the corresponding true space. Then
θ S^,S≲p m,n ε A 2gapI.
where
gapI=min σi-σj  for ​i∈I,j∉I
is the absolute gap between the singular values in I and the nearest other singular value. Thus, a cluster of close singular values which is far away from any other singular value may have a well determined space S^ even if its individual singular vectors are ill-conditioned. The same bound applies to a set of right singular vectors v^i,i∈I.
In the special case of bidiagonal matrices, the singular values and singular vectors may be computed much more accurately (see Demmel and Kahan (1990)). A bidiagonal matrix B has nonzero entries only on the main diagonal and the diagonal immediately above it (or immediately below it). Reduction of a dense matrix to bidiagonal form B can introduce additional errors, so the following bounds for the bidiagonal case do not apply to the dense case.
Using the methods in this chapter, each computed singular value of a bidiagonal matrix is accurate to nearly full relative accuracy, no matter how tiny it is, so that
σ^i-σi≤p m,n ε σi.
The computed left singular vector u^i has an angular error at most about
θ u^i,ui≲p m,n ε relgapi
where
relgapi=min j≠i σi-σj/σi+σj
is the relative gap between σi and the nearest other singular value. The same bound applies to the right singular vector v^i and vi. Since the relative gap may be much larger than the absolute gap, this error bound may be much smaller than the previous one. The relative gaps may be easily obtained from the computed singular values.

The symmetric eigenproblem

The usual error analysis of the symmetric eigenproblem is as follows (see Parlett (1998)).
The computed eigendecomposition Z^Λ^Z^T is nearly the exact eigendecomposition of A+E, i.e., A+E=Z^+δ Z^Λ^Z^+δ Z^T is the true eigendecomposition so that Z^+δ Z^ is orthogonal, where E 2/A 2≤p n ε and δ Z^2≤p n ε and p n is a modestly growing function of n and ε is the machine precision. Each computed eigenvalue λ^i differs from the true λi by an amount satisfying the bound
λ^i-λi≤p n ε A 2.
Thus large eigenvalues (those near maxi λi=A 2) are computed to high relative accuracy and small ones may not be.
The angular difference between the computed unit eigenvector z^i and the true zi satisfies the approximate bound
θ z^i,zi≲p n ε A 2 gapi
if p n ε is small enough, where
gapi=min j≠i λi-λj
is the absolute gap between λi and the nearest other eigenvalue. Thus, if λi is close to other eigenvalues, its corresponding eigenvector zi may be inaccurate. The gaps may be easily obtained from the computed eigenvalues.
Let S^ be the invariant subspace spanned by a collection of eigenvectors z^i,i∈I, where I is a subset of the integers from 1 to n. Let S be the corresponding true subspace. Then
θ S^,S≲p n ε A 2gapI
where
gapI=min λi-λj  for ​i∈I,j∉I
is the absolute gap between the eigenvalues in I and the nearest other eigenvalue. Thus, a cluster of close eigenvalues which is far away from any other eigenvalue may have a well determined invariant subspace S^ even if its individual eigenvectors are ill-conditioned.
In the special case of a real symmetric tridiagonal matrix T, methods in this chapter can compute the eigenvalues and eigenvectors much more accurately. See Anderson et al. (1999) for further details.

The generalized symmetric-definite eigenproblem

The three types of problem to be considered are A-λB, AB-λI and BA-λI. In each case A and B are real symmetric (or complex Hermitian) and B is positive definite. We consider each case in turn, assuming that methods in this chapter are used to transform the generalized problem to the standard symmetric problem, followed by the solution of the symmetric problem. In all cases
gapi=min j≠i λi-λj
is the absolute gap between λi and the nearest other eigenvalue.
1. A-λB. The computed eigenvalues λ^i can differ from the true eigenvalues λi by an amount
λ^i-λi≲p n ε B-1 2A 2.
The angular difference between the computed eigenvector z^i and the true eigenvector zi is
θ z^i,zi≲p n ε B-1 2A 2 κ 2 B1/2 gapi.
2. AB-λI or BA-λI. The computed eigenvalues λ^i can differ from the true eigenvalues λi by an amount
λ^i-λi≲p n ε B 2A 2.
The angular difference between the computed eigenvector z^i and the true eigenvector zi is
θ z^i,zi≲p n ε B 2A 2 κ 2 B1/2 gapi.
These error bounds are large when B is ill-conditioned with respect to inversion (κ 2 B is large). It is often the case that the eigenvalues and eigenvectors are much better conditioned than indicated here. One way to get tighter bounds is effective when the diagonal entries of B differ widely in magnitude, as for example with a graded matrix.
1. | A-λB. Let D=diag b 11-1/2,…,b nn-1/2 be a diagonal matrix. Then replace B by DBD and A by DAD in the above bounds.
2. | AB-λI or BA-λI. Let D=diag b 11-1/2,…,b nn-1/2 be a diagonal matrix. Then replace B by DBD and A by D-1 A D-1 in the above bounds.
Further details can be found in Anderson et al. (1999).

The nonsymmetric eigenproblem

The nonsymmetric eigenvalue problem is more complicated than the symmetric eigenvalue problem. In this section, we just summarise the bounds. Further details can be found in Anderson et al. (1999).
We let λ^i be the ith computed eigenvalue and λi the ith true eigenvalue. Let v^i be the corresponding computed right eigenvector, and vi the true right eigenvector (so A vi=λivi). If I is a subset of the integers from 1 to n, we let λI denote the average of the selected eigenvalues: λI=∑i∈I λi/∑i∈I 1, and similarly for λ^I. We also let SI denote the subspace spanned by vi,i∈I; it is called a right invariant subspace because if v is any vector in SI then Av is also in SI. S^I is the corresponding computed subspace.
The algorithms for the nonsymmetric eigenproblem are normwise backward stable: they compute the exact eigenvalues, eigenvectors and invariant subspaces of slightly perturbed matrices A+E, where E≤p n ε A. Some of the bounds are stated in terms of E 2 and others in terms of E F; one may use p n ε for either quantity.
Methods are provided so that, for each (λ^i,v^i) pair the two values si and sepi, or for a selected subset I of eigenvalues the values sI and sepI can be obtained, for which the error bounds in Table 2 are true for sufficiently small E, (which is why they are called asymptotic):
Simple eigenvalue | λ^i-λi≲E 2/si
Eigenvalue cluster | λ^I-λI≲E 2/sI
Eigenvector | θ v^i,vi≲E F/sepi
Invariant subspace | θ S^I,SI≲E F/sepI
Table 2
Asymptotic error bounds for the nonsymmetric eigenproblem
If the problem is ill-conditioned, the asymptotic bounds may only hold for extremely small E. The global error bounds of Table 3 are guaranteed to hold for all E F<s×sep/4:
Simple eigenvalue | λ^i-λi≤n E 2/si | Holds for all E
Eigenvalue cluster | λ^I-λI≤2 E 2/sI | Requires E F<sI×sepI/4
Eigenvector | θ v^i,vi≤arctan 2 E F/sepi-4 E F/si | Requires E F<si×sepi/4
Invariant subspace | θ S^I,SI≤arctan 2 E F/sepI-4 E F/sI | Requires E F<sI×sepI/4
Table 3
Global error bounds for the nonsymmetric eigenproblem

Balancing and condition for the nonsymmetric eigenproblem

There are two preprocessing steps one may perform on a matrix A in order to make its eigenproblem easier. The first is permutation, or reordering the rows and columns to make A more nearly upper triangular (closer to Schur form): A′=PA PT, where P is a permutation matrix. If A′ is permutable to upper triangular form (or close to it), then no floating-point operations (or very few) are needed to reduce it to Schur form. The second is scaling by a diagonal matrix D to make the rows and columns of A′ more nearly equal in norm: A′′=D A′D-1. Scaling can make the matrix norm smaller with respect to the eigenvalues, and so possibly reduce the inaccuracy contributed by roundoff (see Chapter 11 of Wilkinson and Reinsch (1971)). We refer to these two operations as balancing.
Permuting has no effect on the condition numbers or their interpretation as described previously. Scaling, however, does change their interpretation and further details can be found in Anderson et al. (1999).

The generalized nonsymmetric eigenvalue problem

The algorithms for the generalized nonsymmetric eigenvalue problem are normwise backward stable: they compute the exact eigenvalues (as the pairs α,β), eigenvectors and deflating subspaces of slightly perturbed pairs A+E,B+F, where
E,F F≤p n ε A,B F.
Asymptotic and global error bounds can be obtained, which are generalizations of those given in Tables 2 and 3. See Section 4.11 of Anderson et al. (1999) for details. Methods are provided to compute estimates of reciprocal conditions numbers for eigenvalues and eigenspaces.

Balancing the generalized eigenvalue problem

As with the standard nonsymmetric eigenvalue problem, there are two preprocessing steps one may perform on a matrix pair A,B in order to make its eigenproblem easier; permutation and scaling, which together are referred to as balancing, as indicated in the following two steps.
1. The balancing method first attempts to permute A and B to block upper triangular form by a similarity transformation:
PA PT=F=F 11F 12F 13F 22F 23F 33,PB PT=G=G 11G 12G 13G 22G 23G 33,
where P is a permutation matrix, F 11, F 33, G 11 and G 33 are upper triangular. Then the diagonal elements of the matrix F 11,G 11 and G 33,H 33 are generalized eigenvalues of A,B. The rest of the generalized eigenvalues are given by the matrix pair F 22,G 22. Subsequent operations to compute the eigenvalues of A,B need only be applied to the matrix F 22,G 22; this can save a significant amount of work if F 22,G 22 is smaller than the original matrix pair A,B. If no suitable permutation exists (as is often the case), then there is no gain in efficiency or accuracy.
2. The balancing method applies a diagonal similarity transformation to F,G, to make the rows and columns of F 22,G 22 as close as possible in the norm:
DF D-1=ID 22IF 11F 12F 13F 22F 23F 33ID 22-1I,DG D-1=ID 22IG 11G 12G 13G 22G 23G 33ID 22-1I.
This transformation usually improves the accuracy of computed generalized eigenvalues and eigenvectors. However, there are exceptional occasions when this transformation increases the norm of the pencil; in this case accuracy could be lower with diagonal balancing.
See Anderson et al. (1999) for further details.

Other problems

Error bounds for other problems such as the generalized linear least squares problem and generalized singular value decomposition can be found in Anderson et al. (1999).

Block Partitioned Algorithms

A number of the methods in this chapter use what is termed a block partitioned algorithm. This means that at each major step of the algorithm a block of rows or columns is updated, and much of the computation is performed by matrix-matrix operations on these blocks. The matrix-matrix operations are performed by calls to the Level 3 BLAS (see F06 class), which are the key to achieving high performance on many modern computers. In the case of the QR algorithm for reducing an upper Hessenberg matrix to Schur form, a multishift strategy is used in order to improve performance. See Golub and Van Loan (2012) or Anderson et al. (1999) for more about block partitioned algorithms and the multishift strategy.
The performance of a block partitioned algorithm varies to some extent with the block size – that is, the number of rows or columns per block. This is a machine-dependent parameter, which is set to a suitable value when the library is implemented on each range of machines. You do not normally need to be aware of what value is being used. Different block sizes may be used for different methods. Values in the range 16 to 64 are typical.
On more conventional machines there is often no advantage from using a block partitioned algorithm, and then the methods use an unblocked algorithm (effectively a block size of 1), relying solely on calls to the Level 2 BLAS (see F06 class again).
The only situation in which you need some awareness of the block size is when it affects the amount of workspace to be supplied to a particular method. This is discussed in [Length of work arrays].

References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia
Arioli M, Duff I S and de Rijk P P M (1989) On the augmented system approach to sparse least squares problems Numer. Math. 55 667–684
Demmel J W and Kahan W (1990) Accurate singular values of bidiagonal matrices SIAM J. Sci. Statist. Comput. 11 873–912
Golub G H and Van Loan C F (2012) Matrix Computations (4th Edition) Johns Hopkins University Press, Baltimore
Moler C B and Stewart G W (1973) An algorithm for generalized matrix eigenproblems SIAM J. Numer. Anal. 10 241–256
Parlett B N (1998) The Symmetric Eigenvalue Problem SIAM, Philadelphia
Stewart G W and Sun J-G (1990) Matrix Perturbation Theory Academic Press, London
Ward R C (1981) Balancing the generalized eigenvalue problem SIAM J. Sci. Stat. Comp. 2 141–152
Wilkinson J H (1965) The Algebraic Eigenvalue Problem Oxford University Press, Oxford
Wilkinson J H and Reinsch C (1971) Handbook for Automatic Computation II, Linear Algebra Springer–Verlag

Inheritance Hierarchy

System..::..Object
NagLibrary..::..F08

See Also

F08 Members


F08 Members

[image] [image]

NAG Library for .NET Release 2
F08 Members
F08 Class Methods See Also Send Feedback

The F08 type exposes the following members.

Methods

Name Description
f08aa
f08aa solves linear least squares problems of the form
minx b-Ax 2  or  minx b-AT x 2,
where A is an m by n real matrix of full rank, using a QR or LQ factorization of A.
f08ag
f08ag multiplies an arbitrary real matrix C by the real orthogonal matrix Q from a QR factorization computed by (F08AEF not in this release) f08be f08bf.
f08an
f08an solves linear least squares problems of the form
minx b-Ax 2  or  minx b-AH x 2,
where A is an m by n complex matrix of full rank, using a QR or LQ factorization of A.
f08be
f08be computes the QR factorization, with column pivoting, of a real m by n matrix.
f08bf
f08bf computes the QR factorization, with column pivoting, of a real m by n matrix.
f08fa
f08fa computes all the eigenvalues and, optionally, all the eigenvectors of a real n by n symmetric matrix A.
f08fb
f08fb computes selected eigenvalues and, optionally, eigenvectors of a real n by n symmetric matrix A. Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.
f08fl
f08fl computes the reciprocal condition numbers for the eigenvectors of a real symmetric or complex Hermitian m by m matrix A, or for the left or right singular vectors of a general m by n matrix A.
f08fp
f08fp computes selected eigenvalues and, optionally, eigenvectors of a complex n by n Hermitian matrix A. Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.
f08kb
f08kb computes the singular value decomposition (SVD) of a real m by n matrix A, optionally computing the left and/or right singular vectors.
f08kp
f08kp computes the singular value decomposition (SVD) of a complex m by n matrix A, optionally computing the left and/or right singular vectors.
f08nb
f08nb computes the eigenvalues and, optionally, the left and/or right eigenvectors for an n by n real nonsymmetric matrix A.
Optionally, it also computes a balancing transformation to improve the conditioning of the eigenvalues and eigenvectors, reciprocal condition numbers for the eigenvalues, and reciprocal condition numbers for the right eigenvectors.
f08np
f08np computes the eigenvalues and, optionally, the left and/or right eigenvectors for an n by n complex nonsymmetric matrix A.
Optionally, it also computes a balancing transformation to improve the conditioning of the eigenvalues and eigenvectors, reciprocal condition numbers for the eigenvalues, and reciprocal condition numbers for the right eigenvectors.
f08wb
f08wb computes for a pair of n by n real nonsymmetric matrices A,B the generalized eigenvalues and, optionally, the left and/or right generalized eigenvectors using the QZ algorithm.
Optionally it also computes a balancing transformation to improve the conditioning of the eigenvalues and eigenvectors, reciprocal condition numbers for the eigenvalues, and reciprocal condition numbers for the right eigenvectors.
f08wp
f08wp computes for a pair of n by n complex nonsymmetric matrices A,B the generalized eigenvalues and, optionally, the left and/or right generalized eigenvectors using the QZ algorithm.
Optionally it also computes a balancing transformation to improve the conditioning of the eigenvalues and eigenvectors, reciprocal condition numbers for the eigenvalues, and reciprocal condition numbers for the right eigenvectors.

See Also

F08 Class


F08 Methods

[image] [image]

NAG Library for .NET Release 2
F08 Methods
F08 Class See Also Send Feedback

The F08 type exposes the following members.

Methods

Name Description
f08aa
f08aa solves linear least squares problems of the form
minx b-Ax 2  or  minx b-AT x 2,
where A is an m by n real matrix of full rank, using a QR or LQ factorization of A.
f08ag
f08ag multiplies an arbitrary real matrix C by the real orthogonal matrix Q from a QR factorization computed by (F08AEF not in this release) f08be f08bf.
f08an
f08an solves linear least squares problems of the form
minx b-Ax 2  or  minx b-AH x 2,
where A is an m by n complex matrix of full rank, using a QR or LQ factorization of A.
f08be
f08be computes the QR factorization, with column pivoting, of a real m by n matrix.
f08bf
f08bf computes the QR factorization, with column pivoting, of a real m by n matrix.
f08fa
f08fa computes all the eigenvalues and, optionally, all the eigenvectors of a real n by n symmetric matrix A.
f08fb
f08fb computes selected eigenvalues and, optionally, eigenvectors of a real n by n symmetric matrix A. Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.
f08fl
f08fl computes the reciprocal condition numbers for the eigenvectors of a real symmetric or complex Hermitian m by m matrix A, or for the left or right singular vectors of a general m by n matrix A.
f08fp
f08fp computes selected eigenvalues and, optionally, eigenvectors of a complex n by n Hermitian matrix A. Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.
f08kb
f08kb computes the singular value decomposition (SVD) of a real m by n matrix A, optionally computing the left and/or right singular vectors.
f08kp
f08kp computes the singular value decomposition (SVD) of a complex m by n matrix A, optionally computing the left and/or right singular vectors.
f08nb
f08nb computes the eigenvalues and, optionally, the left and/or right eigenvectors for an n by n real nonsymmetric matrix A.
Optionally, it also computes a balancing transformation to improve the conditioning of the eigenvalues and eigenvectors, reciprocal condition numbers for the eigenvalues, and reciprocal condition numbers for the right eigenvectors.
f08np
f08np computes the eigenvalues and, optionally, the left and/or right eigenvectors for an n by n complex nonsymmetric matrix A.
Optionally, it also computes a balancing transformation to improve the conditioning of the eigenvalues and eigenvectors, reciprocal condition numbers for the eigenvalues, and reciprocal condition numbers for the right eigenvectors.
f08wb
f08wb computes for a pair of n by n real nonsymmetric matrices A,B the generalized eigenvalues and, optionally, the left and/or right generalized eigenvectors using the QZ algorithm.
Optionally it also computes a balancing transformation to improve the conditioning of the eigenvalues and eigenvectors, reciprocal condition numbers for the eigenvalues, and reciprocal condition numbers for the right eigenvectors.
f08wp
f08wp computes for a pair of n by n complex nonsymmetric matrices A,B the generalized eigenvalues and, optionally, the left and/or right generalized eigenvectors using the QZ algorithm.
Optionally it also computes a balancing transformation to improve the conditioning of the eigenvalues and eigenvectors, reciprocal condition numbers for the eigenvalues, and reciprocal condition numbers for the right eigenvectors.

See Also

F08 Class


f08aa Method

[image]

NAG Library for .NET Release 2
F08..::f08aa Method
F08 Class See Also Send Feedback
f08aa solves linear least squares problems of the form
minx b-Ax 2  or  minx b-AT x 2,
where A is an m by n real matrix of full rank, using a QR or LQ factorization of A.

Syntax

C#
public static void f08aa(
    string trans,
    int m,
    int n,
    int nrhs,
    double[,] a,
    double[,] b,
    out int info
)
Visual Basic
Public Shared Sub f08aa ( _
    trans As String, _
    m As Integer, _
    n As Integer, _
    nrhs As Integer, _
    a As Double(,), _
    b As Double(,), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f08aa(
    String^ trans,
    int m,
    int n,
    int nrhs,
    array<double,2>^ a,
    array<double,2>^ b,
    [OutAttribute] int% info
)
F#
static member f08aa :
        trans : string *
        m : int *
        n : int *
        nrhs : int *
        a : float[,] *
        b : float[,] *
        info : int byref -> unit

Parameters

trans
Type: System..::..String
On entry: if trans="N", the linear system involves A.
If trans="T", the linear system involves AT.
Constraint: trans="N" or "T".
m
Type: System..::..Int32
On entry: m, the number of rows of the matrix A.
Constraint: m≥0.
n
Type: System..::..Int32
On entry: n, the number of columns of the matrix A.
Constraint: n≥0.
nrhs
Type: System..::..Int32
On entry: r, the number of right-hand sides, i.e., the number of columns of the matrices B and X.
Constraint: nrhs≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,m
Note: the second dimension of the array a must be at least max 1,n.
On entry: the m by n matrix A.
On exit: if m≥n, a is overwritten by details of its QR factorization, as returned by f08ae.
If m<n, a is overwritten by details of its LQ factorization, as returned by f08ah.
b
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,m,n
Note: the second dimension of the array b must be at least max 1,nrhs.
On entry: the matrix B of right-hand side vectors, stored in columns; b is m by r if trans="N", or n by r if trans="T".
On exit: b is overwritten by the solution vectors, x, stored in columns:
  • if trans="N" and m≥n, or trans="T" and m<n, elements 1 to min m,n in each column of b contain the least squares solution vectors; the residual sum of squares for the solution is given by the sum of squares of the modulus of elements min m,n+1 to max m,n in that column;
  • otherwise, elements 1 to max m,n in each column of b contain the minimum norm solution vectors.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

The following options are provided:
1. If trans="N" and m≥n: find the least squares solution of an overdetermined system, i.e., solve the least squares problem
minx b-Ax 2.
2. | If trans="N" and m<n: find the minimum norm solution of an underdetermined system Ax=b.
3. | If trans="T" and m≥n: find the minimum norm solution of an undetermined system AT x=b.
4. If trans="T" and m<n: find the least squares solution of an overdetermined system, i.e., solve the least squares problem
minx b-AT x 2.
Several right-hand side vectors b and solution vectors x can be handled in a single call; they are stored as the columns of the m by r right-hand side matrix B and the n by r solution matrix X.

References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA, LDB) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
info>0
If info=i, diagonal element i of the triangular factor of A is zero, so that A does not have full rank; the least squares solution could not be computed.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

See Section 4.5 of Anderson et al. (1999) for details of error bounds.

Parallelism and Performance

None.

Further Comments

The total number of floating-point operations required to factorize A is approximately 23 n 2 3 m-n if m≥n and 23 m 2 3 n-m otherwise. Following the factorization the solution for a single vector x requires O min m 2,n 2 operations.
The complex analogue of this method is f08an.

Example

This example solves the linear least squares problem
minx b-Ax 2,
where
A= -0.57 -1.28 -0.39 0.25 -1.93 1.08 -0.31 -2.14 2.30 0.24 0.40 -0.35 -1.93 0.64 -0.66 0.08 0.15 0.30 0.15 -2.13 -0.02 1.03 -1.43 0.50   and  b= -2.67 -0.55 3.34 -0.77 0.48 4.10 .
The square root of the residual sum of squares is also output.

Example program (C#): f08aae.cs

Example program data: f08aae.d

Example program results: f08aae.r

See Also

F08 Class
F08 Members


f08ag Method

[image]

NAG Library for .NET Release 2
F08..::f08ag Method
F08 Class See Also Send Feedback
f08ag multiplies an arbitrary real matrix C by the real orthogonal matrix Q from a QR factorization computed by (F08AEF not in this release) f08be f08bf.

Syntax

C#
public static void f08ag(
    string side,
    string trans,
    int m,
    int n,
    int k,
    double[,] a,
    double[] tau,
    double[,] c,
    out int info
)
Visual Basic
Public Shared Sub f08ag ( _
    side As String, _
    trans As String, _
    m As Integer, _
    n As Integer, _
    k As Integer, _
    a As Double(,), _
    tau As Double(), _
    c As Double(,), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f08ag(
    String^ side,
    String^ trans,
    int m,
    int n,
    int k,
    array<double,2>^ a,
    array<double>^ tau,
    array<double,2>^ c,
    [OutAttribute] int% info
)
F#
static member f08ag :
        side : string *
        trans : string *
        m : int *
        n : int *
        k : int *
        a : float[,] *
        tau : float[] *
        c : float[,] *
        info : int byref -> unit

Parameters

side
Type: System..::..String
On entry: indicates how Q or QT is to be applied to C.
side="L"
Q or QT is applied to C from the left.
side="R"
Q or QT is applied to C from the right.
Constraint: side="L" or "R".
trans
Type: System..::..String
On entry: indicates whether Q or QT is to be applied to C.
trans="N"
Q is applied to C.
trans="T"
QT is applied to C.
Constraint: trans="N" or "T".
m
Type: System..::..Int32
On entry: m, the number of rows of the matrix C.
Constraint: m≥0.
n
Type: System..::..Int32
On entry: n, the number of columns of the matrix C.
Constraint: n≥0.
k
Type: System..::..Int32
On entry: k, the number of elementary reflectors whose product defines the matrix Q.
Constraints:
  • if side="L", m≥k≥0;
  • if side="R", n≥k≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint:
  • if side="L", dim1≥max 1,m;
  • if side="R", dim1≥max 1,n.
Note: the second dimension of the array a must be at least max 1,k.
On entry: details of the vectors which define the elementary reflectors, as returned by f08ae, f08be or f08bf.
tau
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array tau must be at least max 1,k.
On entry: further details of the elementary reflectors, as returned by f08ae, f08be or f08bf.
c
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,m
Note: the second dimension of the array c must be at least max 1,n.
On entry: the m by n matrix C.
On exit: c is overwritten by QC or QT C or CQ or C QT as specified by side and trans.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f08ag is intended to be used after a call to (F08AEF not in this release) f08be f08bf which perform a QR factorization of a real matrix A. The orthogonal matrix Q is represented as a product of elementary reflectors.
This method may be used to form one of the matrix products
QC,QT C,CQ​ or ​C QT,
overwriting the result on c (which may be any real rectangular matrix).
A common application of this method is in solving linear least squares problems, as described in the F08 class and illustrated in [Example] in f08ae.

References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA, LDC) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

The computed result differs from the exact result by a matrix E such that
E 2=O ε C 2,
where ε is the machine precision.

Parallelism and Performance

None.

Further Comments

The total number of floating-point operations is approximately 2 nk 2 m-k if side="L" and 2 mk 2 n-k if side="R".
The complex analogue of this method is (F08AUF not in this release).

Example

See [Example] in f08ae.

See Also

F08 Class
F08 Members


f08an Method

[image]

NAG Library for .NET Release 2
F08..::f08an Method
F08 Class See Also Send Feedback
f08an solves linear least squares problems of the form
minx b-Ax 2  or  minx b-AH x 2,
where A is an m by n complex matrix of full rank, using a QR or LQ factorization of A.

Syntax

C#
public static void f08an(
    string trans,
    int m,
    int n,
    int nrhs,
    Complex[,] a,
    Complex[,] b,
    out int info
)
Visual Basic
Public Shared Sub f08an ( _
    trans As String, _
    m As Integer, _
    n As Integer, _
    nrhs As Integer, _
    a As Complex(,), _
    b As Complex(,), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f08an(
    String^ trans,
    int m,
    int n,
    int nrhs,
    array<Complex,2>^ a,
    array<Complex,2>^ b,
    [OutAttribute] int% info
)
F#
static member f08an :
        trans : string *
        m : int *
        n : int *
        nrhs : int *
        a : Complex[,] *
        b : Complex[,] *
        info : int byref -> unit

Parameters

trans
Type: System..::..String
On entry: if trans="N", the linear system involves A.
If trans="C", the linear system involves AH.
Constraint: trans="N" or "C".
m
Type: System..::..Int32
On entry: m, the number of rows of the matrix A.
Constraint: m≥0.
n
Type: System..::..Int32
On entry: n, the number of columns of the matrix A.
Constraint: n≥0.
nrhs
Type: System..::..Int32
On entry: r, the number of right-hand sides, i.e., the number of columns of the matrices B and X.
Constraint: nrhs≥0.
a
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,m
Note: the second dimension of the array a must be at least max 1,n.
On entry: the m by n matrix A.
On exit: if m≥n, a is overwritten by details of its QR factorization, as returned by f08as.
If m<n, a is overwritten by details of its LQ factorization, as returned by f08av.
b
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,m,n
Note: the second dimension of the array b must be at least max 1,nrhs.
On entry: the matrix B of right-hand side vectors, stored in columns; b is m by r if trans="N", or n by r if trans="C".
On exit: b is overwritten by the solution vectors, x, stored in columns:
  • if trans="N" and m≥n, or trans="C" and m<n, elements 1 to min m,n in each column of b contain the least squares solution vectors; the residual sum of squares for the solution is given by the sum of squares of the modulus of elements min m,n+1 to max m,n in that column;
  • otherwise, elements 1 to max m,n in each column of b contain the minimum norm solution vectors.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

The following options are provided:
1. If trans="N" and m≥n: find the least squares solution of an overdetermined system, i.e., solve the least squares problem
minx b-Ax 2.
2. | If trans="N" and m<n: find the minimum norm solution of an underdetermined system Ax=b.
3. | If trans="C" and m≥n: find the minimum norm solution of an undetermined system AH x=b.
4. If trans="C" and m<n: find the least squares solution of an overdetermined system, i.e., solve the least squares problem
minx b-AH x 2.
Several right-hand side vectors b and solution vectors x can be handled in a single call; they are stored as the columns of the m by r right-hand side matrix B and the n by r solution matrix X.

References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA, LDB) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
info>0
If info=i, diagonal element i of the triangular factor of A is zero, so that A does not have full rank; the least squares solution could not be computed.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

See Section 4.5 of Anderson et al. (1999) for details of error bounds.

Parallelism and Performance

None.

Further Comments

The total number of floating-point operations required to factorize A is approximately 83 n 2 3 m-n if m≥n and 83 m 2 3 n-m otherwise. Following the factorization the solution for a single vector x requires O min m 2,n 2 operations.
The real analogue of this method is f08aa.

Example

This example solves the linear least squares problem
minx b-Ax 2,
where
A= 0.96-0.81 i -0.03+0.96 i -0.91+2.06 i -0.05+0.41 i -0.98+1.98 i -1.20+0.19 i -0.66+0.42 i -0.81+0.56 i 0.62-0.46 i 1.01+0.02 i 0.63-0.17 i -1.11+0.60 i -0.37+0.38 i 0.19-0.54 i -0.98-0.36 i 0.22-0.20 i 0.83+0.51 i 0.20+0.01 i -0.17-0.46 i 1.47+1.59 i 1.08-0.28 i 0.20-0.12 i -0.07+1.23 i 0.26+0.26 i
and
b= -2.09+1.93 i 3.34-3.53 i -4.94-2.04 i 0.17+4.23 i -5.19+3.63 i 0.98+2.53 i .
The square root of the residual sum of squares is also output.

Example program (C#): f08ane.cs

Example program data: f08ane.d

Example program results: f08ane.r

See Also

F08 Class
F08 Members


f08be Method

[image]

NAG Library for .NET Release 2
F08..::f08be Method
F08 Class See Also Send Feedback
f08be computes the QR factorization, with column pivoting, of a real m by n matrix.

Syntax

C#
public static void f08be(
    int m,
    int n,
    double[,] a,
    int[] jpvt,
    double[] tau,
    out int info
)
Visual Basic
Public Shared Sub f08be ( _
    m As Integer, _
    n As Integer, _
    a As Double(,), _
    jpvt As Integer(), _
    tau As Double(), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f08be(
    int m,
    int n,
    array<double,2>^ a,
    array<int>^ jpvt,
    array<double>^ tau,
    [OutAttribute] int% info
)
F#
static member f08be :
        m : int *
        n : int *
        a : float[,] *
        jpvt : int[] *
        tau : float[] *
        info : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: m, the number of rows of the matrix A.
Constraint: m≥0.
n
Type: System..::..Int32
On entry: n, the number of columns of the matrix A.
Constraint: n≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,m
Note: the second dimension of the array a must be at least max 1,n.
On entry: the m by n matrix A.
On exit: if m≥n, the elements below the diagonal are overwritten by details of the orthogonal matrix Q and the upper triangle is overwritten by the corresponding elements of the n by n upper triangular matrix R.
If m<n, the strictly lower triangular part is overwritten by details of the orthogonal matrix Q and the remaining elements are overwritten by the corresponding elements of the m by n upper trapezoidal matrix R.
jpvt
Type: array< System..::..Int32 >[]()[][]
An array of size [dim1]
Note: the dimension of the array jpvt must be at least max 1,n.
On entry: if jpvt[i-1]≠0, then the i th column of A is moved to the beginning of AP before the decomposition is computed and is fixed in place during the computation. Otherwise, the i th column of A is a free column (i.e., one which may be interchanged during the computation with any other free column).
On exit: details of the permutation matrix P. More precisely, if jpvt[i-1]=k, then the kth column of A is moved to become the i th column of AP; in other words, the columns of AP are the columns of A in the order jpvt[0],jpvt[1],…,jpvt[n-1].
tau
Type: array< System..::..Double >[]()[][]
An array of size [min m,n]
On exit: further details of the orthogonal matrix Q.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f08be forms the QR factorization, with column pivoting, of an arbitrary rectangular real m by n matrix.
If m≥n, the factorization is given by:
AP=Q R0,
where R is an n by n upper triangular matrix, Q is an m by m orthogonal matrix and P is an n by n permutation matrix. It is sometimes more convenient to write the factorization as
AP=Q 1Q 2R0,
which reduces to
AP=Q 1 R,
where Q 1 consists of the first n columns of Q, and Q 2 the remaining m-n columns.
If m<n, R is trapezoidal, and the factorization can be written
AP=Q R 1R 2,
where R 1 is upper triangular and R 2 is rectangular.
The matrix Q is not formed explicitly but is represented as a product of min m,n elementary reflectors (see the F08 class for details). Methods are provided to work with Q in this representation (see [Further Comments]).
Note also that for any k<n, the information returned in the first k columns of the array a represents a QR factorization of the first k columns of the permuted matrix AP.
The method allows specified columns of A to be moved to the leading columns of AP at the start of the factorization and fixed there. The remaining columns are free to be interchanged so that at the ith stage the pivot column is chosen to be the column which maximizes the 2-norm of elements i to m over columns i to n.

References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

The computed factorization is the exact factorization of a nearby matrix A+E, where
E 2=O ε A 2,
and ε is the machine precision.

Parallelism and Performance

None.

Further Comments

The total number of floating-point operations is approximately 23 n 2 3 m-n if m≥n or 23 m 2 3 n-m if m<n.
To form the orthogonal matrix Q f08be may be followed by a call to (F08AFF not in this release): but note that the second dimension of the array a must be at least m, which may be larger than was required by f08be.
When m≥n, it is often only the first n columns of Q that are required, and they may be formed by the call:
To apply Q to an arbitrary real rectangular matrix C, f08be may be followed by a call to f08ag. For example, forms C=QT C, where C is m by p.
To compute a QR factorization without column pivoting, use (F08AEF not in this release).
The complex analogue of this method is (F08BSF not in this release).

Example

Example program (C#): f08bee.cs

Example program data: f08bee.d

Example program results: f08bee.r

See Also

F08 Class
F08 Members


f08bf Method

[image]

NAG Library for .NET Release 2
F08..::f08bf Method
F08 Class See Also Send Feedback
f08bf computes the QR factorization, with column pivoting, of a real m by n matrix.

Syntax

C#
public static void f08bf(
    int m,
    int n,
    double[,] a,
    int[] jpvt,
    double[] tau,
    out int info
)
Visual Basic
Public Shared Sub f08bf ( _
    m As Integer, _
    n As Integer, _
    a As Double(,), _
    jpvt As Integer(), _
    tau As Double(), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f08bf(
    int m,
    int n,
    array<double,2>^ a,
    array<int>^ jpvt,
    array<double>^ tau,
    [OutAttribute] int% info
)
F#
static member f08bf :
        m : int *
        n : int *
        a : float[,] *
        jpvt : int[] *
        tau : float[] *
        info : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: m, the number of rows of the matrix A.
Constraint: m≥0.
n
Type: System..::..Int32
On entry: n, the number of columns of the matrix A.
Constraint: n≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,m
Note: the second dimension of the array a must be at least max 1,n.
On entry: the m by n matrix A.
On exit: if m≥n, the elements below the diagonal are overwritten by details of the orthogonal matrix Q and the upper triangle is overwritten by the corresponding elements of the n by n upper triangular matrix R.
If m<n, the strictly lower triangular part is overwritten by details of the orthogonal matrix Q and the remaining elements are overwritten by the corresponding elements of the m by n upper trapezoidal matrix R.
jpvt
Type: array< System..::..Int32 >[]()[][]
An array of size [dim1]
Note: the dimension of the array jpvt must be at least max 1,n.
On entry: if jpvt[j-1]≠0, then the j th column of A is moved to the beginning of AP before the decomposition is computed and is fixed in place during the computation. Otherwise, the j th column of A is a free column (i.e., one which may be interchanged during the computation with any other free column).
On exit: details of the permutation matrix P. More precisely, if jpvt[j-1]=k, then the kth column of A is moved to become the j th column of AP; in other words, the columns of AP are the columns of A in the order jpvt[0],jpvt[1],…,jpvt[n-1].
tau
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array tau must be at least max 1,min m,n.
On exit: the scalar factors of the elementary reflectors.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

f08bf forms the QR factorization, with column pivoting, of an arbitrary rectangular real m by n matrix.
If m≥n, the factorization is given by:
AP=Q R0,
where R is an n by n upper triangular matrix, Q is an m by m orthogonal matrix and P is an n by n permutation matrix. It is sometimes more convenient to write the factorization as
AP=Q 1Q 2R0,
which reduces to
AP=Q 1 R,
where Q 1 consists of the first n columns of Q, and Q 2 the remaining m-n columns.
If m<n, R is trapezoidal, and the factorization can be written
AP=Q R 1R 2,
where R 1 is upper triangular and R 2 is rectangular.
The matrix Q is not formed explicitly but is represented as a product of min m,n elementary reflectors (see the F08 class for details). Methods are provided to work with Q in this representation (see [Further Comments]).
Note also that for any k<n, the information returned in the first k columns of the array a represents a QR factorization of the first k columns of the permuted matrix AP.
The method allows specified columns of A to be moved to the leading columns of AP at the start of the factorization and fixed there. The remaining columns are free to be interchanged so that at the ith stage the pivot column is chosen to be the column which maximizes the 2-norm of elements i to m over columns i to n.

References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

The computed factorization is the exact factorization of a nearby matrix A+E, where
E 2=O ε A 2,
and ε is the machine precision.

Parallelism and Performance

None.

Further Comments

The total number of floating-point operations is approximately 23 n 2 3 m-n if m≥n or 23 m 2 3 n-m if m<n.
To form the orthogonal matrix Q f08bf may be followed by a call to (F08AFF not in this release): but note that the second dimension of the array a must be at least m, which may be larger than was required by f08bf.
When m≥n, it is often only the first n columns of Q that are required, and they may be formed by the call:
To apply Q to an arbitrary real rectangular matrix C, f08bf may be followed by a call to f08ag. For example, forms C=QT C, where C is m by p.
To compute a QR factorization without column pivoting, use (F08AEF not in this release).
The complex analogue of this method is (F08BTF not in this release).

Example

This example solves the linear least squares problems
minx bj-A xj 2,  j=1,2
for the basic solutions x 1 and x 2, where
A= -0.09 0.14 -0.46 0.68 1.29 -1.56 0.20 0.29 1.09 0.51 -1.48 -0.43 0.89 -0.71 -0.96 -1.09 0.84 0.77 2.11 -1.27 0.08 0.55 -1.13 0.14 1.74 -1.59 -0.72 1.06 1.24 0.34   and  B= 7.4 2.7 4.2 -3.0 -8.3 -9.6 1.8 1.1 8.6 4.0 2.1 -5.7
and bj is the jth column of the matrix B. The solution is obtained by first obtaining a QR factorization with column pivoting of the matrix A. A tolerance of 0.01 is used to estimate the rank of A from the upper triangular factor, R.

Example program (C#): f08bfe.cs

Example program data: f08bfe.d

Example program results: f08bfe.r

See Also

F08 Class
F08 Members


f08fa Method

[image]

NAG Library for .NET Release 2
F08..::f08fa Method
F08 Class See Also Send Feedback
f08fa computes all the eigenvalues and, optionally, all the eigenvectors of a real n by n symmetric matrix A.

Syntax

C#
public static void f08fa(
    string jobz,
    string uplo,
    int n,
    double[,] a,
    double[] w,
    out int info
)
Visual Basic
Public Shared Sub f08fa ( _
    jobz As String, _
    uplo As String, _
    n As Integer, _
    a As Double(,), _
    w As Double(), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f08fa(
    String^ jobz,
    String^ uplo,
    int n,
    array<double,2>^ a,
    array<double>^ w,
    [OutAttribute] int% info
)
F#
static member f08fa :
        jobz : string *
        uplo : string *
        n : int *
        a : float[,] *
        w : float[] *
        info : int byref -> unit

Parameters

jobz
Type: System..::..String
On entry: indicates whether eigenvectors are computed.
jobz="N"
Only eigenvalues are computed.
jobz="V"
Eigenvalues and eigenvectors are computed.
Constraint: jobz="N" or "V".
uplo
Type: System..::..String
On entry: if uplo="U", the upper triangular part of A is stored.
If uplo="L", the lower triangular part of A is stored.
Constraint: uplo="U" or "L".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least max 1,n.
On entry: the n by n symmetric matrix A.
  • If uplo="U", the upper triangular part of A must be stored and the elements of the array below the diagonal are not referenced.
  • If uplo="L", the lower triangular part of A must be stored and the elements of the array above the diagonal are not referenced.
On exit: if jobz="V", then a contains the orthonormal eigenvectors of the matrix A.
If jobz="N", then on exit the lower triangle (if uplo="L") or the upper triangle (if uplo="U") of a, including the diagonal, is overwritten.
w
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the eigenvalues in ascending order.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

The symmetric matrix A is first reduced to tridiagonal form, using orthogonal similarity transformations, and then the QR algorithm is applied to the tridiagonal matrix to compute the eigenvalues and (optionally) the eigenvectors.

References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
info>0
If info=i, the algorithm failed to converge; i off-diagonal elements of an intermediate tridiagonal form did not converge to zero.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

The computed eigenvalues and eigenvectors are exact for a nearby matrix A+E, where
E 2=O ε A 2,
and ε is the machine precision. See Section 4.7 of Anderson et al. (1999) for further details.

Parallelism and Performance

None.

Further Comments

The total number of floating-point operations is proportional to n 3.
The complex analogue of this method is (F08FNF not in this release).

Example

This example finds all the eigenvalues and eigenvectors of the symmetric matrix
A=1234223433344444,
together with approximate error bounds for the computed eigenvalues and eigenvectors.

Example program (C#): f08fae.cs

Example program data: f08fae.d

Example program results: f08fae.r

See Also

F08 Class
F08 Members


f08fb Method

[image]

NAG Library for .NET Release 2
F08..::f08fb Method
F08 Class See Also Send Feedback
f08fb computes selected eigenvalues and, optionally, eigenvectors of a real n by n symmetric matrix A. Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

Syntax

C#
public static void f08fb(
    string jobz,
    string range,
    string uplo,
    int n,
    double[,] a,
    double vl,
    double vu,
    int il,
    int iu,
    double abstol,
    out int m,
    double[] w,
    double[,] z,
    int[] jfail,
    out int info
)
Visual Basic
Public Shared Sub f08fb ( _
    jobz As String, _
    range As String, _
    uplo As String, _
    n As Integer, _
    a As Double(,), _
    vl As Double, _
    vu As Double, _
    il As Integer, _
    iu As Integer, _
    abstol As Double, _
    <OutAttribute> ByRef m As Integer, _
    w As Double(), _
    z As Double(,), _
    jfail As Integer(), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f08fb(
    String^ jobz,
    String^ range,
    String^ uplo,
    int n,
    array<double,2>^ a,
    double vl,
    double vu,
    int il,
    int iu,
    double abstol,
    [OutAttribute] int% m,
    array<double>^ w,
    array<double,2>^ z,
    array<int>^ jfail,
    [OutAttribute] int% info
)
F#
static member f08fb :
        jobz : string *
        range : string *
        uplo : string *
        n : int *
        a : float[,] *
        vl : float *
        vu : float *
        il : int *
        iu : int *
        abstol : float *
        m : int byref *
        w : float[] *
        z : float[,] *
        jfail : int[] *
        info : int byref -> unit

Parameters

jobz
Type: System..::..String
On entry: indicates whether eigenvectors are computed.
jobz="N"
Only eigenvalues are computed.
jobz="V"
Eigenvalues and eigenvectors are computed.
Constraint: jobz="N" or "V".
range
Type: System..::..String
On entry: if range="A", all eigenvalues will be found.
If range="V", all eigenvalues in the half-open interval vl,vu will be found.
If range="I", the ilth to iuth eigenvalues will be found.
Constraint: range="A", "V" or "I".
uplo
Type: System..::..String
On entry: if uplo="U", the upper triangular part of A is stored.
If uplo="L", the lower triangular part of A is stored.
Constraint: uplo="U" or "L".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least max 1,n.
On entry: the n by n symmetric matrix A.
  • If uplo="U", the upper triangular part of A must be stored and the elements of the array below the diagonal are not referenced.
  • If uplo="L", the lower triangular part of A must be stored and the elements of the array above the diagonal are not referenced.
On exit: the lower triangle (if uplo="L") or the upper triangle (if uplo="U") of a, including the diagonal, is overwritten.
vl
Type: System..::..Double
On entry: if range="V", the lower and upper bounds of the interval to be searched for eigenvalues.
If range="A" or "I", vl and vu are not referenced.
Constraint: if range="V", vl<vu.
vu
Type: System..::..Double
On entry: if range="V", the lower and upper bounds of the interval to be searched for eigenvalues.
If range="A" or "I", vl and vu are not referenced.
Constraint: if range="V", vl<vu.
il
Type: System..::..Int32
On entry: if range="I", the indices (in ascending order) of the smallest and largest eigenvalues to be returned.
If range="A" or "V", il and iu are not referenced.
Constraints:
  • if range="I" and n=0, il=1 and iu=0;
  • if range="I" and n>0, 1≤il≤iu≤n.
iu
Type: System..::..Int32
On entry: if range="I", the indices (in ascending order) of the smallest and largest eigenvalues to be returned.
If range="A" or "V", il and iu are not referenced.
Constraints:
  • if range="I" and n=0, il=1 and iu=0;
  • if range="I" and n>0, 1≤il≤iu≤n.
abstol
Type: System..::..Double
On entry: the absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval a,b of width less than or equal to
abstol+ε max a,b,
where ε is the machine precision. If abstol is less than or equal to zero, then ε T 1 will be used in its place, where T is the tridiagonal matrix obtained by reducing A to tridiagonal form. Eigenvalues will be computed most accurately when abstol is set to twice the underflow threshold 2×x02am , not zero. If this method returns with info>0, indicating that some eigenvectors did not converge, try setting abstol to 2×x02am . See Demmel and Kahan (1990).
m
Type: System..::..Int32 %
On exit: the total number of eigenvalues found. 0≤m≤n.
If range="A", m=n.
If range="I", m=iu-il+1.
w
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array w must be at least max 1,n.
On exit: the first m elements contain the selected eigenvalues in ascending order.
z
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint:
  • if jobz="V", dim1≥max 1,n;
  • otherwise dim1≥1.
Note: the second dimension of the array z must be at least max 1,m if jobz="V", and at least 1 otherwise.
On exit: if jobz="V", then
  • if info=0, the first m columns of Z contain the orthonormal eigenvectors of the matrix A corresponding to the selected eigenvalues, with the ith column of Z holding the eigenvector associated with w[i-1];
  • if an eigenvector fails to converge (info>0), then that column of Z contains the latest approximation to the eigenvector, and the index of the eigenvector is returned in jfail.
If jobz="N", z is not referenced.
Note: you must ensure that at least max 1,m columns are supplied in the array z; if range="V", the exact value of m is not known in advance and an upper bound of at least n must be used.
jfail
Type: array< System..::..Int32 >[]()[][]
An array of size [dim1]
Note: the dimension of the array jfail must be at least max 1,n.
On exit: if jobz="V", then
  • if info=0, the first m elements of jfail are zero;
  • if info>0, jfail contains the indices of the eigenvectors that failed to converge.
If jobz="N", jfail is not referenced.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

The symmetric matrix A is first reduced to tridiagonal form, using orthogonal similarity transformations. The required eigenvalues and eigenvectors are then computed from the tridiagonal matrix; the method used depends upon whether all, or selected, eigenvalues and eigenvectors are required.

References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Demmel J W and Kahan W (1990) Accurate singular values of bidiagonal matrices SIAM J. Sci. Statist. Comput. 11 873–912
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA, LDZ) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
info>0
If info=i, then i eigenvectors failed to converge. Their indices are stored in array jfail. Please see abstol.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

The computed eigenvalues and eigenvectors are exact for a nearby matrix A+E, where
E 2=O ε A 2,
and ε is the machine precision. See Section 4.7 of Anderson et al. (1999) for further details.

Parallelism and Performance

None.

Further Comments

The total number of floating-point operations is proportional to n 3.
The complex analogue of this method is f08fp.

Example

This example finds the eigenvalues in the half-open interval -1,1, and the corresponding eigenvectors, of the symmetric matrix
A=1234223433344444.

Example program (C#): f08fbe.cs

Example program data: f08fbe.d

Example program results: f08fbe.r

See Also

F08 Class
F08 Members


f08fl Method

[image]

NAG Library for .NET Release 2
F08..::f08fl Method
F08 Class See Also Send Feedback
f08fl computes the reciprocal condition numbers for the eigenvectors of a real symmetric or complex Hermitian m by m matrix A, or for the left or right singular vectors of a general m by n matrix A.

Syntax

C#
public static void f08fl(
    string job,
    int m,
    int n,
    double[] d,
    double[] sep,
    out int info
)
Visual Basic
Public Shared Sub f08fl ( _
    job As String, _
    m As Integer, _
    n As Integer, _
    d As Double(), _
    sep As Double(), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f08fl(
    String^ job,
    int m,
    int n,
    array<double>^ d,
    array<double>^ sep,
    [OutAttribute] int% info
)
F#
static member f08fl :
        job : string *
        m : int *
        n : int *
        d : float[] *
        sep : float[] *
        info : int byref -> unit

Parameters

job
Type: System..::..String
On entry: specifies for which problem the reciprocal condition number should be computed.
job="E"
The eigenvectors of a symmetric or Hermitian matrix.
job="L"
The left singular vectors of a general matrix.
job="R"
The right singular vectors of a general matrix.
Constraint: job="E", "L" or "R".
m
Type: System..::..Int32
On entry: m, the number of rows of the matrix A.
Constraint: m≥0.
n
Type: System..::..Int32
On entry: n, the number of columns of the matrix when job="L" or "R".
If job="E", n is not referenced.
Constraint: if job="L" or "R", n≥0.
d
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array d must be at least max 1,m if job="E" and at least max 1,min m,n if job="L" or "R".
On entry: the eigenvalues if job="E", or singular values if job="L" or "R" of the matrix A.
Constraints:
  • the elements of the array d must be in either increasing or decreasing order;
  • if job="L" or "R" the elements of d must be non-negative.
sep
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array sep must be at least max 1,m if job="E" and at least max 1,min m,n if job="L" or "R".
On exit: the reciprocal condition numbers of the vectors.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

The bound on the error, measured by the angle in radians, for the ith computed vector is given by ε A 2/sepi, where ε is the machine precision and sepi is the reciprocal condition number for the vectors, returned in the array element sep[i-1]. sep[i-1] is restricted to be at least ε A 2 in order to limit the size of the error bound.

References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

Error Indicators and Warnings

info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

The reciprocal condition numbers are computed to machine precision relative to the size of the eigenvalues, or singular values.

Parallelism and Performance

None.

Further Comments

f08fl may also be used towards computing error bounds for the eigenvectors of the generalized symmetric or Hermitian definite eigenproblem. See Golub and Van Loan (1996) for further details on the error bounds.

Example

The use of f08fl in computing error bounds for eigenvectors of the symmetric eigenvalue problem is illustrated in [Example] in f08fa; its use in computing error bounds for singular vectors is illustrated in [Example] in f08kb; and its use in computing error bounds for eigenvectors of the generalized symmetric definite eigenvalue problem is illustrated in [Example] in f08sa.

See Also

F08 Class
F08 Members


f08fp Method

[image]

NAG Library for .NET Release 2
F08..::f08fp Method
F08 Class See Also Send Feedback
f08fp computes selected eigenvalues and, optionally, eigenvectors of a complex n by n Hermitian matrix A. Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

Syntax

C#
public static void f08fp(
    string jobz,
    string range,
    string uplo,
    int n,
    Complex[,] a,
    double vl,
    double vu,
    int il,
    int iu,
    double abstol,
    out int m,
    double[] w,
    Complex[,] z,
    int[] jfail,
    out int info
)
Visual Basic
Public Shared Sub f08fp ( _
    jobz As String, _
    range As String, _
    uplo As String, _
    n As Integer, _
    a As Complex(,), _
    vl As Double, _
    vu As Double, _
    il As Integer, _
    iu As Integer, _
    abstol As Double, _
    <OutAttribute> ByRef m As Integer, _
    w As Double(), _
    z As Complex(,), _
    jfail As Integer(), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f08fp(
    String^ jobz,
    String^ range,
    String^ uplo,
    int n,
    array<Complex,2>^ a,
    double vl,
    double vu,
    int il,
    int iu,
    double abstol,
    [OutAttribute] int% m,
    array<double>^ w,
    array<Complex,2>^ z,
    array<int>^ jfail,
    [OutAttribute] int% info
)
F#
static member f08fp :
        jobz : string *
        range : string *
        uplo : string *
        n : int *
        a : Complex[,] *
        vl : float *
        vu : float *
        il : int *
        iu : int *
        abstol : float *
        m : int byref *
        w : float[] *
        z : Complex[,] *
        jfail : int[] *
        info : int byref -> unit

Parameters

jobz
Type: System..::..String
On entry: indicates whether eigenvectors are computed.
jobz="N"
Only eigenvalues are computed.
jobz="V"
Eigenvalues and eigenvectors are computed.
Constraint: jobz="N" or "V".
range
Type: System..::..String
On entry: if range="A", all eigenvalues will be found.
If range="V", all eigenvalues in the half-open interval vl,vu will be found.
If range="I", the ilth to iuth eigenvalues will be found.
Constraint: range="A", "V" or "I".
uplo
Type: System..::..String
On entry: if uplo="U", the upper triangular part of A is stored.
If uplo="L", the lower triangular part of A is stored.
Constraint: uplo="U" or "L".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
a
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least max 1,n.
On entry: the n by n Hermitian matrix A.
  • If uplo="U", the upper triangular part of A must be stored and the elements of the array below the diagonal are not referenced.
  • If uplo="L", the lower triangular part of A must be stored and the elements of the array above the diagonal are not referenced.
On exit: the lower triangle (if uplo="L") or the upper triangle (if uplo="U") of a, including the diagonal, is overwritten.
vl
Type: System..::..Double
On entry: if range="V", the lower and upper bounds of the interval to be searched for eigenvalues.
If range="A" or "I", vl and vu are not referenced.
Constraint: if range="V", vl<vu.
vu
Type: System..::..Double
On entry: if range="V", the lower and upper bounds of the interval to be searched for eigenvalues.
If range="A" or "I", vl and vu are not referenced.
Constraint: if range="V", vl<vu.
il
Type: System..::..Int32
On entry: if range="I", the indices (in ascending order) of the smallest and largest eigenvalues to be returned.
If range="A" or "V", il and iu are not referenced.
Constraints:
  • if range="I" and n=0, il=1 and iu=0;
  • if range="I" and n>0, 1≤il≤iu≤n.
iu
Type: System..::..Int32
On entry: if range="I", the indices (in ascending order) of the smallest and largest eigenvalues to be returned.
If range="A" or "V", il and iu are not referenced.
Constraints:
  • if range="I" and n=0, il=1 and iu=0;
  • if range="I" and n>0, 1≤il≤iu≤n.
abstol
Type: System..::..Double
On entry: the absolute error tolerance for the eigenvalues. An approximate eigenvalue is accepted as converged when it is determined to lie in an interval a,b of width less than or equal to
abstol+ε max a,b,
where ε is the machine precision. If abstol is less than or equal to zero, then ε T 1 will be used in its place, where T is the tridiagonal matrix obtained by reducing A to tridiagonal form. Eigenvalues will be computed most accurately when abstol is set to twice the underflow threshold 2×x02am , not zero. If this method returns with info>0, indicating that some eigenvectors did not converge, try setting abstol to 2×x02am . See Demmel and Kahan (1990).
m
Type: System..::..Int32 %
On exit: the total number of eigenvalues found. 0≤m≤n.
If range="A", m=n.
If range="I", m=iu-il+1.
w
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array w must be at least max 1,n.
On exit: the first m elements contain the selected eigenvalues in ascending order.
z
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint:
  • if jobz="V", dim1≥max 1,n;
  • otherwise dim1≥1.
Note: the second dimension of the array z must be at least max 1,m if jobz="V", and at least 1 otherwise.
On exit: if jobz="V", then
  • if info=0, the first m columns of Z contain the orthonormal eigenvectors of the matrix A corresponding to the selected eigenvalues, with the ith column of Z holding the eigenvector associated with w[i-1];
  • if an eigenvector fails to converge (info>0), then that column of Z contains the latest approximation to the eigenvector, and the index of the eigenvector is returned in jfail.
If jobz="N", z is not referenced.
Note: you must ensure that at least max 1,m columns are supplied in the array z; if range="V", the exact value of m is not known in advance and an upper bound of at least n must be used.
jfail
Type: array< System..::..Int32 >[]()[][]
An array of size [dim1]
Note: the dimension of the array jfail must be at least max 1,n.
On exit: if jobz="V", then
  • if info=0, the first m elements of jfail are zero;
  • if info>0, jfail contains the indices of the eigenvectors that failed to converge.
If jobz="N", jfail is not referenced.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

The Hermitian matrix A is first reduced to real tridiagonal form, using unitary similarity transformations. The required eigenvalues and eigenvectors are then computed from the tridiagonal matrix; the method used depends upon whether all, or selected, eigenvalues and eigenvectors are required.

References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Demmel J W and Kahan W (1990) Accurate singular values of bidiagonal matrices SIAM J. Sci. Statist. Comput. 11 873–912
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA, LDZ) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
info>0
If info=i, then i eigenvectors failed to converge. Their indices are stored in array jfail. Please see abstol.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

The computed eigenvalues and eigenvectors are exact for a nearby matrix A+E, where
E 2=O ε A 2,
and ε is the machine precision. See Section 4.7 of Anderson et al. (1999) for further details.

Parallelism and Performance

None.

Further Comments

The total number of floating-point operations is proportional to n 3.
The real analogue of this method is f08fb.

Example

This example finds the eigenvalues in the half-open interval -2,2, and the corresponding eigenvectors, of the Hermitian matrix
A=12-i3-i4-i2+i23-2 i4-2 i3+i3+2 i34-3 i4+i4+2 i4+3 i4.

Example program (C#): f08fpe.cs

Example program data: f08fpe.d

Example program results: f08fpe.r

See Also

F08 Class
F08 Members


f08kb Method

[image]

NAG Library for .NET Release 2
F08..::f08kb Method
F08 Class See Also Send Feedback
f08kb computes the singular value decomposition (SVD) of a real m by n matrix A, optionally computing the left and/or right singular vectors.

Syntax

C#
public static void f08kb(
    string jobu,
    string jobvt,
    int m,
    int n,
    double[,] a,
    double[] s,
    double[,] u,
    double[,] vt,
    out int info
)
Visual Basic
Public Shared Sub f08kb ( _
    jobu As String, _
    jobvt As String, _
    m As Integer, _
    n As Integer, _
    a As Double(,), _
    s As Double(), _
    u As Double(,), _
    vt As Double(,), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f08kb(
    String^ jobu,
    String^ jobvt,
    int m,
    int n,
    array<double,2>^ a,
    array<double>^ s,
    array<double,2>^ u,
    array<double,2>^ vt,
    [OutAttribute] int% info
)
F#
static member f08kb :
        jobu : string *
        jobvt : string *
        m : int *
        n : int *
        a : float[,] *
        s : float[] *
        u : float[,] *
        vt : float[,] *
        info : int byref -> unit

Parameters

jobu
Type: System..::..String
On entry: specifies options for computing all or part of the matrix U.
jobu="A"
All m columns of U are returned in array u.
jobu="S"
The first min m,n columns of U (the left singular vectors) are returned in the array u.
jobu="O"
The first min m,n columns of U (the left singular vectors) are overwritten on the array a.
jobu="N"
No columns of U (no left singular vectors) are computed.
Constraint: jobu="A", "S", "O" or "N".
jobvt
Type: System..::..String
On entry: specifies options for computing all or part of the matrix VT.
jobvt="A"
All n rows of VT are returned in the array vt.
jobvt="S"
The first min m,n rows of VT (the right singular vectors) are returned in the array vt.
jobvt="O"
The first min m,n rows of VT (the right singular vectors) are overwritten on the array a.
jobvt="N"
No rows of VT (no right singular vectors) are computed.
Constraints:
  • jobvt="A", "S", "O" or "N";
  • jobvt and jobu cannot both be "O".
m
Type: System..::..Int32
On entry: m, the number of rows of the matrix A.
Constraint: m≥0.
n
Type: System..::..Int32
On entry: n, the number of columns of the matrix A.
Constraint: n≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,m
Note: the second dimension of the array a must be at least max 1,n.
On entry: the m by n matrix A.
On exit: if jobu="O", a is overwritten with the first min m,n columns of U (the left singular vectors, stored column-wise).
If jobvt="O", a is overwritten with the first min m,n rows of VT (the right singular vectors, stored row-wise).
If jobu≠"O" and jobvt≠"O", the contents of a are destroyed.
s
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array s must be at least max 1,min m,n.
On exit: the singular values of A, sorted so that s[i-1]≥s[i].
u
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint:
  • if jobu="A" or "S", dim1≥max 1,m;
  • otherwise dim1≥1.
  • if jobu="A", dim1≥max 1,m;
  • if jobu="S", dim1≥max 1,m;
  • otherwise dim1≥1.
Note: the second dimension of the array u must be at least max 1,m if jobu="A", max 1,min m,n if jobu="S", and at least 1 otherwise.
On exit: if jobu="A", u contains the m by m orthogonal matrix U.
If jobu="S", u contains the first min m,n columns of U (the left singular vectors, stored column-wise).
If jobu="N" or "O", u is not referenced.
vt
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint:
  • if jobvt="A", dim1≥max 1,n;
  • if jobvt="S", dim1≥max 1,min m,n;
  • otherwise dim1≥1.
Note: the second dimension of the array vt must be at least max 1,n if jobvt="A", max 1,n if jobvt="S", and at least 1 otherwise.
On exit: if jobvt="A", vt contains the n by n orthogonal matrix VT.
If jobvt="S", vt contains the first min m,n rows of VT (the right singular vectors, stored row-wise).
If jobvt="N" or "O", vt is not referenced.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

The SVD is written as
A=UΣ VT,
where Σ is an m by n matrix which is zero except for its min m,n diagonal elements, U is an m by m orthogonal matrix, and V is an n by n orthogonal matrix. The diagonal elements of Σ are the singular values of A; they are real and non-negative, and are returned in descending order. The first min m,n columns of U and V are the left and right singular vectors of A.
Note that the method returns VT, not V.

References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA, LDU, LDVT) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
info>0
If f08kb did not converge, info specifies how many superdiagonals of an intermediate bidiagonal form did not converge to zero. See the description of work above for details.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

The computed singular value decomposition is nearly the exact singular value decomposition for a nearby matrix A+E, where
E 2=O ε A 2,
and ε is the machine precision. In addition, the computed singular vectors are nearly orthogonal to working precision. See Section 4.9 of Anderson et al. (1999) for further details.

Parallelism and Performance

None.

Further Comments

The total number of floating-point operations is approximately proportional to m n 2 when m>n and m 2 n otherwise.
The singular values are returned in descending order.
The complex analogue of this method is f08kp.

Example

This example finds the singular values and left and right singular vectors of the 6 by 4 matrix
A= 2.27 -1.54 1.15 -1.94 0.28 -1.67 0.94 -0.78 -0.48 -3.09 0.99 -0.21 1.07 1.22 0.79 0.63 -2.35 2.93 -1.45 2.30 0.62 -7.39 1.03 -2.57 ,
together with approximate error bounds for the computed singular values and vectors.

Example program (C#): f08kbe.cs

Example program data: f08kbe.d

Example program results: f08kbe.r

See Also

F08 Class
F08 Members


f08kp Method

[image]

NAG Library for .NET Release 2
F08..::f08kp Method
F08 Class See Also Send Feedback
f08kp computes the singular value decomposition (SVD) of a complex m by n matrix A, optionally computing the left and/or right singular vectors.

Syntax

C#
public static void f08kp(
    string jobu,
    string jobvt,
    int m,
    int n,
    Complex[,] a,
    double[] s,
    Complex[,] u,
    Complex[,] vt,
    out int info
)
Visual Basic
Public Shared Sub f08kp ( _
    jobu As String, _
    jobvt As String, _
    m As Integer, _
    n As Integer, _
    a As Complex(,), _
    s As Double(), _
    u As Complex(,), _
    vt As Complex(,), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f08kp(
    String^ jobu,
    String^ jobvt,
    int m,
    int n,
    array<Complex,2>^ a,
    array<double>^ s,
    array<Complex,2>^ u,
    array<Complex,2>^ vt,
    [OutAttribute] int% info
)
F#
static member f08kp :
        jobu : string *
        jobvt : string *
        m : int *
        n : int *
        a : Complex[,] *
        s : float[] *
        u : Complex[,] *
        vt : Complex[,] *
        info : int byref -> unit

Parameters

jobu
Type: System..::..String
On entry: specifies options for computing all or part of the matrix U.
jobu="A"
All m columns of U are returned in array u.
jobu="S"
The first min m,n columns of U (the left singular vectors) are returned in the array u.
jobu="O"
The first min m,n columns of U (the left singular vectors) are overwritten on the array a.
jobu="N"
No columns of U (no left singular vectors) are computed.
Constraint: jobu="A", "S", "O" or "N".
jobvt
Type: System..::..String
On entry: specifies options for computing all or part of the matrix VH.
jobvt="A"
All n rows of VH are returned in the array vt.
jobvt="S"
The first min m,n rows of VH (the right singular vectors) are returned in the array vt.
jobvt="O"
The first min m,n rows of VH (the right singular vectors) are overwritten on the array a.
jobvt="N"
No rows of VH (no right singular vectors) are computed.
Constraints:
  • jobvt="A", "S", "O" or "N";
  • jobvt and jobu cannot both be "O".
m
Type: System..::..Int32
On entry: m, the number of rows of the matrix A.
Constraint: m≥0.
n
Type: System..::..Int32
On entry: n, the number of columns of the matrix A.
Constraint: n≥0.
a
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,m
Note: the second dimension of the array a must be at least max 1,n.
On entry: the m by n matrix A.
On exit: if jobu="O", a is overwritten with the first min m,n columns of U (the left singular vectors, stored column-wise).
If jobvt="O", a is overwritten with the first min m,n rows of VH (the right singular vectors, stored row-wise).
If jobu≠"O" and jobvt≠"O", the contents of a are destroyed.
s
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array s must be at least max 1,min m,n.
On exit: the singular values of A, sorted so that s[i-1]≥s[i].
u
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint:
  • if jobu="A" or "S", dim1≥max 1,m;
  • otherwise dim1≥1.
  • if jobu="A", dim1≥max 1,m;
  • if jobu="S", dim1≥max 1,m;
  • otherwise dim1≥1.
Note: the second dimension of the array u must be at least max 1,m if jobu="A", max 1,min m,n if jobu="S", and at least 1 otherwise.
On exit: if jobu="A", u contains the m by m unitary matrix U.
If jobu="S", u contains the first min m,n columns of U (the left singular vectors, stored column-wise).
If jobu="N" or "O", u is not referenced.
vt
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint:
  • if jobvt="A", dim1≥max 1,n;
  • if jobvt="S", dim1≥max 1,min m,n;
  • otherwise dim1≥1.
Note: the second dimension of the array vt must be at least max 1,n if jobvt="A", max 1,n if jobvt="S", and at least 1 otherwise.
On exit: if jobvt="A", vt contains the n by n unitary matrix VH.
If jobvt="S", vt contains the first min m,n rows of VH (the right singular vectors, stored row-wise).
If jobvt="N" or "O", vt is not referenced.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

The SVD is written as
A=UΣ VH,
where Σ is an m by n matrix which is zero except for its min m,n diagonal elements, U is an m by m unitary matrix, and V is an n by n unitary matrix. The diagonal elements of Σ are the singular values of A; they are real and non-negative, and are returned in descending order. The first min m,n columns of U and V are the left and right singular vectors of A.
Note that the method returns VH, not V.

References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA, LDU, LDVT) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
info>0
If f08kp did not converge, info specifies how many superdiagonals of an intermediate bidiagonal form did not converge to zero. See the description of rwork above for details.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

The computed singular value decomposition is nearly the exact singular value decomposition for a nearby matrix A+E, where
E 2=O ε A 2,
and ε is the machine precision. In addition, the computed singular vectors are nearly orthogonal to working precision. See Section 4.9 of Anderson et al. (1999) for further details.

Parallelism and Performance

None.

Further Comments

The total number of floating-point operations is approximately proportional to m n 2 when m>n and m 2 n otherwise.
The singular values are returned in descending order.
The real analogue of this method is f08kb.

Example

This example finds the singular values and left and right singular vectors of the 6 by 4 matrix
A= 0.96-0.81 i -0.03+0.96 i -0.91+2.06 i -0.05+0.41 i -0.98+1.98 i -1.20+0.19 i -0.66+0.42 i -0.81+0.56 i 0.62-0.46 i 1.01+0.02 i 0.63-0.17 i -1.11+0.60 i -0.37+0.38 i 0.19-0.54 i -0.98-0.36 i 0.22-0.20 i 0.83+0.51 i 0.20+0.01 i -0.17-0.46 i 1.47+1.59 i 1.08-0.28 i 0.20-0.12 i -0.07+1.23 i 0.26+0.26 i ,
together with approximate error bounds for the computed singular values and vectors.

Example program (C#): f08kpe.cs

Example program data: f08kpe.d

Example program results: f08kpe.r

See Also

F08 Class
F08 Members


f08nb Method

[image]

NAG Library for .NET Release 2
F08..::f08nb Method
F08 Class See Also Send Feedback
f08nb computes the eigenvalues and, optionally, the left and/or right eigenvectors for an n by n real nonsymmetric matrix A.
Optionally, it also computes a balancing transformation to improve the conditioning of the eigenvalues and eigenvectors, reciprocal condition numbers for the eigenvalues, and reciprocal condition numbers for the right eigenvectors.

Syntax

C#
public static void f08nb(
    string balanc,
    string jobvl,
    string jobvr,
    string sense,
    int n,
    double[,] a,
    double[] wr,
    double[] wi,
    double[,] vl,
    double[,] vr,
    out int ilo,
    out int ihi,
    double[] scale,
    out double abnrm,
    double[] rconde,
    double[] rcondv,
    out int info
)
Visual Basic
Public Shared Sub f08nb ( _
    balanc As String, _
    jobvl As String, _
    jobvr As String, _
    sense As String, _
    n As Integer, _
    a As Double(,), _
    wr As Double(), _
    wi As Double(), _
    vl As Double(,), _
    vr As Double(,), _
    <OutAttribute> ByRef ilo As Integer, _
    <OutAttribute> ByRef ihi As Integer, _
    scale As Double(), _
    <OutAttribute> ByRef abnrm As Double, _
    rconde As Double(), _
    rcondv As Double(), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f08nb(
    String^ balanc,
    String^ jobvl,
    String^ jobvr,
    String^ sense,
    int n,
    array<double,2>^ a,
    array<double>^ wr,
    array<double>^ wi,
    array<double,2>^ vl,
    array<double,2>^ vr,
    [OutAttribute] int% ilo,
    [OutAttribute] int% ihi,
    array<double>^ scale,
    [OutAttribute] double% abnrm,
    array<double>^ rconde,
    array<double>^ rcondv,
    [OutAttribute] int% info
)
F#
static member f08nb :
        balanc : string *
        jobvl : string *
        jobvr : string *
        sense : string *
        n : int *
        a : float[,] *
        wr : float[] *
        wi : float[] *
        vl : float[,] *
        vr : float[,] *
        ilo : int byref *
        ihi : int byref *
        scale : float[] *
        abnrm : float byref *
        rconde : float[] *
        rcondv : float[] *
        info : int byref -> unit

Parameters

balanc
Type: System..::..String
On entry: indicates how the input matrix should be diagonally scaled and/or permuted to improve the conditioning of its eigenvalues.
balanc="N"
Do not diagonally scale or permute.
balanc="P"
Perform permutations to make the matrix more nearly upper triangular. Do not diagonally scale.
balanc="S"
Diagonally scale the matrix, i.e., replace A by DA D-1, where D is a diagonal matrix chosen to make the rows and columns of A more equal in norm. Do not permute.
balanc="B"
Both diagonally scale and permute A.
Computed reciprocal condition numbers will be for the matrix after balancing and/or permuting. Permuting does not change condition numbers (in exact arithmetic), but balancing does.
Constraint: balanc="N", "P", "S" or "B".
jobvl
Type: System..::..String
On entry: if jobvl="N", the left eigenvectors of A are not computed.
If jobvl="V", the left eigenvectors of A are computed.
If sense="E" or "B", jobvl must be set to jobvl="V".
Constraint: jobvl="N" or "V".
jobvr
Type: System..::..String
On entry: if jobvr="N", the right eigenvectors of A are not computed.
If jobvr="V", the right eigenvectors of A are computed.
If sense="E" or "B", jobvr must be set to jobvr="V".
Constraint: jobvr="N" or "V".
sense
Type: System..::..String
On entry: determines which reciprocal condition numbers are computed.
sense="N"
None are computed.
sense="E"
Computed for eigenvalues only.
sense="V"
Computed for right eigenvectors only.
sense="B"
Computed for eigenvalues and right eigenvectors.
If sense="E" or "B", both left and right eigenvectors must also be computed (jobvl="V" and jobvr="V").
Constraint: sense="N", "E", "V" or "B".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least max 1,n.
On entry: the n by n matrix A.
On exit: a has been overwritten. If jobvl="V" or jobvr="V", A contains the real Schur form of the balanced version of the input matrix A.
wr
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the arrays wr and wi must be at least max 1,n.
On exit: wr and wi contain the real and imaginary parts, respectively, of the computed eigenvalues. Complex conjugate pairs of eigenvalues appear consecutively with the eigenvalue having the positive imaginary part first.
wi
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the arrays wr and wi must be at least max 1,n.
On exit: wr and wi contain the real and imaginary parts, respectively, of the computed eigenvalues. Complex conjugate pairs of eigenvalues appear consecutively with the eigenvalue having the positive imaginary part first.
vl
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint:
  • if jobvl="V", dim1≥max 1,n;
  • otherwise dim1≥1.
Note: the second dimension of the array vl must be at least max 1,n if jobvl="V", and at least 1 otherwise.
On exit: if jobvl="V", the left eigenvectors uj are stored one after another in the columns of vl, in the same order as their corresponding eigenvalues. If the jth eigenvalue is real, then uj=vl[i-1,j-1], for i=1,2,…,n. If the jth and j+1st eigenvalues form a complex conjugate pair, then uj=vl[i-1,j-1]+i×vl[i-1,j] and u j+1=vl[i-1,j-1]-i×vl[i-1,j], for i=1,2,…,n.
If jobvl="N", vl is not referenced.
vr
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint:
  • if jobvr="V", dim1≥max 1,n;
  • otherwise dim1≥1.
Note: the second dimension of the array vr must be at least max 1,n if jobvr="V", and at least 1 otherwise.
On exit: if jobvr="V", the right eigenvectors vj are stored one after another in the columns of vr, in the same order as their corresponding eigenvalues. If the jth eigenvalue is real, then vj=vr[i-1,j-1], for i=1,2,…,n. If the jth and j+1st eigenvalues form a complex conjugate pair, then vj=vr[i-1,j-1]+i×vr[i-1,j] and v j+1=vr[i-1,j-1]-i×vr[i-1,j], for i=1,2,…,n.
If jobvr="N", vr is not referenced.
ilo
Type: System..::..Int32 %
On exit: ilo and ihi are integer values determined when A was balanced. The balanced A has a ij=0 if i>j and j=1,2,…,ilo-1 or i=ihi+1,…,n.
ihi
Type: System..::..Int32 %
On exit: ilo and ihi are integer values determined when A was balanced. The balanced A has a ij=0 if i>j and j=1,2,…,ilo-1 or i=ihi+1,…,n.
scale
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array scale must be at least max 1,n.
On exit: details of the permutations and scaling factors applied when balancing A.
If pj is the index of the row and column interchanged with row and column j, and dj is the scaling factor applied to row and column j, then
  • scale[j-1]=pj, for j=1,2,…,ilo-1;
  • scale[j-1]=dj, for j=ilo,…,ihi;
  • scale[j-1]=pj, for j=ihi+1,…,n.
The order in which the interchanges are made is n to ihi+1, then 1 to ilo-1.
abnrm
Type: System..::..Double %
On exit: the 1-norm of the balanced matrix (the maximum of the sum of absolute values of elements of any column).
rconde
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array rconde must be at least max 1,n.
On exit: rconde[j-1] is the reciprocal condition number of the jth eigenvalue.
rcondv
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array rcondv must be at least max 1,n.
On exit: rcondv[j-1] is the reciprocal condition number of the jth right eigenvector.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

The right eigenvector vj of A satisfies
A vj=λjvj
where λj is the jth eigenvalue of A. The left eigenvector uj of A satisfies
ujH A=λj ujH
where ujH denotes the conjugate transpose of uj.
Balancing a matrix means permuting the rows and columns to make it more nearly upper triangular, and applying a diagonal similarity transformation DA D-1, where D is a diagonal matrix, with the aim of making its rows and columns closer in norm and the condition numbers of its eigenvalues and eigenvectors smaller. The computed reciprocal condition numbers correspond to the balanced matrix. Permuting rows and columns will not change the condition numbers (in exact arithmetic) but diagonal scaling will. For further explanation of balancing, see Section 4.8.1.2 of Anderson et al. (1999).
Following the optional balancing, the matrix A is first reduced to upper Hessenberg form by means of unitary similarity transformations, and the QR algorithm is then used to further reduce the matrix to upper triangular Schur form, T, from which the eigenvalues are computed. Optionally, the eigenvectors of T are also computed and backtransformed to those of A.

References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA, LDVL, LDVR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
info>0
If info=i, the QR algorithm failed to compute all the eigenvalues, and no eigenvectors or condition numbers have been computed; elements 1:ilo-1 and i+1:n of wr and wi contain eigenvalues which have converged.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

The computed eigenvalues and eigenvectors are exact for a nearby matrix A+E, where
E 2=O ε A 2,
and ε is the machine precision. See Section 4.8 of Anderson et al. (1999) for further details.

Parallelism and Performance

None.

Further Comments

Each eigenvector is normalized to have Euclidean norm equal to unity and the element of largest absolute value real and positive.
The total number of floating-point operations is proportional to n 3.
The complex analogue of this method is f08np.

Example

This example finds all the eigenvalues and right eigenvectors of the matrix
A= 0.35 0.45 -0.14 -0.17 0.09 0.07 -0.54 0.35 -0.44 -0.33 -0.03 0.17 0.25 -0.32 -0.13 0.11 ,
together with estimates of the condition number and forward error bounds for each eigenvalue and eigenvector. The option to balance the matrix is used. In order to compute the condition numbers of the eigenvalues, the left eigenvectors also have to be computed, but they are not printed out in this example.

Example program (C#): f08nbe.cs

Example program data: f08nbe.d

Example program results: f08nbe.r

See Also

F08 Class
F08 Members


f08np Method

[image]

NAG Library for .NET Release 2
F08..::f08np Method
F08 Class See Also Send Feedback
f08np computes the eigenvalues and, optionally, the left and/or right eigenvectors for an n by n complex nonsymmetric matrix A.
Optionally, it also computes a balancing transformation to improve the conditioning of the eigenvalues and eigenvectors, reciprocal condition numbers for the eigenvalues, and reciprocal condition numbers for the right eigenvectors.

Syntax

C#
public static void f08np(
    string balanc,
    string jobvl,
    string jobvr,
    string sense,
    int n,
    Complex[,] a,
    Complex[] w,
    Complex[,] vl,
    Complex[,] vr,
    out int ilo,
    out int ihi,
    double[] scale,
    out double abnrm,
    double[] rconde,
    double[] rcondv,
    out int info
)
Visual Basic
Public Shared Sub f08np ( _
    balanc As String, _
    jobvl As String, _
    jobvr As String, _
    sense As String, _
    n As Integer, _
    a As Complex(,), _
    w As Complex(), _
    vl As Complex(,), _
    vr As Complex(,), _
    <OutAttribute> ByRef ilo As Integer, _
    <OutAttribute> ByRef ihi As Integer, _
    scale As Double(), _
    <OutAttribute> ByRef abnrm As Double, _
    rconde As Double(), _
    rcondv As Double(), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f08np(
    String^ balanc,
    String^ jobvl,
    String^ jobvr,
    String^ sense,
    int n,
    array<Complex,2>^ a,
    array<Complex>^ w,
    array<Complex,2>^ vl,
    array<Complex,2>^ vr,
    [OutAttribute] int% ilo,
    [OutAttribute] int% ihi,
    array<double>^ scale,
    [OutAttribute] double% abnrm,
    array<double>^ rconde,
    array<double>^ rcondv,
    [OutAttribute] int% info
)
F#
static member f08np :
        balanc : string *
        jobvl : string *
        jobvr : string *
        sense : string *
        n : int *
        a : Complex[,] *
        w : Complex[] *
        vl : Complex[,] *
        vr : Complex[,] *
        ilo : int byref *
        ihi : int byref *
        scale : float[] *
        abnrm : float byref *
        rconde : float[] *
        rcondv : float[] *
        info : int byref -> unit

Parameters

balanc
Type: System..::..String
On entry: indicates how the input matrix should be diagonally scaled and/or permuted to improve the conditioning of its eigenvalues.
balanc="N"
Do not diagonally scale or permute.
balanc="P"
Perform permutations to make the matrix more nearly upper triangular. Do not diagonally scale.
balanc="S"
Diagonally scale the matrix, i.e., replace A by DA D-1, where D is a diagonal matrix chosen to make the rows and columns of A more equal in norm. Do not permute.
balanc="B"
Both diagonally scale and permute A.
Computed reciprocal condition numbers will be for the matrix after balancing and/or permuting. Permuting does not change condition numbers (in exact arithmetic), but balancing does.
Constraint: balanc="N", "P", "S" or "B".
jobvl
Type: System..::..String
On entry: if jobvl="N", the left eigenvectors of A are not computed.
If jobvl="V", the left eigenvectors of A are computed.
If sense="E" or "B", jobvl must be set to jobvl="V".
Constraint: jobvl="N" or "V".
jobvr
Type: System..::..String
On entry: if jobvr="N", the right eigenvectors of A are not computed.
If jobvr="V", the right eigenvectors of A are computed.
If sense="E" or "B", jobvr must be set to jobvr="V".
Constraint: jobvr="N" or "V".
sense
Type: System..::..String
On entry: determines which reciprocal condition numbers are computed.
sense="N"
None are computed.
sense="E"
Computed for eigenvalues only.
sense="V"
Computed for right eigenvectors only.
sense="B"
Computed for eigenvalues and right eigenvectors.
If sense="E" or "B", both left and right eigenvectors must also be computed (jobvl="V" and jobvr="V").
Constraint: sense="N", "E", "V" or "B".
n
Type: System..::..Int32
On entry: n, the order of the matrix A.
Constraint: n≥0.
a
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least max 1,n.
On entry: the n by n matrix A.
On exit: a has been overwritten. If jobvl="V" or jobvr="V", A contains the Schur form of the balanced version of the matrix A.
w
Type: array< NagLibrary..::..Complex >[]()[][]
An array of size [dim1]
Note: the dimension of the array w must be at least max 1,n.
On exit: contains the computed eigenvalues.
vl
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint:
  • if jobvl="V", dim1≥max 1,n;
  • otherwise dim1≥1.
Note: the second dimension of the array vl must be at least max 1,n if jobvl="V", and at least 1 otherwise.
On exit: if jobvl="V", the left eigenvectors uj are stored one after another in the columns of vl, in the same order as their corresponding eigenvalues; that is uj=vl[i-1,j-1], for i=1,2,…,n.
If jobvl="N", vl is not referenced.
vr
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint:
  • if jobvr="V", dim1≥max 1,n;
  • otherwise dim1≥1.
Note: the second dimension of the array vr must be at least max 1,n if jobvr="V", and at least 1 otherwise.
On exit: if jobvr="V", the right eigenvectors vj are stored one after another in the columns of vr, in the same order as their corresponding eigenvalues; that is vj=vr[i-1,j-1], for i=1,2,…,n.
If jobvr="N", vr is not referenced.
ilo
Type: System..::..Int32 %
On exit: ilo and ihi are integer values determined when A was balanced. The balanced A has a ij=0 if i>j and j=1,2,…,ilo-1 or i=ihi+1,…,n.
ihi
Type: System..::..Int32 %
On exit: ilo and ihi are integer values determined when A was balanced. The balanced A has a ij=0 if i>j and j=1,2,…,ilo-1 or i=ihi+1,…,n.
scale
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array scale must be at least max 1,n.
On exit: details of the permutations and scaling factors applied when balancing A.
If pj is the index of the row and column interchanged with row and column j, and dj is the scaling factor applied to row and column j, then
  • scale[j-1]=pj, for j=1,2,…,ilo-1;
  • scale[j-1]=dj, for j=ilo,…,ihi;
  • scale[j-1]=pj, for j=ihi+1,…,n.
The order in which the interchanges are made is n to ihi+1, then 1 to ilo-1.
abnrm
Type: System..::..Double %
On exit: the 1-norm of the balanced matrix (the maximum of the sum of absolute values of elements of any column).
rconde
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array rconde must be at least max 1,n.
On exit: rconde[j-1] is the reciprocal condition number of the jth eigenvalue.
rcondv
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array rcondv must be at least max 1,n.
On exit: rcondv[j-1] is the reciprocal condition number of the jth right eigenvector.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

The right eigenvector vj of A satisfies
A vj=λjvj
where λj is the jth eigenvalue of A. The left eigenvector uj of A satisfies
ujH A=λj ujH
where ujH denotes the conjugate transpose of uj.
Balancing a matrix means permuting the rows and columns to make it more nearly upper triangular, and applying a diagonal similarity transformation DA D-1, where D is a diagonal matrix, with the aim of making its rows and columns closer in norm and the condition numbers of its eigenvalues and eigenvectors smaller. The computed reciprocal condition numbers correspond to the balanced matrix. Permuting rows and columns will not change the condition numbers (in exact arithmetic) but diagonal scaling will. For further explanation of balancing, see Section 4.8.1.2 of Anderson et al. (1999).
Following the optional balancing, the matrix A is first reduced to upper Hessenberg form by means of unitary similarity transformations, and the QR algorithm is then used to further reduce the matrix to upper triangular Schur form, T, from which the eigenvalues are computed. Optionally, the eigenvectors of T are also computed and backtransformed to those of A.

References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA, LDVL, LDVR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
info>0
If info=i, the QR algorithm failed to compute all the eigenvalues, and no eigenvectors or condition numbers have been computed; elements 1:ilo-1 and i+1:n of w contain eigenvalues which have converged.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

The computed eigenvalues and eigenvectors are exact for a nearby matrix A+E, where
E 2=O ε A 2,
and ε is the machine precision. See Section 4.8 of Anderson et al. (1999) for further details.

Parallelism and Performance

None.

Further Comments

Each eigenvector is normalized to have Euclidean norm equal to unity and the element of largest absolute value real and positive.
The total number of floating-point operations is proportional to n 3.
The real analogue of this method is f08nb.

Example

This example finds all the eigenvalues and right eigenvectors of the matrix
A= -3.97-5.04 i -4.11+3.70 i -0.34+1.01 i 1.29-0.86 i 0.34-1.50 i 1.52-0.43 i 1.88-5.38 i 3.36+0.65 i 3.31-3.85 i 2.50+3.45 i 0.88-1.08 i 0.64-1.48 i -1.10+0.82 i 1.81-1.59 i 3.25+1.33 i 1.57-3.44 i ,
together with estimates of the condition number and forward error bounds for each eigenvalue and eigenvector. The option to balance the matrix is used. In order to compute the condition numbers of the eigenvalues, the left eigenvectors also have to be computed, but they are not printed out in this example.

Example program (C#): f08npe.cs

Example program data: f08npe.d

Example program results: f08npe.r

See Also

F08 Class
F08 Members


f08wb Method

[image]

NAG Library for .NET Release 2
F08..::f08wb Method
F08 Class See Also Send Feedback
f08wb computes for a pair of n by n real nonsymmetric matrices A,B the generalized eigenvalues and, optionally, the left and/or right generalized eigenvectors using the QZ algorithm.
Optionally it also computes a balancing transformation to improve the conditioning of the eigenvalues and eigenvectors, reciprocal condition numbers for the eigenvalues, and reciprocal condition numbers for the right eigenvectors.

Syntax

C#
public static void f08wb(
    string balanc,
    string jobvl,
    string jobvr,
    string sense,
    int n,
    double[,] a,
    double[,] b,
    double[] alphar,
    double[] alphai,
    double[] beta,
    double[,] vl,
    double[,] vr,
    out int ilo,
    out int ihi,
    double[] lscale,
    double[] rscale,
    out double abnrm,
    out double bbnrm,
    double[] rconde,
    double[] rcondv,
    out int info
)
Visual Basic
Public Shared Sub f08wb ( _
    balanc As String, _
    jobvl As String, _
    jobvr As String, _
    sense As String, _
    n As Integer, _
    a As Double(,), _
    b As Double(,), _
    alphar As Double(), _
    alphai As Double(), _
    beta As Double(), _
    vl As Double(,), _
    vr As Double(,), _
    <OutAttribute> ByRef ilo As Integer, _
    <OutAttribute> ByRef ihi As Integer, _
    lscale As Double(), _
    rscale As Double(), _
    <OutAttribute> ByRef abnrm As Double, _
    <OutAttribute> ByRef bbnrm As Double, _
    rconde As Double(), _
    rcondv As Double(), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f08wb(
    String^ balanc,
    String^ jobvl,
    String^ jobvr,
    String^ sense,
    int n,
    array<double,2>^ a,
    array<double,2>^ b,
    array<double>^ alphar,
    array<double>^ alphai,
    array<double>^ beta,
    array<double,2>^ vl,
    array<double,2>^ vr,
    [OutAttribute] int% ilo,
    [OutAttribute] int% ihi,
    array<double>^ lscale,
    array<double>^ rscale,
    [OutAttribute] double% abnrm,
    [OutAttribute] double% bbnrm,
    array<double>^ rconde,
    array<double>^ rcondv,
    [OutAttribute] int% info
)
F#
static member f08wb :
        balanc : string *
        jobvl : string *
        jobvr : string *
        sense : string *
        n : int *
        a : float[,] *
        b : float[,] *
        alphar : float[] *
        alphai : float[] *
        beta : float[] *
        vl : float[,] *
        vr : float[,] *
        ilo : int byref *
        ihi : int byref *
        lscale : float[] *
        rscale : float[] *
        abnrm : float byref *
        bbnrm : float byref *
        rconde : float[] *
        rcondv : float[] *
        info : int byref -> unit

Parameters

balanc
Type: System..::..String
On entry: specifies the balance option to be performed.
balanc="N"
Do not diagonally scale or permute.
balanc="P"
Permute only.
balanc="S"
Scale only.
balanc="B"
Both permute and scale.
Computed reciprocal condition numbers will be for the matrices after permuting and/or balancing. Permuting does not change condition numbers (in exact arithmetic), but balancing does. In the absence of other information, balanc="B" is recommended.
Constraint: balanc="N", "P", "S" or "B".
jobvl
Type: System..::..String
On entry: if jobvl="N", do not compute the left generalized eigenvectors.
If jobvl="V", compute the left generalized eigenvectors.
Constraint: jobvl="N" or "V".
jobvr
Type: System..::..String
On entry: if jobvr="N", do not compute the right generalized eigenvectors.
If jobvr="V", compute the right generalized eigenvectors.
Constraint: jobvr="N" or "V".
sense
Type: System..::..String
On entry: determines which reciprocal condition numbers are computed.
sense="N"
None are computed.
sense="E"
Computed for eigenvalues only.
sense="V"
Computed for eigenvectors only.
sense="B"
Computed for eigenvalues and eigenvectors.
Constraint: sense="N", "E", "V" or "B".
n
Type: System..::..Int32
On entry: n, the order of the matrices A and B.
Constraint: n≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least max 1,n.
On entry: the matrix A in the pair A,B.
On exit: a has been overwritten. If jobvl="V" or jobvr="V" or both, then A contains the first part of the real Schur form of the ‘balanced’ versions of the input A and B.
b
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array b must be at least max 1,n.
On entry: the matrix B in the pair A,B.
On exit: b has been overwritten.
alphar
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the element alphar[j-1] contains the real part of αj.
alphai
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the element alphai[j-1] contains the imaginary part of αj.
beta
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: alphar[j-1]+alphai[j-1]×i/beta[j-1], for j=1,2,…,n, will be the generalized eigenvalues.
If alphai[j-1] is zero, then the jth eigenvalue is real; if positive, then the jth and j+1st eigenvalues are a complex conjugate pair, with alphai[j] negative.
Note: the quotients alphar[j-1]/beta[j-1] and alphai[j-1]/beta[j-1] may easily overflow or underflow, and beta[j-1] may even be zero. Thus, you should avoid naively computing the ratio αj/βj. However, max αj will always be less than and usually comparable with a 2 in magnitude, and max βj will always be less than and usually comparable with b 2.
vl
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint:
  • if jobvl="V", dim1≥max 1,n;
  • otherwise dim1≥1.
Note: the second dimension of the array vl must be at least max 1,n if jobvl="V", and at least 1 otherwise.
On exit: if jobvl="V", the left generalized eigenvectors uj are stored one after another in the columns of vl, in the same order as the corresponding eigenvalues. Each eigenvector will be scaled so the largest component will have real part+imag. part=1.
If jobvl="N", vl is not referenced.
vr
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint:
  • if jobvr="V", dim1≥max 1,n;
  • otherwise dim1≥1.
Note: the second dimension of the array vr must be at least max 1,n if jobvr="V", and at least 1 otherwise.
On exit: if jobvr="V", the right generalized eigenvectors vj are stored one after another in the columns of vr, in the same order as the corresponding eigenvalues. Each eigenvector will be scaled so the largest component will have real part+imag. part=1.
If jobvr="N", vr is not referenced.
ilo
Type: System..::..Int32 %
On exit: ilo and ihi are integer values such that a[i-1,j-1]=0 and b[i-1,j-1]=0 if i>j and j=1,2,…,ilo-1 or i=ihi+1,…,n.
If balanc="N" or "S", ilo=1 and ihi=n.
ihi
Type: System..::..Int32 %
On exit: ilo and ihi are integer values such that a[i-1,j-1]=0 and b[i-1,j-1]=0 if i>j and j=1,2,…,ilo-1 or i=ihi+1,…,n.
If balanc="N" or "S", ilo=1 and ihi=n.
lscale
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: details of the permutations and scaling factors applied to the left side of A and B.
If plj is the index of the row interchanged with row j, and dlj is the scaling factor applied to row j, then:
  • lscale[j-1]=plj, for j=1,2,…,ilo-1;
  • lscale=dlj, for j=ilo,…,ihi;
  • lscale=plj, for j=ihi+1,…,n.
The order in which the interchanges are made is n to ihi+1, then 1 to ilo-1.
rscale
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: details of the permutations and scaling factors applied to the right side of A and B.
If prj is the index of the column interchanged with column j, and drj is the scaling factor applied to column j, then:
  • rscale[j-1]=prj, for j=1,2,…,ilo-1;
  • if rscale=drj, for j=ilo,…,ihi;
  • if rscale=prj, for j=ihi+1,…,n.
The order in which the interchanges are made is n to ihi+1, then 1 to ilo-1.
abnrm
Type: System..::..Double %
On exit: the 1-norm of the balanced matrix A.
bbnrm
Type: System..::..Double %
On exit: the 1-norm of the balanced matrix B.
rconde
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array rconde must be at least max 1,n.
On exit: if sense="E" or "B", the reciprocal condition numbers of the eigenvalues, stored in consecutive elements of the array. For a complex conjugate pair of eigenvalues two consecutive elements of rconde are set to the same value. Thus rconde[j-1], rcondv[j-1], and the jth columns of vl and vr all correspond to the jth eigenpair.
If sense="V", rconde is not referenced.
rcondv
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array rcondv must be at least max 1,n.
On exit: if sense="V" or "B", the estimated reciprocal condition numbers of the eigenvectors, stored in consecutive elements of the array. For a complex eigenvector two consecutive elements of rcondv are set to the same value.
If sense="E", rcondv is not referenced.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

A generalized eigenvalue for a pair of matrices A,B is a scalar λ or a ratio α/β=λ, such that A-λB is singular. It is usually represented as the pair α,β, as there is a reasonable interpretation for β=0, and even for both being zero.
The right eigenvector vj corresponding to the eigenvalue λj of A,B satisfies
A vj=λj B vj.
The left eigenvector uj corresponding to the eigenvalue λj of A,B satisfies
ujH A=λj ujH B,
where ujH is the conjugate-transpose of uj.
All the eigenvalues and, if required, all the eigenvectors of the generalized eigenproblem Ax=λBx, where A and B are real, square matrices, are determined using the QZ algorithm. The QZ algorithm consists of four stages:
1. | A is reduced to upper Hessenberg form and at the same time B is reduced to upper triangular form.
2. | A is further reduced to quasi-triangular form while the triangular form of B is maintained. This is the real generalized Schur form of the pair A,B.
3. The quasi-triangular form of A is reduced to triangular form and the eigenvalues extracted. This method does not actually produce the eigenvalues λj, but instead returns αj and βj such that
λj=αj/βj,  j=1,2,…,n.
The division by βj becomes your responsibility, since βj may be zero, indicating an infinite eigenvalue. Pairs of complex eigenvalues occur with αj/βj and α j+1/β j+1 complex conjugates, even though αj and α j+1 are not conjugate.
4. | If the eigenvectors are required they are obtained from the triangular matrices and then transformed back into the original coordinate system.
For details of the balancing option, see [Description] in f08wh.

References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Wilkinson J H (1979) Kronecker's canonical form and the QZ algorithm Linear Algebra Appl. 28 285–303

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA, LDB, LDVL, LDVR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
info=1 to n
The QZ iteration failed. No eigenvectors have been calculated, but alphar[j-1], alphai[j-1], and beta[j-1] should be correct for j=info+1,…,n.
info=n+1
Unexpected error returned from f08xe.
info=n+2
Error returned from f08yk.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

The computed eigenvalues and eigenvectors are exact for a nearby matrices A+E and B+F, where
E,F F=O ε A,B F,
and ε is the machine precision.
An approximate error bound on the chordal distance between the ith computed generalized eigenvalue w and the corresponding exact eigenvalue λ is
ε×abnrm,bbnrm 2/rconde[i-1].
An approximate error bound for the angle between the ith computed eigenvector uj or vj is given by
ε×abnrm,bbnrm 2/rcondv[i-1].
For further explanation of the reciprocal condition numbers rconde and rcondv, see Section 4.11 of Anderson et al. (1999).
Note: interpretation of results obtained with the QZ algorithm often requires a clear understanding of the effects of small changes in the original data. These effects are reviewed in Wilkinson (1979), in relation to the significance of small values of αj and βj. It should be noted that if αj and βj are both small for any j, it may be that no reliance can be placed on any of the computed eigenvalues λi=αi/βi. You are recommended to study Wilkinson (1979) and, if in difficulty, to seek expert advice on determining the sensitivity of the eigenvalues to perturbations in the data.

Parallelism and Performance

None.

Further Comments

The total number of floating-point operations is proportional to n 3.
The complex analogue of this method is f08wp.

Example

This example finds all the eigenvalues and right eigenvectors of the matrix pair A,B, where
A= 3.9 12.5 -34.5 -0.5 4.3 21.5 -47.5 7.5 4.3 21.5 -43.5 3.5 4.4 26.0 -46.0 6.0   and  B= 1.0 2.0 -3.0 1.0 1.0 3.0 -5.0 4.0 1.0 3.0 -4.0 3.0 1.0 3.0 -4.0 4.0 ,
together with estimates of the condition number and forward error bounds for each eigenvalue and eigenvector. The option to balance the matrix pair is used.

Example program (C#): f08wbe.cs

Example program data: f08wbe.d

Example program results: f08wbe.r

See Also

F08 Class
F08 Members


f08wp Method

[image]

NAG Library for .NET Release 2
F08..::f08wp Method
F08 Class See Also Send Feedback
f08wp computes for a pair of n by n complex nonsymmetric matrices A,B the generalized eigenvalues and, optionally, the left and/or right generalized eigenvectors using the QZ algorithm.
Optionally it also computes a balancing transformation to improve the conditioning of the eigenvalues and eigenvectors, reciprocal condition numbers for the eigenvalues, and reciprocal condition numbers for the right eigenvectors.

Syntax

C#
public static void f08wp(
    string balanc,
    string jobvl,
    string jobvr,
    string sense,
    int n,
    Complex[,] a,
    Complex[,] b,
    Complex[] alpha,
    Complex[] beta,
    Complex[,] vl,
    Complex[,] vr,
    out int ilo,
    out int ihi,
    double[] lscale,
    double[] rscale,
    out double abnrm,
    out double bbnrm,
    double[] rconde,
    double[] rcondv,
    out int info
)
Visual Basic
Public Shared Sub f08wp ( _
    balanc As String, _
    jobvl As String, _
    jobvr As String, _
    sense As String, _
    n As Integer, _
    a As Complex(,), _
    b As Complex(,), _
    alpha As Complex(), _
    beta As Complex(), _
    vl As Complex(,), _
    vr As Complex(,), _
    <OutAttribute> ByRef ilo As Integer, _
    <OutAttribute> ByRef ihi As Integer, _
    lscale As Double(), _
    rscale As Double(), _
    <OutAttribute> ByRef abnrm As Double, _
    <OutAttribute> ByRef bbnrm As Double, _
    rconde As Double(), _
    rcondv As Double(), _
    <OutAttribute> ByRef info As Integer _
)
Visual C++
public:
static void f08wp(
    String^ balanc,
    String^ jobvl,
    String^ jobvr,
    String^ sense,
    int n,
    array<Complex,2>^ a,
    array<Complex,2>^ b,
    array<Complex>^ alpha,
    array<Complex>^ beta,
    array<Complex,2>^ vl,
    array<Complex,2>^ vr,
    [OutAttribute] int% ilo,
    [OutAttribute] int% ihi,
    array<double>^ lscale,
    array<double>^ rscale,
    [OutAttribute] double% abnrm,
    [OutAttribute] double% bbnrm,
    array<double>^ rconde,
    array<double>^ rcondv,
    [OutAttribute] int% info
)
F#
static member f08wp :
        balanc : string *
        jobvl : string *
        jobvr : string *
        sense : string *
        n : int *
        a : Complex[,] *
        b : Complex[,] *
        alpha : Complex[] *
        beta : Complex[] *
        vl : Complex[,] *
        vr : Complex[,] *
        ilo : int byref *
        ihi : int byref *
        lscale : float[] *
        rscale : float[] *
        abnrm : float byref *
        bbnrm : float byref *
        rconde : float[] *
        rcondv : float[] *
        info : int byref -> unit

Parameters

balanc
Type: System..::..String
On entry: specifies the balance option to be performed.
balanc="N"
Do not diagonally scale or permute.
balanc="P"
Permute only.
balanc="S"
Scale only.
balanc="B"
Both permute and scale.
Computed reciprocal condition numbers will be for the matrices after permuting and/or balancing. Permuting does not change condition numbers (in exact arithmetic), but balancing does. In the absence of other information, balanc="B" is recommended.
Constraint: balanc="N", "P", "S" or "B".
jobvl
Type: System..::..String
On entry: if jobvl="N", do not compute the left generalized eigenvectors.
If jobvl="V", compute the left generalized eigenvectors.
Constraint: jobvl="N" or "V".
jobvr
Type: System..::..String
On entry: if jobvr="N", do not compute the right generalized eigenvectors.
If jobvr="V", compute the right generalized eigenvectors.
Constraint: jobvr="N" or "V".
sense
Type: System..::..String
On entry: determines which reciprocal condition numbers are computed.
sense="N"
None are computed.
sense="E"
Computed for eigenvalues only.
sense="V"
Computed for eigenvectors only.
sense="B"
Computed for eigenvalues and eigenvectors.
Constraint: sense="N", "E", "V" or "B".
n
Type: System..::..Int32
On entry: n, the order of the matrices A and B.
Constraint: n≥0.
a
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array a must be at least max 1,n.
On entry: the matrix A in the pair A,B.
On exit: a has been overwritten. If jobvl="V" or jobvr="V" or both, then A contains the first part of the Schur form of the ‘balanced’ versions of the input A and B.
b
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,n
Note: the second dimension of the array b must be at least max 1,n.
On entry: the matrix B in the pair A,B.
On exit: b has been overwritten.
alpha
Type: array< NagLibrary..::..Complex >[]()[][]
An array of size [n]
On exit: see the description of beta.
beta
Type: array< NagLibrary..::..Complex >[]()[][]
An array of size [n]
On exit: alpha[j-1]/beta[j-1], for j=1,2,…,n, will be the generalized eigenvalues.
Note: the quotients alpha[j-1]/beta[j-1] may easily overflow or underflow, and beta[j-1] may even be zero. Thus, you should avoid naively computing the ratio αj/βj. However, max αj will always be less than and usually comparable with a 2 in magnitude, and max βj will always be less than and usually comparable with b 2.
vl
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint:
  • if jobvl="V", dim1≥max 1,n;
  • otherwise dim1≥1.
Note: the second dimension of the array vl must be at least max 1,n if jobvl="V", and at least 1 otherwise.
On exit: if jobvl="V", the left generalized eigenvectors uj are stored one after another in the columns of vl, in the same order as the corresponding eigenvalues. Each eigenvector will be scaled so the largest component will have real part+imag. part=1.
If jobvl="N", vl is not referenced.
vr
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint:
  • if jobvr="V", dim1≥max 1,n;
  • otherwise dim1≥1.
Note: the second dimension of the array vr must be at least max 1,n if jobvr="V", and at least 1 otherwise.
On exit: if jobvr="V", the right generalized eigenvectors vj are stored one after another in the columns of vr, in the same order as the corresponding eigenvalues. Each eigenvector will be scaled so the largest component will have real part+imag. part=1.
If jobvr="N", vr is not referenced.
ilo
Type: System..::..Int32 %
On exit: ilo and ihi are integer values such that a[i-1,j-1]=0 and b[i-1,j-1]=0 if i>j and j=1,2,…,ilo-1 or i=ihi+1,…,n.
If balanc="N" or "S", ilo=1 and ihi=n.
ihi
Type: System..::..Int32 %
On exit: ilo and ihi are integer values such that a[i-1,j-1]=0 and b[i-1,j-1]=0 if i>j and j=1,2,…,ilo-1 or i=ihi+1,…,n.
If balanc="N" or "S", ilo=1 and ihi=n.
lscale
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: details of the permutations and scaling factors applied to the left side of A and B.
If plj is the index of the row interchanged with row j, and dlj is the scaling factor applied to row j, then:
  • lscale[j-1]=plj, for j=1,2,…,ilo-1;
  • lscale=dlj, for j=ilo,…,ihi;
  • lscale=plj, for j=ihi+1,…,n.
The order in which the interchanges are made is n to ihi+1, then 1 to ilo-1.
rscale
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: details of the permutations and scaling factors applied to the right side of A and B.
If prj is the index of the column interchanged with column j, and drj is the scaling factor applied to column j, then:
  • rscale[j-1]=prj, for j=1,2,…,ilo-1;
  • if rscale=drj, for j=ilo,…,ihi;
  • if rscale=prj, for j=ihi+1,…,n.
The order in which the interchanges are made is n to ihi+1, then 1 to ilo-1.
abnrm
Type: System..::..Double %
On exit: the 1-norm of the balanced matrix A.
bbnrm
Type: System..::..Double %
On exit: the 1-norm of the balanced matrix B.
rconde
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array rconde must be at least max 1,n.
On exit: if sense="E" or "B", the reciprocal condition numbers of the eigenvalues, stored in consecutive elements of the array.
If sense="N" or "V", rconde is not referenced.
rcondv
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array rcondv must be at least max 1,n.
On exit: if sense="V" or "B", the estimated reciprocal condition numbers of the selected eigenvectors, stored in consecutive elements of the array.
If sense="N" or "E", rcondv is not referenced.
info
Type: System..::..Int32 %
On exit: info=0 unless the method detects an error (see [Error Indicators and Warnings]).

Description

A generalized eigenvalue for a pair of matrices A,B is a scalar λ or a ratio α/β=λ, such that A-λB is singular. It is usually represented as the pair α,β, as there is a reasonable interpretation for β=0, and even for both being zero.
The right generalized eigenvector vj corresponding to the generalized eigenvalue λj of A,B satisfies
A vj=λj B vj.
The left generalized eigenvector uj corresponding to the generalized eigenvalue λj of A,B satisfies
ujH A=λj ujH B,
where ujH is the conjugate-transpose of uj.
All the eigenvalues and, if required, all the eigenvectors of the complex generalized eigenproblem Ax=λBx, where A and B are complex, square matrices, are determined using the QZ algorithm. The complex QZ algorithm consists of three stages:
1. | A is reduced to upper Hessenberg form (with real, non-negative subdiagonal elements) and at the same time B is reduced to upper triangular form.
2. A is further reduced to triangular form while the triangular form of B is maintained and the diagonal elements of B are made real and non-negative. This is the generalized Schur form of the pair A,B.
This method does not actually produce the eigenvalues λj, but instead returns αj and βj such that
λj=αj/βj,  j=1,2,…,n.
The division by βj becomes your responsibility, since βj may be zero, indicating an infinite eigenvalue.
3. | If the eigenvectors are required they are obtained from the triangular matrices and then transformed back into the original coordinate system.
For details of the balancing option, see [Description] in f08wv.

References

Anderson E, Bai Z, Bischof C, Blackford S, Demmel J, Dongarra J J, Du Croz J J, Greenbaum A, Hammarling S, McKenney A and Sorensen D (1999) LAPACK Users' Guide (3rd Edition) SIAM, Philadelphia http://www.netlib.org/lapack/lug
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Wilkinson J H (1979) Kronecker's canonical form and the QZ algorithm Linear Algebra Appl. 28 285–303

Error Indicators and Warnings

Some error messages may refer to parameters that are dropped from this interface (LDA, LDB, LDVL, LDVR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
info<0
If info=-i, argument i had an illegal value. An explanatory message is output, and execution of the program is terminated.
info=1 to n
The QZ iteration failed. No eigenvectors have been calculated, but alpha[j-1] and beta[j-1] should be correct for j=info+1,…,n.
info=n+1
Unexpected error returned from f08xs.
info=n+2
Error returned from f08yx.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
ifail=-6000
Invalid Parameters value

Accuracy

The computed eigenvalues and eigenvectors are exact for a nearby matrices A+E and B+F, where
E,F F=O ε A,B F,
and ε is the machine precision.
An approximate error bound on the chordal distance between the ith computed generalized eigenvalue w and the corresponding exact eigenvalue λ is
ε×abnrm,bbnrm 2/rconde[i-1].
An approximate error bound for the angle between the ith computed eigenvector uj or vj is given by
ε×abnrm,bbnrm 2/rcondv[i-1].
For further explanation of the reciprocal condition numbers rconde and rcondv, see Section 4.11 of Anderson et al. (1999).
Note: interpretation of results obtained with the QZ algorithm often requires a clear understanding of the effects of small changes in the original data. These effects are reviewed in Wilkinson (1979), in relation to the significance of small values of αj and βj. It should be noted that if αj and βj are both small for any j, it may be that no reliance can be placed on any of the computed eigenvalues λi=αi/βi. You are recommended to study Wilkinson (1979) and, if in difficulty, to seek expert advice on determining the sensitivity of the eigenvalues to perturbations in the data.

Parallelism and Performance

None.

Further Comments

The total number of floating-point operations is proportional to n 3.
The real analogue of this method is f08wb.

Example

This example finds all the eigenvalues and right eigenvectors of the matrix pair A,B, where
A= -21.10-22.50 i 53.50-50.50 i -34.50+127.50 i 7.50+0 0.50 i -0.46-0 7.78 i -3.50-37.50 i -15.50+0 58.50 i -10.50-0 1.50 i 4.30-0 5.50 i 39.70-17.10 i -68.50+0 12.50 i -7.50-0 3.50 i 5.50+0 4.40 i 14.40+43.30 i -32.50-0 46.00 i -19.00-32.50 i
and
B= 1.00-5.00 i 1.60+1.20 i -3.00+0.00 i 0.00-1.00 i 0.80-0.60 i 3.00-5.00 i -4.00+3.00 i -2.40-3.20 i 1.00+0.00 i 2.40+1.80 i -4.00-5.00 i 0.00-3.00 i 0.00+1.00 i -1.80+2.40 i 0.00-4.00 i 4.00-5.00 i ,
together with estimates of the condition number and forward error bounds for each eigenvalue and eigenvector. The option to balance the matrix pair is used.

Example program (C#): f08wpe.cs

Example program data: f08wpe.d

Example program results: f08wpe.r

See Also

F08 Class
F08 Members


G01 Class

[image]

NAG Library for .NET Release 2
G01 Class
Members See Also Send Feedback
This chapter covers three topics:
  • plots, descriptive statistics, and exploratory data analysis;
  • statistical distribution functions and their inverses;
  • testing for Normality and other distributions.

Syntax

C#
public static class G01
Visual Basic
Public NotInheritable Class G01
Visual C++
public ref class G01 abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type G01 =  class end

Background to the Problems

Plots, Descriptive Statistics and Exploratory Data Analysis

Plots and simple descriptive statistics are generally used for one of two purposes:
  • the presentation of data;
  • exploratory data analysis.
Exploratory data analysis (EDA) is used to pick out the important features of the data in order to guide the choice of appropriate models. EDA makes use of simple displays and summary statistics. These may suggest models or transformations of the data which can then be confirmed by further plots. The process is interactive between you, the data, and the program producing the EDA displays.
The summary statistics consist of two groups. The first group are those based on moments; for example mean, standard deviation, coefficient of skewness, and coefficient of kurtosis (sometimes called the ‘excess of kurtosis’, which has the value 0 for the Normal distribution). These statistics may be sensitive to extreme observations and some robust versions are available in G07 class. The second group of summary statistics are based on the order statistics, where the ith order statistic in a sample is the ith smallest observation in that sample. Examples of such statistics are minimum, maximum, median, hinges and quantiles.
In addition to summarising the data by using suitable statistics the data can be displayed using tables and diagrams. Such data displays include frequency tables, stem and leaf displays, box and whisker plots, histograms and scatter plots.

Statistical Distribution Functions and Their Inverses

Statistical distributions are commonly used in three problems:
  • evaluation of probabilities and expected frequencies for a distribution model;
  • testing of hypotheses about the variables being observed;
  • evaluation of confidence limits for parameters of fitted model, for example the mean of a Normal distribution.
Random variables can be either discrete (i.e., they can take only a limited number of values) or continuous (i.e., can take any value in a given range). However, for a large sample from a discrete distribution an approximation by a continuous distribution, usually the Normal distribution, can be used. Distributions commonly used as a model for discrete random variables are the binomial, hypergeometric, and Poisson distributions. The binomial distribution arises when there is a fixed probability of a selected outcome as in sampling with replacement, the hypergeometric distribution is used in sampling from a finite population without replacement, and the Poisson distribution is often used to model counts.
Distributions commonly used as a model for continuous random variables are the Normal, gamma, and beta distributions. The Normal is a symmetric distribution whereas the gamma is skewed and only appropriate for non-negative values. The beta is for variables in the range 0,1 and may take many different shapes. For circular data, the ‘equivalent’ to the Normal distribution is the von Mises distribution. The assumption of the Normal distribution leads to procedures for testing and interval estimation based on the χ 2, F (variance ratio), and Student's t-distributions.
In the hypothesis testing situation, a statistic X with known distribution under the null hypothesis is evaluated, and the probability α of observing such a value or one more ‘extreme’ value is found. This probability (the significance) is usually then compared with a preassigned value (the significance level of the test), to decide whether the null hypothesis can be rejected in favour of an alternate hypothesis on the basis of the sample values. Many tests make use of those distributions derived from the Normal distribution as listed above, but for some tests specific distributions such as the Studentized range distribution and the distribution of the Durbin–Watson test have been derived. Nonparametric tests as given in (G08 not in this release), such as the Kolmogorov–Smirnov test, often use statistics with distributions specific to the test. The probability that the null hypothesis will be rejected when the simple alternate hypothesis is true (the power of the test) can be found from the noncentral distribution.
The confidence interval problem requires the inverse calculation. In other words, given a probability α, the value x is to be found, such that the probability that a value not exceeding x is observed is equal to α. A confidence interval of size 1-2 α, for the quantity of interest, can then be computed as a function of x and the sample values.
The required statistics for either testing hypotheses or constructing confidence intervals can be computed with the aid of methods in this chapter, and G02 class (for regression), (G04 not in this release) (for analysis of designed experiments), G13 class (for time eries), and E04 class (for nonlinear least squares problems).
Pseudorandom numbers from many statistical distributions can be generated by methods in G05 class.

Testing for Normality and Other Distributions

Methods of checking that observations (or residuals from a model) come from a specified distribution, for example, the Normal distribution, are often based on order statistics. Graphical methods include the use of probability plots. These can be either P-P plots (probability–probability plots), in which the empirical probabilities are plotted against the theoretical probabilities for the distribution, or Q-Q plots (quantile–quantile plots), in which the sample points are plotted against the theoretical quantiles. Q-Q plots are more common, partly because they are invariant to differences in scale and location. In either case if the observations come from the specified distribution then the plotted points should roughly lie on a straight line.
If yi is the ith smallest observation from a sample of size n (i.e., the ith order statistic) then in a Q-Q plot for a distribution with cumulative distribution function F, the value yi is plotted against xi, where F xi=i-α/n-2 α+1, a common value of α being 12. For the Normal distribution, the Q-Q plot is known as a Normal probability plot.
The values xi used in Q-Q plots can be regarded as approximations to the expected values of the order statistics. For a sample from a Normal distribution the expected values of the order statistics are known as Normal scores and for an exponential distribution they are known as Savage scores.
An alternative approach to probability plots are the more formal tests. A test for Normality is the Shapiro and Wilk's W Test, which uses Normal scores. Other tests are the χ 2 goodness-of-fit test and the Kolmogorov–Smirnov test; both can be found in (G08 not in this release).

Distribution of Quadratic Forms

Many test statistics for Normally distributed data lead to quadratic forms in Normal variables. If X is a n-dimensional Normal variable with mean μ and variance-covariance matrix Σ then for an n by n matrix A the quadratic form is
Q=XT AX.
The distribution of Q depends on the relationship between A and Σ: if AΣ is idempotent then the distribution of Q will be central or noncentral χ 2 depending on whether μ is zero.
The distribution of other statistics may be derived as the distribution of linear combinations of quadratic forms, for example the Durbin–Watson test statistic, or as ratios of quadratic forms. In some cases rather than the distribution of these functions of quadratic forms the values of the moments may be all that is required.

Energy Loss Distributions

An application of distributions in the field of high-energy physics where there is a requirement to model fluctuations in energy loss experienced by a particle passing through a layer of material. Three models are commonly used:
(i) | Gaussian (Normal) distribution;
(ii) | the Landau distribution;
(iii) | the Vavilov distribution.
Both the Landau and the Vavilov density functions can be defined in terms of a complex integral. The Vavilov distribution is the more general energy loss distribution with the Landau and Gaussian being suitable when the Vavilov parameter κ is less than 0.01 and greater than 10.0 respectively.

Vectorized Methods

A number of vectorized methods are included in this chapter. Unlike their scalar counterparts, which take a single set of parameters and perform a single function evaluation, these methods take vectors of parameters and perform multiple function evaluations in a single call. The input arrays to these vectorized methods are designed to allow maximum flexibility in the supply of the parameters by reusing, in a cyclic manner, elements of any arrays that are shorter than the number of functions to be evaluated, where the total number of functions evaluated is the size of the largest array.
To illustrate this we will consider (G01SFF not in this release), a vectorized version of g01ef, which calculates the probabilities for a gamma distribution. The gamma distribution has two parameters α and β therefore (G01SFF not in this release) has four input arrays, one indicating the tail required (tail), one giving the value of the gamma variate, g, whose probability is required (g), one for α (a) and one for β (b). The lengths of these arrays are ltail, lg, la and lb respectively.
For sake of argument, lets assume that ltail=1, lg=2, la=3 and lb=4, then max ltail,lg,la,lb=4 values will be returned. These four probabilities would be calculated using the following parameters:
i | Tail | g | α | β
1 | tail[0] | g[0] | a[0] | b[0]
2 | tail[0] | g[1] | a[1] | b[1]
3 | tail[0] | g[0] | a[2] | b[2]
4 | tail[0] | g[1] | a[0] | b[3]

Recommendations on Choice and Use of Available Methods

Descriptive statistics / Exploratory analysis,
summaries,
frequency / contingency table,
one variable g01ae
two variables, with χ 2 and Fisher's exact test g01af
mean, variance, skewness, kurtosis (one variable),
from frequency table g01ad
from raw data g01aa
median, hinges / quartiles, minimum, maximum g01al
quantiles,
unordered vector g01am
Distributions,
Beta,
central,
deviates,
scalar g01fe
probabilities and probability density function,
scalar g01ee
non-central,
probabilities g01ge
binomial,
distribution function,
scalar g01bj
Durbin–Watson statistic,
probabilities g01ep
energy loss distributions,
Landau,
density g01mt
derivative of density g01rt
distribution g01et
first moment g01pt
inverse distribution g01ft
second moment g01qt
Vavilov,
density g01mu
distribution g01eu
initialization g01zu
F:
central,
deviates,
scalar g01fd
probabilities,
scalar g01ed
non-central,
probabilities g01gd
gamma,
deviates,
scalar g01ff
probabilities,
scalar g01ef
Hypergeometric,
distribution function,
scalar g01bl
Kolomogorov–Smirnov,
probabilities,
one-sample g01ey
two-sample g01ez
Normal,
bivariate,
probabilities g01ha
multivariate,
probabilities g01hb
quadratic forms,
cumulants and moments g01na
moments of ratios g01nb
univariate,
deviates,
scalar g01fa
probabilities,
scalar g01ea
reciprocal of Mill's Ratio g01mb
Shapiro and Wilk's test for Normality g01dd
Poisson,
distribution function,
scalar g01bk
Student's t:
central,
univariate,
deviates,
scalar g01fb
probabilities,
scalar g01eb
non-central,
probabilities g01gb
Studentized range statistic,
deviates g01fm
probabilities g01em
von Mises,
probabilities g01er
χ 2:
central,
deviates g01fc
probabilities g01ec
probability of linear combination g01jd
non-central,
probabilities g01gc
probability of linear combination g01jc
Scores,
Normal scores,
accurate g01da
approximate g01db
variance-covariance matrix g01dc
Normal scores, ranks or exponential (Savage) scores g01dh
Note: the Student's t, χ 2, and F methods do not aim to achieve a high degree of accuracy, only about four or five significant figures, but this should be quite sufficient for hypothesis testing. However, both the Student's t and the F-distributions can be transformed to a beta distribution and the χ 2-distribution can be transformed to a gamma distribution, so a higher accuracy can be obtained by calls to the gamma or beta methods.
Note: g01dh computes either ranks, approximations to the Normal scores, Normal, or Savage scores for a given sample. g01dh also gives you control over how it handles tied observations. g01da computes the Normal scores for a given sample size to a requested accuracy; the scores are returned in ascending order. g01da can be used if either high accuracy is required or if Normal scores are required for many samples of the same size, in which case you will have to sort the data or scores.

Working with Streamed or Extremely Large Datasets

The majority of the methods in this chapter are ‘in-core’, that is all the data required must be held in memory prior to calling the method. In some situations this might not be possible, for example, when working with extremely large datasets or where all of the data is not available at once (i.e., the data is being streamed).
There are five methods in this chapter applicable to datasets of this form:
(G01ATF not in this release) computes the mean, variance and the coefficients of skewness and kurtosis for a single variable.
(G01AUF not in this release), takes the results from two calls to (G01ATF not in this release) and combines them, returning the mean, variance and the coefficients of skewness and kurtosis for the combined dataset. This method allows the easy utilization of more than one processor to spread the computational burden inherent in summarising a very large dataset.
(G01ANF not in this release) (G01APF not in this release) compute the approximate quantiles for a dataset of known and unknown size respectively.
(G01WAF not in this release) computes the mean and standard deviation in a rolling window.
In addition, see g02bu (G02BZF not in this release) for methods to summarise two or more variables.

References

Hastings N A J and Peacock J B (1975) Statistical Distributions Butterworth
Kendall M G and Stuart A (1969) The Advanced Theory of Statistics (Volume 1) (3rd Edition) Griffin
Tukey J W (1977) Exploratory Data Analysis Addison–Wesley

Inheritance Hierarchy

System..::..Object
NagLibrary..::..G01

See Also

G01 Members


G01 Members

[image] [image]

NAG Library for .NET Release 2
G01 Members
G01 Class Methods See Also Send Feedback

The G01 type exposes the following members.

Methods

Name | Description
g01aa | g01aa calculates the mean, standard deviation, coefficients of skewness and kurtosis, and the maximum and minimum values for a set of ungrouped data. Weighting may be used.
g01ad | g01ad calculates the mean, standard deviation and coefficients of skewness and kurtosis for data grouped in a frequency distribution.
g01ae | g01ae constructs a frequency distribution of a variable, according to either user-supplied, or method-calculated class boundary values.
g01af | g01af performs the analysis of a two-way r×c contingency table or classification. If r=c=2, and the total number of objects classified is 40 or fewer, then the probabilities for Fisher's exact test are computed. Otherwise, a test statistic is computed (with Yates' correction when r=c=2), which under the assumption of no association between the classifications has approximately a chi-square distribution with r-1×c-1 degrees of freedom.
g01al | g01al calculates a five-point summary for a single sample.
g01am | g01am finds specified quantiles from a vector of unsorted data.
g01bj | g01bj returns the lower tail, upper tail and point probabilities associated with a binomial distribution.
g01bk | g01bk returns the lower tail, upper tail and point probabilities associated with a Poisson distribution.
g01bl | g01bl returns the lower tail, upper tail and point probabilities associated with a hypergeometric distribution.
g01da | g01da computes a set of Normal scores, i.e., the expected values of an ordered set of independent observations from a Normal distribution with mean 0.0 and standard deviation 1.0.
g01db | g01db calculates an approximation to the set of Normal Scores, i.e., the expected values of an ordered set of independent observations from a Normal distribution with mean 0.0 and standard deviation 1.0.
g01dc | g01dc computes an approximation to the variance-covariance matrix of an ordered set of independent observations from a Normal distribution with mean 0.0 and standard deviation 1.0.
g01dd | g01dd calculates Shapiro and Wilk's W statistic and its significance level for testing Normality.
g01dh | g01dh computes the ranks, Normal scores, an approximation to the Normal scores or the exponential scores as requested by you.
g01ea | g01ea returns a one or two tail probability for the standard Normal distribution.
g01eb | g01eb returns the lower tail, upper tail or two tail probability for the Student's t-distribution with real degrees of freedom.
g01ec | g01ec returns the lower or upper tail probability for the χ 2-distribution with real degrees of freedom.
g01ed | g01ed returns the probability for the lower or upper tail of the F or variance-ratio distribution with real degrees of freedom.
g01ee | g01ee computes the upper and lower tail probabilities and the probability density function of the beta distribution with parameters a and b.
g01ef | g01ef returns the lower or upper tail probability of the gamma distribution, with parameters α and β.
g01em | g01em returns the probability associated with the lower tail of the distribution of the Studentized range statistic.
g01ep | g01ep calculates upper and lower bounds for the significance of a Durbin–Watson statistic.
g01er | g01er returns the probability associated with the lower tail of the von Mises distribution between -π and π through the function name.
g01et | g01et returns the value of the Landau distribution function Φ λ.
g01eu | g01eu returns the value of the Vavilov distribution function ΦV λ;κ,β 2. It is intended to be used after a call to g01zu.
g01ey | g01ey returns the upper tail probability associated with the one sample Kolmogorov–Smirnov distribution.
g01ez | g01ez returns the probability associated with the upper tail of the Kolmogorov–Smirnov two sample distribution.
g01fa | g01fa returns the deviate associated with the given probability of the standard Normal distribution.
g01fb | g01fb returns the deviate associated with the given tail probability of Student's t-distribution with real degrees of freedom.
g01fc | g01fc returns the deviate associated with the given lower tail probability of the χ 2-distribution with real degrees of freedom.
g01fd | g01fd returns the deviate associated with the given lower tail probability of the F or variance-ratio distribution with real degrees of freedom.
g01fe | g01fe returns the deviate associated with the given lower tail probability of the beta distribution.
g01ff | g01ff returns the deviate associated with the given lower tail probability of the gamma distribution.
g01fm | g01fm returns the deviate associated with the lower tail probability of the distribution of the Studentized range statistic.
g01ft | g01ft returns the value of the inverse Φ-1 x of the Landau distribution function.
g01gb | g01gb returns the lower tail probability for the noncentral Student's t-distribution.
g01gc | g01gc returns the probability associated with the lower tail of the noncentral χ 2-distribution .
g01gd | g01gd returns the probability associated with the lower tail of the noncentral F or variance-ratio distribution.
g01ge | g01ge returns the probability associated with the lower tail of the noncentral beta distribution.
g01ha | g01ha returns the lower tail probability for the bivariate Normal distribution.
g01hb | g01hb returns the upper tail, lower tail or central probability associated with a multivariate Normal distribution of up to ten dimensions.
g01jc | g01jc returns the lower tail probability of a distribution of a positive linear combination of χ 2 random variables.
g01jd | g01jd calculates the lower tail probability for a linear combination of (central) χ 2 variables.
g01mb | g01mb returns the reciprocal of Mills' Ratio.
g01mt | g01mt returns the value of the Landau density function ϕ λ.
g01mu | g01mu returns the value of the Vavilov density function ϕV λ;κ,β 2. It is intended to be used after a call to g01zu.
g01na | g01na computes the cumulants and moments of quadratic forms in Normal variates.
g01nb | g01nb computes the moments of ratios of quadratic forms in Normal variables and related statistics.
g01pt | g01pt returns the value of the first moment Φ 1 x of the Landau density function.
g01qt | g01qt returns the value of the second moment Φ 2 x of the Landau density function.
g01rt | g01rt returns the value of the derivative ϕ′λ of the Landau density function.
g01zu | g01zu is used to initialize methods g01eu and g01mu. It is intended to be used before a call to g01eu or g01mu.

See Also

G01 Class


G01 Methods

[image] [image]

NAG Library for .NET Release 2
G01 Methods
G01 Class See Also Send Feedback

The G01 type exposes the following members.

Methods

Name | Description
g01aa | g01aa calculates the mean, standard deviation, coefficients of skewness and kurtosis, and the maximum and minimum values for a set of ungrouped data. Weighting may be used.
g01ad | g01ad calculates the mean, standard deviation and coefficients of skewness and kurtosis for data grouped in a frequency distribution.
g01ae | g01ae constructs a frequency distribution of a variable, according to either user-supplied, or method-calculated class boundary values.
g01af | g01af performs the analysis of a two-way r×c contingency table or classification. If r=c=2, and the total number of objects classified is 40 or fewer, then the probabilities for Fisher's exact test are computed. Otherwise, a test statistic is computed (with Yates' correction when r=c=2), which under the assumption of no association between the classifications has approximately a chi-square distribution with r-1×c-1 degrees of freedom.
g01al | g01al calculates a five-point summary for a single sample.
g01am | g01am finds specified quantiles from a vector of unsorted data.
g01bj | g01bj returns the lower tail, upper tail and point probabilities associated with a binomial distribution.
g01bk | g01bk returns the lower tail, upper tail and point probabilities associated with a Poisson distribution.
g01bl | g01bl returns the lower tail, upper tail and point probabilities associated with a hypergeometric distribution.
g01da | g01da computes a set of Normal scores, i.e., the expected values of an ordered set of independent observations from a Normal distribution with mean 0.0 and standard deviation 1.0.
g01db | g01db calculates an approximation to the set of Normal Scores, i.e., the expected values of an ordered set of independent observations from a Normal distribution with mean 0.0 and standard deviation 1.0.
g01dc | g01dc computes an approximation to the variance-covariance matrix of an ordered set of independent observations from a Normal distribution with mean 0.0 and standard deviation 1.0.
g01dd | g01dd calculates Shapiro and Wilk's W statistic and its significance level for testing Normality.
g01dh | g01dh computes the ranks, Normal scores, an approximation to the Normal scores or the exponential scores as requested by you.
g01ea | g01ea returns a one or two tail probability for the standard Normal distribution.
g01eb | g01eb returns the lower tail, upper tail or two tail probability for the Student's t-distribution with real degrees of freedom.
g01ec | g01ec returns the lower or upper tail probability for the χ 2-distribution with real degrees of freedom.
g01ed | g01ed returns the probability for the lower or upper tail of the F or variance-ratio distribution with real degrees of freedom.
g01ee | g01ee computes the upper and lower tail probabilities and the probability density function of the beta distribution with parameters a and b.
g01ef | g01ef returns the lower or upper tail probability of the gamma distribution, with parameters α and β.
g01em | g01em returns the probability associated with the lower tail of the distribution of the Studentized range statistic.
g01ep | g01ep calculates upper and lower bounds for the significance of a Durbin–Watson statistic.
g01er | g01er returns the probability associated with the lower tail of the von Mises distribution between -π and π through the function name.
g01et | g01et returns the value of the Landau distribution function Φ λ.
g01eu | g01eu returns the value of the Vavilov distribution function ΦV λ;κ,β 2. It is intended to be used after a call to g01zu.
g01ey | g01ey returns the upper tail probability associated with the one sample Kolmogorov–Smirnov distribution.
g01ez | g01ez returns the probability associated with the upper tail of the Kolmogorov–Smirnov two sample distribution.
g01fa | g01fa returns the deviate associated with the given probability of the standard Normal distribution.
g01fb | g01fb returns the deviate associated with the given tail probability of Student's t-distribution with real degrees of freedom.
g01fc | g01fc returns the deviate associated with the given lower tail probability of the χ 2-distribution with real degrees of freedom.
g01fd | g01fd returns the deviate associated with the given lower tail probability of the F or variance-ratio distribution with real degrees of freedom.
g01fe | g01fe returns the deviate associated with the given lower tail probability of the beta distribution.
g01ff | g01ff returns the deviate associated with the given lower tail probability of the gamma distribution.
g01fm | g01fm returns the deviate associated with the lower tail probability of the distribution of the Studentized range statistic.
g01ft | g01ft returns the value of the inverse Φ-1 x of the Landau distribution function.
g01gb | g01gb returns the lower tail probability for the noncentral Student's t-distribution.
g01gc | g01gc returns the probability associated with the lower tail of the noncentral χ 2-distribution .
g01gd | g01gd returns the probability associated with the lower tail of the noncentral F or variance-ratio distribution.
g01ge | g01ge returns the probability associated with the lower tail of the noncentral beta distribution.
g01ha | g01ha returns the lower tail probability for the bivariate Normal distribution.
g01hb | g01hb returns the upper tail, lower tail or central probability associated with a multivariate Normal distribution of up to ten dimensions.
g01jc | g01jc returns the lower tail probability of a distribution of a positive linear combination of χ 2 random variables.
g01jd | g01jd calculates the lower tail probability for a linear combination of (central) χ 2 variables.
g01mb | g01mb returns the reciprocal of Mills' Ratio.
g01mt | g01mt returns the value of the Landau density function ϕ λ.
g01mu | g01mu returns the value of the Vavilov density function ϕV λ;κ,β 2. It is intended to be used after a call to g01zu.
g01na | g01na computes the cumulants and moments of quadratic forms in Normal variates.
g01nb | g01nb computes the moments of ratios of quadratic forms in Normal variables and related statistics.
g01pt | g01pt returns the value of the first moment Φ 1 x of the Landau density function.
g01qt | g01qt returns the value of the second moment Φ 2 x of the Landau density function.
g01rt | g01rt returns the value of the derivative ϕ′λ of the Landau density function.
g01zu | g01zu is used to initialize methods g01eu and g01mu. It is intended to be used before a call to g01eu or g01mu.

See Also

G01 Class


g01aa Method

[image]

NAG Library for .NET Release 2
G01..::g01aa Method
G01 Class See Also Send Feedback
g01aa calculates the mean, standard deviation, coefficients of skewness and kurtosis, and the maximum and minimum values for a set of ungrouped data. Weighting may be used.

Syntax

C#
public static void g01aa(
    int n,
    double[] x,
    ref int iwt,
    double[] wt,
    out double xmean,
    out double s2,
    out double s3,
    out double s4,
    out double xmin,
    out double xmax,
    out double wtsum,
    out int ifail
)
Visual Basic
Public Shared Sub g01aa ( _
    n As Integer, _
    x As Double(), _
    ByRef iwt As Integer, _
    wt As Double(), _
    <OutAttribute> ByRef xmean As Double, _
    <OutAttribute> ByRef s2 As Double, _
    <OutAttribute> ByRef s3 As Double, _
    <OutAttribute> ByRef s4 As Double, _
    <OutAttribute> ByRef xmin As Double, _
    <OutAttribute> ByRef xmax As Double, _
    <OutAttribute> ByRef wtsum As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g01aa(
    int n,
    array<double>^ x,
    int% iwt,
    array<double>^ wt,
    [OutAttribute] double% xmean,
    [OutAttribute] double% s2,
    [OutAttribute] double% s3,
    [OutAttribute] double% s4,
    [OutAttribute] double% xmin,
    [OutAttribute] double% xmax,
    [OutAttribute] double% wtsum,
    [OutAttribute] int% ifail
)
F#
static member g01aa :
        n : int *
        x : float[] *
        iwt : int byref *
        wt : float[] *
        xmean : float byref *
        s2 : float byref *
        s3 : float byref *
        s4 : float byref *
        xmin : float byref *
        xmax : float byref *
        wtsum : float byref *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n≥1.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the sample observations, xi, for i=1,2,…,n.
iwt
Type: System..::..Int32 %
On entry: indicates whether weights are to be supplied by you or not. In the latter case, the weights will be assumed equal and assigned the value 1.0 in the method.
iwt=0
Indicates no user-supplied weights.
iwt=1
Indicates user-supplied weights are required, and they will be supplied in the array wt.
On exit: iwt is used to indicate the number of valid observations, m; see (g) in [Description] above.
wt
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: if iwt=1, the elements of wt must contain the weights associated with the observations, wi, for i=1,2,…,n.
If iwt=0, the elements of wt need not be set.
On exit: if iwt=1, the elements of wt are unchanged.
If iwt=0, each element of wt will be assigned the value 1.0.
xmean
Type: System..::..Double %
On exit: the mean, x-.
s2
Type: System..::..Double %
On exit: the standard deviation, s 2.
s3
Type: System..::..Double %
On exit: the coefficient of skewness, s 3.
s4
Type: System..::..Double %
On exit: the coefficient of kurtosis, s 4.
xmin
Type: System..::..Double %
On exit: the smallest value in the sample.
xmax
Type: System..::..Double %
On exit: the largest value in the sample.
wtsum
Type: System..::..Double %
On exit: the sum of the weights in the array wt, that is ∑i=1 n wi. This will be n if iwt was 0 on entry.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The data consist of a single sample of n observations, denoted by xi, with corresponding weights, wi, for i=1,2,…,n.
If no specific weighting is required, then each wi is set to 1.
The quantities computed are:
(a) The sum of the weights
W=∑i=1 n wi.
(b) Mean
x-=∑i=1 n wixi W.
(c) Standard deviation
s 2=∑i=1 n wi xi-x-2 d,   where  d=W-∑i=1 n wi 2 W.
(d) Coefficient of skewness
s 3=∑i=1 n wi xi-x-3d×s 23.
(e) Coefficient of kurtosis
s 4=∑i=1 n wi xi-x-4d×s 24-3.
(f) | Maximum and minimum elements of the sample.
(g) | The number of observations for which wi>0, i.e., the number of valid observations. Suppose m observations are valid, then the quantities in (c), (d) and (e) will be computed if m≥2, and will be based on m-1 degrees of freedom. The other quantities are evaluated provided m≥1.

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<1.
ifail=2
The number of valid cases, m, is 1. In this case, standard deviation and coefficients of skewness and of kurtosis cannot be calculated.
ifail=3
Either the number of valid cases is 0, or at least one weight is negative.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The method used is believed to be stable.

Parallelism and Performance

None.

Further Comments

The time taken by g01aa is approximately proportional to n.

Example

This example summarises an (optionally weighted) dataset and displays the results.

Example program (C#): g01aae.cs

Example program data: g01aae.d

Example program results: g01aae.r

See Also

G01 Class
G01 Members


g01ad Method

[image]

NAG Library for .NET Release 2
G01..::g01ad Method
G01 Class See Also Send Feedback
g01ad calculates the mean, standard deviation and coefficients of skewness and kurtosis for data grouped in a frequency distribution.

Syntax

C#
public static void g01ad(
    int k,
    double[] x,
    int[] ifreq,
    out double xmean,
    out double s2,
    out double s3,
    out double s4,
    out int n,
    out int ifail
)
Visual Basic
Public Shared Sub g01ad ( _
    k As Integer, _
    x As Double(), _
    ifreq As Integer(), _
    <OutAttribute> ByRef xmean As Double, _
    <OutAttribute> ByRef s2 As Double, _
    <OutAttribute> ByRef s3 As Double, _
    <OutAttribute> ByRef s4 As Double, _
    <OutAttribute> ByRef n As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g01ad(
    int k,
    array<double>^ x,
    array<int>^ ifreq,
    [OutAttribute] double% xmean,
    [OutAttribute] double% s2,
    [OutAttribute] double% s3,
    [OutAttribute] double% s4,
    [OutAttribute] int% n,
    [OutAttribute] int% ifail
)
F#
static member g01ad :
        k : int *
        x : float[] *
        ifreq : int[] *
        xmean : float byref *
        s2 : float byref *
        s3 : float byref *
        s4 : float byref *
        n : int byref *
        ifail : int byref -> unit

Parameters

k
Type: System..::..Int32
On entry: k, the number of class boundaries, which is one more than the number of classes of the frequency distribution.
Constraint: k>1.
x
Type: array< System..::..Double >[]()[][]
An array of size [k]
On entry: the elements of x must contain the boundary values of the classes in ascending order, so that class i is bounded by the values in x[i-1] and x[i], for i=1,2,…,k-1.
Constraint: x[i]<x[i+1], for i=0,1,…,k-2.
ifreq
Type: array< System..::..Int32 >[]()[][]
An array of size [k]
On entry: the ith element of ifreq must contain the frequency associated with the ith class, for i=1,2,…,k-1. ifreq[k-1] is not used by the method.
Constraints:
  • ifreq[i-1]≥0, for i=1,2,…,k-1;
  • ∑i=1k-1 ifreq[i-1]>0.
xmean
Type: System..::..Double %
On exit: the mean value, y-.
s2
Type: System..::..Double %
On exit: the standard deviation, s 2.
s3
Type: System..::..Double %
On exit: the coefficient of skewness, s 3.
s4
Type: System..::..Double %
On exit: the coefficient of kurtosis, s 4.
n
Type: System..::..Int32 %
On exit: the total frequency, n.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The input data consist of a univariate frequency distribution, denoted by fi, for i=1,2,…,k-1, and the boundary values of the classes xi, for i=1,2,…,k. Thus the frequency associated with the interval xi,x i+1 is fi, and g01ad assumes that all the values in this interval are concentrated at the point
yi=x i+1+xi/2,  i=1,2,…,k-1.
The following quantities are calculated:
(a) total frequency,
n=∑i=1k-1 fi.
(b) mean,
y-=∑i=1k-1 fiyi n.
(c) standard deviation,
s 2=∑i=1k-1 fi yi-y-2 n-1,  n≥2.
(d) coefficient of skewness,
s 3=∑i=1k-1 fi yi-y-3n-1×s 23,  n≥2.
(e) coefficient of kurtosis,
s 4=∑i=1k-1 fi yi-y-4n-1×s 24-3,  n≥2.
The method has been developed primarily for groupings of a continuous variable. If, however, the method is to be used on the frequency distribution of a discrete variable, taking the values y 1,…,y k-1, then the boundary values for the classes may be defined as follows:
(i) for k>2,
x 1=3 y 1-y 2/2xj=y j-1+yj/2,j=2,…,k-1xk=3 y k-1-y k-2/2
(ii) for k=2,
x 1=y 1-a  and  x 2=y 1+a  for any ​a>0.

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, k≤1.
ifail=2
On entry, the boundary values of the classes in x are not in ascending order.
ifail=3
On entry, ∑i=1k-1 ifreq[i-1]=0 or ifreq[i-1]<0 for some i, for i=1,2,…,k-1.
ifail=4
The total frequency, n, is less than 2, hence the quantities s 2, s 3 and s 4 cannot be calculated.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The method used is believed to be stable.

Parallelism and Performance

None.

Further Comments

The time taken by g01ad increases linearly with k.

Example

In the example program, NPROB determines the number of sets of data to be analysed. For each analysis, the boundary values of the classes and the frequencies are read. After g01ad has been successfully called, the input data and calculated quantities are printed. In the example, there is one set of data, with 14 classes.

Example program (C#): g01ade.cs

Example program data: g01ade.d

Example program results: g01ade.r

See Also

G01 Class
G01 Members


g01ae Method

[image]

NAG Library for .NET Release 2
G01..::g01ae Method
G01 Class See Also Send Feedback
g01ae constructs a frequency distribution of a variable, according to either user-supplied, or method-calculated class boundary values.

Syntax

C#
public static void g01ae(
    int n,
    int k,
    double[] x,
    int iclass,
    double[] cb,
    int[] ifreq,
    out double xmin,
    out double xmax,
    out int ifail
)
Visual Basic
Public Shared Sub g01ae ( _
    n As Integer, _
    k As Integer, _
    x As Double(), _
    iclass As Integer, _
    cb As Double(), _
    ifreq As Integer(), _
    <OutAttribute> ByRef xmin As Double, _
    <OutAttribute> ByRef xmax As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g01ae(
    int n,
    int k,
    array<double>^ x,
    int iclass,
    array<double>^ cb,
    array<int>^ ifreq,
    [OutAttribute] double% xmin,
    [OutAttribute] double% xmax,
    [OutAttribute] int% ifail
)
F#
static member g01ae :
        n : int *
        k : int *
        x : float[] *
        iclass : int *
        cb : float[] *
        ifreq : int[] *
        xmin : float byref *
        xmax : float byref *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n≥1.
k
Type: System..::..Int32
On entry: k, the number of classes desired in the frequency distribution. Whether or not class boundary values are user-supplied, k must include the two extreme classes which stretch to ±∞.
Constraint: k≥2.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the sample of observations of the variable for which the frequency distribution is required, xi, for i=1,2,…,n. The values may be in any order.
iclass
Type: System..::..Int32
On entry: indicates whether class boundary values are to be calculated within g01ae, or are supplied by you.
If iclass=0, then the class boundary values are to be calculated within the method.
If iclass=1, they are user-supplied.
Constraint: iclass=0 or 1.
cb
Type: array< System..::..Double >[]()[][]
An array of size [k]
On entry: if iclass=0, then the elements of cb need not be assigned values, as g01ae calculates k-1 class boundary values.
If iclass=1, the first k-1 elements of cb must contain the class boundary values you supplied, in ascending order.
In both cases, the element cb[k-1] need not be assigned, as it is not used in the method.
On exit: the first k-1 elements of cb contain the class boundary values in ascending order.
Constraint: if iclass=1, cb[i-1]<cb[i], for i=1,2,…,k-2.
ifreq
Type: array< System..::..Int32 >[]()[][]
An array of size [k]
On exit: the elements of ifreq contain the frequencies in each class, fi, for i=1,2,…,k. In particular ifreq[0] contains the frequency of the class up to cb[0], f 1, and ifreq[k-1] contains the frequency of the class greater than cb[k-2], fk.
xmin
Type: System..::..Double %
On exit: the smallest value in the sample, a.
xmax
Type: System..::..Double %
On exit: the largest value in the sample, b.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The data consists of a sample of n observations of a continuous variable, denoted by xi, for i=1,2,…,n. Let a=min x 1,…,xn and b=max x 1,…,xn.
g01ae constructs a frequency distribution with k>1 classes denoted by fi, for i=1,2,…,k.
The boundary values may be either user-supplied, or method-calculated, and are denoted by yj, for j=1,2,…,k-1.
If the boundary values of the classes are to be method-calculated, then they are determined in one of the following ways:
(a) | if k>2, the range of x values is divided into k-2 intervals of equal length, and two extreme intervals, defined by the class boundary values y 1,y 2,…,y k-1;
(b) | if k=2, y 1=12 a+b.
However formed, the values y 1,…,y k-1 are assumed to be in ascending order. The class frequencies are formed with
  • f 1= the number of x values in the interval -∞,y 1
  • fi= the number of x values in the interval y i-1,yi,  i=2,…,k-1
  • fk= the number of x values in the interval y k-1,∞,
where [ means inclusive, and ) means exclusive. If the class boundary values are method-calculated and k>2, then f 1=fk=0, and y 1 and y k-1 are chosen so that y 1<a and y k-1>b.
If a frequency distribution is required for a discrete variable, then it is suggested that you supply the class boundary values; method-calculated boundary values may be slightly imprecise (due to the adjustment of y 1 and y k-1 outlined above) and cause values very close to a class boundary to be assigned to the wrong class.

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, k<2.
ifail=2
On entry, n<1.
ifail=3
On entry, the user-supplied class boundary values are not in ascending order.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The method used is believed to be stable.

Parallelism and Performance

None.

Further Comments

The time taken by g01ae increases with k and n. It also depends on the distribution of the sample observations.

Example

This example summarises a number of datasets. For each dataset the sample observations and optionally class boundary values are read. g01ae is then called and the frequency distribution and largest and smallest observations printed.

Example program (C#): g01aee.cs

Example program data: g01aee.d

Example program results: g01aee.r

See Also

G01 Class
G01 Members


g01af Method

[image]

NAG Library for .NET Release 2
G01..::g01af Method
G01 Class See Also Send Feedback
g01af performs the analysis of a two-way r×c contingency table or classification. If r=c=2, and the total number of objects classified is 40 or fewer, then the probabilities for Fisher's exact test are computed. Otherwise, a test statistic is computed (with Yates' correction when r=c=2), which under the assumption of no association between the classifications has approximately a chi-square distribution with r-1×c-1 degrees of freedom.

Syntax

C#
public static void g01af(
    int m,
    int n,
    int[,] nobs,
    ref int num,
    double[,] pred,
    out double chis,
    double[] p,
    out int npos,
    out int ndf,
    out int m1,
    out int n1,
    out int ifail
)
Visual Basic
Public Shared Sub g01af ( _
    m As Integer, _
    n As Integer, _
    nobs As Integer(,), _
    ByRef num As Integer, _
    pred As Double(,), _
    <OutAttribute> ByRef chis As Double, _
    p As Double(), _
    <OutAttribute> ByRef npos As Integer, _
    <OutAttribute> ByRef ndf As Integer, _
    <OutAttribute> ByRef m1 As Integer, _
    <OutAttribute> ByRef n1 As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g01af(
    int m,
    int n,
    array<int,2>^ nobs,
    int% num,
    array<double,2>^ pred,
    [OutAttribute] double% chis,
    array<double>^ p,
    [OutAttribute] int% npos,
    [OutAttribute] int% ndf,
    [OutAttribute] int% m1,
    [OutAttribute] int% n1,
    [OutAttribute] int% ifail
)
F#
static member g01af :
        m : int *
        n : int *
        nobs : int[,] *
        num : int byref *
        pred : float[,] *
        chis : float byref *
        p : float[] *
        npos : int byref *
        ndf : int byref *
        m1 : int byref *
        n1 : int byref *
        ifail : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: m+1, one more than the number of rows of the frequency matrix.
Constraint: m>2.
n
Type: System..::..Int32
On entry: n+1, one more than the number of columns of the frequency matrix.
Constraint: n>2.
nobs
Type: array< System..::..Int32 ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥m
On entry: the elements nobs[i-1,j-1], for i=1,2,…,m and j=1,2,…,n, must contain the frequencies for the two-way classification. The m+1th row and the n+1th column of nobs need not be set.
On exit: contains the following information:
  • nobs[i-1,j-1], for i=1,2,…,m 1 and j=1,2,…,n 1, contain the frequencies for the two-way classification after ‘shrinkage’ has taken place (see [Description]).
  • nobs[i-1,n], for i=1,2,…,m 1, contain the total frequencies in the remaining rows, Ri.
  • nobs[m,j-1], for j=1,2,…,n 1, contain the total frequencies in the remaining columns, Cj.
  • nobs[m,n], contains the total frequency, T.
If any ‘shrinkage’ has occurred, then all other cells contain no useful information.
Constraint: nobs[i-1,j-1]≥0, for i=1,2,…,m-1 and j=1,2,…,n-1.
num
Type: System..::..Int32 %
On entry: the value assigned to num must determine whether automatic ‘shrinkage’ is required when any r ij<1, as outlined in [Description] (i).
If num=1, shrinkage is required, otherwise shrinkage is not required.
On exit: when Fisher's exact test for a 2×2 classification is used then num contains the number of elements used in the array p, otherwise num is set to zero.
pred
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: the elements pred[i-1,j-1], where i=1,2,…,m1 and j=1,2,…,n1 contain the expected frequencies, r ij corresponding to the observed frequencies nobs[i-1,j-1], except in the case when Fisher's exact test for a 2×2 classification is to be used, when pred is not used. No other elements are utilized.
chis
Type: System..::..Double %
On exit: the value of the test statistic, χ 2, except when Fisher's exact test for a 2×2 classification is used in which case it is unspecified.
p
Type: array< System..::..Double >[]()[][]
An array of size [21]
p is used only when Fisher's exact test for a 2×2 classification is to be used.
On exit: the first num elements contain the probabilities associated with the various possible frequency tables, Pr, for r=0,1,…,R 1, the remainder are unspecified.
npos
Type: System..::..Int32 %
npos is used only when Fisher's exact test for a 2×2 classification is to be used.
On exit: p[npos-1] holds the probability associated with the given table of frequencies.
ndf
Type: System..::..Int32 %
On exit: the value of ndf gives the number of degrees of freedom for the chi-square distribution, m 1-1×n 1-1; when Fisher's exact test is used ndf=1.
m1
Type: System..::..Int32 %
On exit: the number of rows of the two-way classification, after any ‘shrinkage’, m 1.
n1
Type: System..::..Int32 %
On exit: the number of columns of the two-way classification, after any ‘shrinkage’, n 1.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The data consist of the frequencies for the two-way classification, denoted by n ij, for i=1,2,…,m and j=1,2,…,n with m,n>1.
A check is made to see whether any row or column of the matrix of frequencies consists entirely of zeros, and if so, the matrix of frequencies is reduced by omitting that row or column. Suppose the final size of the matrix is m 1 by n 1 (m 1,n 1>1), and let
  • Ri=∑j=1 n 1 n ij, the total frequency for the ith row, for i=1,2,…,m 1,
  • Cj=∑i=1 m 1 n ij, the total frequency for the jth column, for j=1,2,…,n 1, and
  • T=∑i=1 m 1 Ri=∑j=1 n 1 Cj, the total frequency.
There are two situations:
(i) If m 1>2 and/or n 1>2, or m 1=n 1=2 and T>40, then the matrix of expected frequencies, denoted by r ij, for i=1,2,…,m 1 and j=1,2,…,n 1, and the test statistic, χ 2, are computed, where
r ij=RiCj/T,  i=1,2,…,m 1;j=1,2,…,n 1
and
χ 2=∑i=1 m 1∑j=1 n 1 r ij-n ij-Y 2/r ij,
where
Y=12  if ​m 1=n 1=20  otherwise
is Yates' correction for continuity.
Under the assumption that there is no association between the two classifications, χ 2 will have approximately a chi-square distribution with m 1-1×n 1-1 degrees of freedom.
An option exists which allows for further ‘shrinkage’ of the matrix of frequencies in the case where r ij<1 for the (i,j)th cell. If this is the case, then row i or column j will be combined with the adjacent row or column with smaller total. Row i is selected for combination if Ri×m 1≤Cj×n 1. This ‘shrinking’ process is continued until r ij≥1 for all cells (i,j).
(ii) If m 1=n 1=2 and T≤40, the probabilities to enable Fisher's exact test to be made are computed.
The matrix of frequencies may be rearranged so that R 1 is the smallest marginal (i.e., column and row) total, and C 2≥C 1. Under the assumption of no association between the classifications, the probability of obtaining r entries in cell 1,1 is computed where
P r+1=R 1!R 2!C 1!C 2!T!r!R 1-r!C 1-r!T-C 1-R 1+r!,  r=0,1,…,R 1.
The probability of obtaining the table of given frequencies is returned. A test of the assumption against some alternative may then be made by summing the relevant values of Pr.

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDNOB, LDPRED) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
The number of rows or columns of nobs is less than 2, possibly after shrinkage.
ifail=2
At least one frequency is negative, or all frequencies are zero.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The method used is believed to be stable.

Parallelism and Performance

None.

Further Comments

The time taken by g01af will increase with m and n, except when Fisher's exact test is to be used, in which case it increases with size of the marginal and total frequencies.
If, on exit, num>0, or alternatively ndf is 1 and nobs[m-1,n-1]≤40, the probabilities for use in Fisher's exact test for a 2×2 classification will be calculated, and not the test statistic with approximately a chi-square distribution.

Example

In the example program, NPROB determines the number of two-way classifications to be analysed. For each classification the frequencies are read, g01af called, and information given on how much ‘shrinkage’ has taken place. If Fisher's exact test is to be used, the given frequencies and the array of probabilities associated with the possible frequency tables are printed. Otherwise, if the chi-square test is to be used, the given and expected frequencies, and the test statistic with its degrees of freedom are printed. In the example, there is one 2×3 classification, with shrinkage not requested.

Example program (C#): g01afe.cs

Example program data: g01afe.d

Example program results: g01afe.r

See Also

G01 Class
G01 Members


g01al Method

[image]

NAG Library for .NET Release 2
G01..::g01al Method
G01 Class See Also Send Feedback
g01al calculates a five-point summary for a single sample.

Syntax

C#
public static void g01al(
    int n,
    double[] x,
    double[] res,
    out int ifail
)
Visual Basic
Public Shared Sub g01al ( _
    n As Integer, _
    x As Double(), _
    res As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g01al(
    int n,
    array<double>^ x,
    array<double>^ res,
    [OutAttribute] int% ifail
)
F#
static member g01al :
        n : int *
        x : float[] *
        res : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, number of observations in the sample.
Constraint: n≥5.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the sample observations, x 1,x 2,…,xn.
res
Type: array< System..::..Double >[]()[][]
An array of size [5]
On exit: res contains the five-point summary.
res[0]
The minimum.
res[1]
The lower hinge.
res[2]
The median.
res[3]
The upper hinge.
res[4]
The maximum.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g01al calculates the minimum, lower hinge, median, upper hinge and the maximum of a sample of n observations.
The data consist of a single sample of n observations denoted by xi and let zi, for i=1,2,…,n, represent the sample observations sorted into ascending order.
Let m=n 2 if n is even and n+1 2 if n is odd,
and k=m 2 if m is even and m+1 2 if m is odd.
Then we have
Minimum | =z 1, |
Maximum | =zn, |
Median | =zm | if n is odd,
 | =zm+z m+1 2 | if n is even, 12
Lower hinge | =zk | if m is odd,
 | =zk+z k+1 2 | if m is even, 12
Upper hinge | =z n-k+1 | if m is odd,
 | =z n-k+z n-k+1 2 | if m is even.12

References

Erickson B H and Nosanchuk T A (1985) Understanding Data Open University Press, Milton Keynes
Tukey J W (1977) Exploratory Data Analysis Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<5.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The computations are stable.

Parallelism and Performance

None.

Further Comments

The time taken by g01al is proportional to n.

Example

This example calculates a five-point summary for a sample of 12 observations.

Example program (C#): g01ale.cs

Example program data: g01ale.d

Example program results: g01ale.r

See Also

G01 Class
G01 Members


g01am Method

[image]

NAG Library for .NET Release 2
G01..::g01am Method
G01 Class See Also Send Feedback
g01am finds specified quantiles from a vector of unsorted data.

Syntax

C#
public static void g01am(
    int n,
    double[] rv,
    int nq,
    double[] q,
    double[] qv,
    out int ifail
)
Visual Basic
Public Shared Sub g01am ( _
    n As Integer, _
    rv As Double(), _
    nq As Integer, _
    q As Double(), _
    qv As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g01am(
    int n,
    array<double>^ rv,
    int nq,
    array<double>^ q,
    array<double>^ qv,
    [OutAttribute] int% ifail
)
F#
static member g01am :
        n : int *
        rv : float[] *
        nq : int *
        q : float[] *
        qv : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: the number of elements in the input vector rv.
Constraint: n>0.
rv
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the vector whose quantiles are to be determined.
On exit: the order of the elements in rv is not, in general, preserved.
nq
Type: System..::..Int32
On entry: the number of quantiles requested.
Constraint: nq>0.
q
Type: array< System..::..Double >[]()[][]
An array of size [nq]
On entry: the quantiles to be calculated, in ascending order. Note that these must be between 0.0 and 1.0, with 0.0 returning the smallest element and 1.0 the largest.
Constraints:
  • 0.0≤q[i-1]≤1.0, for i=1,2,…,nq;
  • q[i-1]≤q[i+1-1], for i=1,2,…,nq-1.
qv
Type: array< System..::..Double >[]()[][]
An array of size [nq]
On exit: qv[i-1] contains the quantile specified by the value provided in q[i-1], or an interpolated value if the quantile falls between two data values.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

A quantile is a value which divides a frequency distribution such that there is a given proportion of data values below the quantile. For example, the median of a dataset is the 0.5 quantile because half the values are less than or equal to it; and the 0.25 quantile is the 25th percentile.
g01am uses a modified version of Singleton's ‘median-of-three’ Quicksort algorithm (Singleton (1969)) to determine specified quantiles of a vector of real values. The input vector is partially sorted, as far as is required to compute desired quantiles; for a single quantile, this is much faster than sorting the entire vector. Where necessary, linear interpolation is also carried out to return the values of quantiles which lie between two data points.

References

Singleton R C (1969) An efficient algorithm for sorting with minimal storage: Algorithm 347 Comm. ACM 12 185–187

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<1.
ifail=2
On entry, nq<1.
ifail=3
On entry, some q<0.0 or q>1.0.
ifail=4
On entry, q is not in ascending order.
ifail=5
Internal error. Check all array sizes and calls to g01am. Please contact NAG.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

The average time taken by g01am is approximately proportional to n×1+log nq. The worst case time is proportional to n 2 but this is extremely unlikely to occur.

Example

This example computes a list of quantiles from an array of reals and an array of point values.

Example program (C#): g01ame.cs

Example program data: g01ame.d

Example program results: g01ame.r

See Also

G01 Class
G01 Members


g01bj Method

[image]

NAG Library for .NET Release 2
G01..::g01bj Method
G01 Class See Also Send Feedback
g01bj returns the lower tail, upper tail and point probabilities associated with a binomial distribution.

Syntax

C#
public static void g01bj(
    int n,
    double p,
    int k,
    out double plek,
    out double pgtk,
    out double peqk,
    out int ifail
)
Visual Basic
Public Shared Sub g01bj ( _
    n As Integer, _
    p As Double, _
    k As Integer, _
    <OutAttribute> ByRef plek As Double, _
    <OutAttribute> ByRef pgtk As Double, _
    <OutAttribute> ByRef peqk As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g01bj(
    int n,
    double p,
    int k,
    [OutAttribute] double% plek,
    [OutAttribute] double% pgtk,
    [OutAttribute] double% peqk,
    [OutAttribute] int% ifail
)
F#
static member g01bj :
        n : int *
        p : float *
        k : int *
        plek : float byref *
        pgtk : float byref *
        peqk : float byref *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: the parameter n of the binomial distribution.
Constraint: n≥0.
p
Type: System..::..Double
On entry: the parameter p of the binomial distribution.
Constraint: 0.0<p<1.0.
k
Type: System..::..Int32
On entry: the integer k which defines the required probabilities.
Constraint: 0≤k≤n.
plek
Type: System..::..Double %
On exit: the lower tail probability, Prob X≤k.
pgtk
Type: System..::..Double %
On exit: the upper tail probability, Prob X>k.
peqk
Type: System..::..Double %
On exit: the point probability, Prob X=k.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Let X denote a random variable having a binomial distribution with parameters n and p (n≥0 and 0<p<1). Then
Prob X=k=nk pk1-p n-k,  k=0,1,…,n.
The mean of the distribution is np and the variance is np 1-p.
g01bj computes for given n, p and k the probabilities:
plek=Prob X≤kpgtk=Prob X>kpeqk=Prob X=k.
The method is similar to the method for the Poisson distribution described in Knüsel (1986).

References

Knüsel L (1986) Computation of the chi-square and Poisson distribution SIAM J. Sci. Statist. Comput. 7 1022–1036

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<0.
ifail=2
On entry, | p≤0.0,
or | p≥1.0.
ifail=3
On entry, | k<0,
or | k>n.
ifail=4
On entry, n is too large to be represented exactly as a real number.
ifail=5
On entry, the variance (=np 1-p) exceeds 106.
ifail=-9000
An error occured, see message report.

Accuracy

Results are correct to a relative accuracy of at least 10-6 on machines with a precision of 9 or more decimal digits, and to a relative accuracy of at least 10-3 on machines of lower precision (provided that the results do not underflow to zero).

Parallelism and Performance

None.

Further Comments

The time taken by g01bj depends on the variance (=np 1-p) and on k. For given variance, the time is greatest when k≈np (=the mean), and is then approximately proportional to the square-root of the variance.

Example

This example reads values of n and p from a data file until end-of-file is reached, and prints the corresponding probabilities.

Example program (C#): g01bje.cs

Example program data: g01bje.d

Example program results: g01bje.r

See Also

G01 Class
G01 Members


g01bk Method

[image]

NAG Library for .NET Release 2
G01..::g01bk Method
G01 Class See Also Send Feedback
g01bk returns the lower tail, upper tail and point probabilities associated with a Poisson distribution.

Syntax

C#
public static void g01bk(
    double rlamda,
    int k,
    out double plek,
    out double pgtk,
    out double peqk,
    out int ifail
)
Visual Basic
Public Shared Sub g01bk ( _
    rlamda As Double, _
    k As Integer, _
    <OutAttribute> ByRef plek As Double, _
    <OutAttribute> ByRef pgtk As Double, _
    <OutAttribute> ByRef peqk As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g01bk(
    double rlamda,
    int k,
    [OutAttribute] double% plek,
    [OutAttribute] double% pgtk,
    [OutAttribute] double% peqk,
    [OutAttribute] int% ifail
)
F#
static member g01bk :
        rlamda : float *
        k : int *
        plek : float byref *
        pgtk : float byref *
        peqk : float byref *
        ifail : int byref -> unit

Parameters

rlamda
Type: System..::..Double
On entry: the parameter λ of the Poisson distribution.
Constraint: 0.0<rlamda≤106.
k
Type: System..::..Int32
On entry: the integer k which defines the required probabilities.
Constraint: k≥0.
plek
Type: System..::..Double %
On exit: the lower tail probability, Prob X≤k.
pgtk
Type: System..::..Double %
On exit: the upper tail probability, Prob X>k.
peqk
Type: System..::..Double %
On exit: the point probability, Prob X=k.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Let X denote a random variable having a Poisson distribution with parameter λ >0. Then
Prob X=k=e-λ λk k!,  k=0,1,2,…
The mean and variance of the distribution are both equal to λ.
g01bk computes for given λ and k the probabilities:
plek=Prob X≤kpgtk=Prob X>kpeqk=Prob X=k.
The method is described in Knüsel (1986).

References

Knüsel L (1986) Computation of the chi-square and Poisson distribution SIAM J. Sci. Statist. Comput. 7 1022–1036

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, rlamda≤0.0.
ifail=2
On entry, k<0.
ifail=3
On entry, rlamda>106.
ifail=-9000
An error occured, see message report.

Accuracy

Results are correct to a relative accuracy of at least 10-6 on machines with a precision of 9 or more decimal digits, and to a relative accuracy of at least 10-3 on machines of lower precision (provided that the results do not underflow to zero).

Parallelism and Performance

None.

Further Comments

The time taken by g01bk depends on λ and k. For given λ, the time is greatest when k≈λ, and is then approximately proportional to λ.

Example

This example reads values of λ and k from a data file until end-of-file is reached, and prints the corresponding probabilities.

Example program (C#): g01bke.cs

Example program data: g01bke.d

Example program results: g01bke.r

See Also

G01 Class
G01 Members


g01bl Method

[image]

NAG Library for .NET Release 2
G01..::g01bl Method
G01 Class See Also Send Feedback
g01bl returns the lower tail, upper tail and point probabilities associated with a hypergeometric distribution.

Syntax

C#
public static void g01bl(
    int n,
    int l,
    int m,
    int k,
    out double plek,
    out double pgtk,
    out double peqk,
    out int ifail
)
Visual Basic
Public Shared Sub g01bl ( _
    n As Integer, _
    l As Integer, _
    m As Integer, _
    k As Integer, _
    <OutAttribute> ByRef plek As Double, _
    <OutAttribute> ByRef pgtk As Double, _
    <OutAttribute> ByRef peqk As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g01bl(
    int n,
    int l,
    int m,
    int k,
    [OutAttribute] double% plek,
    [OutAttribute] double% pgtk,
    [OutAttribute] double% peqk,
    [OutAttribute] int% ifail
)
F#
static member g01bl :
        n : int *
        l : int *
        m : int *
        k : int *
        plek : float byref *
        pgtk : float byref *
        peqk : float byref *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: the parameter n of the hypergeometric distribution.
Constraint: n≥0.
l
Type: System..::..Int32
On entry: the parameter l of the hypergeometric distribution.
Constraint: 0≤l≤n.
m
Type: System..::..Int32
On entry: the parameter m of the hypergeometric distribution.
Constraint: 0≤m≤n.
k
Type: System..::..Int32
On entry: the integer k which defines the required probabilities.
Constraint: max 0,l-n-m≤k≤min l,m.
plek
Type: System..::..Double %
On exit: the lower tail probability, Prob X≤k.
pgtk
Type: System..::..Double %
On exit: the upper tail probability, Prob X>k.
peqk
Type: System..::..Double %
On exit: the point probability, Prob X=k.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Let X denote a random variable having a hypergeometric distribution with parameters n, l and m (n≥l≥0, n≥m≥0). Then
Prob X=k=mkn-ml-k nl,
where max 0,l-n-m≤k≤min l,m, 0≤l≤n and 0≤m≤n.
The hypergeometric distribution may arise if in a population of size n a number m are marked. From this population a sample of size l is drawn and of these k are observed to be marked.
The mean of the distribution =lm n, and the variance =lm n-ln-mn 2 n-1.
g01bl computes for given n, l, m and k the probabilities:
plek=Prob X≤kpgtk=Prob X>kpeqk=Prob X=k.
The method is similar to the method for the Poisson distribution described in Knüsel (1986).

References

Knüsel L (1986) Computation of the chi-square and Poisson distribution SIAM J. Sci. Statist. Comput. 7 1022–1036

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<0.
ifail=2
On entry, | l<0,
or | l>n.
ifail=3
On entry, | m<0,
or | m>n.
ifail=4
On entry, | k<0,
or | k>l,
or | k>m,
or | k<l+m-n.
ifail=5
On entry, n is too large to be represented exactly as a real number.
ifail=6
On entry, the variance (see [Description]) exceeds 106.
ifail=-9000
An error occured, see message report.

Accuracy

Results are correct to a relative accuracy of at least 10-6 on machines with a precision of 9 or more decimal digits, and to a relative accuracy of at least 10-3 on machines of lower precision (provided that the results do not underflow to zero).

Parallelism and Performance

None.

Further Comments

The time taken by g01bl depends on the variance (see [Description]) and on k. For given variance, the time is greatest when k≈lm/n (= the mean), and is then approximately proportional to the square-root of the variance.

Example

This example reads values of n, l, m and k from a data file until end-of-file is reached, and prints the corresponding probabilities.

Example program (C#): g01ble.cs

Example program data: g01ble.d

Example program results: g01ble.r

See Also

G01 Class
G01 Members


g01da Method

[image]

NAG Library for .NET Release 2
G01..::g01da Method
G01 Class See Also Send Feedback
g01da computes a set of Normal scores, i.e., the expected values of an ordered set of independent observations from a Normal distribution with mean 0.0 and standard deviation 1.0.

Syntax

C#
public static void g01da(
    int n,
    double[] pp,
    double etol,
    out double errest,
    out int ifail
)
Visual Basic
Public Shared Sub g01da ( _
    n As Integer, _
    pp As Double(), _
    etol As Double, _
    <OutAttribute> ByRef errest As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g01da(
    int n,
    array<double>^ pp,
    double etol,
    [OutAttribute] double% errest,
    [OutAttribute] int% ifail
)
F#
static member g01da :
        n : int *
        pp : float[] *
        etol : float *
        errest : float byref *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the size of the set.
Constraint: n>0.
pp
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the Normal scores. pp[i-1] contains the value E x i, for i=1,2,…,n.
etol
Type: System..::..Double
On entry: the maximum value for the estimated absolute error in the computed scores.
Constraint: etol>0.0.
errest
Type: System..::..Double %
On exit: a computed estimate of the maximum error in the computed scores (see [Accuracy]).
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

If a sample of n observations from any distribution (which may be denoted by x 1,x 2,…,xn), is sorted into ascending order, the rth smallest value in the sample is often referred to as the rth ‘order statistic’, sometimes denoted by x r (see Kendall and Stuart (1969)).
The order statistics therefore have the property
x 1≤x 2≤…≤x n.
(If n=2 r+1, x r+1 is the sample median.)
For samples originating from a known distribution, the distribution of each order statistic in a sample of given size may be determined. In particular, the expected values of the order statistics may be found by integration. If the sample arises from a Normal distribution, the expected values of the order statistics are referred to as the ‘Normal scores’. The Normal scores provide a set of reference values against which the order statistics of an actual data sample of the same size may be compared, to provide an indication of Normality for the sample (see (G01AHF not in this release)). Normal scores have other applications; for instance, they are sometimes used as alternatives to ranks in nonparametric testing procedures.
g01da computes the rth Normal score for a given sample size n as
E x r=∫-∞∞xr d Gr,
where
d Gr=Ar r-1 1-Ar n-r d Arβ r,n-r+1,  Ar=1 2 π∫-∞xr e-t 2/2 dt,  r=1,2,…,n,
and β denotes the complete beta function.
The method attempts to evaluate the scores so that the estimated error in each score is less than the value etol specified by you. All integrations are performed in parallel and arranged so as to give good speed and reasonable accuracy.

References

Kendall M G and Stuart A (1969) The Advanced Theory of Statistics (Volume 1) (3rd Edition) Griffin

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<1.
ifail=2
On entry, etol≤0.0.
ifail=3
The method was unable to estimate the scores with estimated error less than etol. The best result obtained is returned together with the associated value of errest.
ifail=4
On entry, | if n is even, iw<3×n/2;
or | if n is odd, iw<3×n-1/2.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Errors are introduced by evaluation of the functions d Gr and errors in the numerical integration process. Errors are also introduced by the approximation of the true infinite range of integration by a finite range a,b but a and b are chosen so that this effect is of lower order than that of the other two factors. In order to estimate the maximum error the functions d Gr are also integrated over the range a,b. g01da returns the estimated maximum error as
errest=maxr max a,b×∫ab d Gr-1.0.

Parallelism and Performance

None.

Further Comments

The time taken by g01da depends on etol and n. For a given value of etol the timing varies approximately linearly with n.

Example

The program below generates the Normal scores for samples of size 5, 10, 15, and prints the scores and the computed error estimates.

Example program (C#): g01dae.cs

Example program data: g01dae.d

Example program results: g01dae.r

See Also

G01 Class
G01 Members


g01db Method

[image]

NAG Library for .NET Release 2
G01..::g01db Method
G01 Class See Also Send Feedback
g01db calculates an approximation to the set of Normal Scores, i.e., the expected values of an ordered set of independent observations from a Normal distribution with mean 0.0 and standard deviation 1.0.

Syntax

C#
public static void g01db(
    int n,
    double[] pp,
    out int ifail
)
Visual Basic
Public Shared Sub g01db ( _
    n As Integer, _
    pp As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g01db(
    int n,
    array<double>^ pp,
    [OutAttribute] int% ifail
)
F#
static member g01db :
        n : int *
        pp : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the size of the sample.
Constraint: n≥1.
pp
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the Normal scores. pp[i-1] contains the value E x i, for i=1,2,…,n.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g01db is an adaptation of the Applied Statistics Algorithm AS 177.3, see Royston (1982). If you are particularly concerned with the accuracy with which g01db computes the expected values of the order statistics (see [Accuracy]), then g01da which is more accurate should be used instead at a cost of increased storage and computing time.
Let x 1,x 2,…,x n be the order statistics from a random sample of size n from the standard Normal distribution. Defining
P r,n=Φ-E x r
and
Q r,n=r-εn+γ,  r=1,2,…,n,
where E x r is the expected value of x r, the current method approximates the Normal upper tail area corresponding to E x r as,
P~r,n=Q r,n+δ 1 n Q r,n λ+δ 2 n Q r,n2 λ-C r,n.
for r=1,2,3, and r≥4. Estimates of ε, γ, δ 1, δ 2 and λ are obtained. A small correction C r,n to P~r,n is necessary when r≤7 and n≤20.
The approximation to E X r is thus given by
E x r=-Φ-1 P~r,n, r=1,2,…,n.
Values of the inverse Normal probability integral Φ-1 are obtained from g01fa.

References

Royston J P (1982) Algorithm AS 177: expected normal order statistics (exact and approximate) Appl. Statist. 31 161–165

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<1.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

For n≤2000, the maximum error is 0.0001, but g01db is usually accurate to 5 or 6 decimal places. For n up to 5000, comparison with the exact scores calculated by g01da shows that the maximum error is 0.001.

Parallelism and Performance

None.

Further Comments

The time taken by g01db is proportional to n.

Example

A program to calculate the expected values of the order statistics for a sample of size 10.

Example program (C#): g01dbe.cs

Example program data: g01dbe.d

Example program results: g01dbe.r

See Also

G01 Class
G01 Members


g01dc Method

[image]

NAG Library for .NET Release 2
G01..::g01dc Method
G01 Class See Also Send Feedback
g01dc computes an approximation to the variance-covariance matrix of an ordered set of independent observations from a Normal distribution with mean 0.0 and standard deviation 1.0.

Syntax

C#
public static void g01dc(
    int n,
    double exp1,
    double exp2,
    double sumssq,
    double[] vec,
    out int ifail
)
Visual Basic
Public Shared Sub g01dc ( _
    n As Integer, _
    exp1 As Double, _
    exp2 As Double, _
    sumssq As Double, _
    vec As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g01dc(
    int n,
    double exp1,
    double exp2,
    double sumssq,
    array<double>^ vec,
    [OutAttribute] int% ifail
)
F#
static member g01dc :
        n : int *
        exp1 : float *
        exp2 : float *
        sumssq : float *
        vec : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the sample size.
Constraint: n>0.
exp1
Type: System..::..Double
On entry: the expected value of the largest Normal order statistic, mn, from a sample of size n.
exp2
Type: System..::..Double
On entry: the expected value of the second largest Normal order statistic, m n-1, from a sample of size n.
sumssq
Type: System..::..Double
On entry: the sum of squares of the expected values of the Normal order statistics from a sample of size n.
vec
Type: array< System..::..Double >[]()[][]
An array of size [n×n+1/2]
On exit: the upper triangle of the n by n variance-covariance matrix packed by column. Thus element V ij is stored in vec[i+j×j-1/1], for 1≤i≤j≤n.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g01dc is an adaptation of the Applied Statistics Algorithm AS 128, see Davis and Stephens (1978). An approximation to the variance-covariance matrix, V, using a Taylor series expansion of the Normal distribution function is discussed in David and Johnson (1954).
However, convergence is slow for extreme variances and covariances. The present method uses the David–Johnson approximation to provide an initial approximation and improves upon it by use of the following identities for the matrix.
For a sample of size n, let mi be the expected value of the ith largest order statistic, then:
(a) | for any i=1,2,…,n, ∑j=1 n V ij=1
(b) | V 12=V 11+mn 2-mnm n-1-1
(c) | the trace of V is tr V=n-∑i=1 n mi 2
(d) | V ij=V ji=V rs=V sr where r=n+1-i, s=n+1-j and i,j=1,2,…,n. Note that only the upper triangle of the matrix is calculated and returned column-wise in vector form.

References

David F N and Johnson N L (1954) Statistical treatment of censored data, Part 1. Fundamental formulae Biometrika 41 228–240
Davis C S and Stephens M A (1978) Algorithm AS 128: approximating the covariance matrix of Normal order statistics Appl. Statist. 27 206–212

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<1.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

For n≤20, where comparison with the exact values can be made, the maximum error is less than 0.0001.

Parallelism and Performance

None.

Further Comments

The time taken by g01dc is approximately proportional to n 2.
The arguments exp1 (=mn), exp2 (=m n-1) and sumssq (=∑j=1 n mj 2) may be found from the expected values of the Normal order statistics obtained from g01da (exact) or g01db (approximate).

Example

Example program (C#): g01dce.cs

Example program data: g01dce.d

Example program results: g01dce.r

See Also

G01 Class
G01 Members


g01dd Method

[image]

NAG Library for .NET Release 2
G01..::g01dd Method
G01 Class See Also Send Feedback
g01dd calculates Shapiro and Wilk's W statistic and its significance level for testing Normality.

Syntax

C#
public static void g01dd(
    double[] x,
    int n,
    bool calwts,
    double[] a,
    out double w,
    out double pw,
    out int ifail
)
Visual Basic
Public Shared Sub g01dd ( _
    x As Double(), _
    n As Integer, _
    calwts As Boolean, _
    a As Double(), _
    <OutAttribute> ByRef w As Double, _
    <OutAttribute> ByRef pw As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g01dd(
    array<double>^ x,
    int n,
    bool calwts,
    array<double>^ a,
    [OutAttribute] double% w,
    [OutAttribute] double% pw,
    [OutAttribute] int% ifail
)
F#
static member g01dd :
        x : float[] *
        n : int *
        calwts : bool *
        a : float[] *
        w : float byref *
        pw : float byref *
        ifail : int byref -> unit

Parameters

x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the ordered sample values, xi, for i=1,2,…,n.
n
Type: System..::..Int32
On entry: n, the sample size.
Constraint: 3≤n≤5000.
calwts
Type: System..::..Boolean
On entry: must be set to true if you wish g01dd to calculate the elements of a.
calwts should be set to false if you have saved the values in a from a previous call to g01dd.
If in doubt, set calwts equal to true.
a
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: if calwts has been set to false then before entry a must contain the n weights as calculated in a previous call to g01dd, otherwise a need not be set.
On exit: the n weights required to calculate w.
w
Type: System..::..Double %
On exit: the value of the statistic, w.
pw
Type: System..::..Double %
On exit: the significance level of w.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g01dd calculates Shapiro and Wilk's W statistic and its significance level for any sample size between 3 and 5000. It is an adaptation of the Applied Statistics Algorithm AS R94, see Royston (1995). The full description of the theory behind this algorithm is given in Royston (1992).
Given a set of observations x 1,x 2,…,xn sorted into either ascending or descending order ( (M01CAF not in this release) may be used to sort the data) this method calculates the value of Shapiro and Wilk's W statistic defined as:
W=∑i=1 n aixi 2∑i=1 n xi-x-2,
where x-=1 n∑1 n xi is the sample mean and ai, for i=1,2,…,n, are a set of ‘weights’ whose values depend only on the sample size n.
On exit, the values of ai, for i=1,2,…,n, are only of interest should you wish to call the method again to calculate w and its significance level for a different sample of the same size.
It is recommended that the method is used in conjunction with a Normal Q-Q plot of the data. Methods g01da and g01db can be used to obtain the required Normal scores.

References

Royston J P (1982) Algorithm AS 181: the W test for normality Appl. Statist. 31 176–180
Royston J P (1986) A remark on AS 181: the W test for normality Appl. Statist. 35 232–234
Royston J P (1992) Approximating the Shapiro–Wilk's W test for non-normality Statistics & Computing 2 117–119
Royston J P (1995) A remark on AS R94: A remark on Algorithm AS 181: the W test for normality Appl. Statist. 44(4) 547–551

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<3.
ifail=2
On entry, n>5000.
ifail=3
On entry, the elements in x are not in ascending or descending order or are all equal.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

There may be a loss of significant figures for large n.

Parallelism and Performance

None.

Further Comments

The time taken by g01dd depends roughly linearly on the value of n.
For very small samples the power of the test may not be very high.
The contents of the array a should not be modified between calls to g01dd for a given sample size, unless calwts is reset to true before each call of g01dd.
The Shapiro and Wilk's W test is very sensitive to ties. If the data has been rounded the test can be improved by using Sheppard's correction to adjust the sum of squares about the mean. This produces an adjusted value of w,
WA=W∑x i-x-2∑i=1 n x i=x-2-n-1 12 ω 2,
where ω is the rounding width. WA can be compared with a standard Normal distribution, but a further approximation is given by Royston (1986).
If n>5000, a value for w and pw is returned, but its accuracy may not be acceptable. See [References] for more details.

Example

This example tests the following two samples (each of size 20) for Normality.
Sample Number | Data
1 | 0.11, 7.87, 4.61, 10.14, 7.95, 3.14, 0.46, 4.43, 0.21, 4.75, 0.71, 1.52, 3.24, 0.93, 0.42, 4.97, 9.53, 4.55, 0.47, 6.66
2 | 1.36, 1.14, 2.92, 2.55, 1.46, 1.06, 5.27, -1.11, 3.48, 1.10, 0.88, -0.51, 1.46, 0.52, 6.20, 1.69, 0.08, 3.67, 2.81, 3.49
The elements of a are calculated only in the first call of g01dd, and are re-used in the second call.

Example program (C#): g01dde.cs

Example program data: g01dde.d

Example program results: g01dde.r

See Also

G01 Class
G01 Members


g01dh Method

[image]

NAG Library for .NET Release 2
G01..::g01dh Method
G01 Class See Also Send Feedback
g01dh computes the ranks, Normal scores, an approximation to the Normal scores or the exponential scores as requested by you.

Syntax

C#
public static void g01dh(
    string scores,
    string ties,
    int n,
    double[] x,
    double[] r,
    out int ifail
)
Visual Basic
Public Shared Sub g01dh ( _
    scores As String, _
    ties As String, _
    n As Integer, _
    x As Double(), _
    r As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g01dh(
    String^ scores,
    String^ ties,
    int n,
    array<double>^ x,
    array<double>^ r,
    [OutAttribute] int% ifail
)
F#
static member g01dh :
        scores : string *
        ties : string *
        n : int *
        x : float[] *
        r : float[] *
        ifail : int byref -> unit

Parameters

scores
Type: System..::..String
On entry: indicates which of the following scores are required.
scores="R"
The ranks.
scores="N"
The Normal scores, that is the expected value of the Normal order statistics.
scores="B"
The Blom version of the Normal scores.
scores="T"
The Tukey version of the Normal scores.
scores="V"
The van der Waerden version of the Normal scores.
scores="S"
The Savage scores, that is the expected value of the exponential order statistics.
Constraint: scores="R", "N", "B", "T", "V" or "S".
ties
Type: System..::..String
On entry: indicates which of the following methods is to be used to assign scores to tied observations.
ties="A"
The average of the scores for tied observations is used.
ties="L"
The lowest score in the group of ties is used.
ties="H"
The highest score in the group of ties is used.
ties="N"
The nonrepeatable random number generator is used to randomly untie any group of tied observations.
ties="R"
The repeatable random number generator is used to randomly untie any group of tied observations.
ties="I"
Any ties are ignored, that is the scores are assigned to tied observations in the order that they appear in the data.
Constraint: ties="A", "L", "H", "N", "R" or "I".
n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n≥1.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the sample of observations, xi, for i=1,2,…,n.
r
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: contains the scores, si, for i=1,2,…,n, as specified by scores.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g01dh computes one of the following scores for a sample of observations, x 1,x 2,…,xn.
1. Rank Scores
The ranks are assigned to the data in ascending order, that is the ith observation has score si=k if it is the kth smallest observation in the sample.
2. Normal Scores
The Normal scores are the expected values of the Normal order statistics from a sample of size n. If xi is the kth smallest observation in the sample, then the score for that observation, si, is E Zk where Zk is the kth order statistic in a sample of size n from a standard Normal distribution and E is the expectation operator.
3. Blom, Tukey and van der Waerden Scores
These scores are approximations to the Normal scores. The scores are obtained by evaluating the inverse cumulative Normal distribution function, Φ-1(·), at the values of the ranks scaled into the interval 0,1 using different scaling transformations.
The Blom scores use the scaling transformation ri-38n+14 for the rank ri, for i=1,2,…,n. Thus the Blom score corresponding to the observation xi is
si=Φ-1 ri-38n+14.
The Tukey scores use the scaling transformation ri-13n+13; the Tukey score corresponding to the observation xi is
si=Φ-1 ri-13n+13.
The van der Waerden scores use the scaling transformation ri n+1; the van der Waerden score corresponding to the observation xi is
si=Φ-1 ri n+1.
The van der Waerden scores may be used to carry out the van der Waerden test for testing for differences between several population distributions, see Conover (1980).
4. Savage Scores
The Savage scores are the expected values of the exponential order statistics from a sample of size n. They may be used in a test discussed by Savage (1956) and Lehmann (1975). If xi is the kth smallest observation in the sample, then the score for that observation is
si=E Yk=1 n+1 n-1+⋯+1 n-k+1,
where Yk is the kth order statistic in a sample of size n from a standard exponential distribution and E is the expectation operator.
Ties may be handled in one of five ways. Let x t i, for i=1,2,…,m, denote m tied observations, that is x t 1=x t 2=⋯=x t m with t 1<t 2<⋯<t m. If the rank of x t 1 is k, then if ties are ignored the rank of x t j will be k+j-1. Let the scores ignoring ties be s t 1*,s t 2*,…,s t m*. Then the scores, s t i, for i=1,2,…,m, may be calculated as follows:
  • – if averages are used, then s t i=∑j=1 m s t j*/m;
  • – if the lowest score is used, then s t i=s t 1*;
  • – if the highest score is used, then s t i=s t m*;
  • – if ties are to be broken randomly, then s t i=s t I* where I∈random permutation of ​1,2,…,m;
  • – if ties are to be ignored, then s t i=s t i*.

References

Blom G (1958) Statistical Estimates and Transformed Beta-variables Wiley
Conover W J (1980) Practical Nonparametric Statistics Wiley
Lehmann E L (1975) Nonparametrics: Statistical Methods Based on Ranks Holden–Day
Savage I R (1956) Contributions to the theory of rank order statistics – the two-sample case Ann. Math. Statist. 27 590–615
Tukey J W (1962) The future of data analysis Ann. Math. Statist. 33 1–67

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | scores≠"R", "N", "B", "T", "V" or "S",
or | ties≠"A", "L", "H", "N", "R" or "I",
or | n<1.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

For scores="R", the results should be accurate to machine precision.
For scores="S", the results should be accurate to a small multiple of machine precision.
For scores="N", the results should have a relative accuracy of at least max 100×ε,10-8 where ε is the machine precision.
For scores="B", "T" or "V", the results should have a relative accuracy of at least max 10×ε,10-12.

Parallelism and Performance

None.

Further Comments

If more accurate Normal scores are required g01da should be used with appropriate settings for the input parameter etol.

Example

This example computes and prints the Savage scores for a sample of five observations. The average of the scores of any tied observations is used.

Example program (C#): g01dhe.cs

Example program data: g01dhe.d

Example program results: g01dhe.r

See Also

G01 Class
G01 Members


g01ea Method

[image]

NAG Library for .NET Release 2
G01..::g01ea Method
G01 Class See Also Send Feedback
g01ea returns a one or two tail probability for the standard Normal distribution.

Syntax

C#
public static double g01ea(
    string tail,
    double x,
    out int ifail
)
Visual Basic
Public Shared Function g01ea ( _
    tail As String, _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01ea(
    String^ tail,
    double x,
    [OutAttribute] int% ifail
)
F#
static member g01ea :
        tail : string *
        x : float *
        ifail : int byref -> float

Parameters

tail
Type: System..::..String
On entry: indicates which tail the returned probability should represent.
tail="L"
The lower tail probability is returned, i.e., P X≤x.
tail="U"
The upper tail probability is returned, i.e., P X≥x.
tail="S"
The two tail (significance level) probability is returned, i.e., P X≥x+P X≤-x.
tail="C"
The two tail (confidence interval) probability is returned, i.e., P X≤x-P X≤-x.
Constraint: tail="L", "U", "S" or "C".
x
Type: System..::..Double
On entry: x, the value of the standard Normal variate.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01ea returns a one or two tail probability for the standard Normal distribution.

Description

The lower tail probability for the standard Normal distribution, P X≤x is defined by:
P X≤x=∫-∞x Z X dX,
where
Z X=1 2 π e-X 2/2,-∞<X<∞.
The relationship
P X≤x=12 erfc-x 2
is used, where erfc is the complementary error function, and is computed using s15ad. For the upper tail probability the relationship P X≥x=P X≤-x is used and for the two tail significance level probability twice the probability obtained from the absolute value of x is returned.
When the two tail confidence probability is required the relationship
P X≤x-P X≤-x=erf x 2,
is used, where erf is the error function, and is computed using s15ae.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Hastings N A J and Peacock J B (1975) Statistical Distributions Butterworth

Error Indicators and Warnings

Errors or warnings detected by the method:
If ifail≠0, then g01ea returns 0.0.
ifail=1
On entry, tail≠"L", "U", "S" or "C".
ifail=-9000
An error occured, see message report.

Accuracy

Accuracy is limited by machine precision. For detailed error analysis see s15ad and s15ae.

Parallelism and Performance

None.

Further Comments

None.

Example

Four values of tail and x are input and the probabilities calculated and printed.

Example program (C#): g01eae.cs

Example program data: g01eae.d

Example program results: g01eae.r

See Also

G01 Class
G01 Members


g01eb Method

[image]

NAG Library for .NET Release 2
G01..::g01eb Method
G01 Class See Also Send Feedback
g01eb returns the lower tail, upper tail or two tail probability for the Student's t-distribution with real degrees of freedom.

Syntax

C#
public static double g01eb(
    string tail,
    double t,
    double df,
    out int ifail
)
Visual Basic
Public Shared Function g01eb ( _
    tail As String, _
    t As Double, _
    df As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01eb(
    String^ tail,
    double t,
    double df,
    [OutAttribute] int% ifail
)
F#
static member g01eb :
        tail : string *
        t : float *
        df : float *
        ifail : int byref -> float

Parameters

tail
Type: System..::..String
On entry: indicates which tail the returned probability should represent.
tail="U"
The upper tail probability is returned, i.e., P T≥t:ν.
tail="S"
The two tail (significance level) probability is returned, i.e., P T≥t:ν+P T≤-t:ν.
tail="C"
The two tail (confidence interval) probability is returned, i.e., P T≤t:ν-P T≤-t:ν.
tail="L"
The lower tail probability is returned, i.e., P T≤t:ν.
Constraint: tail="U", "S", "C" or "L".
t
Type: System..::..Double
On entry: t, the value of the Student's t variate.
df
Type: System..::..Double
On entry: ν, the degrees of freedom of the Student's t-distribution.
Constraint: df≥1.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01eb returns the lower tail, upper tail or two tail probability for the Student's t-distribution with real degrees of freedom.

Description

The lower tail probability for the Student's t-distribution with ν degrees of freedom, P T≤t:ν is defined by:
P T≤t:ν=Γ ν+1/2πν Γ ν/2∫-∞t 1+T 2 ν-ν+1/2 dT,  ν≥1.
Computationally, there are two situations:
(i) when ν<20, a transformation of the beta distribution, Pβ B≤β:a,b is used
P T≤t:ν=12 Pβ B≤ν ν+t 2:ν/2,12  when ​t<0.0
or
P T≤t:ν=12+12 P β B≥νν+t 2:ν/2,12  when ​t>0.0;
(ii) when ν≥20, an asymptotic normalizing expansion of the Cornish–Fisher type is used to evaluate the probability, see Hill (1970).

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Hastings N A J and Peacock J B (1975) Statistical Distributions Butterworth
Hill G W (1970) Student's t-distribution Comm. ACM 13(10) 617–619

Error Indicators and Warnings

Errors or warnings detected by the method:
If ifail≠0, then g01eb returns 0.0.
ifail=1
On entry, tail≠"U", "S", "C" or "L".
ifail=2
On entry, df<1.0.
ifail=-9000
An error occured, see message report.

Accuracy

The computed probability should be accurate to five significant places for reasonable probabilities but there will be some loss of accuracy for very low probabilities (less than 10-10), see Hastings and Peacock (1975).

Parallelism and Performance

None.

Further Comments

The probabilities could also be obtained by using the appropriate transformation to a beta distribution (see Abramowitz and Stegun (1972)) and using g01ee. This method allows you to set the required accuracy.

Example

This example reads values from, and degrees of freedom for Student's t-distributions along with the required tail. The probabilities are calculated and printed until the end of data is reached.

Example program (C#): g01ebe.cs

Example program data: g01ebe.d

Example program results: g01ebe.r

See Also

G01 Class
G01 Members


g01ec Method

[image]

NAG Library for .NET Release 2
G01..::g01ec Method
G01 Class See Also Send Feedback
g01ec returns the lower or upper tail probability for the χ 2-distribution with real degrees of freedom.

Syntax

C#
public static double g01ec(
    string tail,
    double x,
    double df,
    out int ifail
)
Visual Basic
Public Shared Function g01ec ( _
    tail As String, _
    x As Double, _
    df As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01ec(
    String^ tail,
    double x,
    double df,
    [OutAttribute] int% ifail
)
F#
static member g01ec :
        tail : string *
        x : float *
        df : float *
        ifail : int byref -> float

Parameters

tail
Type: System..::..String
On entry: indicates whether the upper or lower tail probability is required.
tail="L"
The lower tail probability is returned, i.e., P X≤x:ν.
tail="U"
The upper tail probability is returned, i.e., P X≥x:ν.
Constraint: tail="L" or "U".
x
Type: System..::..Double
On entry: x, the value of the χ 2 variate with ν degrees of freedom.
Constraint: x≥0.0.
df
Type: System..::..Double
On entry: ν, the degrees of freedom of the χ 2-distribution.
Constraint: df>0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01ec returns the lower or upper tail probability for the χ 2-distribution with real degrees of freedom.

Description

The lower tail probability for the χ 2-distribution with ν degrees of freedom, P X≤x:ν is defined by:
P X≤x:ν=1 2 ν/2 Γ ν/2∫0.0 x X ν/2-1e-X/2 dX,  x≥0,ν>0.
To calculate P X≤x:ν a transformation of a gamma distribution is employed, i.e., a χ 2-distribution with ν degrees of freedom is equal to a gamma distribution with scale parameter 2 and shape parameter ν/2.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Hastings N A J and Peacock J B (1975) Statistical Distributions Butterworth

Error Indicators and Warnings

Note: g01ec may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
If ifail=1, 2 or 3 on exit, then g01ec returns 0.0.
ifail=1
On entry, tail≠"L" or "U".
ifail=2
On entry, x<0.0.
ifail=3
On entry, df≤0.0.
ifail=4
The solution has failed to converge while calculating the gamma variate. The result returned should represent an approximation to the solution.
ifail=-9000
An error occured, see message report.

Accuracy

A relative accuracy of five significant figures is obtained in most cases.

Parallelism and Performance

None.

Further Comments

For higher accuracy the transformation described in [Description] may be used with a direct call to s14ba.

Example

Values from various χ 2-distributions are read, the lower tail probabilities calculated, and all these values printed out, until the end of data is reached.

Example program (C#): g01ece.cs

Example program data: g01ece.d

Example program results: g01ece.r

See Also

G01 Class
G01 Members


g01ed Method

[image]

NAG Library for .NET Release 2
G01..::g01ed Method
G01 Class See Also Send Feedback
g01ed returns the probability for the lower or upper tail of the F or variance-ratio distribution with real degrees of freedom.

Syntax

C#
public static double g01ed(
    string tail,
    double f,
    double df1,
    double df2,
    out int ifail
)
Visual Basic
Public Shared Function g01ed ( _
    tail As String, _
    f As Double, _
    df1 As Double, _
    df2 As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01ed(
    String^ tail,
    double f,
    double df1,
    double df2,
    [OutAttribute] int% ifail
)
F#
static member g01ed :
        tail : string *
        f : float *
        df1 : float *
        df2 : float *
        ifail : int byref -> float

Parameters

tail
Type: System..::..String
On entry: indicates whether an upper or lower tail probability is required.
tail="L"
The lower tail probability is returned, i.e., P F≤f:ν 1,ν 2.
tail="U"
The upper tail probability is returned, i.e., P F≥f:ν 1,ν 2.
Constraint: tail="L" or "U".
f
Type: System..::..Double
On entry: f, the value of the F variate.
Constraint: f≥0.0.
df1
Type: System..::..Double
On entry: the degrees of freedom of the numerator variance, ν 1.
Constraint: df1>0.0.
df2
Type: System..::..Double
On entry: the degrees of freedom of the denominator variance, ν 2.
Constraint: df2>0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01ed returns the probability for the lower or upper tail of the F or variance-ratio distribution with real degrees of freedom.

Description

The lower tail probability for the F, or variance-ratio distribution, with ν 1 and ν 2 degrees of freedom, P F≤f:ν 1,ν 2, is defined by:
P F≤f:ν 1,ν 2=ν 1 ν 1/2ν 2 ν 2/2 Γ ν 1+ν 2/2Γ ν 1/2 Γ ν 2/2∫0 f F ν 1-2/2ν 1 F+ν 2-ν 1+ν 2/2 dF,
for ν 1, ν 2>0, f≥0.
The probability is computed by means of a transformation to a beta distribution, Pβ B≤β:a,b:
P F≤f:ν 1,ν 2=Pβ B≤ν 1 fν 1 f+ν 2:ν 1/2,ν 2/2
and using a call to g01ee.
For very large values of both ν 1 and ν 2, greater than 105, a normal approximation is used. If only one of ν 1 or ν 2 is greater than 105 then a χ 2 approximation is used, see Abramowitz and Stegun (1972).

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Hastings N A J and Peacock J B (1975) Statistical Distributions Butterworth

Error Indicators and Warnings

Note: g01ed may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
If ifail=1, 2 or 3 on exit, then g01ed returns 0.0.
ifail=1
On entry, tail≠"L" or "U".
ifail=2
On entry, f<0.0.
ifail=3
On entry, | df1≤0.0,
or | df2≤0.0.
ifail=4
f is too far out into the tails for the probability to be evaluated exactly. The result tends to approach 1.0 if f is large, or 0.0 if f is small. The result returned is a good approximation to the required solution.
ifail=-9000
An error occured, see message report.

Accuracy

The result should be accurate to five significant digits.

Parallelism and Performance

None.

Further Comments

For higher accuracy g01ee can be used along with the transformations given in [Description].

Example

This example reads values from, and degrees of freedom for, a number of F-distributions and computes the associated lower tail probabilities.

Example program (C#): g01ede.cs

Example program data: g01ede.d

Example program results: g01ede.r

See Also

G01 Class
G01 Members


g01ee Method

[image]

NAG Library for .NET Release 2
G01..::g01ee Method
G01 Class See Also Send Feedback
g01ee computes the upper and lower tail probabilities and the probability density function of the beta distribution with parameters a and b.

Syntax

C#
public static void g01ee(
    double x,
    double a,
    double b,
    double tol,
    out double p,
    out double q,
    out double pdf,
    out int ifail
)
Visual Basic
Public Shared Sub g01ee ( _
    x As Double, _
    a As Double, _
    b As Double, _
    tol As Double, _
    <OutAttribute> ByRef p As Double, _
    <OutAttribute> ByRef q As Double, _
    <OutAttribute> ByRef pdf As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g01ee(
    double x,
    double a,
    double b,
    double tol,
    [OutAttribute] double% p,
    [OutAttribute] double% q,
    [OutAttribute] double% pdf,
    [OutAttribute] int% ifail
)
F#
static member g01ee :
        x : float *
        a : float *
        b : float *
        tol : float *
        p : float byref *
        q : float byref *
        pdf : float byref *
        ifail : int byref -> unit

Parameters

x
Type: System..::..Double
On entry: β, the value of the beta variate.
Constraint: 0.0≤x≤1.0.
a
Type: System..::..Double
On entry: a, the first parameter of the required beta distribution.
Constraint: 0.0<a≤106.
b
Type: System..::..Double
On entry: b, the second parameter of the required beta distribution.
Constraint: 0.0<b≤106.
tol
Type: System..::..Double
On entry: this parameter is no longer referenced, but is included for backwards compatability.
p
Type: System..::..Double %
On exit: the lower tail probability, P B≤β:a,b.
q
Type: System..::..Double %
On exit: the upper tail probability, P B≥β:a,b.
pdf
Type: System..::..Double %
On exit: the probability density function, f B:a,b.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The probability density function of the beta distribution with parameters a and b is:
f B:a,b=Γ a+bΓ a Γ b B a-11-B b-1,  0≤B≤1;a,b>0.
The lower tail probability, P B≤β:a,b is defined by
P B≤β:a,b=Γ a+bΓ a Γ b∫0 β B a-11-B b-1 dB=Iβ a,b,  0≤β≤1;a,b>0.
The function Ix a,b, also known as the incomplete beta function is calculated using (S14CCF not in this release).

References

Hastings N A J and Peacock J B (1975) Statistical Distributions Butterworth

Error Indicators and Warnings

Note: g01ee may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail=1
On entry, | x<0.0,
or | x>1.0.
ifail=2
On entry, | a≤0.0,
or | a>106,
or | b≤0.0,
or | b>106.
ifail=4
x is too far out into the tails for the probability to be evaluated exactly. The results returned are 0 and 1 as appropriate. These should be a good approximation to the required solution.
ifail=-9000
An error occured, see message report.

Accuracy

The accuracy is limited by the error in the incomplete beta function. See [Accuracy] in s14cc for further details.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values from a number of beta distributions and computes the associated upper and lower tail probabilities and the corresponding value of the probability density function.

Example program (C#): g01eee.cs

Example program data: g01eee.d

Example program results: g01eee.r

See Also

G01 Class
G01 Members


g01ef Method

[image]

NAG Library for .NET Release 2
G01..::g01ef Method
G01 Class See Also Send Feedback
g01ef returns the lower or upper tail probability of the gamma distribution, with parameters α and β.

Syntax

C#
public static double g01ef(
    string tail,
    double g,
    double a,
    double b,
    out int ifail
)
Visual Basic
Public Shared Function g01ef ( _
    tail As String, _
    g As Double, _
    a As Double, _
    b As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01ef(
    String^ tail,
    double g,
    double a,
    double b,
    [OutAttribute] int% ifail
)
F#
static member g01ef :
        tail : string *
        g : float *
        a : float *
        b : float *
        ifail : int byref -> float

Parameters

tail
Type: System..::..String
On entry: indicates whether an upper or lower tail probability is required.
tail="L"
The lower tail probability is returned, that is P G≤g:α,β.
tail="U"
The upper tail probability is returned, that is P G≥g:α,β.
Constraint: tail="L" or "U".
g
Type: System..::..Double
On entry: g, the value of the gamma variate.
Constraint: g≥0.0.
a
Type: System..::..Double
On entry: the parameter α of the gamma distribution.
Constraint: a>0.0.
b
Type: System..::..Double
On entry: the parameter β of the gamma distribution.
Constraint: b>0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01ef returns the lower or upper tail probability of the gamma distribution, with parameters α and β.

Description

The lower tail probability for the gamma distribution with parameters α and β, P G≤g, is defined by:
P G≤g;α,β=1 βα Γ α∫0 g G α-1e-G/β dG,  α>0.0, ​β>0.0.
The mean of the distribution is αβ and its variance is α β 2. The transformation Z=Gβ is applied to yield the following incomplete gamma function in normalized form,
P G≤g;α,β=P Z≤g/β:α,1.0=1 Γ α∫0 g/β Z α-1e-Z dZ.
This is then evaluated using s14ba.

References

Hastings N A J and Peacock J B (1975) Statistical Distributions Butterworth

Error Indicators and Warnings

Errors or warnings detected by the method:
If ifail=1, 2, 3 or 4 on exit, then g01ef returns 0.0.
ifail=1
On entry, tail≠"L" or "U".
ifail=2
On entry, g<0.0.
ifail=3
On entry, | a≤0.0,
or | b≤0.0.
ifail=4
The solution did not converge in 600 iterations. See s14ba. The probability returned should be a reasonable approximation to the solution.
ifail=-9000
An error occured, see message report.

Accuracy

The result should have a relative accuracy of machine precision. There are rare occasions when the relative accuracy attained is somewhat less than machine precision but the error should not exceed more than 1 or 2 decimal places. Note also that there is a limit of 18 decimal places on the achievable accuracy, because constants in s14ba are given to this precision.

Parallelism and Performance

None.

Further Comments

The time taken by g01ef varies slightly with the input parameters g, a and b.

Example

This example reads in values from a number of gamma distributions and computes the associated lower tail probabilities.

Example program (C#): g01efe.cs

Example program data: g01efe.d

Example program results: g01efe.r

See Also

G01 Class
G01 Members


g01em Method

[image]

NAG Library for .NET Release 2
G01..::g01em Method
G01 Class See Also Send Feedback
g01em returns the probability associated with the lower tail of the distribution of the Studentized range statistic.

Syntax

C#
public static double g01em(
    double q,
    double v,
    int ir,
    out int ifail
)
Visual Basic
Public Shared Function g01em ( _
    q As Double, _
    v As Double, _
    ir As Integer, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01em(
    double q,
    double v,
    int ir,
    [OutAttribute] int% ifail
)
F#
static member g01em :
        q : float *
        v : float *
        ir : int *
        ifail : int byref -> float

Parameters

q
Type: System..::..Double
On entry: q, the Studentized range statistic.
Constraint: q>0.0.
v
Type: System..::..Double
On entry: v, the number of degrees of freedom for the experimental error.
Constraint: v≥1.0.
ir
Type: System..::..Int32
On entry: r, the number of groups.
Constraint: ir≥2.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01em returns the probability associated with the lower tail of the distribution of the Studentized range statistic.

Description

The externally Studentized range, q, for a sample, x 1,x 2,…,xr, is defined as:
q=max xi-min xi σ^e,
where σ^e is an independent estimate of the standard error of the xi's. The most common use of this statistic is in the testing of means from a balanced design. In this case for a set of group means, T-1,T-2,…,T-r, the Studentized range statistic is defined to be the difference between the largest and smallest means, T-largest and T-smallest, divided by the square root of the mean-square experimental error, M Serror, over the number of observations in each group, n, i.e.,
q=T-largest-T-smallestM Serror/n.
The Studentized range statistic can be used as part of a multiple comparisons procedure such as the Newman–Keuls procedure or Duncan's multiple range test (see Montgomery (1984) and Winer (1970)).
For a Studentized range statistic the probability integral, P q;v,r, for v degrees of freedom and r groups can be written as:
P q;v,r=C∫0∞x v-1e-v x 2/2 r∫-∞∞ϕ y Φ y-Φ y-qxr-1 dy dx,
where
C=v v/2 Γ v/2 2 v/2-1,  ϕ y=1 2 π e-y 2/2  and  Φ y=∫-∞y ϕ t dt.
The above two-dimensional integral is evaluated using d01da with the upper and lower limits computed to give stated accuracy (see [Accuracy]).
If the degrees of freedom v are greater than 2000 the probability integral can be approximated by its asymptotic form:
P q;r=r∫-∞∞ϕ y Φ y-Φ y-qr-1 dy.
This integral is evaluated using d01am.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Lund R E and Lund J R (1983) Algorithm AS 190: probabilities and upper quartiles for the studentized range Appl. Statist. 32(2) 204–210
Montgomery D C (1984) Design and Analysis of Experiments Wiley
Winer B J (1970) Statistical Principles in Experimental Design McGraw–Hill

Error Indicators and Warnings

Note: g01em may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail=1
On entry, | q≤0.0,
or | v<1.0,
or | ir<2.
ifail=2
There is some doubt as to whether full accuracy has been achieved.
ifail=-9000
An error occured, see message report.

Accuracy

The returned value will have absolute accuracy to at least four decimal places (usually five), unless ifail=2. When ifail=2 it is usual that the returned value will be a good estimate of the true value.

Parallelism and Performance

None.

Further Comments

None.

Example

The lower tail probabilities for the distribution of the Studentized range statistic are computed and printed for a range of values of q, ν and r.

Example program (C#): g01eme.cs

Example program data: g01eme.d

Example program results: g01eme.r

See Also

G01 Class
G01 Members


g01ep Method

[image]

NAG Library for .NET Release 2
G01..::g01ep Method
G01 Class See Also Send Feedback
g01ep calculates upper and lower bounds for the significance of a Durbin–Watson statistic.

Syntax

C#
public static void g01ep(
    int n,
    int ip,
    double d,
    out double pdl,
    out double pdu,
    out int ifail
)
Visual Basic
Public Shared Sub g01ep ( _
    n As Integer, _
    ip As Integer, _
    d As Double, _
    <OutAttribute> ByRef pdl As Double, _
    <OutAttribute> ByRef pdu As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g01ep(
    int n,
    int ip,
    double d,
    [OutAttribute] double% pdl,
    [OutAttribute] double% pdu,
    [OutAttribute] int% ifail
)
F#
static member g01ep :
        n : int *
        ip : int *
        d : float *
        pdl : float byref *
        pdu : float byref *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations used in calculating the Durbin–Watson statistic.
Constraint: n>ip.
ip
Type: System..::..Int32
On entry: p, the number of independent variables in the regression model, including the mean.
Constraint: ip≥1.
d
Type: System..::..Double
On entry: d, the Durbin–Watson statistic.
Constraint: d≥0.0.
pdl
Type: System..::..Double %
On exit: lower bound for the significance of the Durbin–Watson statistic, pl.
pdu
Type: System..::..Double %
On exit: upper bound for the significance of the Durbin–Watson statistic, pu.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Let r=r 1,r 2,…,rn T be the residuals from a linear regression of y on p independent variables, including the mean, where the y values y 1,y 2,…,yn can be considered as a time series. The Durbin–Watson test (see Durbin and Watson (1950), Durbin and Watson (1951) and Durbin and Watson (1971)) can be used to test for serial correlation in the error term in the regression.
The Durbin–Watson test statistic is:
d=∑i=1n-1 r i+1-ri 2∑i=1 n ri 2,
which can be written as
d=rT ArrT r,
where the n by n matrix A is given by
A=1-10…:-12-1…:0-12…::0-1…::::…::::…-1000…1
with the nonzero eigenvalues of the matrix A being λj=1-cos πj/n, for j=1,2,…,n-1.
Durbin and Watson show that the exact distribution of d depends on the eigenvalues of a matrix HA, where H is the hat matrix of independent variables, i.e., the matrix such that the vector of fitted values, y^, can be written as y^=Hy. However, bounds on the distribution can be obtained, the lower bound being
dl=∑i=1n-p λi ui 2∑i=1n-p ui 2
and the upper bound being
du=∑i=1n-p λ i-1+p ui 2∑i=1n-p ui 2,
where ui are independent standard Normal variables.
Two algorithms are used to compute the lower tail (significance level) probabilities, pl and pu, associated with dl and du. If n≤60 the procedure due to Pan (1964) is used, see Farebrother (1980), otherwise Imhof's method (see Imhof (1961)) is used.
The bounds are for the usual test of positive correlation; if a test of negative correlation is required the value of d should be replaced by 4-d.

References

Durbin J and Watson G S (1950) Testing for serial correlation in least squares regression. I Biometrika 37 409–428
Durbin J and Watson G S (1951) Testing for serial correlation in least squares regression. II Biometrika 38 159–178
Durbin J and Watson G S (1971) Testing for serial correlation in least squares regression. III Biometrika 58 1–19
Farebrother R W (1980) Algorithm AS 153. Pan's procedure for the tail probabilities of the Durbin–Watson statistic Appl. Statist. 29 224–227
Imhof J P (1961) Computing the distribution of quadratic forms in Normal variables Biometrika 48 419–426
Newbold P (1988) Statistics for Business and Economics Prentice–Hall
Pan Jie–Jian (1964) Distributions of the noncircular serial correlation coefficients Shuxue Jinzhan 7 328–337

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | n≤ip,
or | ip<1.
ifail=2
On entry, d<0.0.
ifail=-9000
An error occured, see message report.

Accuracy

On successful exit at least 4 decimal places of accuracy are achieved.

Parallelism and Performance

None.

Further Comments

If the exact probabilities are required, then the first n-p eigenvalues of HA can be computed and g01jd used to compute the required probabilities with c set to 0.0 and d to the Durbin–Watson statistic.

Example

The values of n, p and the Durbin–Watson statistic d are input and the bounds for the significance level calculated and printed.

Example program (C#): g01epe.cs

Example program data: g01epe.d

Example program results: g01epe.r

See Also

G01 Class
G01 Members


g01er Method

[image]

NAG Library for .NET Release 2
G01..::g01er Method
G01 Class See Also Send Feedback
g01er returns the probability associated with the lower tail of the von Mises distribution between -π and π through the function name.

Syntax

C#
public static double g01er(
    double t,
    double vk,
    out int ifail
)
Visual Basic
Public Shared Function g01er ( _
    t As Double, _
    vk As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01er(
    double t,
    double vk,
    [OutAttribute] int% ifail
)
F#
static member g01er :
        t : float *
        vk : float *
        ifail : int byref -> float

Parameters

t
Type: System..::..Double
On entry: θ, the observed von Mises statistic measured in radians.
vk
Type: System..::..Double
On entry: the concentration parameter κ, of the von Mises distribution.
Constraint: vk≥0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01er returns the probability associated with the lower tail of the von Mises distribution between -π and π through the function name.

Description

The von Mises distribution is a symmetric distribution used in the analysis of circular data. The lower tail area of this distribution on the circle with mean direction μ 0=0 and concentration parameter kappa, κ, can be written as
Pr Θ≤θ:κ=1 2 π I 0 κ∫-π θ e κ cos Θ dΘ,
where θ is reduced modulo 2 π so that -π≤θ<π and κ≥0. Note that if θ=π then g01er returns a probability of 1. For very small κ the distribution is almost the uniform distribution, whereas for κ→∞ all the probability is concentrated at one point.
The method of calculation for small κ involves backwards recursion through a series expansion in terms of modified Bessel functions, while for large κ an asymptotic Normal approximation is used.
In the case of small κ the series expansion of Pr(Θ≤θ: κ) can be expressed as
Pr Θ≤θ:κ=12+θ 2 π+1 π I 0 κ∑n=1∞n-1 In κ sin n θ,
where In κ is the modified Bessel function. This series expansion can be represented as a nested expression of terms involving the modified Bessel function ratio Rn,
Rn κ=In κI n-1 κ,  n=1,2,3,…,
which is calculated using backwards recursion.
For large values of κ (see [Accuracy]) an asymptotic Normal approximation is used. The angle Θ is transformed to the nearly Normally distributed variate Z,
Z=b κ sin Θ 2,
where
b κ=2 π eκI 0 κ
and b κ is computed from a continued fraction approximation. An approximation to order κ-4 of the asymptotic normalizing series for z is then used. Finally the Normal probability integral is evaluated.
For a more detailed analysis of the methods used see Hill (1977).

References

Hill G W (1977) Algorithm 518: Incomplete Bessel function I 0: The Von Mises distribution ACM Trans. Math. Software 3 279–284
Mardia K V (1972) Statistics of Directional Data Academic Press

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, vk<0.0 and g01er returns 0.
ifail=-9000
An error occured, see message report.

Accuracy

g01er uses one of two sets of constants depending on the value of machine precision. One set gives an accuracy of six digits and uses the Normal approximation when vk≥6.5, the other gives an accuracy of 12 digits and uses the Normal approximation when vk≥50.0.

Parallelism and Performance

None.

Further Comments

Using the series expansion for small κ the time taken by g01er increases linearly with κ; for larger κ, for which the asymptotic Normal approximation is used, the time taken is much less.
If angles outside the region -π≤θ<π are used care has to be taken in evaluating the probability of being in a region θ 1≤θ≤θ 2 if the region contains an odd multiple of π, 2 n+1 π. The value of F θ 2;κ-F θ 1;κ will be negative and the correct probability should then be obtained by adding one to the value.

Example

This example inputs four values from the von Mises distribution along with the values of the parameter κ. The probabilities are computed and printed.

Example program (C#): g01ere.cs

Example program data: g01ere.d

Example program results: g01ere.r

See Also

G01 Class
G01 Members


g01et Method

[image]

NAG Library for .NET Release 2
G01..::g01et Method
G01 Class See Also Send Feedback
g01et returns the value of the Landau distribution function Φ λ.

Syntax

C#
public static double g01et(
    double x
)
Visual Basic
Public Shared Function g01et ( _
    x As Double _
) As Double
Visual C++
public:
static double g01et(
    double x
)
F#
static member g01et :
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the argument λ of the function.

Return Value

g01et returns the value of the Landau distribution function Φ λ.

Description

g01et evaluates an approximation to the Landau distribution function Φ λ given by
Φ λ=∫-∞λ ϕ λ dλ,
where ϕ λ is described in g01mt, using piecewise approximation by rational functions. Further details can be found in Kölbig and Schorr (1984).

References

Kölbig K S and Schorr B (1984) A program package for the Landau distribution Comp. Phys. Comm. 31 97–111

Error Indicators and Warnings

There are no failure exits from this routine.

Accuracy

At least 7 significant digits are usually correct, but occasionally only 6. Such accuracy is normally considered to be adequate for applications in experimental physics.
Because of the asymptotic behaviour of Φ λ, which is of the order of exp-exp-λ, underflow may occur on some machines when λ is moderately large and negative.

Parallelism and Performance

None.

Further Comments

None.

Example

This example evaluates Φ λ at λ=0.5, and prints the results.

Example program (C#): g01ete.cs

Example program data: g01ete.d

Example program results: g01ete.r

See Also

G01 Class
G01 Members


g01eu Method

[image]

NAG Library for .NET Release 2
G01..::g01eu Method
G01 Class See Also Send Feedback
g01eu returns the value of the Vavilov distribution function ΦV λ;κ,β 2.
It is intended to be used after a call to g01zu.

Syntax

C#
public static double g01eu(
    double x,
    double[] rcomm,
    out int ifail
)
Visual Basic
Public Shared Function g01eu ( _
    x As Double, _
    rcomm As Double(), _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01eu(
    double x,
    array<double>^ rcomm,
    [OutAttribute] int% ifail
)
F#
static member g01eu :
        x : float *
        rcomm : float[] *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument λ of the function.
rcomm
Type: array< System..::..Double >[]()[][]
An array of size [322]
On entry: this must be the same parameter rcomm as returned by a previous call to g01zu.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01eu returns the value of the Vavilov distribution function ΦV λ;κ,β 2.
It is intended to be used after a call to g01zu.

Description

g01eu evaluates an approximation to the Vavilov distribution function ΦV λ;κ,β 2 given by
ΦV λ;κ,β 2=∫-∞λ ϕV λ;κ,β 2 dλ,
where ϕ λ is described in g01mu. The method used is based on Fourier expansions. Further details can be found in Schorr (1974).

References

Schorr B (1974) Programs for the Landau and the Vavilov distributions and the corresponding random numbers Comp. Phys. Comm. 7 215–224

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
Either the initialization method has not been called prior to the first call of this method or a communication array has become corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

At least five significant digits are usually correct.

Parallelism and Performance

None.

Further Comments

g01eu can be called repeatedly with different values of λ provided that the values of κ and β 2 remain unchanged between calls. Otherwise, g01zu must be called again. This is illustrated in [Example].

Example

This example evaluates ΦV λ;κ,β 2 at λ=0.1, κ=2.5 and β 2=0.7, and prints the results.

Example program (C#): g01eue.cs

Example program data: g01eue.d

Example program results: g01eue.r

See Also

G01 Class
G01 Members


g01ey Method

[image]

NAG Library for .NET Release 2
G01..::g01ey Method
G01 Class See Also Send Feedback
g01ey returns the upper tail probability associated with the one sample Kolmogorov–Smirnov distribution.

Syntax

C#
public static double g01ey(
    int n,
    double d,
    out int ifail
)
Visual Basic
Public Shared Function g01ey ( _
    n As Integer, _
    d As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01ey(
    int n,
    double d,
    [OutAttribute] int% ifail
)
F#
static member g01ey :
        n : int *
        d : float *
        ifail : int byref -> float

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations in the sample.
Constraint: n≥1.
d
Type: System..::..Double
On entry: contains the test statistic, Dn+ or Dn-.
Constraint: 0.0≤d≤1.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01ey returns the upper tail probability associated with the one sample Kolmogorov–Smirnov distribution.

Description

Let Sn x be the sample cumulative distribution function and F 0 x the hypothesised theoretical distribution function.
g01ey returns the upper tail probability, p, associated with the one-sided Kolmogorov–Smirnov test statistic Dn+ or Dn-, where these one-sided statistics are defined as follows;
Dn+=supx Sn x-F 0 x,Dn-=supx F 0 x-Sn x.
If n≤100 an exact method is used; for the details see Conover (1980). Otherwise a large sample approximation derived by Smirnov is used; see Feller (1948), Kendall and Stuart (1973) or Smirnov (1948).

References

Conover W J (1980) Practical Nonparametric Statistics Wiley
Feller W (1948) On the Kolmogorov–Smirnov limit theorems for empirical distributions Ann. Math. Statist. 19 179–181
Kendall M G and Stuart A (1973) The Advanced Theory of Statistics (Volume 2) (3rd Edition) Griffin
Siegel S (1956) Non-parametric Statistics for the Behavioral Sciences McGraw–Hill
Smirnov N (1948) Table for estimating the goodness of fit of empirical distributions Ann. Math. Statist. 19 279–281

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<1.
ifail=2
On entry, | d<0.0,
or | d>1.0.
ifail=-9000
An error occured, see message report.

Accuracy

The large sample distribution used as an approximation to the exact distribution should have a relative error of less than 2.5% for most cases.

Parallelism and Performance

None.

Further Comments

The upper tail probability for the two-sided statistic, Dn=max Dn+,Dn-, can be approximated by twice the probability returned via g01ey, that is 2 p. (Note that if the probability from g01ey is greater than 0.5 then the two-sided probability should be truncated to 1.0). This approximation to the tail probability for Dn is good for small probabilities, (e.g., p≤0.10) but becomes very poor for larger probabilities.
The time taken by the method increases with n, until n>100. At this point the approximation is used and the time decreases significantly. The time then increases again modestly with n.

Example

The following example reads in 10 different sample sizes and values for the test statistic Dn. The upper tail probability is computed and printed for each case.

Example program (C#): g01eye.cs

Example program data: g01eye.d

Example program results: g01eye.r

See Also

G01 Class
G01 Members


g01ez Method

[image]

NAG Library for .NET Release 2
G01..::g01ez Method
G01 Class See Also Send Feedback
g01ez returns the probability associated with the upper tail of the Kolmogorov–Smirnov two sample distribution.

Syntax

C#
public static double g01ez(
    int n1,
    int n2,
    double d,
    out int ifail
)
Visual Basic
Public Shared Function g01ez ( _
    n1 As Integer, _
    n2 As Integer, _
    d As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01ez(
    int n1,
    int n2,
    double d,
    [OutAttribute] int% ifail
)
F#
static member g01ez :
        n1 : int *
        n2 : int *
        d : float *
        ifail : int byref -> float

Parameters

n1
Type: System..::..Int32
On entry: the number of observations in the first sample, n 1.
Constraint: n1≥1.
n2
Type: System..::..Int32
On entry: the number of observations in the second sample, n 2.
Constraint: n2≥1.
d
Type: System..::..Double
On entry: the test statistic D n 1,n 2, for the two sample Kolmogorov–Smirnov goodness-of-fit test, that is the maximum difference between the empirical cumulative distribution functions (CDFs) of the two samples.
Constraint: 0.0≤d≤1.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01ez returns the probability associated with the upper tail of the Kolmogorov–Smirnov two sample distribution.

Description

Let F n 1 x and G n 2 x denote the empirical cumulative distribution functions for the two samples, where n 1 and n 2 are the sizes of the first and second samples respectively.
The function g01ez computes the upper tail probability for the Kolmogorov–Smirnov two sample two-sided test statistic D n 1,n 2, where
D n 1,n 2=supx F n 1 x-G n 2 x.
The probability is computed exactly if n 1,n 2≤10000 and max n 1,n 2≤2500 using a method given by Kim and Jenrich (1973). For the case where min n 1,n 2≤10% of the max n 1,n 2 and min n 1,n 2≤80 the Smirnov approximation is used. For all other cases the Kolmogorov approximation is used. These two approximations are discussed in Kim and Jenrich (1973).

References

Conover W J (1980) Practical Nonparametric Statistics Wiley
Feller W (1948) On the Kolmogorov–Smirnov limit theorems for empirical distributions Ann. Math. Statist. 19 179–181
Kendall M G and Stuart A (1973) The Advanced Theory of Statistics (Volume 2) (3rd Edition) Griffin
Kim P J and Jenrich R I (1973) Tables of exact sampling distribution of the two sample Kolmogorov–Smirnov criterion D mn m<n Selected Tables in Mathematical Statistics 1 80–129 American Mathematical Society
Siegel S (1956) Non-parametric Statistics for the Behavioral Sciences McGraw–Hill
Smirnov N (1948) Table for estimating the goodness of fit of empirical distributions Ann. Math. Statist. 19 279–281

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | n1<1,
or | n2<1.
ifail=2
On entry, | d<0.0,
or | d>1.0.
ifail=3
The approximation solution did not converge in 500 iterations. A tail probability of 1.0 is returned by g01ez.
ifail=-9000
An error occured, see message report.

Accuracy

The large sample distributions used as approximations to the exact distribution should have a relative error of less than 5% for most cases.

Parallelism and Performance

None.

Further Comments

The upper tail probability for the one-sided statistics, D n 1,n 2+ or D n 1,n 2-, can be approximated by halving the two-sided upper tail probability returned by g01ez, that is p/2. This approximation to the upper tail probability for either D n 1,n 2+ or D n 1,n 2- is good for small probabilities, (e.g., p≤0.10) but becomes poor for larger probabilities.
The time taken by the method increases with n 1 and n 2, until n 1n 2>10000 or max n 1,n 2≥2500. At this point one of the approximations is used and the time decreases significantly. The time then increases again modestly with n 1 and n 2.

Example

The following example reads in 10 different sample sizes and values for the test statistic D n 1,n 2. The upper tail probability is computed and printed for each case.

Example program (C#): g01eze.cs

Example program data: g01eze.d

Example program results: g01eze.r

See Also

G01 Class
G01 Members


g01fa Method

[image]

NAG Library for .NET Release 2
G01..::g01fa Method
G01 Class See Also Send Feedback
g01fa returns the deviate associated with the given probability of the standard Normal distribution.

Syntax

C#
public static double g01fa(
    string tail,
    double p,
    out int ifail
)
Visual Basic
Public Shared Function g01fa ( _
    tail As String, _
    p As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01fa(
    String^ tail,
    double p,
    [OutAttribute] int% ifail
)
F#
static member g01fa :
        tail : string *
        p : float *
        ifail : int byref -> float

Parameters

tail
Type: System..::..String
On entry: indicates which tail the supplied probability represents.
tail="L"
The lower probability, i.e., P X≤xp.
tail="U"
The upper probability, i.e., P X≥xp.
tail="S"
The two tail (significance level) probability, i.e., P X≥xp+P X≤-xp.
tail="C"
The two tail (confidence interval) probability, i.e., P X≤xp-P X≤-xp.
Constraint: tail="L", "U", "S" or "C".
p
Type: System..::..Double
On entry: p, the probability from the standard Normal distribution as defined by tail.
Constraint: 0.0<p<1.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01fa returns the deviate associated with the given probability of the standard Normal distribution.

Description

The deviate, xp associated with the lower tail probability, p, for the standard Normal distribution is defined as the solution to
P X≤xp=p=∫-∞xp Z X dX,
where
Z X=1 2 π e-X 2/2,  -∞<X<∞.
The method used is an extension of that of Wichura (1988). p is first replaced by q=p-0.5.
(a) If q≤0.3, xp is computed by a rational Chebyshev approximation
xp=s A s 2B s 2,
where s=2 π q and A, B are polynomials of degree 7.
(b) If 0.3<q≤0.42, xp is computed by a rational Chebyshev approximation
xp=sign q C tD t,
where t=q-0.3 and C, D are polynomials of degree 5.
(c) If q>0.42, xp is computed as
xp=sign q E uF u+u,
where u=-2×log min p,1-p and E, F are polynomials of degree 6.
For the upper tail probability -xp is returned, while for the two tail probabilities the value x p* is returned, where p* is the required tail probability computed from the input value of p.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Hastings N A J and Peacock J B (1975) Statistical Distributions Butterworth
Wichura (1988) Algorithm AS 241: the percentage points of the Normal distribution Appl. Statist. 37 477–484

Error Indicators and Warnings

Errors or warnings detected by the method:
If on exit ifail≠0, then g01fa returns 0.0.
ifail=1
On entry, tail≠"L", "U", "S" or "C".
ifail=2
On entry, | p≤0.0,
or | p≥1.0.
ifail=-9000
An error occured, see message report.

Accuracy

The accuracy is mainly limited by the machine precision.

Parallelism and Performance

None.

Further Comments

None.

Example

Four values of tail and p are input and the deviates calculated and printed.

Example program (C#): g01fae.cs

Example program data: g01fae.d

Example program results: g01fae.r

See Also

G01 Class
G01 Members


g01fb Method

[image]

NAG Library for .NET Release 2
G01..::g01fb Method
G01 Class See Also Send Feedback
g01fb returns the deviate associated with the given tail probability of Student's t-distribution with real degrees of freedom.

Syntax

C#
public static double g01fb(
    string tail,
    double p,
    double df,
    out int ifail
)
Visual Basic
Public Shared Function g01fb ( _
    tail As String, _
    p As Double, _
    df As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01fb(
    String^ tail,
    double p,
    double df,
    [OutAttribute] int% ifail
)
F#
static member g01fb :
        tail : string *
        p : float *
        df : float *
        ifail : int byref -> float

Parameters

tail
Type: System..::..String
On entry: indicates which tail the supplied probability represents.
tail="U"
The upper tail probability, i.e., P T≥tp:ν.
tail="L"
The lower tail probability, i.e., P T≤tp:ν.
tail="S"
The two tail (significance level) probability, i.e., P T≥tp:ν+P T≤-tp:ν.
tail="C"
The two tail (confidence interval) probability, i.e., P T≤tp:ν-P T≤-tp:ν.
Constraint: tail="U", "L", "S" or "C".
p
Type: System..::..Double
On entry: p, the probability from the required Student's t-distribution as defined by tail.
Constraint: 0.0<p<1.0.
df
Type: System..::..Double
On entry: ν, the degrees of freedom of the Student's t-distribution.
Constraint: df≥1.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01fb returns the deviate associated with the given tail probability of Student's t-distribution with real degrees of freedom.

Description

The deviate, tp associated with the lower tail probability, p, of the Student's t-distribution with ν degrees of freedom is defined as the solution to
P T<tp:ν=p=Γ ν+1/2νπ Γ ν/2∫-∞tp 1+T 2 ν-ν+1/2 dT,  ν≥1; ​-∞<tp<∞.
For ν=1​ or ​2 the integral equation is easily solved for tp.
For other values of ν<3 a transformation to the beta distribution is used and the result obtained from g01fe.
For ν≥3 an inverse asymptotic expansion of Cornish–Fisher type is used. The algorithm is described by Hill (1970).

References

Hastings N A J and Peacock J B (1975) Statistical Distributions Butterworth
Hill G W (1970) Student's t-distribution Comm. ACM 13(10) 617–619

Error Indicators and Warnings

Note: g01fb may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
If ifail=1, 2 or 3 on exit, then g01fb returns zero.
ifail=1
On entry, tail≠"U", "S", "C" or "L".
ifail=2
On entry, | p≤0.0,
or | p≥1.0.
ifail=3
On entry, df<1.0.
ifail=5
Convergence in the calculation of the inverse beta value was not achieved. However, the result should be a reasonable approximation to the correct value.
ifail=-9000
An error occured, see message report.

Accuracy

The results should be accurate to five significant digits, for most parameter values. The error behaviour for various parameter values is discussed in Hill (1970).

Parallelism and Performance

None.

Further Comments

The value tp may be calculated by using the transformation described in [Description] and using g01fe. This method allows you to set the required accuracy.

Example

This example reads the probability, the tail that probability represents and the degrees of freedom for a number of Student's t-distributions and computes the corresponding deviates.

Example program (C#): g01fbe.cs

Example program data: g01fbe.d

Example program results: g01fbe.r

See Also

G01 Class
G01 Members


g01fc Method

[image]

NAG Library for .NET Release 2
G01..::g01fc Method
G01 Class See Also Send Feedback
g01fc returns the deviate associated with the given lower tail probability of the χ 2-distribution with real degrees of freedom.

Syntax

C#
public static double g01fc(
    double p,
    double df,
    out int ifail
)
Visual Basic
Public Shared Function g01fc ( _
    p As Double, _
    df As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01fc(
    double p,
    double df,
    [OutAttribute] int% ifail
)
F#
static member g01fc :
        p : float *
        df : float *
        ifail : int byref -> float

Parameters

p
Type: System..::..Double
On entry: p, the lower tail probability from the required χ 2-distribution.
Constraint: 0.0≤p<1.0.
df
Type: System..::..Double
On entry: ν, the degrees of freedom of the χ 2-distribution.
Constraint: df>0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01fc returns the deviate associated with the given lower tail probability of the χ 2-distribution with real degrees of freedom.

Description

The deviate, xp, associated with the lower tail probability p of the χ 2-distribution with ν degrees of freedom is defined as the solution to
P X≤xp:ν=p=1 2 ν/2 Γ ν/2∫0 xp e-X/2X v/2-1 dX,  0≤xp<∞;ν>0.
The required xp is found by using the relationship between a χ 2-distribution and a gamma distribution, i.e., a χ 2-distribution with ν degrees of freedom is equal to a gamma distribution with scale parameter 2 and shape parameter ν/2.
For very large values of ν, greater than 105, Wilson and Hilferty's normal approximation to the χ 2 is used; see Kendall and Stuart (1969).

References

Best D J and Roberts D E (1975) Algorithm AS 91. The percentage points of the χ 2 distribution Appl. Statist. 24 385–388
Hastings N A J and Peacock J B (1975) Statistical Distributions Butterworth
Kendall M G and Stuart A (1969) The Advanced Theory of Statistics (Volume 1) (3rd Edition) Griffin

Error Indicators and Warnings

Note: g01fc may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
If ifail=1, 2, 3 or 5 on exit, then g01fc returns 0.0.
ifail=1
On entry, | p<0.0,
or | p≥1.0.
ifail=2
On entry, df≤0.0.
ifail=3
p is too close to 0 or 1 for the result to be calculated.
ifail=4
The solution has failed to converge. The result should be a reasonable approximation.
ifail=5
The series used to calculate the gamma function has failed to converge. This is an unlikely error exit.
ifail=-9000
An error occured, see message report.

Accuracy

The results should be accurate to five significant digits for most parameter values. Some accuracy is lost for p close to 0.0.

Parallelism and Performance

None.

Further Comments

For higher accuracy the relationship described in [Description] may be used and a direct call to g01ff made.

Example

This example reads lower tail probabilities for several χ 2-distributions, and calculates and prints the corresponding deviates until the end of data is reached.

Example program (C#): g01fce.cs

Example program data: g01fce.d

Example program results: g01fce.r

See Also

G01 Class
G01 Members


g01fd Method

[image]

NAG Library for .NET Release 2
G01..::g01fd Method
G01 Class See Also Send Feedback
g01fd returns the deviate associated with the given lower tail probability of the F or variance-ratio distribution with real degrees of freedom.

Syntax

C#
public static double g01fd(
    double p,
    double df1,
    double df2,
    out int ifail
)
Visual Basic
Public Shared Function g01fd ( _
    p As Double, _
    df1 As Double, _
    df2 As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01fd(
    double p,
    double df1,
    double df2,
    [OutAttribute] int% ifail
)
F#
static member g01fd :
        p : float *
        df1 : float *
        df2 : float *
        ifail : int byref -> float

Parameters

p
Type: System..::..Double
On entry: p, the lower tail probability from the required F-distribution.
Constraint: 0.0≤p<1.0.
df1
Type: System..::..Double
On entry: the degrees of freedom of the numerator variance, ν 1.
Constraint: df1>0.0.
df2
Type: System..::..Double
On entry: the degrees of freedom of the denominator variance, ν 2.
Constraint: df2>0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01fd returns the deviate associated with the given lower tail probability of the F or variance-ratio distribution with real degrees of freedom.

Description

The deviate, fp, associated with the lower tail probability, p, of the F-distribution with degrees of freedom ν 1 and ν 2 is defined as the solution to
P F≤fp:ν 1,ν 2=p=ν 1 12 ν 1ν 2 12 ν 2 Γ ν 1+ν 2 2Γ ν 1 2 Γ ν 2 2∫0 fp F 12 ν 1-2ν 2+ν 1 F-12 ν 1+ν 2 dF,
where ν 1,ν 2>0; 0≤fp<∞.
The value of fp is computed by means of a transformation to a beta distribution, Pβ B≤β:a,b:
P F≤f:ν 1,ν 2=Pβ B≤ν 1 fν 1 f+ν 2:ν 1/2,ν 2/2
and using a call to g01fe.
For very large values of both ν 1 and ν 2, greater than 105, a normal approximation is used. If only one of ν 1 or ν 2 is greater than 105 then a χ 2 approximation is used; see Abramowitz and Stegun (1972).

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Hastings N A J and Peacock J B (1975) Statistical Distributions Butterworth

Error Indicators and Warnings

Note: g01fd may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
If on exit ifail=1, 2 or 4, then g01fd returns 0.0.
ifail=1
On entry, | p<0.0,
or | p≥1.0.
ifail=2
On entry, | df1≤0.0,
or | df2≤0.0.
ifail=3
The solution has not converged. The result should still be a reasonable approximation to the solution. Alternatively, g01fe can be used with a suitable setting of the parameter tol.
ifail=4
The value of p is too close to 0 or 1 for the value of fp to be computed. This will only occur when the large sample approximations are used.
ifail=-9000
An error occured, see message report.

Accuracy

The result should be accurate to five significant digits.

Parallelism and Performance

None.

Further Comments

For higher accuracy g01fe can be used along with the transformations given in [Description].

Example

This example reads the lower tail probabilities for several F-distributions, and calculates and prints the corresponding deviates until the end of data is reached.

Example program (C#): g01fde.cs

Example program data: g01fde.d

Example program results: g01fde.r

See Also

G01 Class
G01 Members


g01fe Method

[image]

NAG Library for .NET Release 2
G01..::g01fe Method
G01 Class See Also Send Feedback
g01fe returns the deviate associated with the given lower tail probability of the beta distribution.

Syntax

C#
public static double g01fe(
    double p,
    double a,
    double b,
    double tol,
    out int ifail
)
Visual Basic
Public Shared Function g01fe ( _
    p As Double, _
    a As Double, _
    b As Double, _
    tol As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01fe(
    double p,
    double a,
    double b,
    double tol,
    [OutAttribute] int% ifail
)
F#
static member g01fe :
        p : float *
        a : float *
        b : float *
        tol : float *
        ifail : int byref -> float

Parameters

p
Type: System..::..Double
On entry: p, the lower tail probability from the required beta distribution.
Constraint: 0.0≤p≤1.0.
a
Type: System..::..Double
On entry: a, the first parameter of the required beta distribution.
Constraint: 0.0<a≤106.
b
Type: System..::..Double
On entry: b, the second parameter of the required beta distribution.
Constraint: 0.0<b≤106.
tol
Type: System..::..Double
On entry: the relative accuracy required by you in the result. If g01fe is entered with tol greater than or equal to 1.0 or less than 10×machine precision (see x02aj), then the value of 10×machine precision is used instead.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01fe returns the deviate associated with the given lower tail probability of the beta distribution.

Description

The deviate, βp, associated with the lower tail probability, p, of the beta distribution with parameters a and b is defined as the solution to
P B≤βp:a,b=p=Γ a+bΓ a Γ b∫0 βp B a-11-B b-1 dB,  0≤βp≤1;a,b>0.
The algorithm is a modified version of the Newton–Raphson method, following closely that of Cran et al. (1977).
An initial approximation, β 0, to βp is found (see Cran et al. (1977)), and the Newton–Raphson iteration
βi=β i-1-f β i-1f′β i-1,
where f β=P B≤β:a,b-p is used, with modifications to ensure that β remains in the range 0,1.

References

Cran G W, Martin K J and Thomas G E (1977) Algorithm AS 109. Inverse of the incomplete beta function ratio Appl. Statist. 26 111–114
Hastings N A J and Peacock J B (1975) Statistical Distributions Butterworth

Error Indicators and Warnings

Note: g01fe may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
If on exit ifail=1 or 2, then g01fe returns 0.0.
ifail=1
On entry, | p<0.0,
or | p>1.0.
ifail=2
On entry, | a≤0.0,
or | a>106,
or | b≤0.0,
or | b>106.
ifail=3
There is doubt concerning the accuracy of the computed result. 100 iterations of the Newton–Raphson method have been performed without satisfying the accuracy criterion (see [Accuracy]). The result should be a reasonable approximation of the solution.
ifail=4
Requested accuracy not achieved when calculating beta probability. The result should be a reasonable approximation to the correct solution. You should try setting tol larger.
ifail=-9000
An error occured, see message report.

Accuracy

The required precision, given by tol, should be achieved in most circumstances.

Parallelism and Performance

None.

Further Comments

The typical timing will be several times that of g01ee and will be very dependent on the input parameter values. See g01ee for further comments on timings.

Example

This example reads lower tail probabilities for several beta distributions and calculates and prints the corresponding deviates until the end of data is reached.

Example program (C#): g01fee.cs

Example program data: g01fee.d

Example program results: g01fee.r

See Also

G01 Class
G01 Members


g01ff Method

[image]

NAG Library for .NET Release 2
G01..::g01ff Method
G01 Class See Also Send Feedback
g01ff returns the deviate associated with the given lower tail probability of the gamma distribution.

Syntax

C#
public static double g01ff(
    double p,
    double a,
    double b,
    double tol,
    out int ifail
)
Visual Basic
Public Shared Function g01ff ( _
    p As Double, _
    a As Double, _
    b As Double, _
    tol As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01ff(
    double p,
    double a,
    double b,
    double tol,
    [OutAttribute] int% ifail
)
F#
static member g01ff :
        p : float *
        a : float *
        b : float *
        tol : float *
        ifail : int byref -> float

Parameters

p
Type: System..::..Double
On entry: p, the lower tail probability from the required gamma distribution.
Constraint: 0.0≤p<1.0.
a
Type: System..::..Double
On entry: α, the shape parameter of the gamma distribution.
Constraint: 0.0<a≤106.
b
Type: System..::..Double
On entry: β, the scale parameter of the gamma distribution.
Constraint: b>0.0.
tol
Type: System..::..Double
On entry: the relative accuracy required by you in the results. The smallest recommended value is 50×δ, where δ=max 10-18,machine precision. If g01ff is entered with tol less than 50×δ or greater or equal to 1.0, then 50×δ is used instead.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01ff returns the deviate associated with the given lower tail probability of the gamma distribution.

Description

The deviate, gp, associated with the lower tail probability, p, of the gamma distribution with shape parameter α and scale parameter β, is defined as the solution to
P G≤gp:α,β=p=1 βα Γ α∫0 gp e-G/βG α-1 dG,  0≤gp<∞;α,β>0.
The method used is described by Best and Roberts (1975) making use of the relationship between the gamma distribution and the χ 2-distribution.
Let y=2 gp β. The required y is found from the Taylor series expansion
y=y 0+∑r Cr y 0r!E ϕ y 0 r,
where y 0 is a starting approximation
  • C 1 u=1,
  • C r+1 u=rΨ+d du Cr u,
  • Ψ=12-α-1 u,
  • E=p-∫0 y 0 ϕ u du,
  • ϕ u=1 2 α Γ α e-u/2u α-1.
For most values of p and α the starting value
y 01=2 α z⁢1 9 α+1-1 9 α 3
is used, where z is the deviate associated with a lower tail probability of p for the standard Normal distribution.
For p close to zero,
y 02=pα 2 α Γ α 1/α
is used.
For large p values, when y 01>4.4 α+6.0,
y 03=-2 ln 1-p-α-1 ln 12 y 01+ln Γ α
is found to be a better starting value than y 01.
For small α α≤0.16, p is expressed in terms of an approximation to the exponential integral and y 04 is found by Newton–Raphson iterations.
Seven terms of the Taylor series are used to refine the starting approximation, repeating the process if necessary until the required accuracy is obtained.

References

Best D J and Roberts D E (1975) Algorithm AS 91. The percentage points of the χ 2 distribution Appl. Statist. 24 385–388

Error Indicators and Warnings

Note: g01ff may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
If on exit ifail=1, 2, 3 or 5, then g01ff returns 0.0.
ifail=1
On entry, | p<0.0,
or | p≥1.0,
ifail=2
On entry, | a≤0.0,
or | a>106,
or | b≤0.0
ifail=3
p is too close to 0.0 or 1.0 to enable the result to be calculated.
ifail=4
The solution has failed to converge in 100 iterations. A larger value of tol should be tried. The result may be a reasonable approximation.
ifail=5
The series to calculate the gamma function has failed to converge. This is an unlikely error exit.
ifail=-9000
An error occured, see message report.

Accuracy

In most cases the relative accuracy of the results should be as specified by tol. However, for very small values of α or very small values of p there may be some loss of accuracy.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads lower tail probabilities for several gamma distributions, and calculates and prints the corresponding deviates until the end of data is reached.

Example program (C#): g01ffe.cs

Example program data: g01ffe.d

Example program results: g01ffe.r

See Also

G01 Class
G01 Members


g01fm Method

[image]

NAG Library for .NET Release 2
G01..::g01fm Method
G01 Class See Also Send Feedback
g01fm returns the deviate associated with the lower tail probability of the distribution of the Studentized range statistic.

Syntax

C#
public static double g01fm(
    double p,
    double v,
    int ir,
    out int ifail
)
Visual Basic
Public Shared Function g01fm ( _
    p As Double, _
    v As Double, _
    ir As Integer, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01fm(
    double p,
    double v,
    int ir,
    [OutAttribute] int% ifail
)
F#
static member g01fm :
        p : float *
        v : float *
        ir : int *
        ifail : int byref -> float

Parameters

p
Type: System..::..Double
On entry: the lower tail probability for the Studentized range statistic, p 0.
Constraint: 0.0<p<1.0.
v
Type: System..::..Double
On entry: v, the number of degrees of freedom.
Constraint: v≥1.0.
ir
Type: System..::..Int32
On entry: r, the number of groups.
Constraint: ir≥2.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01fm returns the deviate associated with the lower tail probability of the distribution of the Studentized range statistic.

Description

The externally Studentized range, q, for a sample, x 1,x 2,…,xr, is defined as
q=max xi-min xi σ^e,
where σ^e is an independent estimate of the standard error of the xi. The most common use of this statistic is in the testing of means from a balanced design. In this case for a set of group means, T-1,T-2,…,T-r, the Studentized range statistic is defined to be the difference between the largest and smallest means, T-largest and T-smallest, divided by the square root of the mean-square experimental error, M S error, over the number of observations in each group, n, i.e.,
q=T-largest-T-smallestM S error/n.
The Studentized range statistic can be used as part of a multiple comparisons procedure such as the Newman–Keuls procedure or Duncan's multiple range test (see Montgomery (1984) and Winer (1970)).
For a Studentized range statistic the probability integral, P q;v,r, for v degrees of freedom and r groups, can be written as:
P q;v,r=C∫0∞x v-1e-v x 2/2 r∫-∞∞ϕ y Φ y-Φ y-qxr-1 dy dx,
where
C=v v/2 Γ v/2 2 v/2-1,  ϕ y=1 2 π e-y 2/2  and  Φ y=∫-∞y ϕ t dt.
For a given probability p 0, the deviate q 0 is found as the solution to the equation
P q 0;v,r=p 0, (1)
using c05az . Initial estimates are found using the approximation given in Lund and Lund (1983) and a simple search procedure.

References

Lund R E and Lund J R (1983) Algorithm AS 190: probabilities and upper quartiles for the studentized range Appl. Statist. 32(2) 204–210
Montgomery D C (1984) Design and Analysis of Experiments Wiley
Winer B J (1970) Statistical Principles in Experimental Design McGraw–Hill

Error Indicators and Warnings

Note: g01fm may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
If on exit ifail=1, then g01fm returns 0.0.
ifail=1
On entry, | p≤0.0,
or | p≥1.0,
or | v<1.0,
or | ir<2.
ifail=2
The method was unable to find an upper bound for the value of q 0. This will be caused by p 0 being too close to 1.0.
ifail=3
There is some doubt as to whether full accuracy has been achieved. The returned value should be a reasonable estimate of the true value.
ifail=-9000
An error occured, see message report.

Accuracy

The returned solution, q*, to equation (1) is determined so that at least one of the following criteria apply.
(a) | P q*;v,r-p 0≤0.000005
(b) | q 0-q*≤0.000005×max 1.0,q*.

Parallelism and Performance

None.

Further Comments

To obtain the factors for Duncan's multiple-range test, equation (1) has to be solved for p 1, where p 1=p 0 r-1, so on input p should be set to p 0 r-1.

Example

Three values of p, ν and r are read in and the Studentized range deviates or quantiles are computed and printed.

Example program (C#): g01fme.cs

Example program data: g01fme.d

Example program results: g01fme.r

See Also

G01 Class
G01 Members


g01ft Method

[image]

NAG Library for .NET Release 2
G01..::g01ft Method
G01 Class See Also Send Feedback
g01ft returns the value of the inverse Φ-1 x of the Landau distribution function.

Syntax

C#
public static double g01ft(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function g01ft ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01ft(
    double x,
    [OutAttribute] int% ifail
)
F#
static member g01ft :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
Constraint: 0.0<x<1.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01ft returns the value of the inverse Φ-1 x of the Landau distribution function.

Description

g01ft evaluates an approximation to the inverse Φ-1 x of the Landau distribution function given by
Ψ x=Φ-1 x
(where Φ λ is described in g01et and g01mt), using either linear or quadratic interpolation or rational approximations which mimic the asymptotic behaviour. Further details can be found in Kölbig and Schorr (1984).
It can also be used to generate Landau distributed random numbers in the range 0<x<1.

References

Kölbig K S and Schorr B (1984) A program package for the Landau distribution Comp. Phys. Comm. 31 97–111

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | x≤0.0,
or | x≥1.0.
ifail=-9000
An error occured, see message report.

Accuracy

At least 5-6 significant digits are correct. Such accuracy is normally considered to be adequate for applications in large scale Monte–Carlo simulations.

Parallelism and Performance

None.

Further Comments

None.

Example

This example evaluates Φ-1 x at x=0.5, and prints the results.

Example program (C#): g01fte.cs

Example program data: g01fte.d

Example program results: g01fte.r

See Also

G01 Class
G01 Members


g01gb Method

[image]

NAG Library for .NET Release 2
G01..::g01gb Method
G01 Class See Also Send Feedback
g01gb returns the lower tail probability for the noncentral Student's t-distribution.

Syntax

C#
public static double g01gb(
    double t,
    double df,
    double delta,
    double tol,
    int maxit,
    out int ifail
)
Visual Basic
Public Shared Function g01gb ( _
    t As Double, _
    df As Double, _
    delta As Double, _
    tol As Double, _
    maxit As Integer, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01gb(
    double t,
    double df,
    double delta,
    double tol,
    int maxit,
    [OutAttribute] int% ifail
)
F#
static member g01gb :
        t : float *
        df : float *
        delta : float *
        tol : float *
        maxit : int *
        ifail : int byref -> float

Parameters

t
Type: System..::..Double
On entry: t, the deviate from the Student's t-distribution with ν degrees of freedom.
df
Type: System..::..Double
On entry: ν, the degrees of freedom of the Student's t-distribution.
Constraint: df≥1.0.
delta
Type: System..::..Double
On entry: δ, the noncentrality parameter of the Students t-distribution.
tol
Type: System..::..Double
On entry: the absolute accuracy required by you in the results. If g01gb is entered with tol greater than or equal to 1.0 or less than 10×machine precision (see x02aj), then the value of 10×machine precision is used instead.
maxit
Type: System..::..Int32
On entry: the maximum number of terms that are used in each of the summations.
Suggested value: 100. See [Further Comments] for further comments.
Constraint: maxit≥1.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01gb returns the lower tail probability for the noncentral Student's t-distribution.

Description

The lower tail probability of the noncentral Student's t-distribution with ν degrees of freedom and noncentrality parameter δ, P T≤t:ν;δ, is defined by
P T≤t:ν;δ=Cν∫0∞1 2 π∫-∞αu-δ e-x 2/2 dx u ν-1e-u 2/2 du,  ν>0.0
with
Cν=1 Γ 12 ν 2 ν-2/2,  α=t ν.
The probability is computed in one of two ways.
(i) When t=0.0, the relationship to the normal is used:
P T≤t:ν;δ=1 2 π∫δ∞e-u 2/2 du.
(ii) Otherwise the series expansion described in Equation 9 of Amos (1964) is used. This involves the sums of confluent hypergeometric functions, the terms of which are computed using recurrence relationships.

References

Amos D E (1964) Representations of the central and non-central t-distributions Biometrika 51 451–458

Error Indicators and Warnings

Errors or warnings detected by the method:
If on exit ifail≠0, then g01gb returns 0.0.
ifail=1
On entry, df<1.0.
ifail=2
On entry, maxit<1.
ifail=3
One of the series has failed to converge. Reconsider the requested tolerance and/or maximum number of iterations.
ifail=4
The probability is too small to calculate accurately.
ifail=-9000
An error occured, see message report.

Accuracy

The series described in Amos (1964) are summed until an estimated upper bound on the contribution of future terms to the probability is less than tol. There may also be some loss of accuracy due to calculation of gamma functions.

Parallelism and Performance

None.

Further Comments

The rate of convergence of the series depends, in part, on the quantity t 2/t 2+ν. The smaller this quantity the faster the convergence. Thus for large t and small ν the convergence may be slow. If ν is an integer then one of the series to be summed is of finite length.
If two tail probabilities are required then the relationship of the t-distribution to the F-distribution can be used:
F=T 2,λ=δ 2,ν 1=1  and  ν 2=ν,
and a call made to g01gd.
Note that g01gb only allows degrees of freedom greater than or equal to 1 although values between 0 and 1 are theoretically possible.

Example

This example reads values from, and degrees of freedom for, and noncentrality parameters of the noncentral Student's t-distributions, calculates the lower tail probabilities and prints all these values until the end of data is reached.

Example program (C#): g01gbe.cs

Example program data: g01gbe.d

Example program results: g01gbe.r

See Also

G01 Class
G01 Members


g01gc Method

[image]

NAG Library for .NET Release 2
G01..::g01gc Method
G01 Class See Also Send Feedback
g01gc returns the probability associated with the lower tail of the noncentral χ 2-distribution .

Syntax

C#
public static double g01gc(
    double x,
    double df,
    double rlamda,
    double tol,
    int maxit,
    out int ifail
)
Visual Basic
Public Shared Function g01gc ( _
    x As Double, _
    df As Double, _
    rlamda As Double, _
    tol As Double, _
    maxit As Integer, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01gc(
    double x,
    double df,
    double rlamda,
    double tol,
    int maxit,
    [OutAttribute] int% ifail
)
F#
static member g01gc :
        x : float *
        df : float *
        rlamda : float *
        tol : float *
        maxit : int *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the deviate from the noncentral χ 2-distribution with ν degrees of freedom and noncentrality parameter λ.
Constraint: x≥0.0.
df
Type: System..::..Double
On entry: ν, the degrees of freedom of the noncentral χ 2-distribution.
Constraint: df≥0.0.
rlamda
Type: System..::..Double
On entry: λ, the noncentrality parameter of the noncentral χ 2-distribution.
Constraint: rlamda≥0.0 if df>0.0 or rlamda>0.0 if df=0.0.
tol
Type: System..::..Double
On entry: the required accuracy of the solution. If g01gc is entered with tol greater than or equal to 1.0 or less than 10×machine precision (see x02aj), then the value of 10×machine precision is used instead.
maxit
Type: System..::..Int32
On entry: the maximum number of iterations to be performed.
Suggested value: 100. See [Further Comments] for further discussion.
Constraint: maxit≥1.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01gc returns the probability associated with the lower tail of the noncentral χ 2-distribution .

Description

The lower tail probability of the noncentral χ 2-distribution with ν degrees of freedom and noncentrality parameter λ, P X≤x:ν;λ, is defined by
P X≤x:ν;λ=∑j=0∞e-λ/2 λ/2 j j!P X≤x:ν+2 j;0, (1)
where P X≤x:ν+2 j;0 is a central χ 2-distribution with ν+2 j degrees of freedom.
The value of j at which the Poisson weight, e-λ/2 λ/2 j j!, is greatest is determined and the summation (1) is made forward and backward from that value of j.
The recursive relationship:
P X≤x:a+2;0=P X≤x:a;0-xa/2 e-x/2Γ a+1 (2)
is used during the summation in (1).

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Note: g01gc may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
If on exit ifail=1, 2, 4 or 5, then g01gc returns 0.0.
ifail=1
On entry, | df<0.0,
or | rlamda<0.0,
or | df=0.0 and rlamda=0.0,
or | x<0.0,
or | maxit<1.
ifail=2
The initial value of the Poisson weight used in the summation (1) was too small to be calculated. The value of P x≤x:ν;λ is likely to be zero.
ifail=3
The solution has failed to converge in maxit iterations.
ifail=4
The value of a term required in (2) is too large to be evaluated accurately. The most likely cause of this error is both x and rlamda being very large.
ifail=5
The calculations for the central χ 2 probability has failed to converge. This is an unlikely error exit. A larger value of tol should be used.
ifail=-9000
An error occured, see message report.

Accuracy

The summations described in [Description] are made until an upper bound on the truncation error relative to the current summation value is less than tol.

Parallelism and Performance

None.

Further Comments

The number of terms in (1) required for a given accuracy will depend on the following factors:
(i) | The rate at which the Poisson weights tend to zero. This will be slower for larger values of λ.
(ii) | The rate at which the central χ 2 probabilities tend to zero. This will be slower for larger values of ν and x.

Example

This example reads values from various noncentral χ 2-distributions, calculates the lower tail probabilities and prints all these values until the end of data is reached.

Example program (C#): g01gce.cs

Example program data: g01gce.d

Example program results: g01gce.r

See Also

G01 Class
G01 Members


g01gd Method

[image]

NAG Library for .NET Release 2
G01..::g01gd Method
G01 Class See Also Send Feedback
g01gd returns the probability associated with the lower tail of the noncentral F or variance-ratio distribution.

Syntax

C#
public static double g01gd(
    double f,
    double df1,
    double df2,
    double rlamda,
    double tol,
    int maxit,
    out int ifail
)
Visual Basic
Public Shared Function g01gd ( _
    f As Double, _
    df1 As Double, _
    df2 As Double, _
    rlamda As Double, _
    tol As Double, _
    maxit As Integer, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01gd(
    double f,
    double df1,
    double df2,
    double rlamda,
    double tol,
    int maxit,
    [OutAttribute] int% ifail
)
F#
static member g01gd :
        f : float *
        df1 : float *
        df2 : float *
        rlamda : float *
        tol : float *
        maxit : int *
        ifail : int byref -> float

Parameters

f
Type: System..::..Double
On entry: f, the deviate from the noncentral F-distribution.
Constraint: f>0.0.
df1
Type: System..::..Double
On entry: the degrees of freedom of the numerator variance, ν 1.
Constraint: 0.0<df1≤106.
df2
Type: System..::..Double
On entry: the degrees of freedom of the denominator variance, ν 2.
Constraint: df2>0.0.
rlamda
Type: System..::..Double
On entry: λ, the noncentrality parameter.
Constraint: 0.0≤rlamda≤-2.0log U where U is the safe range parameter as defined by x02am.
tol
Type: System..::..Double
On entry: the relative accuracy required by you in the results. If g01gd is entered with tol greater than or equal to 1.0 or less than 10×machine precision (see x02aj), then the value of 10×machine precision is used instead.
maxit
Type: System..::..Int32
On entry: the maximum number of iterations to be used.
Suggested value: 500. See g01gc and g01ge for further details.
Constraint: maxit≥1.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01gd returns the probability associated with the lower tail of the noncentral F or variance-ratio distribution.

Description

The lower tail probability of the noncentral F-distribution with ν 1 and ν 2 degrees of freedom and noncentrality parameter λ, P F≤f:ν 1,ν 2;λ, is defined by
P F≤f:ν 1,ν 2;λ=∫0 x p F:ν 1,ν 2;λ dF,
where
P F:ν 1,ν 2;λ=∑j=0∞e-λ/2 λ/2 j j!×ν 1+2 j ν 1+2 j/2 ν 2 ν 2/2B ν 1+2 j/2,ν 2/2
×u ν 1+2 j-2/2ν 2+ν 1+2 j u-ν 1+2 j+ν 2/2
and B·,· is the beta function.
The probability is computed by means of a transformation to a noncentral beta distribution:
P F≤f:ν 1,ν 2;λ=Pβ X≤x:a,b;λ,
where x=ν 1 fν 1 f+ν 2 and Pβ X≤x:a,b;λ is the lower tail probability integral of the noncentral beta distribution with parameters a, b, and λ.
If ν 2 is very large, greater than 106, then a χ 2 approximation is used.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Note: g01gd may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
If on exit ifail=1 or 3, then g01gd returns 0.0.
ifail=1
On entry, | df1≤0.0,
or | df1>106,
or | df2≤0.0,
or | f≤0.0,
or | rlamda<0.0,
or | maxit<1,
or | rlamda>-2.0log U, where U= safe range parameter as defined by x02am.
ifail=2
The solution has failed to converge in maxit iterations. You should try a larger value of maxit or tol.
ifail=3
The required probability cannot be computed accurately. This may happen if the result would be very close to 0.0 or 1.0. Alternatively the values of df1 and f may be too large. In the latter case you could try using a normal approximation; see Abramowitz and Stegun (1972).
ifail=4
The required accuracy was not achieved when calculating the initial value of the central F (or χ 2) probability. You should try a larger value of tol. If the χ 2 approximation is being used then g01gd returns zero otherwise the value returned should be an approximation to the correct value.
ifail=-9000
An error occured, see message report.

Accuracy

The relative accuracy should be as specified by tol. For further details see g01gc and g01ge.

Parallelism and Performance

None.

Further Comments

When both ν 1 and ν 2 are large a Normal approximation may be used and when only ν 1 is large a χ 2 approximation may be used. In both cases λ is required to be of the same order as ν 1. See Abramowitz and Stegun (1972) for further details.

Example

This example reads values from, and degrees of freedom for, F-distributions, computes the lower tail probabilities and prints all these values until the end of data is reached.

Example program (C#): g01gde.cs

Example program data: g01gde.d

Example program results: g01gde.r

See Also

G01 Class
G01 Members


g01ge Method

[image]

NAG Library for .NET Release 2
G01..::g01ge Method
G01 Class See Also Send Feedback
g01ge returns the probability associated with the lower tail of the noncentral beta distribution.

Syntax

C#
public static double g01ge(
    double x,
    double a,
    double b,
    double rlamda,
    double tol,
    int maxit,
    out int ifail
)
Visual Basic
Public Shared Function g01ge ( _
    x As Double, _
    a As Double, _
    b As Double, _
    rlamda As Double, _
    tol As Double, _
    maxit As Integer, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01ge(
    double x,
    double a,
    double b,
    double rlamda,
    double tol,
    int maxit,
    [OutAttribute] int% ifail
)
F#
static member g01ge :
        x : float *
        a : float *
        b : float *
        rlamda : float *
        tol : float *
        maxit : int *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: β, the deviate from the beta distribution, for which the probability P B≤β:a,b;λ is to be found.
Constraint: 0.0≤x≤1.0.
a
Type: System..::..Double
On entry: a, the first parameter of the required beta distribution.
Constraint: 0.0<a≤106.
b
Type: System..::..Double
On entry: b, the second parameter of the required beta distribution.
Constraint: 0.0<b≤106.
rlamda
Type: System..::..Double
On entry: λ, the noncentrality parameter of the required beta distribution.
Constraint: 0.0≤rlamda≤-2.0log U, where U is the safe range parameter as defined by x02am.
tol
Type: System..::..Double
On entry: the relative accuracy required by you in the results. If g01ge is entered with tol greater than or equal to 1.0 or less than 10×machine precision (see x02aj), then the value of 10×machine precision is used instead.
See [Accuracy] for the relationship between tol and maxit.
maxit
Type: System..::..Int32
On entry: the maximum number of iterations that the algorithm should use.
See [Accuracy] for suggestions as to suitable values for maxit for different values of the parameters.
Suggested value: 500.
Constraint: maxit≥1.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01ge returns the probability associated with the lower tail of the noncentral beta distribution.

Description

The lower tail probability for the noncentral beta distribution with parameters a and b and noncentrality parameter λ, P B≤β:a,b;λ, is defined by
P B≤β:a,b;λ=∑j=0∞e-λ/2 λ/2 j!P B≤β:a,b;0, (1)
where
P B≤β:a,b;0=Γ a+bΓ a Γ b∫0 β B a-11-B b-1 dB,
which is the central beta probability function or incomplete beta function.
Recurrence relationships given in Abramowitz and Stegun (1972) are used to compute the values of P B≤β:a,b;0 for each step of the summation (1).
The algorithm is discussed in Lenth (1987).

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Lenth R V (1987) Algorithm AS 226: Computing noncentral beta probabilities Appl. Statist. 36 241–244

Error Indicators and Warnings

Note: g01ge may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail=1
On entry, | a≤0.0,
or | a>106,
or | b≤0.0,
or | b>106,
or | rlamda<0.0,
or | rlamda>-2.0log U, where U= safe range parameter as defined by x02am,
or | x<0.0,
or | x>1.0,
or | maxit<1.
If on exit ifail=1 then g01ge returns zero.
ifail=2
The solution has failed to converge in maxit iterations. You should try a larger value of maxit or tol. The returned value will be an approximation to the correct value.
ifail=3
The probability is too close to 0.0 or 1.0 for the algorithm to be able to calculate the required probability. g01ge will return 0.0 or 1.0 as appropriate, this should be a reasonable approximation.
ifail=4
The required accuracy was not achieved when calculating the initial value of P B≤β:a,b;λ. You should try a larger value of tol. The returned value will be an approximation to the correct value.
ifail=-9000
An error occured, see message report.

Accuracy

Convergence is theoretically guaranteed whenever P Y>maxit≤tol where Y has a Poisson distribution with mean λ/2. Excessive round-off errors are possible when the number of iterations used is high and tol is close to machine precision. See Lenth (1987) for further comments on the error bound.

Parallelism and Performance

None.

Further Comments

The central beta probabilities can be obtained by setting rlamda=0.0.

Example

This example reads values for several beta distributions and calculates and prints the lower tail probabilities until the end of data is reached.

Example program (C#): g01gee.cs

Example program data: g01gee.d

Example program results: g01gee.r

See Also

G01 Class
G01 Members


g01ha Method

[image]

NAG Library for .NET Release 2
G01..::g01ha Method
G01 Class See Also Send Feedback
g01ha returns the lower tail probability for the bivariate Normal distribution.

Syntax

C#
public static double g01ha(
    double x,
    double y,
    double rho,
    out int ifail
)
Visual Basic
Public Shared Function g01ha ( _
    x As Double, _
    y As Double, _
    rho As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01ha(
    double x,
    double y,
    double rho,
    [OutAttribute] int% ifail
)
F#
static member g01ha :
        x : float *
        y : float *
        rho : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: x, the first argument for which the bivariate Normal distribution function is to be evaluated.
y
Type: System..::..Double
On entry: y, the second argument for which the bivariate Normal distribution function is to be evaluated.
rho
Type: System..::..Double
On entry: ρ, the correlation coefficient.
Constraint: -1.0≤rho≤1.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01ha returns the lower tail probability for the bivariate Normal distribution.

Description

For the two random variables X,Y following a bivariate Normal distribution with
E X=0,  E Y=0,  E X 2=1,  E Y 2=1  and  E XY=ρ,
the lower tail probability is defined by:
P X≤x,Y≤y:ρ=1 2 π⁢1-ρ 2∫-∞y∫-∞x exp-X 2-2 ρXY+Y 2 2 1-ρ 2 dXdY.
For a more detailed description of the bivariate Normal distribution and its properties see Abramowitz and Stegun (1972) and Kendall and Stuart (1969). The method used is described by Genz (2004).

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Genz A (2004) Numerical computation of rectangular bivariate and trivariate Normal and t probabilities Statistics and Computing 14 151–160
Kendall M G and Stuart A (1969) The Advanced Theory of Statistics (Volume 1) (3rd Edition) Griffin

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | rho<-1.0,
or | rho>1.0.
If on exit ifail=1 then g01ha returns zero.
ifail=-9000
An error occured, see message report.

Accuracy

Accuracy of the hybrid algorithm implemented here is discussed in Genz (2004). This algorithm should give a maximum absolute error of less than 5×10-16.

Parallelism and Performance

None.

Further Comments

The probabilities for the univariate Normal distribution can be computed using s15ab and s15ac.

Example

This example reads values of x and y for a bivariate Normal distribution along with the value of ρ and computes the lower tail probabilities.

Example program (C#): g01hae.cs

Example program data: g01hae.d

Example program results: g01hae.r

See Also

G01 Class
G01 Members


g01hb Method

[image]

NAG Library for .NET Release 2
G01..::g01hb Method
G01 Class See Also Send Feedback
g01hb returns the upper tail, lower tail or central probability associated with a multivariate Normal distribution of up to ten dimensions.

Syntax

C#
public static double g01hb(
    string tail,
    int n,
    double[] a,
    double[] b,
    double[] xmu,
    double[,] sig,
    double tol,
    out int ifail
)
Visual Basic
Public Shared Function g01hb ( _
    tail As String, _
    n As Integer, _
    a As Double(), _
    b As Double(), _
    xmu As Double(), _
    sig As Double(,), _
    tol As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01hb(
    String^ tail,
    int n,
    array<double>^ a,
    array<double>^ b,
    array<double>^ xmu,
    array<double,2>^ sig,
    double tol,
    [OutAttribute] int% ifail
)
F#
static member g01hb :
        tail : string *
        n : int *
        a : float[] *
        b : float[] *
        xmu : float[] *
        sig : float[,] *
        tol : float *
        ifail : int byref -> float

Parameters

tail
Type: System..::..String
On entry: indicates which probability is to be returned.
tail="L"
The lower tail probability is returned.
tail="U"
The upper tail probability is returned.
tail="C"
The central probability is returned.
Constraint: tail="L", "U" or "C".
n
Type: System..::..Int32
On entry: n, the number of dimensions.
Constraint: 1≤n≤10.
a
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: if tail="C" or "U", the lower bounds, ai, for i=1,2,…,n.
If tail="L", a is not referenced.
b
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: if tail="C" or "L", the upper bounds, bi, for i=1,2,…,n.
If tail="U" b, is not referenced.
Constraint: if tail="C", a[i-1]<b[i-1], for i=1,2,…,n.
xmu
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: μ, the mean vector of the multivariate Normal distribution.
sig
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: Σ, the variance-covariance matrix of the multivariate Normal distribution. Only the lower triangle is referenced.
Constraint: Σ must be positive definite.
tol
Type: System..::..Double
On entry: if n>2 the relative accuracy required for the probability, and if the upper or the lower tail probability is requested then tol is also used to determine the cut-off points, see [Accuracy].
If n=1, tol is not referenced.
Suggested value: tol=0.0001.
Constraint: if n>1, tol>0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01hb returns the upper tail, lower tail or central probability associated with a multivariate Normal distribution of up to ten dimensions.

Description

Let the vector random variable X=X 1,X 2,…,Xn T follow an n-dimensional multivariate Normal distribution with mean vector μ and n by n variance-covariance matrix Σ, then the probability density function, f X:μ,Σ, is given by
f X:μ,Σ=2 π-1/2 nΣ-1/2 exp-12 X-μ TΣ-1 X-μ.
The lower tail probability is defined by:
P X 1≤b 1,…,Xn≤bn:μ,Σ=∫-∞b 1⋯∫-∞bn f X:μ,Σ d Xn⋯d X 1.
The upper tail probability is defined by:
P X 1≥a 1,…,Xn≥an:μ,Σ=∫a 1∞⋯∫an∞f X:μ,Σ d Xn⋯d X 1.
The central probability is defined by:
P a 1≤X 1≤b 1,…,an≤Xn≤bn:μ,Σ=∫a 1 b 1⋯∫an bn f X:μ,Σ d Xn⋯d X 1.
To evaluate the probability for n≥3, the probability density function of X 1,X 2,…,Xn is considered as the product of the conditional probability of X 1,X 2,…,X n-2 given X n-1 and Xn and the marginal bivariate Normal distribution of X n-1 and Xn. The bivariate Normal probability can be evaluated as described in g01ha and numerical integration is then used over the remaining n-2 dimensions. In the case of n=3, d01aj is used and for n>3 d01fc is used.
To evaluate the probability for n=1 a direct call to g01ea is made and for n=2 calls to g01ha are made.

References

Kendall M G and Stuart A (1969) The Advanced Theory of Statistics (Volume 1) (3rd Edition) Griffin

Error Indicators and Warnings

Note: g01hb may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
If on exit ifail=1, 2 or 3, then g01hb returns zero.
Some error messages may refer to parameters that are dropped from this interface (LDSIG) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | n<1,
or | n>10,
or | tail≠"L", "U" or "C",
or | n>1 and tol≤0.0,
or | lwk is too small.
ifail=2
On entry, tail="C" and a[i-1]≥b[i-1], for some i=0,1,…,n-1.
ifail=3
On entry, Σ is not positive definite, i.e., is not a correct variance-covariance matrix.
ifail=4
The requested accuracy has not been achieved, a larger value of tol should be tried or the length of the workspace should be increased. The returned value will be an approximation to the required result.
ifail=5
Round-off error prevents the requested accuracy from being achieved; a larger value of tol should be tried. The returned value will be an approximation to the required result. This error will only occur if n=3.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The accuracy should be as specified by tol. When on exit ifail=4 the approximate accuracy achieved is given in the error message. For the upper and lower tail probabilities the infinite limits are approximated by cut-off points for the n-2 dimensions over which the numerical integration takes place; these cut-off points are given by Φ-1 tol/10×n, where Φ-1 is the inverse univariate Normal distribution function.

Parallelism and Performance

None.

Further Comments

The time taken is related to the number of dimensions, the range over which the integration takes place (bi-ai, for i=1,2,…,n) and the value of Σ as well as the accuracy required. As the numerical integration does not take place over the last two dimensions speed may be improved by arranging X so that the largest ranges of integration are for X n-1 and Xn.

Example

This example reads in the mean and covariance matrix for a multivariate Normal distribution and computes and prints the associated central probability.

Example program (C#): g01hbe.cs

Example program data: g01hbe.d

Example program results: g01hbe.r

See Also

G01 Class
G01 Members


g01jc Method

[image]

NAG Library for .NET Release 2
G01..::g01jc Method
G01 Class See Also Send Feedback
g01jc returns the lower tail probability of a distribution of a positive linear combination of χ 2 random variables.

Syntax

C#
public static void g01jc(
    double[] a,
    int[] mult,
    double[] rlamda,
    int n,
    double c,
    out double p,
    out double pdf,
    double tol,
    int maxit,
    out int ifail
)
Visual Basic
Public Shared Sub g01jc ( _
    a As Double(), _
    mult As Integer(), _
    rlamda As Double(), _
    n As Integer, _
    c As Double, _
    <OutAttribute> ByRef p As Double, _
    <OutAttribute> ByRef pdf As Double, _
    tol As Double, _
    maxit As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g01jc(
    array<double>^ a,
    array<int>^ mult,
    array<double>^ rlamda,
    int n,
    double c,
    [OutAttribute] double% p,
    [OutAttribute] double% pdf,
    double tol,
    int maxit,
    [OutAttribute] int% ifail
)
F#
static member g01jc :
        a : float[] *
        mult : int[] *
        rlamda : float[] *
        n : int *
        c : float *
        p : float byref *
        pdf : float byref *
        tol : float *
        maxit : int *
        ifail : int byref -> unit

Parameters

a
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the weights, a 1,a 2,…,an.
Constraint: a[i]>0.0, for i=0,1,…,n-1.
mult
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On entry: the degrees of freedom, m 1,m 2,…,mn.
Constraint: mult[i]≥1, for i=0,1,…,n-1.
rlamda
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the noncentrality parameters, λ 1,λ 2,…,λn.
Constraint: rlamda[i]≥0.0, for i=0,1,…,n-1.
n
Type: System..::..Int32
On entry: n, the number of χ 2 random variables in the combination, i.e., the number of terms in equation (1).
Constraint: n≥1.
c
Type: System..::..Double
On entry: c, the point for which the lower tail probability is to be evaluated.
Constraint: c≥0.0.
p
Type: System..::..Double %
On exit: the lower tail probability associated with the linear combination of n χ 2 random variables with mj degrees of freedom, and noncentrality parameters λj, for j=1,2,…,n.
pdf
Type: System..::..Double %
On exit: the value of the probability density function of the linear combination of χ 2 variables.
tol
Type: System..::..Double
On entry: the relative accuracy required by you in the results. If g01jc is entered with tol greater than or equal to 1.0 or less than 10×machine precision (see x02aj), then the value of 10×machine precision is used instead.
maxit
Type: System..::..Int32
On entry: the maximum number of terms that should be used during the summation.
Suggested value: 500.
Constraint: maxit≥1.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

For a linear combination of noncentral χ 2 random variables with integer degrees of freedom the lower tail probability is
P∑j=1 n aj χ 2 mj,λj≤c, (1)
where aj and c are positive constants and where χ 2 mj,λj represents an independent χ 2 random variable with mj degrees of freedom and noncentrality parameter λj. The linear combination may arise from considering a quadratic form in Normal variables.
Ruben's method as described in Farebrother (1984) is used. Ruben has shown that (1) may be expanded as an infinite series of the form
∑k=0∞dk F m+2 k,c/β, (2)
where F m+2 k,c/β=P χ 2 m+2 k<c/β, i.e., the probability that a central χ 2 is less than c/β.
The value of β is set at
β=βB=2 1/amin+1/amax
unless βB>1.8 amin, in which case
β=βA=amin
is used, where amin=min aj and amax=max aj, for j=1,2,…,n.

References

Farebrother R W (1984) The distribution of a positive linear combination of χ 2 random variables Appl. Statist. 33(3)

Error Indicators and Warnings

Note: g01jc may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
If on exit ifail=1 or 2, then g01jc returns 0.0.
ifail=1
On entry, | n<1,
or | maxit<1,
or | c<0.0.
ifail=2
On entry, | a has an element ≤0.0,
or | mult has an element <1,
or | rlamda has an element <0.0.
ifail=3
The central χ 2 calculation has failed to converge. This is an unlikely exit. A larger value of tol should be tried.
ifail=4
The solution has failed to converge within maxit iterations. A larger value of maxit or tol should be used. The returned value should be a reasonable approximation to the correct value.
ifail=5
The solution appears to be too close to 0 or 1 for accurate calculation. The value returned is 0 or 1 as appropriate.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The series (2) is summed until a bound on the truncation error is less than tol. See Farebrother (1984) for further discussion.

Parallelism and Performance

None.

Further Comments

None.

Example

The number of χ 2 variables is read along with their coefficients, degrees of freedom and noncentrality parameters. The lower tail probability is then computed and printed.

Example program (C#): g01jce.cs

Example program data: g01jce.d

Example program results: g01jce.r

See Also

G01 Class
G01 Members


g01jd Method

[image]

NAG Library for .NET Release 2
G01..::g01jd Method
G01 Class See Also Send Feedback
g01jd calculates the lower tail probability for a linear combination of (central) χ 2 variables.

Syntax

C#
public static void g01jd(
    string method,
    int n,
    double[] rlam,
    double d,
    double c,
    out double prob,
    out int ifail
)
Visual Basic
Public Shared Sub g01jd ( _
    method As String, _
    n As Integer, _
    rlam As Double(), _
    d As Double, _
    c As Double, _
    <OutAttribute> ByRef prob As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g01jd(
    String^ method,
    int n,
    array<double>^ rlam,
    double d,
    double c,
    [OutAttribute] double% prob,
    [OutAttribute] int% ifail
)
F#
static member g01jd :
        method : string *
        n : int *
        rlam : float[] *
        d : float *
        c : float *
        prob : float byref *
        ifail : int byref -> unit

Parameters

method
Type: System..::..String
On entry: indicates whether Pan's, Imhof's or an appropriately selected procedure is to be used.
method="P"
Pan's method is used.
method="I"
Imhof's method is used.
method="D"
Pan's method is used if λi*, for i=1,2,…,n are at least 1% distinct and n≤60; otherwise Imhof's method is used.
Constraint: method="P", "I" or "D".
n
Type: System..::..Int32
On entry: n, the number of independent standard Normal variates, (central χ 2 variates).
Constraint: n≥1.
rlam
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the weights, λi, for i=1,2,…,n, of the central χ 2 variables.
Constraint: rlam[i-1]≠d for at least one i. If method="P", then the λi* must be at least 1% distinct; see [Further Comments], for i=1,2,…,n.
d
Type: System..::..Double
On entry: d, the multiplier of the central χ 2 variables.
Constraint: d≥0.0.
c
Type: System..::..Double
On entry: c, the value of the constant.
prob
Type: System..::..Double %
On exit: the lower tail probability for the linear combination of central χ 2 variables.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Let u 1,u 2,…,un be independent Normal variables with mean zero and unit variance, so that u 12,u 22,…,un 2 have independent χ 2-distributions with unit degrees of freedom. g01jd evaluates the probability that
λ 1 u 12+λ 2 u 22+⋯+λn un 2<d u 12+u 22+⋯+un 2+c.
If c=0.0 this is equivalent to the probability that
λ 1 u 12+λ 2 u 22+⋯+λn un 2u 12+u 22+⋯+un 2<d.
Alternatively let
λi*=λi-d,   ​i=1,2,…,n,
then g01jd returns the probability that
λ 1*u 12+λ 2*u 22+⋯+λn*un 2<c.
Two methods are available. One due to Pan (1964) (see Farebrother (1980)) makes use of series approximations. The other method due to Imhof (1961) reduces the problem to a one-dimensional integral. If n≥6 then a non-adaptive method described in d01bd is used to compute the value of the integral otherwise d01aj is used.
Pan's procedure can only be used if the λi* are sufficiently distinct; g01jd requires the λi* to be at least 1% distinct; see [Further Comments]. If the λi* are at least 1% distinct and n≤60, then Pan's procedure is recommended; otherwise Imhof's procedure is recommended.

References

Farebrother R W (1980) Algorithm AS 153. Pan's procedure for the tail probabilities of the Durbin–Watson statistic Appl. Statist. 29 224–227
Imhof J P (1961) Computing the distribution of quadratic forms in Normal variables Biometrika 48 419–426
Pan Jie–Jian (1964) Distributions of the noncircular serial correlation coefficients Shuxue Jinzhan 7 328–337

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | n<1,
or | d<0.0,
or | method≠"P", "I" or "D".
ifail=2
On entry, rlam[i-1]=d for all values of i, for i=1,2,…,n.
ifail=3
On entry, method="P" yet two successive values of the ordered λi*, for i=1,2,…,n, were not at least 1% distinct.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

On successful exit at least four decimal places of accuracy should be achieved.

Parallelism and Performance

None.

Further Comments

Pan's procedure can only work if the λi* are sufficiently distinct. g01jd uses the check wj-w j-1≥0.01×max wj,w j-1, where the wj are the ordered nonzero values of λi*.
For the situation when all the λi are positive g01jc may be used. If the probabilities required are for the Durbin–Watson test, then the bounds for the probabilities are given by g01ep.

Example

For n=10, the choice of method, values of c and d and the λi are input and the probabilities computed and printed.

Example program (C#): g01jde.cs

Example program data: g01jde.d

Example program results: g01jde.r

See Also

G01 Class
G01 Members


g01mb Method

[image]

NAG Library for .NET Release 2
G01..::g01mb Method
G01 Class See Also Send Feedback
g01mb returns the reciprocal of Mills' Ratio.

Syntax

C#
public static double g01mb(
    double x
)
Visual Basic
Public Shared Function g01mb ( _
    x As Double _
) As Double
Visual C++
public:
static double g01mb(
    double x
)
F#
static member g01mb :
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: x, the argument of the reciprocal of Mills' Ratio.

Return Value

g01mb returns the reciprocal of Mills' Ratio.

Description

g01mb calculates the reciprocal of Mills' Ratio, the hazard rate, λ x, for the standard Normal distribution. It is defined as the ratio of the ordinate to the upper tail area of the standard Normal distribution, that is,
λ x=Z xQ x=1 2 π e-x 2/21 2 π∫x∞e-t 2/2 dt.
The calculation is based on a Chebyshev expansion as described in s15ag.

References

Gross A J and Clark V A (1975) Survival Distributions: Reliability Applications in the Biomedical Sciences Wiley

Error Indicators and Warnings

None.

Accuracy

In the left-hand tail, x<0.0, if 12 e-1/2 x 2≤ the safe range parameter (x02am), then 0.0 is returned, which is close to the true value.
The relative accuracy is bounded by the effective machine precision. See s15ag for further discussion.

Parallelism and Performance

None.

Further Comments

If, before entry, x is not a standard Normal variable, it has to be standardized, and on exit, g01mb has to be divided by the standard deviation. That is, if the Normal distribution has mean μ and variance σ 2, then its hazard rate, λ x;μ,σ 2, is given by
λ x;μ,σ 2=λ x-μ/σ/σ.

Example

The hazard rate is evaluated at different values of x for Normal distributions with different means and variances. The results are then printed.

Example program (C#): g01mbe.cs

Example program data: g01mbe.d

Example program results: g01mbe.r

See Also

G01 Class
G01 Members


g01mt Method

[image]

NAG Library for .NET Release 2
G01..::g01mt Method
G01 Class See Also Send Feedback
g01mt returns the value of the Landau density function ϕ λ.

Syntax

C#
public static double g01mt(
    double x
)
Visual Basic
Public Shared Function g01mt ( _
    x As Double _
) As Double
Visual C++
public:
static double g01mt(
    double x
)
F#
static member g01mt :
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the argument λ of the function.

Return Value

g01mt returns the value of the Landau density function ϕ λ.

Description

g01mt evaluates an approximation to the Landau density function ϕ λ given by
ϕ λ=1 2 πi∫c-i∞c+i∞exp λs+s ln sds,
where c is an arbitrary real constant, using piecewise approximation by rational functions. Further details can be found in Kölbig and Schorr (1984).
To obtain the value of ϕ′λ, g01rt can be used.

References

Kölbig K S and Schorr B (1984) A program package for the Landau distribution Comp. Phys. Comm. 31 97–111

Error Indicators and Warnings

There are no failure exits from this routine.

Accuracy

At least 7 significant digits are usually correct, but occasionally only 6. Such accuracy is normally considered to be adequate for applications in experimental physics.
Because of the asymptotic behaviour of ϕ λ, which is of the order of exp-exp-λ, underflow may occur on some machines when λ is moderately large and negative.

Parallelism and Performance

None.

Further Comments

None.

Example

This example evaluates ϕ λ at λ=0.5, and prints the results.

Example program (C#): g01mte.cs

Example program data: g01mte.d

Example program results: g01mte.r

See Also

G01 Class
G01 Members


g01mu Method

[image]

NAG Library for .NET Release 2
G01..::g01mu Method
G01 Class See Also Send Feedback
g01mu returns the value of the Vavilov density function ϕV λ;κ,β 2.
It is intended to be used after a call to g01zu.

Syntax

C#
public static double g01mu(
    double x,
    double[] rcomm,
    out int ifail
)
Visual Basic
Public Shared Function g01mu ( _
    x As Double, _
    rcomm As Double(), _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double g01mu(
    double x,
    array<double>^ rcomm,
    [OutAttribute] int% ifail
)
F#
static member g01mu :
        x : float *
        rcomm : float[] *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument λ of the function.
rcomm
Type: array< System..::..Double >[]()[][]
An array of size [322]
On entry: this must be the same parameter rcomm as returned by a previous call to g01zu.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g01mu returns the value of the Vavilov density function ϕV λ;κ,β 2.
It is intended to be used after a call to g01zu.

Description

g01mu evaluates an approximation to the Vavilov density function ϕV λ;κ,β 2 given by
ϕV λ;κ,β 2=1 2 πi∫c-i∞c+i∞e λs f s;κ,β 2 ds,
where κ>0 and 0≤β 2≤1, c is an arbitrary real constant and
f s;κ,β 2=C κ,β 2 exp s ln κ+s+κ β 2ln sκ+E 1 sκ-κ exp-sκ.
E 1 x=∫0 x t-1 1-e-t dt is the exponential integral, C κ,β 2=exp κ 1+γ β 2 and γ is Euler's constant.
The method used is based on Fourier expansions. Further details can be found in Schorr (1974).
For values of κ≤0.01, the Vavilov distribution can be replaced by the Landau distribution since λV=λL-ln κ/κ. For values of κ≥10, the Vavilov distribution can be replaced by a Gaussian distribution with mean μ=γ-1-β 2-ln κ and variance σ 2=2-β 2/2 κ.

References

Schorr B (1974) Programs for the Landau and the Vavilov distributions and the corresponding random numbers Comp. Phys. Comm. 7 215–224

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
Either the initialization method has not been called prior to the first call of this method or a communication array has become corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

At least five significant digits are usually correct.

Parallelism and Performance

None.

Further Comments

g01mu can be called repeatedly with different values of λ provided that the values of κ and β 2 remain unchanged between calls. Otherwise, g01zu must be called again. This is illustrated in [Example].

Example

This example evaluates ϕV λ;κ,β 2 at λ=2.5, κ=0.4 and β 2=0.1, and prints the results.

Example program (C#): g01mue.cs

Example program data: g01mue.d

Example program results: g01mue.r

See Also

G01 Class
G01 Members


g01na Method

[image]

NAG Library for .NET Release 2
G01..::g01na Method
G01 Class See Also Send Feedback
g01na computes the cumulants and moments of quadratic forms in Normal variates.

Syntax

C#
public static void g01na(
    string mom,
    string mean,
    int n,
    double[,] a,
    double[] emu,
    double[,] sigma,
    int l,
    double[] rkum,
    double[] rmom,
    out int ifail
)
Visual Basic
Public Shared Sub g01na ( _
    mom As String, _
    mean As String, _
    n As Integer, _
    a As Double(,), _
    emu As Double(), _
    sigma As Double(,), _
    l As Integer, _
    rkum As Double(), _
    rmom As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g01na(
    String^ mom,
    String^ mean,
    int n,
    array<double,2>^ a,
    array<double>^ emu,
    array<double,2>^ sigma,
    int l,
    array<double>^ rkum,
    array<double>^ rmom,
    [OutAttribute] int% ifail
)
F#
static member g01na :
        mom : string *
        mean : string *
        n : int *
        a : float[,] *
        emu : float[] *
        sigma : float[,] *
        l : int *
        rkum : float[] *
        rmom : float[] *
        ifail : int byref -> unit

Parameters

mom
Type: System..::..String
On entry: indicates if moments are computed in addition to cumulants.
mom="C"
Only cumulants are computed.
mom="M"
Moments are computed in addition to cumulants.
Constraint: mom="C" or "M".
mean
Type: System..::..String
On entry: indicates if the mean, μ, is zero.
mean="Z"
μ is zero.
mean="M"
The value of μ is supplied in emu.
Constraint: mean="Z" or "M".
n
Type: System..::..Int32
On entry: n, the dimension of the quadratic form.
Constraint: n>1.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: the n by n symmetric matrix A. Only the lower triangle is referenced.
emu
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array emu must be at least n if mean="M", and at least 1 otherwise.
On entry: if mean="M", emu must contain the n elements of the vector μ.
If mean="Z", emu is not referenced.
sigma
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: the n by n variance-covariance matrix Σ. Only the lower triangle is referenced.
Constraint: the matrix Σ must be positive definite.
l
Type: System..::..Int32
On entry: the required number of cumulants, and moments if specified.
Constraint: 1≤l≤12.
rkum
Type: array< System..::..Double >[]()[][]
An array of size [l]
On exit: the l cumulants of the quadratic form.
rmom
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array rmom must be at least l if mom="M", and at least 1 otherwise.
On exit: if mom="M", the l moments of the quadratic form.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Let x have an n-dimensional multivariate Normal distribution with mean μ and variance-covariance matrix Σ. Then for a symmetric matrix A, g01na computes up to the first 12 moments and cumulants of the quadratic form Q=xT Ax. The sth moment (about the origin) is defined as
E Qs,
where E denotes expectation. The sth moment of Q can also be found as the coefficient of ts/s! in the expansion of E e Qt. The sth cumulant is defined as the coefficient of ts/s! in the expansion of log E e Qt.
The method is based on the method CUM written by Magnus and Pesaran (1993a) and based on the theory given by Magnus (1978), Magnus (1979) and Magnus (1986).

References

Magnus J R (1978) The moments of products of quadratic forms in Normal variables Statist. Neerlandica 32 201–210
Magnus J R (1979) The expectation of products of quadratic forms in Normal variables: the practice Statist. Neerlandica 33 131–136
Magnus J R (1986) The exact moments of a ratio of quadratic forms in Normal variables Ann. Économ. Statist. 4 95–109
Magnus J R and Pesaran B (1993a) The evaluation of cumulants and moments of quadratic forms in Normal variables (CUM): Technical description Comput. Statist. 8 39–45
Magnus J R and Pesaran B (1993b) The evaluation of moments of quadratic forms and ratios of quadratic forms in Normal variables: Background, motivation and examples Comput. Statist. 8 47–55

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA, LDSIG) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | n≤1,
or | l<1,
or | l>12,
or | mom≠"C" or "M",
or | mean≠"M" or "Z".
ifail=2
On entry, the matrix Σ is not positive definite.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

In a range of tests the accuracy was found to be a modest multiple of machine precision. See Magnus and Pesaran (1993b).

Parallelism and Performance

None.

Further Comments

None.

Example

This example is given by Magnus and Pesaran (1993b) and considers the simple autoregression
yt=β y t-1+ut,  t=1,2,…n,
where ut is a sequence of independent Normal variables with mean zero and variance one, and y 0 is known. The moments of the quadratic form
Q=∑t=2 n yty t-1
are computed using g01na. The matrix A is given by:
A i+1,i=12,  i=1,2,…n-1;A i,j=0,   otherwise.
The value of Σ can be computed using the relationships
var yt=β 2 var y t-1+1
and
cov yty t+k=β cov yty t+k-1
for k≥0 and var y 1=1.
The values of β, y 0, n, and the number of moments required are read in and the moments and cumulants printed.

Example program (C#): g01nae.cs

Example program data: g01nae.d

Example program results: g01nae.r

See Also

G01 Class
G01 Members


g01nb Method

[image]

NAG Library for .NET Release 2
G01..::g01nb Method
G01 Class See Also Send Feedback
g01nb computes the moments of ratios of quadratic forms in Normal variables and related statistics.

Syntax

C#
public static void g01nb(
    string dncase,
    string mean,
    int n,
    double[,] a,
    double[,] b,
    double[,] c,
    double[] ela,
    double[] emu,
    double[,] sigma,
    int l1,
    int l2,
    out int lmax,
    double[] rmom,
    out double abserr,
    double eps,
    out int ifail
)
Visual Basic
Public Shared Sub g01nb ( _
    dncase As String, _
    mean As String, _
    n As Integer, _
    a As Double(,), _
    b As Double(,), _
    c As Double(,), _
    ela As Double(), _
    emu As Double(), _
    sigma As Double(,), _
    l1 As Integer, _
    l2 As Integer, _
    <OutAttribute> ByRef lmax As Integer, _
    rmom As Double(), _
    <OutAttribute> ByRef abserr As Double, _
    eps As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g01nb(
    String^ dncase,
    String^ mean,
    int n,
    array<double,2>^ a,
    array<double,2>^ b,
    array<double,2>^ c,
    array<double>^ ela,
    array<double>^ emu,
    array<double,2>^ sigma,
    int l1,
    int l2,
    [OutAttribute] int% lmax,
    array<double>^ rmom,
    [OutAttribute] double% abserr,
    double eps,
    [OutAttribute] int% ifail
)
F#
static member g01nb :
        dncase : string *
        mean : string *
        n : int *
        a : float[,] *
        b : float[,] *
        c : float[,] *
        ela : float[] *
        emu : float[] *
        sigma : float[,] *
        l1 : int *
        l2 : int *
        lmax : int byref *
        rmom : float[] *
        abserr : float byref *
        eps : float *
        ifail : int byref -> unit

Parameters

dncase
Type: System..::..String
On entry: indicates the moments of which function are to be computed.
case="R" (Ratio)
E Rs is computed.
case="L" (Linear with ratio)
E Rs aT x is computed.
case="Q" (Quadratic with ratio)
E Rs xT Cx is computed.
Constraint: case="R", "L" or "Q".
mean
Type: System..::..String
On entry: indicates if the mean, μ, is zero.
mean="Z"
μ is zero.
mean="M"
The value of μ is supplied in emu.
Constraint: mean="Z" or "M".
n
Type: System..::..Int32
On entry: n, the dimension of the quadratic form.
Constraint: n>1.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: the n by n symmetric matrix A. Only the lower triangle is referenced.
b
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: the n by n positive semidefinite symmetric matrix B. Only the lower triangle is referenced.
Constraint: the matrix B must be positive semidefinite.
c
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint:
  • if case="Q", dim1≥n;
  • otherwise dim1≥1.
Note: the second dimension of the array c must be at least n if case="Q", and at least 1 otherwise.
On entry: if case="Q", c must contain the n by n symmetric matrix C; only the lower triangle is referenced.
If case≠"Q", c is not referenced.
ela
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array ela must be at least n if case="L", and at least 1 otherwise.
On entry: if case="L", ela must contain the vector a of length n, otherwise a is not referenced.
emu
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array emu must be at least n if mean="M", and at least 1 otherwise.
On entry: if mean="M", emu must contain the n elements of the vector μ.
If mean="Z", emu is not referenced.
sigma
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: the n by n variance-covariance matrix Σ. Only the lower triangle is referenced.
Constraint: the matrix Σ must be positive definite.
l1
Type: System..::..Int32
On entry: the first moment to be computed, l 1.
Constraint: 0<l1≤l2.
l2
Type: System..::..Int32
On entry: the last moment to be computed, l 2.
Constraint: l1≤l2≤12.
lmax
Type: System..::..Int32 %
On exit: the highest moment computed, lMAX. This will be l 2 if ifail=0 on exit.
rmom
Type: array< System..::..Double >[]()[][]
An array of size [l2-l1+1]
On exit: the l 1 to lMAX moments.
abserr
Type: System..::..Double %
On exit: the estimated maximum absolute error in any computed moment.
eps
Type: System..::..Double
On entry: the relative accuracy required for the moments, this value is also used in the checks for the existence of the moments.
If eps=0.0, a value of ε where ε is the machine precision used.
Constraint: eps=0.0 or eps≥machine precision.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Let x have an n-dimensional multivariate Normal distribution with mean μ and variance-covariance matrix Σ. Then for a symmetric matrix A and symmetric positive semidefinite matrix B, g01nb computes a subset, l 1 to l 2, of the first 12 moments of the ratio of quadratic forms
R=xT Ax/xT Bx.
The sth moment (about the origin) is defined as
E Rs, (1)
where E denotes the expectation. Alternatively, this method will compute the following expectations:
E Rs aT x (2)
and
E Rs xT Cx, (3)
where a is a vector of length n and C is a n by n symmetric matrix, if they exist. In the case of (2) the moments are zero if μ=0.
The conditions of theorems 1, 2 and 3 of Magnus (1986) and Magnus (1990) are used to check for the existence of the moments. If all the requested moments do not exist, the computations are carried out for those moments that are requested up to the maximum that exist, lMAX.
This method is based on the method QRMOM written by Magnus and Pesaran (1993a) and based on the theory given by Magnus (1986) and Magnus (1990). The computation of the moments requires first the computation of the eigenvectors of the matrix LT BL, where L LT=Σ. The matrix LT BL must be positive semidefinite and not null. Given the eigenvectors of this matrix, a function which has to be integrated over the range zero to infinity can be computed. This integration is performed using d01am.

References

Magnus J R (1986) The exact moments of a ratio of quadratic forms in Normal variables Ann. Économ. Statist. 4 95–109
Magnus J R (1990) On certain moments relating to quadratic forms in Normal variables: Further results Sankhyā, Ser. B 52 1–13
Magnus J R and Pesaran B (1993a) The evaluation of cumulants and moments of quadratic forms in Normal variables (CUM): Technical description Comput. Statist. 8 39–45
Magnus J R and Pesaran B (1993b) The evaluation of moments of quadratic forms and ratios of quadratic forms in Normal variables: Background, motivation and examples Comput. Statist. 8 47–55

Error Indicators and Warnings

Note: g01nb may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA, LDB, LDC, LDSIG) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | n≤1,
or | l1<1,
or | l1>l2,
or | l2>12,
or | case≠"R", "L" or "Q",
or | mean≠"M" or "Z",
or | eps≠0.0 and eps<machine precision.
ifail=2
On entry, | Σ is not positive definite,
or | b is not positive semidefinite or is null.
ifail=3
None of the required moments can be computed.
ifail=4
The matrix LT BL is not positive semidefinite or is null.
ifail=5
The computation to compute the eigenvalues required in the calculation of moments has failed to converge: this is an unlikely error exit.
ifail=6
Only some of the required moments have been computed, the highest is given by lmax.
ifail=7
The required accuracy has not been achieved in the integration. An estimate of the accuracy is returned in abserr.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The relative accuracy is specified by eps and an estimate of the maximum absolute error for all computed moments is returned in abserr.

Parallelism and Performance

None.

Further Comments

None.

Example

This example is given by Magnus and Pesaran (1993b) and considers the simple autoregression:
yt=β y t-1+ut,  t=1,2,…,n,
where ut is a sequence of independent Normal variables with mean zero and variance one, and y 0 is known. The least squares estimate of β, β^, is given by
β^=∑t=2 n yty t-1∑t=2 n yt 2.
Thus β^ can be written as a ratio of quadratic forms and its moments computed using g01nb. The matrix A is given by
A i+1,i=12,i=1,2,…n-1;A i,j=0,otherwise,
and the matrix B is given by
B i,i=1,i=1,2,…n-1;B i,j=0,otherwise.
The value of Σ can be computed using the relationships
var yt=β 2 var y t-1+1
and
cov yty t+k=β cov yty t+k-1
for k≥0 and var y 1=1.
The values of β, y 0, n, and the number of moments required are read in and the moments computed and printed.

Example program (C#): g01nbe.cs

Example program data: g01nbe.d

Example program results: g01nbe.r

See Also

G01 Class
G01 Members


g01pt Method

[image]

NAG Library for .NET Release 2
G01..::g01pt Method
G01 Class See Also Send Feedback
g01pt returns the value of the first moment Φ 1 x of the Landau density function.

Syntax

C#
public static double g01pt(
    double x
)
Visual Basic
Public Shared Function g01pt ( _
    x As Double _
) As Double
Visual C++
public:
static double g01pt(
    double x
)
F#
static member g01pt :
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.

Return Value

g01pt returns the value of the first moment Φ 1 x of the Landau density function.

Description

g01pt evaluates an approximation to the first moment Φ 1 x of the Landau density function given by
Φ 1 x=1 Φ x∫-∞x λϕ λ dλ,
where ϕ λ is described in g01mt, using piecewise approximation by rational functions. Further details can be found in Kölbig and Schorr (1984).
To obtain the value of Φ 2 x, g01qt can be used.

References

Kölbig K S and Schorr B (1984) A program package for the Landau distribution Comp. Phys. Comm. 31 97–111

Error Indicators and Warnings

There are no failure exits from this routine.

Accuracy

At least 7 significant digits are usually correct, but occasionally only 6. Such accuracy is normally considered to be adequate for applications in experimental physics.

Parallelism and Performance

None.

Further Comments

None.

Example

This example evaluates Φ 1 x at x=0.5, and prints the results.

Example program (C#): g01pte.cs

Example program data: g01pte.d

Example program results: g01pte.r

See Also

G01 Class
G01 Members


g01qt Method

[image]

NAG Library for .NET Release 2
G01..::g01qt Method
G01 Class See Also Send Feedback
g01qt returns the value of the second moment Φ 2 x of the Landau density function.

Syntax

C#
public static double g01qt(
    double x
)
Visual Basic
Public Shared Function g01qt ( _
    x As Double _
) As Double
Visual C++
public:
static double g01qt(
    double x
)
F#
static member g01qt :
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.

Return Value

g01qt returns the value of the second moment Φ 2 x of the Landau density function.

Description

g01qt evaluates an approximation to the second moment Φ 2 x of the Landau density function given by
Φ 2 x=1 Φ x∫-∞x λ 2 ϕ λ dλ,
where ϕ λ is described in g01mt, using piecewise approximation by rational functions. Further details can be found in Kölbig and Schorr (1984).
To obtain the value of Φ 1 x, g01pt can be used.

References

Kölbig K S and Schorr B (1984) A program package for the Landau distribution Comp. Phys. Comm. 31 97–111

Error Indicators and Warnings

There are no failure exits from this routine.

Accuracy

At least 7 significant digits are usually correct, but occasionally only 6. Such accuracy is normally considered to be adequate for applications in experimental physics.

Parallelism and Performance

None.

Further Comments

None.

Example

This example evaluates Φ 2 x at x=0.5, and prints the results.

Example program (C#): g01qte.cs

Example program data: g01qte.d

Example program results: g01qte.r

See Also

G01 Class
G01 Members


g01rt Method

[image]

NAG Library for .NET Release 2
G01..::g01rt Method
G01 Class See Also Send Feedback
g01rt returns the value of the derivative ϕ′λ of the Landau density function.

Syntax

C#
public static double g01rt(
    double x
)
Visual Basic
Public Shared Function g01rt ( _
    x As Double _
) As Double
Visual C++
public:
static double g01rt(
    double x
)
F#
static member g01rt :
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the argument λ of the function.

Return Value

g01rt returns the value of the derivative ϕ′λ of the Landau density function.

Description

g01rt evaluates an approximation to the derivative ϕ′λ of the Landau density function given by
ϕ′λ=dϕ λdλ,
where ϕ λ is described in g01mt, using piecewise approximation by rational functions. Further details can be found in Kölbig and Schorr (1984).
To obtain the value of ϕ λ, g01mt can be used.

References

Kölbig K S and Schorr B (1984) A program package for the Landau distribution Comp. Phys. Comm. 31 97–111

Error Indicators and Warnings

There are no failure exits from this routine.

Accuracy

At least 7 significant digits are usually correct, but occasionally only 6. Such accuracy is normally considered to be adequate for applications in experimental physics.
Because of the asymptotic behaviour of ϕ′λ, which is of the order of exp-exp-λ, underflow may occur on some machines when λ is moderately large and negative.

Parallelism and Performance

None.

Further Comments

None.

Example

This example evaluates ϕ′λ at λ=0.5, and prints the results.

Example program (C#): g01rte.cs

Example program data: g01rte.d

Example program results: g01rte.r

See Also

G01 Class
G01 Members


g01zu Method

[image]

NAG Library for .NET Release 2
G01..::g01zu Method
G01 Class See Also Send Feedback
g01zu is used to initialize methods g01eu and g01mu.
It is intended to be used before a call to g01eu or g01mu.

Syntax

C#
public static void g01zu(
    double rkappa,
    double beta2,
    int mode,
    out double xl,
    out double xu,
    double[] rcomm,
    out int ifail
)
Visual Basic
Public Shared Sub g01zu ( _
    rkappa As Double, _
    beta2 As Double, _
    mode As Integer, _
    <OutAttribute> ByRef xl As Double, _
    <OutAttribute> ByRef xu As Double, _
    rcomm As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g01zu(
    double rkappa,
    double beta2,
    int mode,
    [OutAttribute] double% xl,
    [OutAttribute] double% xu,
    array<double>^ rcomm,
    [OutAttribute] int% ifail
)
F#
static member g01zu :
        rkappa : float *
        beta2 : float *
        mode : int *
        xl : float byref *
        xu : float byref *
        rcomm : float[] *
        ifail : int byref -> unit

Parameters

rkappa
Type: System..::..Double
On entry: the argument κ of the function.
Constraint: 0.01≤rkappa≤10.0.
beta2
Type: System..::..Double
On entry: the argument β 2 of the function.
Constraint: 0.0≤beta2≤1.0.
mode
Type: System..::..Int32
On entry: if mode=0, then g01mu is to be called after the call to g01zu. Otherwise, g01eu is to be called.
xl
Type: System..::..Double %
On exit: xl, a threshold value below which ϕV λ;κ,β 2 will be set to zero by g01mu and ΦV λ;κ,β 2 will be set to zero by g01eu if λ<xl.
xu
Type: System..::..Double %
On exit: xu, a threshold value above which ϕV λ;κ,β 2 will be set to zero by g01mu and ΦV λ;κ,β 2 will be set to unity by g01eu if λ>xu.
rcomm
Type: array< System..::..Double >[]()[][]
An array of size [322]
On exit: this parameter should be passed unchanged to g01eu or g01mu.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g01zu initializes the array rcomm for use by g01eu or g01mu in the evaluation of the Vavilov functions ϕV λ;κ,β 2 and ΦV λ;κ,β 2 respectively.
Multiple calls to g01eu or g01mu can be made following a single call to g01zu, provided that rkappa or beta2 do not change, and that either all calls are to g01eu or all calls are to g01mu. If you wish to call both g01eu and g01mu, then you will need to initialize both separately.

References

Schorr B (1974) Programs for the Landau and the Vavilov distributions and the corresponding random numbers Comp. Phys. Comm. 7 215–224

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | rkappa<0.01,
or | rkappa>10.0,
or | beta2<0.0,
or | beta2>1.0.
ifail=2
The initialization has been abandoned due to an internal error. This error exit is unlikely to occur, but if it does change the values of rkappa and/or beta2 and rerun g01zu.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

At least five significant digits are usually correct.

Parallelism and Performance

None.

Further Comments

None.

Example

See Section in g01mu and g01eu.

See Also

G01 Class
G01 Members


G02 Class

[image]

NAG Library for .NET Release 2
G02 Class
Members See Also Send Feedback
This chapter is concerned with two techniques – correlation analysis and regression modelling – both of which are concerned with determining the inter-relationships among two or more variables.
Other chapters of the NAG Library which cover similar problems are E02 class E04 class. E02 class methods may be used to fit linear models by criteria other than least squares, and also for polynomial regression; E04 class methods may be used to fit nonlinear models and linearly constrained linear models.

Syntax

C#
public static class G02
Visual Basic
Public NotInheritable Class G02
Visual C++
public ref class G02 abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type G02 =  class end

Background to the Problems

Correlation

Aims of correlation analysis

Correlation analysis provides a single summary statistic – the correlation coefficient – describing the strength of the association between two variables. The most common types of association which are investigated by correlation analysis are linear relationships, and there are a number of forms of linear correlation coefficients for use with different types of data.

Correlation coefficients

The (Pearson) product-moment correlation coefficients measure a linear relationship, while Kendall's tau and Spearman's rank order correlation coefficients measure monotonicity only. All three coefficients range from -1.0 to +1.0. A coefficient of zero always indicates that no linear relationship exists; a +1.0 coefficient implies a ‘perfect’ positive relationship (i.e., an increase in one variable is always associated with a corresponding increase in the other variable); and a coefficient of -1.0 indicates a ‘perfect’ negative relationship (i.e., an increase in one variable is always associated with a corresponding decrease in the other variable).
Consider the bivariate scattergrams in Figure 1: (a) and (b) show strictly linear functions for which the values of the product-moment correlation coefficient, and (since a linear function is also monotonic) both Kendall's tau and Spearman's rank order coefficients, would be +1.0 and -1.0 respectively. However, though the relationships in figures (c) and (d) are respectively monotonically increasing and monotonically decreasing, for which both Kendall's and Spearman's nonparametric coefficients would be +1.0 (in (c)) and -1.0 (in (d)), the functions are nonlinear so that the product-moment coefficients would not take such ‘perfect’ extreme values. There is no obvious relationship between the variables in figure (e), so all three coefficients would assume values close to zero, while in figure (f) though there is an obvious parabolic relationship between the two variables, it would not be detected by any of the correlation coefficients which would again take values near to zero; it is important therefore to examine scattergrams as well as the correlation coefficients.
In order to decide which type of correlation is the most appropriate, it is necessary to appreciate the different groups into which variables may be classified. Variables are generally divided into four types of scales: the nominal scale, the ordinal scale, the interval scale, and the ratio scale. The nominal scale is used only to categorise data; for each category a name, perhaps numeric, is assigned so that two different categories will be identified by distinct names. The ordinal scale, as well as categorising the observations, orders the categories. Each category is assigned a distinct identifying symbol, in such a way that the order of the symbols corresponds to the order of the categories. (The most common system for ordinal variables is to assign numerical identifiers to the categories, though if they have previously been assigned alphabetic characters, these may be transformed to a numerical system by any convenient method which preserves the ordering of the categories.) The interval scale not only categorises and orders the observations, but also quantifies the comparison between categories; this necessitates a common unit of measurement and an arbitrary zero-point. Finally, the ratio scale is similar to the interval scale, except that it has an absolute (as opposed to arbitrary) zero-point.
For a more complete discussion of these four types of scales, and some examples, you are referred to Churchman and Ratoosh (1959) and Hays (1970).
Figure 1
Product-moment correlation coefficients are used with variables which are interval (or ratio) scales; these coefficients measure the amount of spread about the linear least squares equation. For a product-moment correlation coefficient, r, based on n pairs of observations, testing against the null hypothesis that there is no correlation between the two variables, the statistic
r⁢n-21-r 2
has a Student's t-distribution with n-2 degrees of freedom; its significance can be tested accordingly.
Ranked and ordinal scale data are generally analysed by nonparametric methods – usually either Spearman's or Kendall's tau rank order correlation coefficients, which, as their names suggest, operate solely on the ranks, or relative orders, of the data values. Interval or ratio scale variables may also be validly analysed by nonparametric methods, but such techniques are statistically less powerful than a product-moment method. For a Spearman rank order correlation coefficient, R, based on n pairs of observations, testing against the null hypothesis that there is no correlation between the two variables, for large samples the statistic
R⁢n-21-R 2
has approximately a Student's t-distribution with n-2 degrees of freedom, and may be treated accordingly. (This is similar to the product-moment correlation coefficient, r, see above.) Kendall's tau coefficient, based on n pairs of observations, has, for large samples, an approximately Normal distribution with mean zero and standard deviation
4 n+109 n n-1
when tested against the null hypothesis that there is no correlation between the two variables; the coefficient should therefore be divided by this standard deviation and tested against the standard Normal distribution, N 0,1.
When the number of ordinal categories a variable takes is large, and the number of ties is relatively small, Spearman's rank order correlation coefficients have advantages over Kendall's tau; conversely, when the number of categories is small, or there are a large number of ties, Kendall's tau is usually preferred. Thus when the ordinal scale is more or less continuous, Spearman's rank order coefficients are preferred, whereas Kendall's tau is used when the data is grouped into a smaller number of categories; both measures do however include corrections for the occurrence of ties, and the basic concepts underlying the two coefficients are quite similar. The absolute value of Kendall's tau coefficient tends to be slightly smaller than Spearman's coefficient for the same set of data.
There is no authoritative dictum on the selection of correlation coefficients – particularly on the advisability of using correlations with ordinal data. This is a matter of discretion for you.

Partial correlation

The correlation coefficients described above measure the association between two variables ignoring any other variables in the system. Suppose there are three variables X,Y and Z as shown in the path diagram below.
Figure 2
The association between Y and Z is made up of the direct association between Y and Z and the association caused by the path through X, that is the association of both Y and Z with the third variable X. For example if Z and Y were cholesterol level and blood pressure and X were age since both blood pressure and cholesterol level may increase with age the correlation between blood pressure and cholesterol level eliminating the effect of age is required.
The correlation between two variables eliminating the effect of a third variable is known as the partial correlation. If ρ zy, ρ zx and ρ xy represent the correlations between x, y and z then the partial correlation between Z and Y given X is
ρ zy-ρ zxρ xy 1-ρ zx 21-ρ xy 2.
The partial correlation is then estimated by using product-moment correlation coefficients.
In general, let a set of variables be partitioned into two groups Y and X with ny variables in Y and nx variables in X and let the variance-covariance matrix of all ny+nx variables be partitioned into
Σ xxΣ yxΣ xyΣ yy.
Then the variance-covariance of Y conditional on fixed values of the X variables is given by
Σ y∣x=Σ yy-Σ yx Σ xx-1 Σ xy.
The partial correlation matrix is then computed by standardizing Σ y∣x.

Robust estimation of correlation coefficients

The product-moment correlation coefficient can be greatly affected by the presence of a few extreme observations or outliers. There are robust estimation procedures which aim to decrease the effect of extreme values.
Mathematically these methods can be described as follows. A robust estimate of the variance-covariance matrix, C, can be written as
C=τ 2AT A-1
where τ 2 is a correction factor to give an unbiased estimator if the data is Normal and A is a lower triangular matrix. Let xi be the vector of values for the ith observation and let zi=A xi-θ, θ being a robust estimate of location, then θ and A are found as solutions to
1 n∑i=1 n w zi 2 zi=0
and
1 n∑i=1 n w zi 2 zi ziT-v zi 2 I=0,
where w t, u t and v t are functions such that they return a value of 1 for reasonable values of t and decreasing values for large t. The correlation matrix can then be calculated from the variance-covariance matrix. If w, u, and v returned 1 for all values then the product-moment correlation coefficient would be calculated.

Missing values

When there are missing values in the data these may be handled in one of two ways. Firstly, if a case contains a missing observation for any variable, then that case is omitted in its entirety from all calculations; this may be termed casewise treatment of missing data. Secondly, if a case contains a missing observation for any variable, then the case is omitted from only those calculations involving the variable for which the value is missing; this may be called pairwise treatment of missing data. Pairwise deletion of missing data has the advantage of using as much of the data as possible in the computation of each coefficient. In extreme circumstances, however, it can have the disadvantage of producing coefficients which are based on a different number of cases, and even on different selections of cases or samples; furthermore, the ‘correlation’ matrices formed in this way need not necessarily be positive semidefinite, a requirement for a correlation matrix. Casewise deletion of missing data generally causes fewer cases to be used in the calculation of the coefficients than does pairwise deletion. How great this difference is will obviously depend on the distribution of the missing data, both among cases and among variables.
Pairwise treatment does therefore use more information from the sample, but should not be used without careful consideration of the location of the missing observations in the data matrix, and the consequent effect of processing the missing data in that fashion.

Nearest Correlation Matrix

A correlation matrix is, by definition, a symmetric, positive semidefinite matrix with unit diagonals and all elements in the range -1,1.
In practice, rather than having a true correlation matrix, you may find that you have a matrix of pairwise correlations. This usually occurs in the presence of missing values, when the missing values are treated in a pairwise fashion as discussed in [Missing values]. Matrices constructed in this way may not be not positive semidefinite, and therefore are not a valid correlation matrix. However, a valid correlation matrix can be calculated that is in some sense ‘close’ to the original.
Given an n×n matrix, G, there are a number of available ways of computing the ‘nearest’ correlation matrix, Σ to G:
(a) Frobenius Norm
Find Σ such that
∑i=1 n∑j=1 n s ij-σ ij 2
is minimized.
Where S is the symmetric matrix defined as S=12 G+GT and s ij and σ ij denotes the elements of S and Σ respectively.
A weighted Frobenius norm can also be used. The term being summed across therefore becomes wiwj s ij-σ ij 2 if row and column weights are being used or w ij s ij-σ ij 2 when element-wise weights are used.
(b) Factor Loading Method
This method is similar to (a) in that it finds a Σ that is closest to S in the Frobenius norm. However, it also ensures that Σ has a k-factor structure, that is Σ can be written as
Σ=X XT+diag I-X XT
where I is the identity matrix and X has n rows and k columns.
X is often referred to as the factor loading matrix. This problem primarily arises when a factor model ξ=Xη+Dε is used to describe a multivariate time series or collateralized debt obligations. In this model η∈ℝk and ξ∈ℝn are vectors of independent random variables having zero mean and unit variance, with η and ε independent of each other, and X∈ℝ n×k with D∈ℝ n×n diagonal. In the case of modelling debt obligations ξ can, for example, model the equity returns of n different companies of a portfolio where η describes k factors influencing all companies, in contrast to the elements of ε having only an effect on the equity of the corresponding company. With this model the complex behaviour of a portfolio, with potentially thousands of equities, is captured by looking at the major factors driving the behaviour.
The number of factors usually chosen is a lot smaller than n, perhaps between 1 and 10, yielding a large reduction in the complexity. The number of the factors, k, which yields a matrix X such that G-X XT+diag I-X XT F is within a required tolerance can also be determined, by experimenting with the input k and comparing the norms.

Regression

Aims of regression modelling

In regression analysis the relationship between one specific random variable, the dependent or response variable, and one or more known variables, called the independent variables or covariates, is studied. This relationship is represented by a mathematical model, or an equation, which associates the dependent variable with the independent variables, together with a set of relevant assumptions. The independent variables are related to the dependent variable by a function, called the regression function, which involves a set of unknown parameters. Values of the parameters which give the best fit for a given set of data are obtained; these values are known as the estimates of the parameters.
The reasons for using a regression model are twofold. The first is to obtain a description of the relationship between the variables as an indicator of possible causality. The second reason is to predict the value of the dependent variable from a set of values of the independent variables. Accordingly, the most usual statistical problems involved in regression analysis are:
(i) | to obtain best estimates of the unknown regression parameters;
(ii) | to test hypotheses about these parameters;
(iii) | to determine the adequacy of the assumed model; and
(iv) | to verify the set of relevant assumptions.

Regression models and designed experiments

One application of regression models is in the analysis of experiments. In this case the model relates the dependent variable to qualitative independent variables known as factors. Factors may take a number of different values known as levels. For example, in an experiment in which one of four different treatments is applied, the model will have one factor with four levels. Each level of the factor can be represented by a dummy variable taking the values 0 or 1. So in the example there are four dummy variables xj, for j=1,2,3,4, such that:
x ij=1​ if the ​i th observation received the ​j th treatment=0​ otherwise,
along with a variable for the mean x 0:
x i 0=1​ for all ​i.
If there were 7 observations the data would be:
TreatmentYx 0x 1x 2x 3x 41y 1110002y 2101002y 3101003y 4100103y 5100104y 6100014y 710001
When dummy variables are used it is common for the model not to be of full rank. In the case above, the model would not be of full rank because
x i 4=x i 0-x i 1-x i 2-x i 3,  i=1,2,…,7.
This means that the effect of x 4 cannot be distinguished from the combined effect of x 0,x 1,x 2 and x 3. This is known as aliasing. In this situation, the aliasing can be deduced from the experimental design and as a result the model to be fitted; in such situations it is known as intrinsic aliasing. In the example above no matter how many times each treatment is replicated (other than 0) the aliasing will still be present. If the aliasing is due to a particular dataset to which the model is to be fitted then it is known as extrinsic aliasing. If in the example above observation 1 was missing then the x 1 term would also be aliased. In general intrinsic aliasing may be overcome by changing the model, e.g., remove x 0 or x 1 from the model, or by introducing constraints on the parameters, e.g., β 1+β 2+β 3+β 4=0.
If aliasing is present then there will no longer be a unique set of least squares estimates for the parameters of the model but the fitted values will still have a unique estimate. Some linear functions of the parameters will also have unique estimates; these are known as estimable functions. In the example given above the functions (β 0+β 1) and (β 2-β 3) are both estimable.

Selecting the regression model

In many situations there are several possible independent variables, not all of which may be needed in the model. In order to select a suitable set of independent variables, two basic approaches can be used.
(a) | All possible regressions In this case all the possible combinations of independent variables are fitted and the one considered the best selected. To choose the best, two conflicting criteria have to be balanced. One is the fit of the model which will improve as more variables are added to the model. The second criterion is the desire to have a model with a small number of significant terms. Depending on how the model is fit, statistics such as R 2, which gives the proportion of variation explained by the model, and Cp, which tries to balance the size of the residual sum of squares against the number of terms in the model, can be used to aid in the choice of model.
(b) | Stepwise model building In stepwise model building the regression model is constructed recursively, adding or deleting the independent variables one at a time. When the model is built up the procedure is known as forward selection. The first step is to choose the single variable which is the best predictor. The second independent variable to be added to the regression equation is that which provides the best fit in conjunction with the first variable. Further variables are then added in this recursive fashion, adding at each step the optimum variable, given the other variables already in the equation. Alternatively, backward elimination can be used. This is when all variables are added and then the variables dropped one at a time, the variable dropped being the one which has the least effect on the fit of the model at that stage. There are also hybrid techniques which combine forward selection with backward elimination.

Linear Regression Models

When the regression model is linear in the parameters (but not necessarily in the independent variables), then the regression model is said to be linear; otherwise the model is classified as nonlinear.
The most elementary form of regression model is the simple linear regression of the dependent variable, Y, on a single independent variable, x, which takes the form
E Y=β 0+β 1 x (1)
where E Y is the expected or average value of Y and β 0 and β 1 are the parameters whose values are to be estimated, or, if the regression is required to pass through the origin (i.e., no constant term),
E Y=β 1 x (2)
where β 1 is the only unknown parameter.
An extension of this is multiple linear regression in which the dependent variable, Y, is regressed on the p (p>1) independent variables, x 1,x 2,…,xp, which takes the form
E Y=β 0+β 1x 1+β 2x 2+⋯+βpxp (3)
where β 1,β 2,…,βp and β 0 are the unknown parameters. Multiple linear regression models test include factors are sometimes known as General Linear (Regression) Models.
A special case of multiple linear regression is polynomial linear regression, in which the p independent variables are in fact powers of the same single variable x (i.e., xj=xj, for j=1,2,…,p).
In this case, the model defined by (3) becomes
E Y=β 0+β 1 x+β 2 x 2+⋯+βp xp. (4)
There are a great variety of nonlinear regression models; one of the most common is exponential regression, in which the equation may take the form
E Y=a+b e cx. (5)
It should be noted that equation (4) represents a linear regression, since even though the equation is not linear in the independent variable, x, it is linear in the parameters β 0,β 1,β 2,….,βp, whereas the regression model of equation (5) is nonlinear, as it is nonlinear in the parameters (a, b and c).

Fitting the regression model – least squares estimation

One method used to determine values for the parameters is, based on a given set of data, to minimize the sums of squares of the differences between the observed values of the dependent variable and the values predicted by the regression equation for that set of data – hence the term least squares estimation. For example, if a regression model of the type given by equation (3), namely
E Y=β 0x 0+β 1x 1+β 2x 2+⋯+βpxp,
where x 0=1 for all observations, is to be fitted to the n data points
x 01,x 11,x 21,…,x p 1,y 1x 02,x 12,x 22,…,x p 2,y 2⋮x 0 n,x 1 n,x 2 n,…,x pn,yn (6)
such that
yi=β 0x 0+β 1x 1 i+β 2x 2 i+⋯+βpx pi+ei,  i=1,2,…,n
where ei are unknown independent random errors with E ei=0 and var ei=σ 2, σ 2 being a constant, then the method used is to calculate the estimates of the regression parameters β 0,β 1,β 2,…,βp by minimizing
∑i=1 n ei 2. (7)
If the errors do not have constant variance, i.e.,
var ei=σi 2=σ 2 wi
then weighted least squares estimation is used in which
∑i=1 n wi ei 2
is minimized. For a more complete discussion of these least squares regression methods, and details of the mathematical techniques used, see Draper and Smith (1985) or Kendall and Stuart (1973).

Computational methods for least squares regression

Let X be the n by p matrix of independent variables and y be the vector of values for the dependent variable. To find the least squares estimates of the vector of parameters, β^, the QR decomposition of X is found, i.e.,
X=Q R*
where R*=R0, R being a p by p upper triangular matrix, and Q an n by n orthogonal matrix. If R is of full rank then β^ is the solution to
R β^=c 1
where c=QT y and c 1 is the first p rows of c. If R is not of full rank, a solution is obtained by means of a singular value decomposition (SVD) of R,
R=Q*D000 PT,
where D is a k by k diagonal matrix with nonzero diagonal elements, k being the rank of R, and Q* and P are p by p orthogonal matrices. This gives the solution
β^=P 1 D-1 Q*1 T c 1,
P 1 being the first k columns of P and Q*1 being the first k columns of Q*.
This will be only one of the possible solutions. Other estimates may be obtained by applying constraints to the parameters. If weighted regression with a vector of weights w is required then both X and y are premultiplied by w 1/2.
The method described above will, in general, be more accurate than methods based on forming (XT X), (or a scaled version), and then solving the equations
XT X β^=XT y.

Examining the fit of the model

Having fitted a model two questions need to be asked: first, ‘are all the terms in the model needed?’ and second, ‘is there some systematic lack of fit?’. To answer the first question either confidence intervals can be computed for the parameters or t-tests can be calculated to test hypotheses about the regression parameters – for example, whether the value of the parameter, βk, is significantly different from a specified value, bk (often zero). If the estimate of βk is β^k and its standard error is se β^k then the t-statistic is
β^k-bkse β^k.
It should be noted that both the tests and the confidence intervals may not be independent. Alternatively F-tests based on the residual sums of squares for different models can also be used to test the significance of terms in the model. If model 1, giving residual sum of squares RSS 1 with degrees of freedom ν 1, is a sub-model of model 2, giving residual sum of squares RSS 2 with degrees of freedom ν 2, i.e., all terms in model 1 are also in model 2, then to test if the extra terms in model 2 are needed the F-statistic
F=RSS 1-RSS 2/ν 1-ν 2RSS 2/ν 2
may be used. These tests and confidence intervals require the additional assumption that the errors, ei, are Normally distributed.
To check for systematic lack of fit the residuals, ri=yi-y^i, where y^i is the fitted value, should be examined. If the model is correct then they should be random with no discernible pattern. Due to the way they are calculated the residuals do not have constant variance. Now the vector of fitted values can be written as a linear combination of the vector of observations of the dependent variable, y, y^=Hy. The variance-covariance matrix of the residuals is then I-H σ 2, I being the identity matrix. The diagonal elements of H, h ii, can therefore be used to standardize the residuals. The h ii are a measure of the effect of the ith observation on the fitted model and are sometimes known as leverages.
If the observations were taken serially the residuals may also be used to test the assumption of the independence of the ei and hence the independence of the observations.

Ridge regression

When data on predictor variables x are multicollinear, ridge regression models provide an alternative to variable selection in the multiple regression model. In the ridge regression case, parameter estimates in the linear model are found by penalised least squares:
∑i=1 n∑j=1 p x ijβ^j-yi 2+h∑j=1 pβ^j 2,  h∈ℝ+,
where the value of the ridge parameter h controls the trade-off between the goodness-of-fit and smoothness of a solution.

Robust Estimation

Least squares regression can be greatly affected by a small number of unusual, atypical, or extreme observations. To protect against such occurrences, robust regression methods have been developed. These methods aim to give less weight to an observation which seems to be out of line with the rest of the data given the model under consideration. That is to seek to bound the influence. For a discussion of influence in regression, see Hampel et al. (1986) and Huber (1981).
There are two ways in which an observation for a regression model can be considered atypical. The values of the independent variables for the observation may be atypical or the residual from the model may be large.
The first problem of atypical values of the independent variables can be tackled by calculating weights for each observation which reflect how atypical it is, i.e., a strongly atypical observation would have a low weight. There are several ways of finding suitable weights; some are discussed in Hampel et al. (1986).
The second problem is tackled by bounding the contribution of the individual ei to the criterion to be minimized. When minimizing (7) a set of linear equations is formed, the solution of which gives the least squares estimates. The equations are
∑i=1 n eix ij=0, j=0,1,…,k.
These equations are replaced by
∑i=1 n ψ ei/σ x ij=0, j=0,1,…,k, (8)
where σ 2 is the variance of the ei, and ψ is a suitable function which down weights large values of the standardized residuals ei/σ. There are several suggested forms for ψ, one of which is Huber's function,
ψ t=-c,t<c-t,t≤c-c,t>c (9)
Figure 3
The solution to (8) gives the M-estimates of the regression coefficients. The weights can be included in (8) to protect against both types of extreme value. The parameter σ can be estimated by the median absolute deviations of the residuals or as a solution to, in the unweighted case,
∑i=1 n χ ei/σ^=n-k β,
where χ is a suitable function and β is a constant chosen to make the estimate unbiased. χ is often chosen to be ψ 2/2 where ψ is given in (9). Another form of robust regression is to minimize the sum of absolute deviations, i.e.,
∑i=1 n ei.
For details of robust regression, see Hampel et al. (1986) and Huber (1981).
Robust regressions using least absolute deviations can be computed using methods in E02 class.

Generalized Linear Models

Generalized linear models are an extension of the general linear regression model discussed above. They allow a wide range of models to be fitted. These included certain nonlinear regression models, logistic and probit regression models for binary data, and log-linear models for contingency tables. A generalized linear model consists of three basic components:
(a) A suitable distribution for the dependent variable Y. The following distributions are common:
(i) | Normal
(ii) | binomial
(iii) | Poisson
(iv) | gamma
In addition to the obvious uses of models with these distributions it should be noted that the Poisson distribution can be used in the analysis of contingency tables while the gamma distribution can be used to model variance components. The effect of the choice of the distribution is to define the relationship between the expected value of Y, E Y=μ, and its variance and so a generalized linear model with one of the above distributions may be used in a wider context when that relationship holds.
(b) A linear model η=∑βjxj, η is known as a linear predictor.
(c) A link function g(·) between the expected value of Y and the linear predictor, g μ=η. The following link functions are available:
For the binomial distribution ε, observing y out of t:
(i) | logistic link: η=log μ t-μ;
(ii) | probit link: η=Φ-1 μt;
(iii) | complementary log-log: η=log-log 1-μt.
For the Normal, Poisson, and gamma distributions:
(i) | exponent link: η=μa, for a constant a;
(ii) | identity link: η=μ;
(iii) | log link: η=log μ;
(iv) | square root link: η=μ;
(v) | reciprocal link: η=1 μ.
For each distribution there is a canonical link. For the canonical link there exist sufficient statistics for the parameters. The canonical links are:
(i) | Normal – identity;
(ii) | binomial – logistic;
(iii) | Poisson – logarithmic;
(iv) | gamma – reciprocal.
For the general linear regression model described above the three components are:
(i) | Distribution – Normal;
(ii) | Linear model – ∑βjxj;
(iii) | Link – identity.
The model is fitted by maximum likelihood; this is equivalent to least squares in the case of the Normal distribution. The residual sums of squares used in regression models is generalized to the concept of deviance. The deviance is the logarithm of the ratio of the likelihood of the model to the full model in which μ^i=yi, where μ^i is the estimated value of μi. For the Normal distribution the deviance is the residual sum of squares. Except for the case of the Normal distribution with the identity link, the χ 2 and F-tests based on the deviance are only approximate; also the estimates of the parameters will only be approximately Normally distributed. Thus only approximate z- or t-tests may be performed on the parameter values and approximate confidence intervals computed.
The estimates are found by using an iterative weighted least squares procedure. This is equivalent to the Fisher scoring method in which the Hessian matrix used in the Newton–Raphson method is replaced by its expected value. In the case of canonical links the Fisher scoring method and the Newton–Raphson method are identical. Starting values for the iterative procedure are obtained by replacing the μi by yi in the appropriate equations.

Linear Mixed Effects Regression

In a standard linear model the independent (or explanatory) variables are assumed to take the same set of values for all units in the population of interest. This type of variable is called fixed. In contrast, an independent variable that fluctuates over the different units is said to be random. Modelling a variable as fixed allows conclusions to be drawn only about the particular set of values observed. Modelling a variable as random allows the results to be generalized to the different levels that may have been observed. In general, if the effects of the levels of a variable are thought of as being drawn from a probability distribution of such effects then the variable is random. If the levels are not a sample of possible levels then the variable is fixed. In practice many qualitative variables can be considered as having fixed effects and most blocking, sampling design, control and repeated measures as having random effects.
In a general linear regression model, defined by
y=Xβ+ε
where | y is a vector of n observations on the dependent variable,
 | X is an n by p design matrix of independent variables,
 | β is a vector of p unknown parameters,
and | ε is a vector of n, independent and identically distributed, unknown errors, with ε~N 0,σ 2,
there are p fixed effects (the β) and a single random effect (the error term ε).
An extension to the general linear regression model that allows for additional random effects is the linear mixed effects regression model, (sometimes called the variance components model). One parameterisation of a linear mixed effects model is
y=Xβ+Zν+ε
where | y is a vector of n observations on the dependent variable,
 | X is an n by p design matrix of fixed independent variables,
 | β is a vector of p unknown fixed effects,
 | Z is an n by q design matrix of random independent variables,
 | ν is a vector of length q of unknown random effects,
 | ε is a vector of length n of unknown random errors,
and ν and ε are normally distributed with expectation zero and variance / covariance matrix defined by
Var νε=G00R.
The methods currently available in this chapter are restricted to cases where R=σR 2 I, I is the n×n identity matrix and G is a diagonal matrix. Given this restriction the random variables, Z, can be subdivided into g≤q groups containing one or more variables. The variables in the ith group are identically distributed with expectation zero and variance σi 2. The model therefore contains three sets of unknowns, the fixed effects, β, the random effects, ν, and a vector of g+1 variance components, γ, with γ=σ1 2,σ2 2,…,,,σ g-1 2,σg2,σR2. Rather than work directly with γ and the full likelihood function, γ is replaced by γ*=σ1 2/σR2,σ2 2/σR2,…,σ g-1 2/σR2,σg2/σR2,1 and the profiled likelihood function is used instead.
The model parameters are estimated using an iterative method based on maximizing either the restricted (profiled) likelihood function or the (profiled) likelihood functions. Fitting the model via restricted maximum likelihood involves maximizing the function
-2 lR=log V+n-p log rTV-1 r+log XTV-1 X+n-p1+log 2 π/n-p+n-p.
Whereas fitting the model via maximum likelihood involves maximizing
-2 lR=log V+n log rTV-1 r+n log 2 π/n+n.
In both cases
V=ZG ZT+R,  r=y-Xb  and  b=XTV-1 X-1XTV-1 y.
Once the final estimates for γ* have been obtained, the value of σR 2 is given by
σR 2=rTV-1 r/n-p.
Case weights, Wc, can be incorporated into the model by replacing XT X and ZT Z with XT Wc X and ZT Wc Z respectively, for a diagonal weight matrix Wc.

Quantile Regression

Quantile regression is related to least squares regression in that both are interested in studying the relationship between a response variable and one or more independent or explanatory variables. However, whereas least squares regression is concerned with modelling the conditional mean of the dependent variable, quantile regression models the conditional τth quantile of the dependent variable, for some value of τ∈0,1. So, for example, τ=0.5 would be the median.
Throughout this section we will be making use of the following definitions:
(a) If Z is a real valued random variable with distribution function F and density function f, such that
F α=P Z≤α=∫-∞α f z dz
then the τth quantile, α, can be defined as
α=F-1 τ=inf z:F z≥τ,τ∈0,1.
(b) | I L denotes an indicator function taking the value 1 if the logical expression L is true and 0 otherwise, e.g., I z<0=1 if z<0 and 0 if z≥0.
(c) | y denotes a vector of n observations on the dependent (or response) variable, y=yi:i=1,2,…,n.
(d) | X denotes an n×p matrix of explanatory or independent variables, often referred to as the design matrix, and xi denotes a column vector of length p which holds the ith row of X.

Finding a sample quantile as an optimization problem

Consider the piecewise linear loss function
ρτ z=z⁢τ-I z<0
The minimum of the expectation
E ρτ z-α=τ-1∫-∞α z-α f z dz+τ∫α∞z-α f z dz
can be obtained by using the integral rule of Leibnitz to differentiate with respect to z and then setting the result to zero, giving
1-τ∫-∞α f z dz-∫α∞f z dz=F α-τ=0
hence α=F-1 τ when the solution is unique. If the solution is not unique then there exists a range of quantiles, each of which is equally valid. Taking the smallest value of such a range ensures that the empirical quantile function is left-continuous. Therefore obtaining the τth quantile of a distribution F can be achieved by minimizing the expected value of the loss function ρτ.
This idea of obtaining the quantile by solving an optimization problem can be extended to finding the τth sample quantile. Given a vector of n observed values, y, from some distribution the empirical distribution function, Fn α=n-1∑ i=1 n I yi≤α provides an estimate of the unknown distribution function F giving an expected loss of
E ρτ y-α=n-1∑ i=1 n ρτ yi-α
and therefore the problem of finding the τth sample quantile, α^τ, can be expressed as finding the solution to the problem
minimize α∈ℝ∑ i=1 n ρτ yi-α
effectively replacing the operation of sorting, usually required when obtaining a sample quantile, with an optimization.

From least squares to quantile regression

Given the vector y it is a well known result that the sample mean, y^, solves the least squares problem
minimize μ∈ℝ∑ i=1 n yi-μ 2.
This result leads to least squares regression where, given design matrix X and defining the conditional mean of y as μ X=Xβ, an estimate of β is obtained from the solution to
minimize β∈ℝp∑ i=1 n yi-xiT β 2.
Quantile regression can be derived in a similar manner by specifying the τth conditional quantile as Qy τ|X=Xβ τ and estimating β τ as the solution to
minimize β∈ℝp∑ i=1 n ρτ yi-xiT β. (10)

Quantile regression as a linear programming problem

By introducing 2 n slack variables, u=ui:i=1,2,…,n and v=ui:i=1,2,…,n, the quantile regression minimization problem, (10), can be expressed as a linear programming (LP) problem, with primal and associated dual formulations
(a) Primal form
minimize u,v,β∈ℝ+n×ℝ+n×ℝp τ eT u+1-τ eT v​   subject to  y=Xβ+u-v (11)
where e is a vector of length n, where each element is 1.
If ri denotes the ith residual, ri=yi-xiT β, then the slack variables, u,v, can be thought as corresponding to the absolute value of the positive and negative residuals respectively with
ui=ri​ if ​ri>00​ otherwisevi=-ri​ if ​ri<00​ otherwise
(b) Dual form
The dual formulation of (11) is given by
maximized yT d​   subject to  XT d=0,d∈τ-1,τ n
which, on setting a=d+1-τ e, is equivalent to
maximizea yT a​   subject to  XT a=1-τ XT e,a∈0,1 n (12)
(c) Canonical form
Linear programming problems are often described in a standard way, called the canonical form. The canonical form of an LP problem is
minimizez cT z​   subject to  ll≤zAz≤lu.
Letting 0 p denote a vector of p zeros ±∞p denote a vector of p arbitarily small or large values, I n×n denote the n×n identity matrix, c=a,b denote the row vector constructed by concatenating the elements of vector b to the elements of vector a and C=A,B denote the matrix constructed by concatenating the columns of matrix B onto the columns of matrix A then setting
cT=0 p,τ⁢eT,1-τ eTzT=βT,uT,vTA=X,I n×n,-I n×nb=ylu=+∞p,∞n,∞n,yll=-∞p,0 n,0 n,y
gives the quantile regression LP problem as described in (11).
Once expressed as an LP problem the parameter estimates β^τ can be obtained in a number of ways, for example via the inertia-controlling method of Gill and Murray (1978) (see e04mf), the simplex method or an interior point method as used by g02qf and g02qg.

Estimation of the covariance matrix

Koenker (2005) shows that the limiting covariance matrix of n β^τ-β τ is of the form of a Huber Sandwich. Therefore, under the assumption of Normally distributed errors
n β^τ-β τ∼N 0,τ 1-τ Hn τ-1 Jn Hn τ-1 (13)
where
Jn=n-1⁢∑ i=1 n xi xiTHn τ=lim n→∞n-1⁢∑ i=1 n xi xiT fi Q yi τ|xi
and fi Q yi τ|xi denotes the conditional density of the response y evaluated at the τth conditional quantile.
More generally, the asymptotic covariance matrix for β^τ 1,β^τ 1,…,β^τn has blocks defined by
cov n β^τi-β τi,n β^τj-β τj=min τi,τj-τiτj Hn τi-1 Jn Hn τj-1 (14)
Under the assumption of independent, identically distributed (iid) errors, (13) simplifies to
n β^τ-β τ∼N 0,τ 1-τ s τ 2XT X-1
where s τ is the sparsity function, given by
s τ=1 f F-1 τ
a similar simplification occurs with (14).
In cases where the assumption of iid errors does not hold, Powell (1991) suggests using a kernel estimator of the form
H^n τ=n cn-1∑ i=1 n K yi-xiT β^τ cn xi xiT
for some bandwidth parameter cn satisfying lim n→∞cn→0 and lim n→∞n cn→∞ and Hendricks and Koenker (1991) suggest a method based on an extension of the idea of sparsity.
Rather than use an asymptotic estimate of the covariance matrix, it is also possible to use bootstrapping. Roughly speaking the original data is resampled and a set of parameter estimates obtained from each new sample. A sample covariance matrix is then constructed from the resulting matrix of parameter estimates.

Latent Variable Methods

Regression by means of projections to latent structures also known as partial least squares, is a latent variable linear model suited to data for which:
  • the number of x-variables is high compared to the number of observations;
  • x-variables and/or y-variables are multicollinear.
Latent variables are linear combinations of x-variables that explain variance in x and y-variables. These latent variables, known as factors, are extracted iteratively from the data. A choice of the number of factors to include in a model can be made by considering diagnostic statistics such as the variable influence on projections (VIP).

Recommendations on Choice and Use of Available Methods

Correlation

Product-moment correlation

Let SSx be the sum of squares of deviations from the mean, x-, for the variable x for a sample of size n, i.e.,
SSx=∑i=1 n xi-x-2
and let SC xy be the cross-products of deviations from the means, x- and y-, for the variables x and y for a sample of size n, i.e.,
SC xy=∑i=1 n xi-x-yi-y-.
Then the sample covariance of x and y is
cov x,y=SC xy n-1
and the product-moment correlation coefficient is
r=cov x,yvar xvar y=SC xy SSxSSy.
g02ba computes the product-moment correlation coefficients.
g02bt updates the sample sums of squares and cross-products and deviations from the means by the addition/deletion of a (weighted) observation.
g02bu computes the sample sums of squares and cross-products deviations from the means (optionally weighted). The output from multiple calls to g02bu can be combined via a call to (G02BZF not in this release), allowing large datasets to be summarised across multiple processing units.
g02bt updates the sample sums of squares and cross-products and deviations from the means by the addition/deletion of a (weighted) observation.
g02bw computes the product-moment correlation coefficients from the sample sums of squares and cross-products of deviations from the means.
The three methods compute only the upper triangle of the correlation matrix which is stored in a one-dimensional array in packed form.
g02bx computes both the (optionally weighted) covariance matrix and the (optionally weighted) correlation matrix. These are returned in two-dimensional arrays. (Note that g02bt and g02bu can be used to compute the sums of squares from zero.)
g02bg can be used to calculate the correlation coefficients for a subset of variables in the data matrix.

Product-moment correlation with missing values

If there are missing values then g02bu and g02bx, as described above, will allow casewise deletion by you giving the observation zero weight (compared with unit weight for an otherwise unweighted computation).
Other methods also handle missing values in the calculation of unweighted product-moment correlation coefficients. Casewise exclusion of missing values is provided by g02bb while pairwise omission of missing values is carried out by g02bc. These two methods calculate a correlation matrix for all the variables in the data matrix; similar output but for only a selected subset of variables is provided by methods g02bh and g02bj respectively. As well as providing the Pearson product-moment correlation coefficients, these methods also calculate the means and standard deviations of the variables, and the matrix of sums of squares and cross-products of deviations from the means. For all four methods you are free to select appropriate values for consideration as missing values, bearing in mind the nature of the data and the possible range of valid values. The missing values for each variable may be either different or alike and it is not necessary to specify missing values for all the variables.

Nonparametric correlation

There are five methods which perform nonparametric correlations, each of which is capable of producing both Spearman's rank order and Kendall's tau correlation coefficients. The basic underlying concept of both these methods is to replace each observation by its corresponding rank or order within the observations on that variable, and the correlations are then calculated using these ranks.
It is obviously more convenient to order the observations and calculate the ranks for a particular variable just once, and to store these ranks for subsequent use in calculating all coefficients involving that variable; this does however require an amount of store of the same size as the original data matrix, which in some cases might be excessive. Accordingly, some methods calculate the ranks only once, and replace the input data matrix by the matrix of ranks, which are then also made available to you on exit from the method, while others preserve the data matrix and calculate the ranks a number of times within the method; the ranks of the observations are not provided as output by methods which work in the latter way. If it is possible to arrange the program in such a way that the first technique can be used, then efficiency of timing is achieved with no additional storage, whereas in the second case, it is necessary to have a second matrix of the same size as the data matrix, which may not be acceptable in certain circumstances; in this case it is necessary to reach a compromise between efficiency of time and of storage, and this may well be dependent upon local conditions.
Methods g02bn and g02bq both calculate Kendall's tau and/or Spearman's rank order correlation coefficients taking no account of missing values; g02bn does so by calculating the ranks of each variable only once, and replacing the data matrix by the matrix of ranks, whereas g02bq calculates the ranks of each variable several times. Methods g02bp and g02br provide the same output, but treat missing values in a ‘casewise’ manner (see above); g02bp calculates the ranks of each variable only once, and overwrites the data matrix of ranks, while g02br determines the ranks of each variable several times. For ‘pairwise’ omission of missing data (see above), the method g02bs provides Kendall and/or Spearman coefficients.
Since g02bn and g02bp order the observations and calculate the ranks of each variable only once, then if there are M variables involved, there are only M separate ‘ranking’ operations; this should be contrasted with the method used by methods g02bq and g02br which perform M M-1/2+1 similar ranking operations. These ranking operations are by far the most time-consuming parts of these nonparametric methods, so for a matrix of as few as five variables, the time taken by one of the slower methods can be expected to be at least a factor of two slower than the corresponding efficient method; as the number of variables increases, so this relative efficiency factor increases. Only one method, g02bs, is provided for pairwise missing values, and this method carries out M M-1 separate rankings; since by the very nature of the pairwise method it is necessary to treat each pair of variables separately and rank them individually, it is impossible to reduce this number of operations, and so no alternative method is provided.

Partial correlation

g02by computes a matrix of partial correlation coefficients from the correlation coefficients or variance-covariance matrix returned by g02bx.

Robust correlation

g02hl and g02hm compute robust estimates of the variance-covariance matrix by solving the equations
1 n∑i=1 n w zi 2 zi=0
and
1 n∑i=1 n u zi 2 zi ziT-v zi 2 I=0,
as described in [Robust estimation of correlation coefficients] for user-supplied functions w and u. Two options are available for v, either v t=1 for all t or v t=u t.
g02hm requires only the function w and u to be supplied while g02hl also requires their derivatives.
In general g02hl will be considerably faster than g02hm and should be used if derivatives are available.
g02hk computes a robust variance-covariance matrix for the following functions:
u t=au/t 2​ if ​t<au 2u t=1​ if ​au 2≤t≤bu 2u t=bu/t 2​ if ​t>bu 2
and
w t=1​ if ​t≤cww t=cw/t​ if ​t>cw
for constants au, bu and cw.
These functions solve a minimax space problem considered by Huber (1981). The values of au, bu and cw are calculated from the fraction of gross errors; see Hampel et al. (1986) and Huber (1981).
To compute a correlation matrix from the variance-covariance matrix g02bw may be used.

Nearest correlation matrix

Four methods are provided to calculate a nearest correlation matrix. The choice of method will depend on what definition of ‘nearest’ is required and whether there is any particular structure desired in the resulting correlation matrix.
g02aa computes the nearest correlation matrix in the Frobenius norm, using the method of Qi and Sun (2006).
g02ab uses an extension of the method implemented in g02aa allowing for the row and column weighted Frobenius norm to be used as well as bounds on the eigenvalues of the resulting correlation matrix to be specified.
g02ae computes the factor loading matrix, allowing a correlation matrix with a k-factor structure to be computed.
(G02AJF not in this release) again computes the nearest correlation matrix in the Frobenius norm, but allows for element-wise weighting as well as bounds on the eigenvalues.

Regression

Simple linear regression

Four methods are provided for simple linear regressions: g02ca and g02cc perform the simple linear regression with a constant term (equation (1) above), while g02cb and g02cd fit the simple linear regression with no constant term (equation (2) above). Two of these methods, g02cc and g02cd, take account of missing values, which the others do not. In these two methods, an observation is omitted if it contains a missing value for either the dependent or the independent variable; this is equivalent to both the casewise and pairwise methods, since both are identical when there are only two variables involved. Input to these methods consists of the raw data, and output includes the coefficients, their standard errors and t values for testing the significance of the coefficients; the F value for testing the overall significance of the regression is also given.

Ridge regression

g02ka calculates a ridge regression, optimizing the ridge parameter according to one of four prediction error criteria.
g02kb calculates ridge regressions for a given set of ridge parameters.

Polynomial regression and nonlinear regression

No methods are currently provided in this chapter for polynomial regression. If you wish to perform polynomial regressions you have three alternatives: you can use the multiple linear regression methods, g02da, with a set of independent variables which are in fact simply the same single variable raised to different powers, or you can use the method (G04EAF not in this release) to compute orthogonal polynomials which can then be used with g02da, or you can use the methods in E02 class (Curve and Surface Fitting) which fit polynomials to sets of data points using the techniques of orthogonal polynomials. This latter course is to be preferred, since it is more efficient and liable to be more accurate, but in some cases more statistical information may be required than is provided by those methods, and it may be necessary to use the methods of this chapter.
More general nonlinear regression models may be fitted using the optimization methods in E04 class, which contains methods to minimize the function
∑i=1 n ei 2
where the regression parameters are the variables of the minimization problem.

Multiple linear regression – general linear model

g02da fits a general linear regression model using the QR method and an SVD if the model is not of full rank. The results returned include: residual sum of squares, parameter estimates, their standard errors and variance-covariance matrix, residuals and leverages. There are also several methods to modify the model fitted by g02da and to aid in the interpretation of the model.
g02dc adds or deletes an observation from the model.
g02dd computes the parameter estimates, and their standard errors and variance-covariance matrix for a model that is modified by g02dc, g02de or g02df.
g02de adds a new variable to a model.
g02df drops a variable from a model.
g02dg fits the regression to a new dependent variable, i.e., keeping the same independent variables.
g02dk calculates the estimates of the parameters for a given set of constraints, (e.g., parameters for the levels of a factor sum to zero) for a model which is not of full rank and the SVD has been used.
g02dn calculates the estimate of an estimable function and its standard error.
Note: g02de also allows you to initialize a model building process and then to build up the model by adding variables one at a time.
If you wish to use methods based on forming the cross-products/correlation matrix (i.e., (XT X) matrix) rather than the recommended use of g02da then the following methods should be used.
For regression through the origin (i.e., no constant) g02ch preceded by:
  • g02bd (no missing values, all variables)
  • g02bk (no missing values, subset of variables)
  • g02be (casewise missing values, all variables)
  • g02bl(casewise missing values, subset of variables)
  • g02bf* (pairwise missing values, all variables)
  • g02bm* (pairwise missing values, subset of variables)
For regression with intercept (i.e., with constant) g02cg preceded by:
  • g02ba (no missing values, all variables)
  • g02bg (no missing values, subset of variables)
  • g02bb (casewise missing values, all variables)
  • g02bh (casewise missing values, subset of variables)
  • g02bc* (pairwise missing values, all variables)
  • g02bj* (pairwise missing values, subset of variables)
Note that the four methods using pairwise deletion of missing value (marked with *) should be used with great caution as the use of this method can lead to misleading results, particularly if a significant proportion of values are missing.
Both g02cg and g02ch require that the correlations/sums of squares involving the dependent variable must appear as the last row/column. Because the layout of the variables in your data array may not be arranged in this way, two methods, g02ce and g02cf, are provided for rearranging the rows and columns of vectors and matrices. g02cf simply reorders the rows and columns while g02ce forms smaller vectors and matrices from larger ones.
Output from g02cg and g02ch consists of the coefficients, their standard errors, R 2-values, t and F statistics.

Selecting regression models

To aid the selection of a regression model the following methods are available.
(G02EAF not in this release) computes the residual sums of squares for all possible regressions for a given set of dependent variables. The method allows some variables to be forced into all regressions.
(G02ECF not in this release) computes the values of R 2 and Cp from the residual sums of squares as provided by (G02EAF not in this release).
(G02EEF not in this release) enables you to fit a model by forward selection. You may call (G02EEF not in this release) a number of times. At each call the method will calculate the changes in the residual sum of squares from adding each of the variables not already included in the model, select the variable which gives the largest change and then if the change in residual sum of squares meets the given criterion will add it to the model.
g02ef uses a full stepwise selection to choose a subset of the explanatory variables. The method repeatedly applies a forward selection step followed by a backward elimination step until neither step updates the current model.

Residuals

g02fa computes the following standardized residuals and measures of influence for the residuals and leverages produced by g02da:
(i) | Internally studentized residual;
(ii) | Externally studentized residual;
(iii) | Cook's D statistic;
(iv) | Atkinson's T statistic.
g02fc computes the Durbin–Watson test statistic and bounds for its significance to test for serial correlation in the errors, ei.

Robust regression

For robust regression using M-estimates instead of least squares the method g02ha will generally be suitable. g02ha provides a choice of four ψ-functions (Huber's, Hampel's, Andrew's and Tukey's) plus two different weighting methods and the option not to use weights. If other weights or different ψ-functions are needed the method g02hd may be used. g02hd requires you to supply weights, if required, and also methods to calculate the ψ-function and, optionally, the χ-function. g02hb can be used in calculating suitable weights. The method g02hf can be used after a call to g02hd in order to calculate the variance-covariance estimate of the estimated regression coefficients.
For robust regression, using least absolute deviation, (E02GAF not in this release) can be used.

Generalized linear models

There are four methods for fitting generalized linear models. The output includes: the deviance, parameter estimates and their standard errors, fitted values, residuals and leverages.
g02ga Normal distribution.
g02gb binomial distribution.
g02gc Poisson distribution.
g02gd gamma distribution.
While g02ga can be used to fit linear regression models (i.e., by using an identity link) this is not recommended as g02da will fit these models more efficiently. g02gc can be used to fit log-linear models to contingency tables.
In addition to the methods to fit the models there is one method to predict from the fitted model and two methods to aid interpretation when the fitted model is not of full rank, i.e., aliasing is present.
g02gp computes a predicted value and its associated standard error based on a previously fitted generalized linear model.
g02gk computes parameter estimates for a set of constraints, (e.g., sum of effects for a factor is zero), from the SVD solution provided by the fitting method.
g02gn calculates an estimate of an estimable function along with its standard error.

Linear mixed effects regression

There are four methods for fitting linear mixed effects regression.
g02ja (G02JDF not in this release) uses restricted maximum likelihood (REML) to fit the model.
g02jb (G02JEF not in this release) uses maximum likelihood to fit the model.
For all methods the output includes: either the maximum likelihood or restricted maximum likelihood and the fixed and random parameter estimates, along with their standard errors. Whilst it is possible to fit a hierachical model using g02ja or g02jb, (G02JDF not in this release) (G02JEF not in this release) allow the model to be specified in a more intuitive way. (G02JCF not in this release) must be called prior to calling (G02JDF not in this release) (G02JEF not in this release).
As the estimates of the variance components are found using an iterative procedure initial values must be supplied for each σ. In all four methods you can either specify these initial values, or allow the method to calculate them from the data using minimum variance quadratic unbiased estimation (MIVQUE0). Setting the maximum number of iterations to zero in any of the methods will return the corresponding likelihood, parameter estimates and standard errors based on these initial values.

Linear quantile regression

Two methods are provided for performing linear quantile regression, g02qf and g02qg. Of these, g02qf provides a simplified interface to g02qg, where many of the input parameters have been given default values and the amount of output available has been reduced.
Prior to calling g02qg the optional parameter array must be initialized by calling (G02ZKF not in this release) with optstr set to initialize. Once these arrays have been initialized (G02ZLF not in this release) can be called to query the value of an optional parameter.

Partial Least Squares (PLS)

g02la calculates a nonlinear, iterative PLS by using singular value decomposition.
g02lb calculates a nonlinear, iterative PLS by using Wold's method.
g02lc calculates parameter estimates for a given number of PLS factors.
g02ld calculates predictions given a PLS model.

References

Atkinson A C (1986) Plots, Transformations and Regressions Clarendon Press, Oxford
Churchman C W and Ratoosh P (1959) Measurement Definitions and Theory Wiley
Cook R D and Weisberg S (1982) Residuals and Influence in Regression Chapman and Hall
Draper N R and Smith H (1985) Applied Regression Analysis (2nd Edition) Wiley
Gill P E and Murray W (1978) Numerically stable methods for quadratic programming Math. Programming 14 349–372
Hammarling S (1985) The singular value decomposition in multivariate statistics SIGNUM Newsl. 20(3) 2–25
Hampel F R, Ronchetti E M, Rousseeuw P J and Stahel W A (1986) Robust Statistics. The Approach Based on Influence Functions Wiley
Hays W L (1970) Statistics Holt, Rinehart and Winston
Hendricks W and Koenker R (1991) Hierarchical spline models for conditional quantiles and the demand for electricity Journal of the Maerican Statistical Association 87 58–68
Huber P J (1981) Robust Statistics Wiley
Kendall M G and Stuart A (1973) The Advanced Theory of Statistics (Volume 2) (3rd Edition) Griffin
Koenker R (2005) Quantile Regression Econometric Society Monographs, Cambridge University Press, New York
McCullagh P and Nelder J A (1983) Generalized Linear Models Chapman and Hall
Powell J L (1991) Estimation of monotonic regression models under quantile restrictions Nonparametric and Semiparametric Methods in Econometrics Cambridge University Press, Cambridge
Qi H and Sun D (2006) A quadratically convergent Newton method for computing the nearest correlation matrix SIAM J. Matrix AnalAppl 29(2) 360–385
Searle S R (1971) Linear Models Wiley
Siegel S (1956) Non-parametric Statistics for the Behavioral Sciences McGraw–Hill
Weisberg S (1985) Applied Linear Regression Wiley

Inheritance Hierarchy

System..::..Object
NagLibrary..::..G02

See Also

G02 Members


G02 Members

[image] [image]

NAG Library for .NET Release 2
G02 Members
G02 Class Methods See Also Send Feedback

The G02 type exposes the following members.

Methods

Name | Description
g02aa | g02aa computes the nearest correlation matrix, in the Frobenius norm, to a given square, input matrix.
g02ab | g02ab computes the nearest correlation matrix, in the Frobenius norm or weighted Frobenius norm, and optionally with bounds on the eigenvalues, to a given square, input matrix.
g02ae | g02ae computes the factor loading matrix associated with the nearest correlation matrix with k-factor structure, in the Frobenius norm, to a given square, input matrix.
g02ba | g02ba computes means and standard deviations of variables, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients for a set of data.
g02bb | g02bb computes means and standard deviations of variables, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients for a set of data omitting completely any cases with a missing observation for any variable.
g02bc | g02bc computes means and standard deviations of variables, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients for a set of data omitting cases with missing values from only those calculations involving the variables for which the values are missing.
g02bd | g02bd computes means and standard deviations of variables, sums of squares and cross-products about zero, and correlation-like coefficients for a set of data.
g02be | g02be computes means and standard deviations of variables, sums of squares and cross-products about zero, and correlation-like coefficients for a set of data omitting completely any cases with a missing observation for any variable.
g02bf | g02bf computes means and standard deviations of variables, sums of squares and cross-products about zero and correlation-like coefficients for a set of data omitting cases with missing values from only those calculations involving the variables for which the values are missing.
g02bg | g02bg computes means and standard deviations, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients for selected variables.
g02bh | g02bh computes means and standard deviations, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients for selected variables omitting completely any cases with a missing observation for any variable (either over all variables in the dataset or over only those variables in the selected subset).
g02bj | g02bj computes means and standard deviations, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients for selected variables omitting cases with missing values from only those calculations involving the variables for which the values are missing.
g02bk | g02bk computes means and standard deviations, sums of squares and cross-products about zero, and correlation-like coefficients for selected variables.
g02bl | g02bl computes means and standard deviations, sums of squares and cross-products about zero, and correlation-like coefficients for selected variables omitting completely any cases with a missing observation for any variable (either over all variables in the dataset or over only those variables in the selected subset).
g02bm | g02bm computes means and standard deviations, sums of squares and cross-products about zero, and correlation-like coefficients for selected variables omitting cases with missing values from only those calculations involving the variables for which the values are missing.
g02bn | g02bn computes Kendall and/or Spearman nonparametric rank correlation coefficients for a set of data; the data array is overwritten with the ranks of the observations.
g02bp | g02bp computes Kendall and/or Spearman nonparametric rank correlation coefficients for a set of data omitting completely any cases with a missing observation for any variable; the data array is overwritten with the ranks of the observations.
g02bq | g02bq computes Kendall and/or Spearman nonparametric rank correlation coefficients for a set of data; the data array is preserved, and the ranks of the observations are not available on exit from the method.
g02br | g02br computes Kendall and/or Spearman nonparametric rank correlation coefficients for a set of data, omitting completely any cases with a missing observation for any variable; the data array is preserved, and the ranks of the observations are not available on exit from the method.
g02bs | g02bs computes Kendall and/or Spearman nonparametric rank correlation coefficients for a set of data omitting cases with missing values from only those calculations involving the variables for which the values are missing; the data array is preserved, and the ranks of the observations are not available on exit from the method.
g02bt | g02bt updates the sample means and sums of squares and cross-products, or sums of squares and cross-products of deviations about the mean, for a new observation. The data may be weighted.
g02bu | g02bu calculates the sample means and sums of squares and cross-products, or sums of squares and cross-products of deviations from the mean, in a single pass for a set of data. The data may be weighted.
g02bw | g02bw calculates a matrix of Pearson product-moment correlation coefficients from sums of squares and cross-products of deviations about the mean.
g02bx | g02bx calculates the sample means, the standard deviations, the variance-covariance matrix, and the matrix of Pearson product-moment correlation coefficients for a set of data. Weights may be used.
g02by | g02by computes a partial correlation/variance-covariance matrix from a correlation or variance-covariance matrix computed by g02bx.
g02ca | g02ca performs a simple linear regression with dependent variable y and independent variable x.
g02cb | g02cb performs a simple linear regression with no constant, with dependent variable y and independent variable x.
g02cc | g02cc performs a simple linear regression with dependent variable y and independent variable x, omitting cases involving missing values.
g02cd | g02cd performs a simple linear regression with no constant, with dependent variable y and independent variable x, omitting cases involving missing values.
g02ce | g02ce takes selected elements from two vectors (typically vectors of means and standard deviations) to form two smaller vectors, and selected rows and columns from two matrices (typically either matrices of sums of squares and cross-products of deviations from means and Pearson product-moment correlation coefficients, or matrices of sums of squares and cross-products about zero and correlation-like coefficients) to form two smaller matrices, allowing reordering of elements in the process.
g02cf | g02cf reorders the elements in two vectors (typically vectors of means and standard deviations), and the rows and columns in two matrices (typically either matrices of sums of squares and cross-products of deviations from means and Pearson product-moment correlation coefficients, or matrices of sums of squares and cross-products about zero and correlation-like coefficients).
g02cg | g02cg performs a multiple linear regression on a set of variables whose means, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients are given.
g02ch | g02ch performs a multiple linear regression with no constant on a set of variables whose sums of squares and cross-products about zero and correlation-like coefficients are given.
g02da | g02da performs a general multiple linear regression when the independent variables may be linearly dependent. Parameter estimates, standard errors, residuals and influence statistics are computed. g02da may be used to perform a weighted regression.
g02dc | g02dc adds or deletes an observation from a general regression model fitted by g02da.
g02dd | g02dd calculates the regression parameters for a general linear regression model. It is intended to be called after g02dc, g02de or g02df.
g02de | g02de adds a new independent variable to a general linear regression model.
g02df | g02df deletes an independent variable from a general linear regression model.
g02dg | g02dg calculates the estimates of the parameters of a general linear regression model for a new dependent variable after a call to g02da.
g02dk | g02dk calculates the estimates of the parameters of a general linear regression model for given constraints from the singular value decomposition results.
g02dn | g02dn gives the estimate of an estimable function along with its standard error.
g02ef | g02ef calculates a full stepwise selection from p variables by using Clarke's sweep algorithm on the correlation matrix of a design and data matrix, Z. The (weighted) variance-covariance, (weighted) means and sum of weights of Z must be supplied.
g02fa | g02fa calculates two types of standardized residuals and two measures of influence for a linear regression.
g02fc | g02fc calculates the Durbin–Watson statistic, for a set of residuals, and the upper and lower bounds for its significance.
g02ga | g02ga fits a generalized linear model with normal errors.
g02gb | g02gb fits a generalized linear model with binomial errors.
g02gc | g02gc fits a generalized linear model with Poisson errors.
g02gd | g02gd fits a generalized linear model with gamma errors.
g02gk | g02gk calculates the estimates of the parameters of a generalized linear model for given constraints from the singular value decomposition results.
g02gn | g02gn gives the estimate of an estimable function along with its standard error from the results from fitting a generalized linear model.
g02gp | g02gp allows prediction from a generalized linear model fit via g02ga, g02gb, g02gc or g02gd.
g02ha | g02ha performs bounded influence regression (M-estimates). Several standard methods are available.
g02hb | g02hb finds, for a real matrix X of full column rank, a lower triangular matrix A such that AT A-1 is proportional to a robust estimate of the covariance of the variables. g02hb is intended for the calculation of weights of bounded influence regression using g02hd.
g02hd | g02hd performs bounded influence regression (M-estimates) using an iterative weighted least squares algorithm.
g02hdz | Auxiliary for use as a delegate parameter
g02hf | g02hf calculates an estimate of the asymptotic variance-covariance matrix for the bounded influence regression estimates (M-estimates). It is intended for use with g02hd.
g02hk | g02hk computes a robust estimate of the covariance matrix for an expected fraction of gross errors.
g02hl | g02hl calculates a robust estimate of the covariance matrix for user-supplied weight functions and their derivatives.
g02hm | g02hm computes a robust estimate of the covariance matrix for user-supplied weight functions. The derivatives of the weight functions are not required.
g02ja | g02ja fits a linear mixed effects regression model using restricted maximum likelihood (REML).
g02jb | g02jb fits a linear mixed effects regression model using maximum likelihood (ML).
g02ka | g02ka calculates a ridge regression, optimizing the ridge parameter according to one of four prediction error criteria.
g02kb | g02kb calculates a ridge regression, with ridge parameters supplied by you.
g02la | g02la fits an orthogonal scores partial least squares (PLS) regression by using singular value decomposition.
g02lb | g02lb fits an orthogonal scores partial least squares (PLS) regression by using Wold's iterative method.
g02lc | g02lc calculates parameter estimates for a given number of factors given the output from an orthogonal scores PLS regression (g02la or g02lb).
g02ld | g02ld calculates predictions given the output from an orthogonal scores PLS regression (g02la or g02lb) and g02lc.
g02qf | g02qf performs a multiple linear quantile regression, returning the parameter estimates and associated confidence limits based on an assumption of Normal, independent, identically distributed errors. g02qf is a simplified version of g02qg.
g02qg | g02qg performs a multiple linear quantile regression. Parameter estimates and, if required, confidence limits, covariance matrices and residuals are calculated. g02qg may be used to perform a weighted quantile regression. A simplified interface for g02qg is provided by g02qf.

See Also

G02 Class


G02 Delegates

[image]

NAG Library for .NET Release 2
G02 Delegates

G02 Delegate Types

  • G02.G02EF_MONFUN Delegate
  • G02.G02HB_UCV Delegate
  • G02.G02HD_CHI Delegate
  • G02.G02HD_PSI Delegate
  • G02.G02HF_PSI Delegate
  • G02.G02HF_PSP Delegate
  • G02.G02HL_UCV Delegate
  • G02.G02HM_UCV Delegate


G02.G02EF_MONFUN Delegate

[image]

NAG Library for .NET Release 2
G02..::..G02EF_MONFUN Delegate
G02 Class See Also Send Feedback
You may define your own function or specify the NAG defined default function G02EFH.

Syntax

C#
public delegate void G02EF_MONFUN(
    string flag,
    int var,
    double val
)
Visual Basic
Public Delegate Sub G02EF_MONFUN ( _
    flag As String, _
    var As Integer, _
    val As Double _
)
Visual C++
public delegate void G02EF_MONFUN(
    String^ flag,
    int var,
    double val
)
F#
type G02EF_MONFUN =
    delegate of
        flag : string *
        var : int *
        val : float -> unit

Parameters

flag
Type: System..::..String
On entry: the value of flag indicates the stage of the stepwise selection of explanatory variables.
flag="A"
Variable var was added to the current model.
flag="B"
Beginning the backward elimination step.
flag="C"
Variable var failed the collinearity test and is excluded from the model.
flag="D"
Variable var was dropped from the current model.
flag="F"
Beginning the forward selection step
flag="K"
Backward elimination did not remove any variables from the current model.
flag="S"
Starting stepwise selection procedure.
flag="V"
The variance ratio for variable var takes the value val.
flag="X"
Finished stepwise selection procedure.
var
Type: System..::..Int32
On entry: the index of the explanatory variable in the design matrix Z to which flag pertains.
val
Type: System..::..Double
On entry: if flag="V", val is the variance ratio value for the coefficient associated with explanatory variable index var.

See Also

NagLibrary Namespace
NAG Library Overview
g02ef


G02.G02HB_UCV Delegate

[image]

NAG Library for .NET Release 2
G02..::..G02HB_UCV Delegate
G02 Class See Also Send Feedback
ucv must return the value of the function u for a given value of its argument. The value of u must be non-negative.

Syntax

C#
public delegate double G02HB_UCV(
    double t
)
Visual Basic
Public Delegate Function G02HB_UCV ( _
    t As Double _
) As Double
Visual C++
public delegate double G02HB_UCV(
    double t
)
F#
type G02HB_UCV =
    delegate of
        t : float -> float

Parameters

t
Type: System..::..Double
On entry: the argument for which ucv must be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
g02hb


G02.G02HD_CHI Delegate

[image]

NAG Library for .NET Release 2
G02..::..G02HD_CHI Delegate
G02 Class See Also Send Feedback
If isigma>0, chi must return the value of the weight function χ for a given value of its argument. The value of χ must be non-negative.

Syntax

C#
public delegate double G02HD_CHI(
    double t
)
Visual Basic
Public Delegate Function G02HD_CHI ( _
    t As Double _
) As Double
Visual C++
public delegate double G02HD_CHI(
    double t
)
F#
type G02HD_CHI =
    delegate of
        t : float -> float

Parameters

t
Type: System..::..Double
On entry: the argument for which chi must be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
g02hd


G02.G02HD_PSI Delegate

[image]

NAG Library for .NET Release 2
G02..::..G02HD_PSI Delegate
G02 Class See Also Send Feedback
psi must return the value of the weight function ψ for a given value of its argument.

Syntax

C#
public delegate double G02HD_PSI(
    double t
)
Visual Basic
Public Delegate Function G02HD_PSI ( _
    t As Double _
) As Double
Visual C++
public delegate double G02HD_PSI(
    double t
)
F#
type G02HD_PSI =
    delegate of
        t : float -> float

Parameters

t
Type: System..::..Double
On entry: the argument for which psi must be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
g02hd


G02.G02HF_PSI Delegate

[image]

NAG Library for .NET Release 2
G02..::..G02HF_PSI Delegate
G02 Class See Also Send Feedback
psi must return the value of the ψ function for a given value of its argument.

Syntax

C#
public delegate double G02HF_PSI(
    double t
)
Visual Basic
Public Delegate Function G02HF_PSI ( _
    t As Double _
) As Double
Visual C++
public delegate double G02HF_PSI(
    double t
)
F#
type G02HF_PSI =
    delegate of
        t : float -> float

Parameters

t
Type: System..::..Double
On entry: the argument for which psi must be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
g02hf


G02.G02HF_PSP Delegate

[image]

NAG Library for .NET Release 2
G02..::..G02HF_PSP Delegate
G02 Class See Also Send Feedback
psp must return the value of ψ′t=d dt ψ t for a given value of its argument.

Syntax

C#
public delegate double G02HF_PSP(
    double t
)
Visual Basic
Public Delegate Function G02HF_PSP ( _
    t As Double _
) As Double
Visual C++
public delegate double G02HF_PSP(
    double t
)
F#
type G02HF_PSP =
    delegate of
        t : float -> float

Parameters

t
Type: System..::..Double
On entry: the argument for which psp must be evaluated.

See Also

NagLibrary Namespace
NAG Library Overview
g02hf


G02.G02HL_UCV Delegate

[image]

NAG Library for .NET Release 2
G02..::..G02HL_UCV Delegate
G02 Class See Also Send Feedback
ucv must return the values of the functions u and w and their derivatives for a given value of its argument.

Syntax

C#
public delegate void G02HL_UCV(
    double t,
    out double u,
    out double ud,
    out double w,
    out double wd
)
Visual Basic
Public Delegate Sub G02HL_UCV ( _
    t As Double, _
    <OutAttribute> ByRef u As Double, _
    <OutAttribute> ByRef ud As Double, _
    <OutAttribute> ByRef w As Double, _
    <OutAttribute> ByRef wd As Double _
)
Visual C++
public delegate void G02HL_UCV(
    double t,
    [OutAttribute] double% u,
    [OutAttribute] double% ud,
    [OutAttribute] double% w,
    [OutAttribute] double% wd
)
F#
type G02HL_UCV =
    delegate of
        t : float *
        u : float byref *
        ud : float byref *
        w : float byref *
        wd : float byref -> unit

Parameters

t
Type: System..::..Double
On entry: the argument for which the functions u and w must be evaluated.
u
Type: System..::..Double %
On exit: the value of the u function at the point t.
Constraint: u≥0.0.
ud
Type: System..::..Double %
On exit: the value of the derivative of the u function at the point t.
w
Type: System..::..Double %
On exit: the value of the w function at the point t.
Constraint: w≥0.0.
wd
Type: System..::..Double %
On exit: the value of the derivative of the w function at the point t.

See Also

NagLibrary Namespace
NAG Library Overview
g02hl


G02.G02HM_UCV Delegate

[image]

NAG Library for .NET Release 2
G02..::..G02HM_UCV Delegate
G02 Class See Also Send Feedback
ucv must return the values of the functions u and w for a given value of its argument.

Syntax

C#
public delegate void G02HM_UCV(
    double t,
    out double u,
    out double w
)
Visual Basic
Public Delegate Sub G02HM_UCV ( _
    t As Double, _
    <OutAttribute> ByRef u As Double, _
    <OutAttribute> ByRef w As Double _
)
Visual C++
public delegate void G02HM_UCV(
    double t,
    [OutAttribute] double% u,
    [OutAttribute] double% w
)
F#
type G02HM_UCV =
    delegate of
        t : float *
        u : float byref *
        w : float byref -> unit

Parameters

t
Type: System..::..Double
On entry: the argument for which the functions u and w must be evaluated.
u
Type: System..::..Double %
On exit: the value of the u function at the point t.
Constraint: u≥0.0.
w
Type: System..::..Double %
On exit: the value of the w function at the point t.
Constraint: w≥0.0.

See Also

NagLibrary Namespace
NAG Library Overview
g02hm


G02 Classes

[image]

NAG Library for .NET Release 2
G02 Classes

G02 Classes

  • G02.g02qgOptions Class


G02.g02qgOptions Class

[image]

NAG Library for .NET Release 2
G02..::..g02qgOptions Class
G02 Class Members See Also Send Feedback
Options Class for g02qg

Syntax

C#
public class g02qgOptions
Visual Basic
Public Class g02qgOptions
Visual C++
public ref class g02qgOptions
F#
type g02qgOptions =  class end

Description of the Optional Parameters

For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
  • the keywords, where the minimum abbreviation of each keyword is underlined (if no characters of an optional qualifier are underlined, the qualifier may be omitted);
  • a parameter value, where the letters a, i​ and ​r denote options that take character, integer and real values respectively;
  • the default value, where the symbol ε is a generic notation for machine precision (see x02aj).
Keywords and character values are case and white space insensitive.
Band Width Alpha
A multiplier used to construct the parameter αb used when calculating the Sheather–Hall bandwidth (see [Description]), with αb=1-α×Band Width Alpha. Here, α is the Significance Level.
Constraint: Band Width Alpha>0.0.
Band Width Method
The method used to calculate the bandwidth used in the calculation of the asymptotic covariance matrix Σ and H-1 if Interval Method=HKS, KERNEL or IID (see [Description]).
Constraint: Band Width Method=SHEATHER HALL or BOFINGER.
Big
This parameter should be set to something larger than the biggest value supplied in dat and y.
Constraint: Big>0.0.
Bootstrap Interval Method
If Interval Method=BOOTSTRAP XY, Bootstrap Interval Method controls how the confidence intervals are calculated from the bootstrap estimates.
Bootstrap Interval Method=T
t intervals are calculated. That is, the covariance matrix, Σ=σ ij:i,j=1,2,…,p is calculated from the bootstrap estimates and the limits calculated as βi±t n-p,1+α/2σ ii where t n-p,1+α/2 is the 1+α/2 percentage point from a Student's t distribution on n-p degrees of freedom, n is the effective number of observations and α is given by the optional parameter Significance Level.
Bootstrap Interval Method=QUANTILE
Quantile intervals are calculated. That is, the upper and lower limits are taken as the 1+α/2 and 1-α/2 quantiles of the bootstrap estimates, as calculated using g01am.
Constraint: Bootstrap Interval Method=T or QUANTILE.
Bootstrap Iterations
The number of bootstrap samples used to calculate the confidence limits and covariance matrix (if requested) when Interval Method=BOOTSTRAP XY.
Constraint: Bootstrap Iterations>1.
Bootstrap Monitoring
If Bootstrap Monitoring=YES and Interval Method=BOOTSTRAP XY, then the parameter estimates for each of the bootstrap samples are displayed. This information is sent to the unit number specified by Unit Number.
Constraint: Bootstrap Monitoring=YES or NO.
Calculate Initial Values
If Calculate Initial Values=YES then the initial values for the regression parameters, β, are calculated from the data. Otherwise they must be supplied in b.
Constraint: Calculate Initial Values=YES or NO.
Defaults
This special keyword is used to reset all optional parameters to their default values.
Drop Zero Weights
If a weighted regression is being performed and Drop Zero Weights=YES then observations with zero weight are dropped from the analysis. Otherwise such observations are included.
Constraint: Drop Zero Weights=YES or NO.
Epsilon
εu, the tolerance used when calculating the covariance matrix and the initial values for u and v. For additional details see [Calculation of Covariance Matrix] and [Additional information] respectively.
Constraint: Epsilon≥0.0.
Interval Method
The value of Interval Method controls whether confidence limits are returned in bl and bu and how these limits are calculated. This parameter also controls how the matrices returned in ch are calculated.
Interval Method=NONE
No limits are calculated and bl, bu and ch are not referenced.
Interval Method=KERNEL
The Powell Sandwich method with a Gaussian kernel is used.
Interval Method=HKS
The Hendricks–Koenker Sandwich is used.
Interval Method=IID
The errors are assumed to be identical, and independently distributed.
Interval Method=BOOTSTRAP XY
A bootstrap method is used, where sampling is done on the pair yi,xi. The number of bootstrap samples is controlled by the parameter Bootstrap Iterations and the type of interval constructed from the bootstrap samples is controlled by Bootstrap Interval Method.
Constraint: Interval Method=NONE, KERNEL, HKS, IID or BOOTSTRAP XY.
Iteration Limit
The maximum number of iterations to be performed by the interior point optimization algorithm.
Constraint: Iteration Limit>0.
Matrix Returned
The value of Matrix Returned controls the type of matrices returned in ch. If Interval Method=NONE, this parameter is ignored and ch is not referenced. Otherwise:
Matrix Returned=NONE
No matrices are returned and ch is not referenced.
Matrix Returned=COVARIANCE
The covariance matrices are returned.
Matrix Returned=H INVERSE
If Interval Method=KERNEL or HKS, the matrices J and H-1 are returned. Otherwise no matrices are returned and ch is not referenced.
The matrices returned are calculated as described in [Description], with the algorithm used specified by Interval Method. In the case of Interval Method=BOOTSTRAP XY the covariance matrix is calculated directly from the bootstrap estimates.
Constraint: Matrix Returned=NONE, COVARIANCE or H INVERSE.
Monitoring
If Monitoring=YES then the duality gap is displayed at each iteration of the interior point optimization algorithm. In addition, the final estimates for β are also displayed.
The monitoring information is sent to the unit number specified by Unit Number.
Constraint: Monitoring=YES or NO.
QR Tolerance
The tolerance used to calculate the rank, k, of the p×p cross-product matrix, XT X. Letting Q be the orthogonal matrix obtained from a QR decomposition of XT X, then the rank is calculated by comparing Q ii with Q 11×QR Tolerance.
If the cross-product matrix is rank deficient, then the parameter estimates for the p-k columns with the smallest values of Q ii are set to zero, along with the corresponding entries in bl, bu and ch, if returned. This is equivalent to dropping these variables from the model. Details on the QR decomposition used can be found in f08bf.
Constraint: QR Tolerance>0.0.
Return Residuals
If Return Residuals=YES, the residuals are returned in res. Otherwise res is not referenced.
Constraint: Return Residuals=YES or NO.
Sigma
The scaling factor used when calculating the affine scaling step size (see equation (8)).
Constraint: 0.0<Sigma<1.0.
Significance Level
α, the size of the confidence interval whose limits are returned in bl and bu.
Constraint: 0.0<Significance Level<1.0.
Tolerance
Convergence tolerance. The optimization is deemed to have converged if the duality gap is less than Tolerance (see [Update and convergence]).
Constraint: Tolerance>0.0.
Unit Number
The unit number to which any monitoring information is sent.
Constraint: Unit Number>1.

Inheritance Hierarchy

System..::..Object
NagLibrary..::..G02..::..g02qgOptions

See Also

G02..::..g02qgOptions Members
NagLibrary Namespace
NAG Library Overview
g02qg


G02.g02qgOptions Members

[image] [image]

NAG Library for .NET Release 2
G02..::..g02qgOptions Members
G02..::..g02qgOptions Class Constructors Methods Properties See Also Send Feedback

This chapter is concerned with two techniques – correlation analysis and regression modelling – both of which are concerned with determining the inter-relationships among two or more variables.
Other chapters of the NAG Library which cover similar problems are E02 class E04 class. E02 class methods may be used to fit linear models by criteria other than least squares, and also for polynomial regression; E04 class methods may be used to fit nonlinear models and linearly constrained linear models.

The G02..::..g02qgOptions type exposes the following members.

Constructors

Name | Description
G02..::..g02qgOptions | Constructor

Methods

Name | Description
Get | Overloaded.
Set | Overloaded.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from g02qg.
Warning | Set the method used for logging any warning or error messages from g02qg.

See Also

G02..::..g02qgOptions Class


G02.g02qgOptions Constructor

[image]

NAG Library for .NET Release 2
G02..::..g02qgOptions Constructor
G02..::..g02qgOptions Class See Also Send Feedback
Constructor

Syntax

C#
public g02qgOptions()
Visual Basic
Public Sub New
Visual C++
public:
g02qgOptions()
F#
new : unit -> g02qgOptions

See Also

G02..::..g02qgOptions Class
G02..::..g02qgOptions Members


G02.g02qgOptions Methods

[image] [image]

NAG Library for .NET Release 2
G02..::..g02qgOptions Methods
G02..::..g02qgOptions Class See Also Send Feedback

Methods

Name | Description
Get | Overloaded.
Set | Overloaded.

See Also

G02..::..g02qgOptions Class


Get Method

[image] [image]

NAG Library for .NET Release 2
G02..::..g02qgOptions..::Get Method
G02..::..g02qgOptions Class See Also Send Feedback

Overload List

Name | Description
Get(String, Double) | Get an Option value for g02qg
Get(String, Int32%) | Get an Option value for g02qg
Get(String, String%) | Get an Option value for g02qg

See Also

G02..::..g02qgOptions Class
G02..::..g02qgOptions Members


Get Method (String, Double)

[image]

NAG Library for .NET Release 2
G02..::..g02qgOptions..::Get Method (String, Double)
G02..::..g02qgOptions Class See Also Send Feedback
Get an Option value for g02qg

Syntax

C#
public void Get(
    string optstr,
    double rvalue
)
Visual Basic
Public Sub Get ( _
    optstr As String, _
    rvalue As Double _
)
Visual C++
public:
void Get(
    String^ optstr,
    double rvalue
)
F#
member Get :
        optstr : string *
        rvalue : float -> unit

Parameters

optstr
Type: System..::..String
The name of an option.
rvalue
Type: System..::..Double
The option value.

See Also

G02..::..g02qgOptions Class
G02..::..g02qgOptions Members
Get Overload


Get Method (String, Int32)

[image]

NAG Library for .NET Release 2
G02..::..g02qgOptions..::Get Method (String, Int32%)
G02..::..g02qgOptions Class See Also Send Feedback
Get an Option value for g02qg

Syntax

C#
public void Get(
    string optstr,
    out int ivalue
)
Visual Basic
Public Sub Get ( _
    optstr As String, _
    <OutAttribute> ByRef ivalue As Integer _
)
Visual C++
public:
void Get(
    String^ optstr,
    [OutAttribute] int% ivalue
)
F#
member Get :
        optstr : string *
        ivalue : int byref -> unit

Parameters

optstr
Type: System..::..String
The name of an option.
ivalue
Type: System..::..Int32 %
The option value.

See Also

G02..::..g02qgOptions Class
G02..::..g02qgOptions Members
Get Overload


Get Method (String, String)

[image]

NAG Library for .NET Release 2
G02..::..g02qgOptions..::Get Method (String, String%)
G02..::..g02qgOptions Class See Also Send Feedback
Get an Option value for g02qg

Syntax

C#
public void Get(
    string optstr,
    ref string cvalue
)
Visual Basic
Public Sub Get ( _
    optstr As String, _
    ByRef cvalue As String _
)
Visual C++
public:
void Get(
    String^ optstr,
    String^% cvalue
)
F#
member Get :
        optstr : string *
        cvalue : string byref -> unit

Parameters

optstr
Type: System..::..String
The name of an option.
cvalue
Type: System..::..String %
The option value.

See Also

G02..::..g02qgOptions Class
G02..::..g02qgOptions Members
Get Overload


Set Method

[image] [image]

NAG Library for .NET Release 2
G02..::..g02qgOptions..::Set Method
G02..::..g02qgOptions Class See Also Send Feedback

Overload List

Name | Description
Set(String) | Set an Option for g02qg
Set(DataReader) | Set Options for from a DataReader Stream.

See Also

G02..::..g02qgOptions Class
G02..::..g02qgOptions Members


Set Method (String)

[image]

NAG Library for .NET Release 2
G02..::..g02qgOptions..::Set Method (String)
G02..::..g02qgOptions Class See Also Send Feedback
Set an Option for g02qg

Syntax

C#
public void Set(
    string optstr
)
Visual Basic
Public Sub Set ( _
    optstr As String _
)
Visual C++
public:
void Set(
    String^ optstr
)
F#
member Set :
        optstr : string -> unit

Parameters

optstr
Type: System..::..String
A string of the form option = value, or for boolean options, simply option.

See Also

G02..::..g02qgOptions Class
G02..::..g02qgOptions Members
Set Overload


Set Method (DataReader)

[image]

NAG Library for .NET Release 2
G02..::..g02qgOptions..::Set Method (DataReader)
G02..::..g02qgOptions Class See Also Send Feedback
Set Options for from a DataReader Stream.

Syntax

C#
public void Set(
    DataReader sr
)
Visual Basic
Public Sub Set ( _
    sr As DataReader _
)
Visual C++
public:
void Set(
    DataReader^ sr
)
F#
member Set :
        sr : DataReader -> unit

Parameters

sr
Type: NagLibrary..::..DataReader
A DataReader Stream, containing an option setting on each line.

See Also

G02..::..g02qgOptions Class
G02..::..g02qgOptions Members
Set Overload


G02.g02qgOptions Properties

[image] [image]

NAG Library for .NET Release 2
G02..::..g02qgOptions Properties
G02..::..g02qgOptions Class See Also Send Feedback

The G02..::..g02qgOptions type exposes the following members.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from g02qg.
Warning | Set the method used for logging any warning or error messages from g02qg.

See Also

G02..::..g02qgOptions Class


Message Property

[image]

NAG Library for .NET Release 2
G02..::..g02qgOptions..::Message Property
G02..::..g02qgOptions Class See Also Send Feedback
Set the method used for logging any monitoring messages from g02qg.

Syntax

C#
public PrintManager..::..MessageLogger Message { get; set; }
Visual Basic
Public Property Message As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Message {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Message : PrintManager..::..MessageLogger with get, set

See Also

G02..::..g02qgOptions Class
G02..::..g02qgOptions Members


Warning Property

[image]

NAG Library for .NET Release 2
G02..::..g02qgOptions..::Warning Property
G02..::..g02qgOptions Class See Also Send Feedback
Set the method used for logging any warning or error messages from g02qg.

Syntax

C#
public PrintManager..::..MessageLogger Warning { get; set; }
Visual Basic
Public Property Warning As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Warning {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Warning : PrintManager..::..MessageLogger with get, set

See Also

G02..::..g02qgOptions Class
G02..::..g02qgOptions Members


G02 Methods

[image] [image]

NAG Library for .NET Release 2
G02 Methods
G02 Class See Also Send Feedback

The G02 type exposes the following members.

Methods

Name | Description
g02aa | g02aa computes the nearest correlation matrix, in the Frobenius norm, to a given square, input matrix.
g02ab | g02ab computes the nearest correlation matrix, in the Frobenius norm or weighted Frobenius norm, and optionally with bounds on the eigenvalues, to a given square, input matrix.
g02ae | g02ae computes the factor loading matrix associated with the nearest correlation matrix with k-factor structure, in the Frobenius norm, to a given square, input matrix.
g02ba | g02ba computes means and standard deviations of variables, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients for a set of data.
g02bb | g02bb computes means and standard deviations of variables, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients for a set of data omitting completely any cases with a missing observation for any variable.
g02bc | g02bc computes means and standard deviations of variables, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients for a set of data omitting cases with missing values from only those calculations involving the variables for which the values are missing.
g02bd | g02bd computes means and standard deviations of variables, sums of squares and cross-products about zero, and correlation-like coefficients for a set of data.
g02be | g02be computes means and standard deviations of variables, sums of squares and cross-products about zero, and correlation-like coefficients for a set of data omitting completely any cases with a missing observation for any variable.
g02bf | g02bf computes means and standard deviations of variables, sums of squares and cross-products about zero and correlation-like coefficients for a set of data omitting cases with missing values from only those calculations involving the variables for which the values are missing.
g02bg | g02bg computes means and standard deviations, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients for selected variables.
g02bh | g02bh computes means and standard deviations, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients for selected variables omitting completely any cases with a missing observation for any variable (either over all variables in the dataset or over only those variables in the selected subset).
g02bj | g02bj computes means and standard deviations, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients for selected variables omitting cases with missing values from only those calculations involving the variables for which the values are missing.
g02bk | g02bk computes means and standard deviations, sums of squares and cross-products about zero, and correlation-like coefficients for selected variables.
g02bl | g02bl computes means and standard deviations, sums of squares and cross-products about zero, and correlation-like coefficients for selected variables omitting completely any cases with a missing observation for any variable (either over all variables in the dataset or over only those variables in the selected subset).
g02bm | g02bm computes means and standard deviations, sums of squares and cross-products about zero, and correlation-like coefficients for selected variables omitting cases with missing values from only those calculations involving the variables for which the values are missing.
g02bn | g02bn computes Kendall and/or Spearman nonparametric rank correlation coefficients for a set of data; the data array is overwritten with the ranks of the observations.
g02bp | g02bp computes Kendall and/or Spearman nonparametric rank correlation coefficients for a set of data omitting completely any cases with a missing observation for any variable; the data array is overwritten with the ranks of the observations.
g02bq | g02bq computes Kendall and/or Spearman nonparametric rank correlation coefficients for a set of data; the data array is preserved, and the ranks of the observations are not available on exit from the method.
g02br | g02br computes Kendall and/or Spearman nonparametric rank correlation coefficients for a set of data, omitting completely any cases with a missing observation for any variable; the data array is preserved, and the ranks of the observations are not available on exit from the method.
g02bs | g02bs computes Kendall and/or Spearman nonparametric rank correlation coefficients for a set of data omitting cases with missing values from only those calculations involving the variables for which the values are missing; the data array is preserved, and the ranks of the observations are not available on exit from the method.
g02bt | g02bt updates the sample means and sums of squares and cross-products, or sums of squares and cross-products of deviations about the mean, for a new observation. The data may be weighted.
g02bu | g02bu calculates the sample means and sums of squares and cross-products, or sums of squares and cross-products of deviations from the mean, in a single pass for a set of data. The data may be weighted.
g02bw | g02bw calculates a matrix of Pearson product-moment correlation coefficients from sums of squares and cross-products of deviations about the mean.
g02bx | g02bx calculates the sample means, the standard deviations, the variance-covariance matrix, and the matrix of Pearson product-moment correlation coefficients for a set of data. Weights may be used.
g02by | g02by computes a partial correlation/variance-covariance matrix from a correlation or variance-covariance matrix computed by g02bx.
g02ca | g02ca performs a simple linear regression with dependent variable y and independent variable x.
g02cb | g02cb performs a simple linear regression with no constant, with dependent variable y and independent variable x.
g02cc | g02cc performs a simple linear regression with dependent variable y and independent variable x, omitting cases involving missing values.
g02cd | g02cd performs a simple linear regression with no constant, with dependent variable y and independent variable x, omitting cases involving missing values.
g02ce | g02ce takes selected elements from two vectors (typically vectors of means and standard deviations) to form two smaller vectors, and selected rows and columns from two matrices (typically either matrices of sums of squares and cross-products of deviations from means and Pearson product-moment correlation coefficients, or matrices of sums of squares and cross-products about zero and correlation-like coefficients) to form two smaller matrices, allowing reordering of elements in the process.
g02cf | g02cf reorders the elements in two vectors (typically vectors of means and standard deviations), and the rows and columns in two matrices (typically either matrices of sums of squares and cross-products of deviations from means and Pearson product-moment correlation coefficients, or matrices of sums of squares and cross-products about zero and correlation-like coefficients).
g02cg | g02cg performs a multiple linear regression on a set of variables whose means, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients are given.
g02ch | g02ch performs a multiple linear regression with no constant on a set of variables whose sums of squares and cross-products about zero and correlation-like coefficients are given.
g02da | g02da performs a general multiple linear regression when the independent variables may be linearly dependent. Parameter estimates, standard errors, residuals and influence statistics are computed. g02da may be used to perform a weighted regression.
g02dc | g02dc adds or deletes an observation from a general regression model fitted by g02da.
g02dd | g02dd calculates the regression parameters for a general linear regression model. It is intended to be called after g02dc, g02de or g02df.
g02de | g02de adds a new independent variable to a general linear regression model.
g02df | g02df deletes an independent variable from a general linear regression model.
g02dg | g02dg calculates the estimates of the parameters of a general linear regression model for a new dependent variable after a call to g02da.
g02dk | g02dk calculates the estimates of the parameters of a general linear regression model for given constraints from the singular value decomposition results.
g02dn | g02dn gives the estimate of an estimable function along with its standard error.
g02ef | g02ef calculates a full stepwise selection from p variables by using Clarke's sweep algorithm on the correlation matrix of a design and data matrix, Z. The (weighted) variance-covariance, (weighted) means and sum of weights of Z must be supplied.
g02fa | g02fa calculates two types of standardized residuals and two measures of influence for a linear regression.
g02fc | g02fc calculates the Durbin–Watson statistic, for a set of residuals, and the upper and lower bounds for its significance.
g02ga | g02ga fits a generalized linear model with normal errors.
g02gb | g02gb fits a generalized linear model with binomial errors.
g02gc | g02gc fits a generalized linear model with Poisson errors.
g02gd | g02gd fits a generalized linear model with gamma errors.
g02gk | g02gk calculates the estimates of the parameters of a generalized linear model for given constraints from the singular value decomposition results.
g02gn | g02gn gives the estimate of an estimable function along with its standard error from the results from fitting a generalized linear model.
g02gp | g02gp allows prediction from a generalized linear model fit via g02ga, g02gb, g02gc or g02gd.
g02ha | g02ha performs bounded influence regression (M-estimates). Several standard methods are available.
g02hb | g02hb finds, for a real matrix X of full column rank, a lower triangular matrix A such that AT A-1 is proportional to a robust estimate of the covariance of the variables. g02hb is intended for the calculation of weights of bounded influence regression using g02hd.
g02hd | g02hd performs bounded influence regression (M-estimates) using an iterative weighted least squares algorithm.
g02hdz | Auxiliary for use as a delegate parameter
g02hf | g02hf calculates an estimate of the asymptotic variance-covariance matrix for the bounded influence regression estimates (M-estimates). It is intended for use with g02hd.
g02hk | g02hk computes a robust estimate of the covariance matrix for an expected fraction of gross errors.
g02hl | g02hl calculates a robust estimate of the covariance matrix for user-supplied weight functions and their derivatives.
g02hm | g02hm computes a robust estimate of the covariance matrix for user-supplied weight functions. The derivatives of the weight functions are not required.
g02ja | g02ja fits a linear mixed effects regression model using restricted maximum likelihood (REML).
g02jb | g02jb fits a linear mixed effects regression model using maximum likelihood (ML).
g02ka | g02ka calculates a ridge regression, optimizing the ridge parameter according to one of four prediction error criteria.
g02kb | g02kb calculates a ridge regression, with ridge parameters supplied by you.
g02la | g02la fits an orthogonal scores partial least squares (PLS) regression by using singular value decomposition.
g02lb | g02lb fits an orthogonal scores partial least squares (PLS) regression by using Wold's iterative method.
g02lc | g02lc calculates parameter estimates for a given number of factors given the output from an orthogonal scores PLS regression (g02la or g02lb).
g02ld | g02ld calculates predictions given the output from an orthogonal scores PLS regression (g02la or g02lb) and g02lc.
g02qf | g02qf performs a multiple linear quantile regression, returning the parameter estimates and associated confidence limits based on an assumption of Normal, independent, identically distributed errors. g02qf is a simplified version of g02qg.
g02qg | g02qg performs a multiple linear quantile regression. Parameter estimates and, if required, confidence limits, covariance matrices and residuals are calculated. g02qg may be used to perform a weighted quantile regression. A simplified interface for g02qg is provided by g02qf.

See Also

G02 Class


g02aa Method

[image]

NAG Library for .NET Release 2
G02..::g02aa Method
G02 Class See Also Send Feedback
g02aa computes the nearest correlation matrix, in the Frobenius norm, to a given square, input matrix.

Syntax

C#
public static void g02aa(
    double[,] g,
    int n,
    double errtol,
    int maxits,
    int maxit,
    double[,] x,
    out int iter,
    out int feval,
    out double nrmgrd,
    out int ifail
)
Visual Basic
Public Shared Sub g02aa ( _
    g As Double(,), _
    n As Integer, _
    errtol As Double, _
    maxits As Integer, _
    maxit As Integer, _
    x As Double(,), _
    <OutAttribute> ByRef iter As Integer, _
    <OutAttribute> ByRef feval As Integer, _
    <OutAttribute> ByRef nrmgrd As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02aa(
    array<double,2>^ g,
    int n,
    double errtol,
    int maxits,
    int maxit,
    array<double,2>^ x,
    [OutAttribute] int% iter,
    [OutAttribute] int% feval,
    [OutAttribute] double% nrmgrd,
    [OutAttribute] int% ifail
)
F#
static member g02aa :
        g : float[,] *
        n : int *
        errtol : float *
        maxits : int *
        maxit : int *
        x : float[,] *
        iter : int byref *
        feval : int byref *
        nrmgrd : float byref *
        ifail : int byref -> unit

Parameters

g
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: G, the initial matrix.
On exit: a symmetric matrix 12 G+GT with the diagonal set to I.
n
Type: System..::..Int32
On entry: the size of the matrix G.
Constraint: n>0.
errtol
Type: System..::..Double
On entry: the termination tolerance for the Newton iteration. If errtol≤0.0 then n×machine precision is used.
maxits
Type: System..::..Int32
On entry: maxits specifies the maximum number of iterations used for the iterative scheme used to solve the linear algebraic equations at each Newton step.
If maxits≤0, 2×n is used.
maxit
Type: System..::..Int32
On entry: specifies the maximum number of Newton iterations.
If maxit≤0, 200 is used.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: contains the nearest correlation matrix.
iter
Type: System..::..Int32 %
On exit: the number of Newton steps taken.
feval
Type: System..::..Int32 %
On exit: the number of function evaluations of the dual problem.
nrmgrd
Type: System..::..Double %
On exit: the norm of the gradient of the last Newton step.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

A correlation matrix may be characterised as a real square matrix that is symmetric, has a unit diagonal and is positive semidefinite.
g02aa applies an inexact Newton method to a dual formulation of the problem, as described by Qi and Sun (2006). It applies the improvements suggested by Borsdorf and Higham (2010).

References

Borsdorf R and Higham N J (2010) A preconditioned (Newton) algorithm for the nearest correlation matrix IMA Journal of Numerical Analysis 30(1) 94–107
Qi H and Sun D (2006) A quadratically convergent Newton method for computing the nearest correlation matrix SIAM J. Matrix AnalAppl 29(2) 360–385

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDG, LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, ldg=value and n=value.
Constraint: ldg≥n.
On entry, ldx=value and n=value.
Constraint: ldx≥n.
On entry, n=value.
Constraint: n>0.
ifail=2
Newton iteration fails to converge in value iterations.
ifail=3
Machine precision is limiting convergence.
The array returned in x may still be of interest.
ifail=4
An intermediate eigenproblem could not be solved. This should not occur. Please contact NAG with details of your call.
ifail=-999
Dynamic memory allocation failed.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The returned accuracy is controlled by errtol and limited by machine precision.

Parallelism and Performance

None.

Further Comments

Arrays are internally allocated by g02aa. The total size of these arrays is 11×n+3×n×n+max 2×n×n+6×n+1,120+9×n real elements and 5×n+3 integer elements.

Example

This example finds the nearest correlation matrix to:
G=2-100-12-100-12-100-12

Example program (C#): g02aae.cs

Example program data: g02aae.d

Example program results: g02aae.r

See Also

G02 Class
G02 Members


g02ab Method

[image]

NAG Library for .NET Release 2
G02..::g02ab Method
G02 Class See Also Send Feedback
g02ab computes the nearest correlation matrix, in the Frobenius norm or weighted Frobenius norm, and optionally with bounds on the eigenvalues, to a given square, input matrix.

Syntax

C#
public static void g02ab(
    double[,] g,
    int n,
    string opt,
    double alpha,
    double[] w,
    double errtol,
    int maxits,
    int maxit,
    double[,] x,
    out int iter,
    out int feval,
    out double nrmgrd,
    out int ifail
)
Visual Basic
Public Shared Sub g02ab ( _
    g As Double(,), _
    n As Integer, _
    opt As String, _
    alpha As Double, _
    w As Double(), _
    errtol As Double, _
    maxits As Integer, _
    maxit As Integer, _
    x As Double(,), _
    <OutAttribute> ByRef iter As Integer, _
    <OutAttribute> ByRef feval As Integer, _
    <OutAttribute> ByRef nrmgrd As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02ab(
    array<double,2>^ g,
    int n,
    String^ opt,
    double alpha,
    array<double>^ w,
    double errtol,
    int maxits,
    int maxit,
    array<double,2>^ x,
    [OutAttribute] int% iter,
    [OutAttribute] int% feval,
    [OutAttribute] double% nrmgrd,
    [OutAttribute] int% ifail
)
F#
static member g02ab :
        g : float[,] *
        n : int *
        opt : string *
        alpha : float *
        w : float[] *
        errtol : float *
        maxits : int *
        maxit : int *
        x : float[,] *
        iter : int byref *
        feval : int byref *
        nrmgrd : float byref *
        ifail : int byref -> unit

Parameters

g
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: G, the initial matrix.
On exit: G is overwritten.
n
Type: System..::..Int32
On entry: the order of the matrix G.
Constraint: n>0.
opt
Type: System..::..String
On entry: indicates the problem to be solved.
opt="A"
The lower bound problem is solved.
opt="W"
The weighted norm problem is solved.
opt="B"
Both problems are solved.
Constraint: opt="A", "W" or "B".
alpha
Type: System..::..Double
On entry: the value of α.
If opt="W", alpha need not be set.
Constraint: 0.0<alpha<1.0.
w
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the square roots of the diagonal elements of W, that is the diagonal of W 12.
If opt="A", w need not be set.
On exit: if opt="W" or "B", the array is scaled so 0<w[i-1]≤1, for i=1,2,…,n.
Constraint: w[i-1]>0.0, for i=1,2,…,n.
errtol
Type: System..::..Double
On entry: the termination tolerance for the Newton iteration. If errtol≤0.0 then n×machine precision is used.
maxits
Type: System..::..Int32
On entry: specifies the maximum number of iterations to be used by the iterative scheme to solve the linear algebraic equations at each Newton step.
If maxits≤0, 2×n is used.
maxit
Type: System..::..Int32
On entry: specifies the maximum number of Newton iterations.
If maxit≤0, 200 is used.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: contains the nearest correlation matrix.
iter
Type: System..::..Int32 %
On exit: the number of Newton steps taken.
feval
Type: System..::..Int32 %
On exit: the number of function evaluations of the dual problem.
nrmgrd
Type: System..::..Double %
On exit: the norm of the gradient of the last Newton step.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Finds the nearest correlation matrix X by minimizing 12 G-X 2 where G is an approximate correlation matrix.
The norm can either be the Frobenius norm or the weighted Frobenius norm 12 W 12 G-X W 12 F 2.
You can optionally specify a lower bound on the eigenvalues, α, of the computed correlation matrix, forcing the matrix to be positive definite, 0<α<1.
Note that if the weights vary by several orders of magnitude from one another the algorithm may fail to converge.

References

Borsdorf R and Higham N J (2010) A preconditioned (Newton) algorithm for the nearest correlation matrix IMA Journal of Numerical Analysis 30(1) 94–107
Qi H and Sun D (2006) A quadratically convergent Newton method for computing the nearest correlation matrix SIAM J. Matrix AnalAppl 29(2) 360–385

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDG, LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The returned accuracy is controlled by errtol and limited by machine precision.

Parallelism and Performance

None.

Further Comments

Arrays are internally allocated by g02ab. The total size of these arrays is 12×n+3×n×n+max 2×n×n+6×n+1,120+9×n real elements and 5×n+3 integer elements. All allocated memory is freed before return of g02ab.

Example

This example finds the nearest correlation matrix to:
G=2-100-12-100-12-100-12
weighted by W 12=diag 100,20,20,20 with minimum eigenvalue 0.02.

Example program (C#): g02abe.cs

Example program data: g02abe.d

Example program results: g02abe.r

See Also

G02 Class
G02 Members


g02ae Method

[image]

NAG Library for .NET Release 2
G02..::g02ae Method
G02 Class See Also Send Feedback
g02ae computes the factor loading matrix associated with the nearest correlation matrix with k-factor structure, in the Frobenius norm, to a given square, input matrix.

Syntax

C#
public static void g02ae(
    double[,] g,
    int n,
    int k,
    double errtol,
    int maxit,
    double[,] x,
    out int iter,
    out int feval,
    out double nrmpgd,
    out int ifail
)
Visual Basic
Public Shared Sub g02ae ( _
    g As Double(,), _
    n As Integer, _
    k As Integer, _
    errtol As Double, _
    maxit As Integer, _
    x As Double(,), _
    <OutAttribute> ByRef iter As Integer, _
    <OutAttribute> ByRef feval As Integer, _
    <OutAttribute> ByRef nrmpgd As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02ae(
    array<double,2>^ g,
    int n,
    int k,
    double errtol,
    int maxit,
    array<double,2>^ x,
    [OutAttribute] int% iter,
    [OutAttribute] int% feval,
    [OutAttribute] double% nrmpgd,
    [OutAttribute] int% ifail
)
F#
static member g02ae :
        g : float[,] *
        n : int *
        k : int *
        errtol : float *
        maxit : int *
        x : float[,] *
        iter : int byref *
        feval : int byref *
        nrmpgd : float byref *
        ifail : int byref -> unit

Parameters

g
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: G, the initial matrix.
On exit: a symmetric matrix 12 G+GT with the diagonal elements set to unity.
n
Type: System..::..Int32
On entry: n, the order of the matrix G.
Constraint: n>0.
k
Type: System..::..Int32
On entry: k, the number of factors and columns of X.
Constraint: 0<k≤n.
errtol
Type: System..::..Double
On entry: the termination tolerance for the projected gradient norm. See references for further details. If errtol≤0.0 then 0.01 is used. This is often a suitable default value.
maxit
Type: System..::..Int32
On entry: specifies the maximum number of iterations in the spectral projected gradient method.
If maxit≤0, 40000 is used.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, k]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: contains the matrix X.
iter
Type: System..::..Int32 %
On exit: the number of steps taken in the spectral projected gradient method.
feval
Type: System..::..Int32 %
On exit: the number of evaluations of G-X XT+diag X XT-I F.
nrmpgd
Type: System..::..Double %
On exit: the norm of the projected gradient at the final iteration.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

A correlation matrix C with k-factor structure may be characterised as a real square matrix that is symmetric, has a unit diagonal, is positive semidefinite and can be written as C=X XT+diag I-X XT, where I is the identity matrix and X has n rows and k columns. X is often referred to as the factor loading matrix.
g02ae applies a spectral projected gradient method to the modified problem min G-X XT+diag X XT-I F such that xiT 2≤1, for i=1,2,…,n, where xi is the ith row of the factor loading matrix, X, which gives us the solution.

References

Birgin E G, Martínez J M and Raydan M (2001) Algorithm 813: SPG–software for convex-constrained optimization ACM Trans. Math. Software 27 340–349
Borsdorf R, Higham N J and Raydan M (2010) Computing a nearest correlation matrix with factor structure. SIAM J. Matrix Anal. Appl. 31(5) 2603–2622

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDG, LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, k=value and n=value.
Constraint: 0<k≤n.
On entry, ldg=value and n=value.
Constraint: ldg≥n.
On entry, ldx=value and n=value.
Constraint: ldx≥n.
On entry, n=value.
Constraint: n>0.
ifail=2
Spectral gradient method fails to converge in value iterations.
ifail=-999
Dynamic memory allocation failed.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The returned accuracy is controlled by errtol and limited by machine precision.

Parallelism and Performance

None.

Further Comments

Arrays are internally allocated by g02ae. The total size of these arrays is n×n+4×n×k+nb+3×n+n+50 real elements and 6×n integer elements. Here nb is the block size required for optimal performance by (F08FEF not in this release) (F08FGF not in this release) which are called internally. All allocated memory is freed before return of g02ae.
See (G03CAF not in this release) for constructing the factor loading matrix from a known correlation matrix.

Example

This example finds the nearest correlation matrix with k=2 factor structure to:
G=2-100-12-100-12-100-12

Example program (C#): g02aee.cs

Example program data: g02aee.d

Example program results: g02aee.r

See Also

G02 Class
G02 Members


g02ba Method

[image]

NAG Library for .NET Release 2
G02..::g02ba Method
G02 Class See Also Send Feedback
g02ba computes means and standard deviations of variables, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients for a set of data.

Syntax

C#
public static void g02ba(
    int n,
    int m,
    double[,] x,
    double[] xbar,
    double[] std,
    double[,] ssp,
    double[,] r,
    out int ifail
)
Visual Basic
Public Shared Sub g02ba ( _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    xbar As Double(), _
    std As Double(), _
    ssp As Double(,), _
    r As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02ba(
    int n,
    int m,
    array<double,2>^ x,
    array<double>^ xbar,
    array<double>^ std,
    array<double,2>^ ssp,
    array<double,2>^ r,
    [OutAttribute] int% ifail
)
F#
static member g02ba :
        n : int *
        m : int *
        x : float[,] *
        xbar : float[] *
        std : float[] *
        ssp : float[,] *
        r : float[,] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations or cases.
Constraint: n≥2.
m
Type: System..::..Int32
On entry: m, the number of variables.
Constraint: m≥2.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must be set to x ij, the ith observation on the jth variable, for i=1,2,…,n and j=1,2,…,m.
xbar
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: the mean value, x-j, of the jth variable, for j=1,2,…,m.
std
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: the standard deviation, sj, of the jth variable, for j=1,2,…,m.
ssp
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: ssp[j-1,k-1] is the cross-product of deviations S jk, for j=1,2,…,m and k=1,2,…,m.
r
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: r[j-1,k-1] is the product-moment correlation coefficient R jk between the jth and kth variables, for j=1,2,…,m and k=1,2,…,m.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The input data consist of n observations for each of m variables, given as an array
x ij,  i=1,2,…,n n≥2,j=1,2,…,m m≥2,
where x ij is the ith observation on the jth variable.
The quantities calculated are:
(a) Means:
x-j=1 n∑i=1 n x ij,  j=1,2,…,m.
(b) Standard deviations:
sj=1 n-1∑i=1 n x ij-x-j 2,  j=1,2,…,m.
(c) Sums of squares and cross-products of deviations from means:
S jk=∑i=1 n x ij-x-jx ik-x-k,  j,k=1,2,…,m.
(d) Pearson product-moment correlation coefficients:
R jk=S jk S jjS kk,  j,k=1,2,…,m.
If S jj or S kk is zero, R jk is set to zero.

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDSSP, LDR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, n<2.
ifail=2
On entry, m<2.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

g02ba does not use additional precision arithmetic for the accumulation of scalar products, so there may be a loss of significant figures for large n.

Parallelism and Performance

None.

Further Comments

The time taken by g02ba depends on n and m.
The method uses a two-pass algorithm.

Example

This example reads in a set of data consisting of five observations on each of three variables. The means, standard deviations, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients for all three variables are then calculated and printed.

Example program (C#): g02bae.cs

Example program data: g02bae.d

Example program results: g02bae.r

See Also

G02 Class
G02 Members


g02bb Method

[image]

NAG Library for .NET Release 2
G02..::g02bb Method
G02 Class See Also Send Feedback
g02bb computes means and standard deviations of variables, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients for a set of data omitting completely any cases with a missing observation for any variable.

Syntax

C#
public static void g02bb(
    int n,
    int m,
    double[,] x,
    int[] miss,
    double[] xmiss,
    double[] xbar,
    double[] std,
    double[,] ssp,
    double[,] r,
    out int ncases,
    out int ifail
)
Visual Basic
Public Shared Sub g02bb ( _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    miss As Integer(), _
    xmiss As Double(), _
    xbar As Double(), _
    std As Double(), _
    ssp As Double(,), _
    r As Double(,), _
    <OutAttribute> ByRef ncases As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02bb(
    int n,
    int m,
    array<double,2>^ x,
    array<int>^ miss,
    array<double>^ xmiss,
    array<double>^ xbar,
    array<double>^ std,
    array<double,2>^ ssp,
    array<double,2>^ r,
    [OutAttribute] int% ncases,
    [OutAttribute] int% ifail
)
F#
static member g02bb :
        n : int *
        m : int *
        x : float[,] *
        miss : int[] *
        xmiss : float[] *
        xbar : float[] *
        std : float[] *
        ssp : float[,] *
        r : float[,] *
        ncases : int byref *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations or cases.
Constraint: n≥2.
m
Type: System..::..Int32
On entry: m, the number of variables.
Constraint: m≥2.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must be set to x ij, the value of the ith observation on the jth variable, for i=1,2,…,n and j=1,2,…,m.
miss
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: miss[j-1] must be set equal to 1 if a missing value, x mj, is to be specified for the jth variable in the array x, or set equal to 0 otherwise. Values of miss must be given for all m variables in the array x.
On exit: the array miss is overwritten by the method, and the information it contained on entry is lost.
xmiss
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: xmiss[j-1] must be set to the missing value, x mj, to be associated with the jth variable in the array x, for those variables for which missing values are specified by means of the array miss (see [Accuracy]).
On exit: the array xmiss is overwritten by the method, and the information it contained on entry is lost.
xbar
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: the mean value, x-j, of the jth variable, for j=1,2,…,m.
std
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: the standard deviation, sj, of the jth variable, for j=1,2,…,m.
ssp
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: ssp[j-1,k-1] is the cross-product of deviations S jk, for j=1,2,…,m and k=1,2,…,m.
r
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: r[j-1,k-1] is the product-moment correlation coefficient R jk between the jth and kth variables, for j=1,2,…,m and k=1,2,…,m.
ncases
Type: System..::..Int32 %
On exit: the number of cases actually used in the calculations (when cases involving missing values have been eliminated).
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The input data consist of n observations for each of m variables, given as an array
x ij,  i=1,2,…,n n≥2,j=1,2,…,m m≥2,
where x ij is the ith observation on the jth variable. In addition, each of the m variables may optionally have associated with it a value which is to be considered as representing a missing observation for that variable; the missing value for the jth variable is denoted by x mj. Missing values need not be specified for all variables.
Let wi=0 if observation i contains a missing value for any of those variables for which missing values have been declared, i.e., if x ij=x mj for any j for which an x mj has been assigned (see also [Accuracy]); and wi=1 otherwise, for i=1,2,…,n.
The quantities calculated are:
(a) Means:
x-j=∑i=1 n wix ij∑i=1 n wi,  j=1,2,…,m.
(b) Standard deviations:
sj=∑i=1 n wi x ij-x-j 2∑i=1 n wi-1,  j=1,2,…,m.
(c) Sums of squares and cross-products of deviations from means:
S jk=∑i=1 n wi x ij-x-jx ik-x-k,  j,k=1,2,…,m.
(d) Pearson product-moment correlation coefficients:
R jk=S jk S jjS kk,  j,k=1,2,…,m.
If S jj or S kk is zero, R jk is set to zero.

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDSSP, LDR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, n<2.
ifail=2
On entry, m<2.
ifail=4
After observations with missing values were omitted, no cases remained.
ifail=5
After observations with missing values were omitted, only one case remained.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

g02bb does not use additional precision arithmetic for the accumulation of scalar products, so there may be a loss of significant figures for large n.
You are warned of the need to exercise extreme care in your selection of missing values. g02bb treats all values in the inclusive range 1±0.1 x02be-2×xm j, where xm j is the missing value for variable j specified in xmiss.
You must therefore ensure that the missing value chosen for each variable is sufficiently different from all valid values for that variable so that none of the valid values fall within the range indicated above.

Parallelism and Performance

None.

Further Comments

The time taken by g02bb depends on n and m, and the occurrence of missing values.
The method uses a two-pass algorithm.

Example

This example reads in a set of data consisting of five observations on each of three variables. Missing values of 0.0 are declared for the first and third variables; no missing value is specified for the second variable. The means, standard deviations, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients for all three variables are then calculated and printed, omitting completely all cases containing missing values; cases 3 and 4 are therefore eliminated, leaving only three cases in the calculations.

Example program (C#): g02bbe.cs

Example program data: g02bbe.d

Example program results: g02bbe.r

See Also

G02 Class
G02 Members


g02bc Method

[image]

NAG Library for .NET Release 2
G02..::g02bc Method
G02 Class See Also Send Feedback
g02bc computes means and standard deviations of variables, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients for a set of data omitting cases with missing values from only those calculations involving the variables for which the values are missing.

Syntax

C#
public static void g02bc(
    int n,
    int m,
    double[,] x,
    int[] miss,
    double[] xmiss,
    double[] xbar,
    double[] std,
    double[,] ssp,
    double[,] r,
    out int ncases,
    double[,] cnt,
    out int ifail
)
Visual Basic
Public Shared Sub g02bc ( _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    miss As Integer(), _
    xmiss As Double(), _
    xbar As Double(), _
    std As Double(), _
    ssp As Double(,), _
    r As Double(,), _
    <OutAttribute> ByRef ncases As Integer, _
    cnt As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02bc(
    int n,
    int m,
    array<double,2>^ x,
    array<int>^ miss,
    array<double>^ xmiss,
    array<double>^ xbar,
    array<double>^ std,
    array<double,2>^ ssp,
    array<double,2>^ r,
    [OutAttribute] int% ncases,
    array<double,2>^ cnt,
    [OutAttribute] int% ifail
)
F#
static member g02bc :
        n : int *
        m : int *
        x : float[,] *
        miss : int[] *
        xmiss : float[] *
        xbar : float[] *
        std : float[] *
        ssp : float[,] *
        r : float[,] *
        ncases : int byref *
        cnt : float[,] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations or cases.
Constraint: n≥2.
m
Type: System..::..Int32
On entry: m, the number of variables.
Constraint: m≥2.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must be set to x ij, the value of the ith observation on the jth variable, for i=1,2,…,n and j=1,2,…,m.
miss
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: miss[j-1] must be set equal to 1 if a missing value, x mj, is to be specified for the jth variable in the array x, or set equal to 0 otherwise. Values of miss must be given for all m variables in the array x.
xmiss
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: xmiss[j-1] must be set to the missing value, x mj, to be associated with the jth variable in the array x, for those variables for which missing values are specified by means of the array miss (see [Accuracy]).
xbar
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: the mean value, x-j, of the jth variable, for j=1,2,…,m.
std
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: the standard deviation, sj, of the jth variable, for j=1,2,…,m.
ssp
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: ssp[j-1,k-1] is the cross-product of deviations S jk, for j=1,2,…,m and k=1,2,…,m.
r
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: r[j-1,k-1] is the product-moment correlation coefficient R jk between the jth and kth variables, for j=1,2,…,m and k=1,2,…,m.
ncases
Type: System..::..Int32 %
On exit: the minimum number of cases used in the calculation of any of the sums of squares and cross-products and correlation coefficients (when cases involving missing values have been eliminated).
cnt
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: cnt[j-1,k-1] is the number of cases, c jk, actually used in the calculation of S jk, and R jk, the sum of cross-products and correlation coefficient for the jth and kth variables, for j=1,2,…,m and k=1,2,…,m.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The input data consist of n observations for each of m variables, given as an array
x ij,  i=1,2,…,n n≥2,j=1,2,…,m m≥2,
where x ij is the ith observation on the jth variable. In addition, each of the m variables may optionally have associated with it a value which is to be considered as representing a missing observation for that variable; the missing value for the jth variable is denoted by xmj. Missing values need not be specified for all variables.
Let w ij=0 if the ith observation for the jth variable is a missing value, i.e., if a missing value, xmj, has been declared for the jth variable, and x ij=xmj (see also [Accuracy]); and w ij=1 otherwise, for i=1,2,…,n and j=1,2,…,m.
The quantities calculated are:
(a) Means:
x-j=∑i=1 n w ijx ij∑i=1 n w ij,  j=1,2,…,m.
(b) Standard deviations:
sj=∑i=1 n w ij x ij-x-j 2∑i=1 n w ij-1,  j=1,2,…,m.
(c) Sums of squares and cross-products of deviations from means:
S jk=∑i=1 n w ijw ik x ij-x-j kx ik-x-k j,  j,k=1,2,…,m,
where
x-j k=∑i=1 n w ijw ikx ij∑i=1 n w ijw ik  and  x-k j=∑i=1 n w ikw ijx ik∑i=1 n w ikw ij,
(i.e., the means used in the calculation of the sums of squares and cross-products of deviations are based on the same set of observations as are the cross-products.)
(d) Pearson product-moment correlation coefficients:
R jk=S jk S jj kS kk j,  j,k,=1,2,…,m,
where S jj k=∑i=1 n w ijw ik x ij-x-j k 2 and S kk j=∑i=1 n w ikw ij x ik-x-k j 2 and x-j k and x-k j are as defined in (c) above
(i.e., the sums of squares of deviations used in the denominator are based on the same set of observations as are used in the calculation of the numerator).
If S jj k or S kk j is zero, R jk is set to zero.
(e) The number of cases used in the calculation of each of the correlation coefficients:
c jk=∑i=1 n w ijw ik,  j,k=1,2,…,m.
(The diagonal terms, c jj, for j=1,2,…,m, also give the number of cases used in the calculation of the means, x-j, and the standard deviations, sj.)

References

None.

Error Indicators and Warnings

Note: g02bc may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDSSP, LDR, LDCNT) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, n<2.
ifail=2
On entry, m<2.
ifail=4
After observations with missing values were omitted, fewer than two cases remained for at least one pair of variables. (The pairs of variables involved can be determined by examination of the contents of the array cnt.) All means, standard deviations, sums of squares and cross-products, and correlation coefficients based on two or more cases are returned by the method even if ifail=4.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

g02bc does not use additional precision arithmetic for the accumulation of scalar products, so there may be a loss of significant figures for large n.
You are warned of the need to exercise extreme care in your selection of missing values. g02bc treats all values in the inclusive range 1±0.1 x02be-2×xm j, where xm j is the missing value for variable j specified in xmiss.
You must therefore ensure that the missing value chosen for each variable is sufficiently different from all valid values for that variable so that none of the valid values fall within the range indicated above.

Parallelism and Performance

None.

Further Comments

The time taken by g02bc depends on n and m, and the occurrence of missing values.
The method uses a two-pass algorithm.

Example

This example reads in a set of data consisting of five observations on each of three variables. Missing values of 0.0, -1.0 and 0.0 are declared for the first, second and third variables respectively. The means, standard deviations, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients for all three variables are then calculated and printed, omitting cases with missing values from only those calculations involving the variables for which the values are missing. The program therefore omits cases 4 and 5 in calculating the correlation between the first and second variables, and cases 3 and 4 for the first and third variables etc.

Example program (C#): g02bce.cs

Example program data: g02bce.d

Example program results: g02bce.r

See Also

G02 Class
G02 Members


g02bd Method

[image]

NAG Library for .NET Release 2
G02..::g02bd Method
G02 Class See Also Send Feedback
g02bd computes means and standard deviations of variables, sums of squares and cross-products about zero, and correlation-like coefficients for a set of data.

Syntax

C#
public static void g02bd(
    int n,
    int m,
    double[,] x,
    double[] xbar,
    double[] std,
    double[,] sspz,
    double[,] rz,
    out int ifail
)
Visual Basic
Public Shared Sub g02bd ( _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    xbar As Double(), _
    std As Double(), _
    sspz As Double(,), _
    rz As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02bd(
    int n,
    int m,
    array<double,2>^ x,
    array<double>^ xbar,
    array<double>^ std,
    array<double,2>^ sspz,
    array<double,2>^ rz,
    [OutAttribute] int% ifail
)
F#
static member g02bd :
        n : int *
        m : int *
        x : float[,] *
        xbar : float[] *
        std : float[] *
        sspz : float[,] *
        rz : float[,] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations or cases.
Constraint: n≥2.
m
Type: System..::..Int32
On entry: m, the number of variables.
Constraint: m≥2.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must be set to the value of x ij, the ith observation on the jth variable, for i=1,2,…,n and j=1,2,…,m.
xbar
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: xbar[j-1] contains the mean value, x-j, of the jth variable, for j=1,2,…,m.
std
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: the standard deviation, sj, of the jth variable, for j=1,2,…,m.
sspz
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: sspz[j-1,k-1] is the cross-product about zero, S~jk, for j=1,2,…,m and k=1,2,…,m.
rz
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: rz[j-1,k-1] is the correlation-like coefficient, R~jk, between the jth and kth variables, for j=1,2,…,m and k=1,2,…,m.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The input data consists of n observations for each of m variables, given as an array
x ij,  i=1,2,…,n n≥2,  j=1,2,…,m m≥2,
where x ij is the ith observation on the jth variable.
The quantities calculated are:
(a) Means:
x-j=1 n∑i=1 n x ij,  j=1,2,…,m.
(b) Standard deviations:
sj=1 n-1∑i=1 n x ij-x-j 2,  j=1,2,…,m.
(c) Sums of squares and cross-products about zero:
S~jk=∑i=1 n x ijx ik,  j,k=1,2,…,m.
(d) Correlation-like coefficients:
R~jk=S~jk S~jjS~kk,  j,k=1,2,…,m.
If S~jj or S~kk is zero, R~jk is set to zero.

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDSSPZ, LDRZ) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, n<2.
ifail=2
On entry, m<2.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

g02bd does not use additional precision arithmetic for the accumulation of scalar products, so there may be a loss of significant figures for large n.

Parallelism and Performance

None.

Further Comments

The time taken by g02bd depends on n and m.
The method uses a two-pass algorithm.

Example

This example reads in a set of data consisting of five observations on each of three variables. The means, standard deviations, sums of squares and cross-products about zero, and correlation-like coefficients for all three variables are then calculated and printed.

Example program (C#): g02bde.cs

Example program data: g02bde.d

Example program results: g02bde.r

See Also

G02 Class
G02 Members


g02be Method

[image]

NAG Library for .NET Release 2
G02..::g02be Method
G02 Class See Also Send Feedback
g02be computes means and standard deviations of variables, sums of squares and cross-products about zero, and correlation-like coefficients for a set of data omitting completely any cases with a missing observation for any variable.

Syntax

C#
public static void g02be(
    int n,
    int m,
    double[,] x,
    int[] miss,
    double[] xmiss,
    double[] xbar,
    double[] std,
    double[,] sspz,
    double[,] rz,
    out int ncases,
    out int ifail
)
Visual Basic
Public Shared Sub g02be ( _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    miss As Integer(), _
    xmiss As Double(), _
    xbar As Double(), _
    std As Double(), _
    sspz As Double(,), _
    rz As Double(,), _
    <OutAttribute> ByRef ncases As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02be(
    int n,
    int m,
    array<double,2>^ x,
    array<int>^ miss,
    array<double>^ xmiss,
    array<double>^ xbar,
    array<double>^ std,
    array<double,2>^ sspz,
    array<double,2>^ rz,
    [OutAttribute] int% ncases,
    [OutAttribute] int% ifail
)
F#
static member g02be :
        n : int *
        m : int *
        x : float[,] *
        miss : int[] *
        xmiss : float[] *
        xbar : float[] *
        std : float[] *
        sspz : float[,] *
        rz : float[,] *
        ncases : int byref *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations or cases.
Constraint: n≥2.
m
Type: System..::..Int32
On entry: m, the number of variables.
Constraint: m≥2.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must be set to x ij, the value of the ith observation on the jth variable, for i=1,2,…,n and j=1,2,…,m.
miss
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: miss[j-1] must be set equal to 1 if a missing value, x mj, is to be specified for the jth variable in the array x, or set equal to 0 otherwise. Values of miss must be given for all m variables in the array x.
On exit: the array miss is overwritten by the method, and the information it contained on entry is lost.
xmiss
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: xmiss[j-1] must be set to the missing value, x mj, to be associated with the jth variable in the array x, for those variables for which missing values are specified by means of the array miss (see [Accuracy]).
On exit: the array xmiss is overwritten by the method, and the information it contained on entry is lost.
xbar
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: the mean value, x-j, of the jth variable, for j=1,2,…,m.
std
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: the standard deviation, sj, of the jth variable, for j=1,2,…,m.
sspz
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: sspz[j-1,k-1] is the cross-product about zero, S~jk, for j=1,2,…,m and k=1,2,…,m.
rz
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: rz[j-1,k-1] is the correlation-like coefficient, R~jk, between the jth and kth variables, for j=1,2,…,m and k=1,2,…,m.
ncases
Type: System..::..Int32 %
On exit: the number of cases actually used in the calculations (when cases involving missing values have been eliminated).
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The input data consists of n observations for each of m variables, given as an array
x ij,  i=1,2,…,n n≥2,j=1,2,…,m m≥2,
where x ij is the ith observation on the jth variable. In addition, each of the m variables may optionally have associated with it a value which is to be considered as representing a missing observation for that variable; the missing value for the jth variable is denoted by xmj. Missing values need not be specified for all variables.
Let wi=0 if observation i contains a missing value for any of those variables for which missing values have been declared, i.e., if x ij=xmj for any j for which an xmj has been assigned (see also [Accuracy]); and wi=1 otherwise, for i=1,2,…,n.
The quantities calculated are:
(a) Means:
x-j=∑i=1 n wix ij∑i=1 n wi,  j=1,2,…,m.
(b) Standard deviations:
sj=∑i=1 n wi x ij-x-j 2∑i=1 n wi-1,  j=1,2,…,m.
(c) Sums of squares and cross-products about zero:
S~jk=∑i=1 n wix ijx ik,  j,k=1,2,…,m.
(d) Correlation-like coefficients:
R~jk=S~jk S~jjS~kk,  j,k=1,2,…,m.
If S~jj or S~kk is zero, R~jk is set to zero.

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDSSPZ, LDRZ) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, n<2.
ifail=2
On entry, m<2.
ifail=4
After observations with missing values were omitted, no cases remained.
ifail=5
After observations with missing values were omitted, only one case remained.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

g02be does not use additional precision arithmetic for the accumulation of scalar products, so there may be a loss of significant figures for large n.
You are warned of the need to exercise extreme care in your selection of missing values. g02be treats all values in the inclusive range 1±0.1 x02be-2×xm j, where xm j is the missing value for variable j specified in xmiss.
You must therefore ensure that the missing value chosen for each variable is sufficiently different from all valid values for that variable so that none of the valid values fall within the range indicated above.

Parallelism and Performance

None.

Further Comments

The time taken by g02be depends on n and m, and the occurrence of missing values.
The method uses a two-pass algorithm.

Example

This example reads in a set of data consisting of five observations on each of three variables. Missing values of 0.0 are declared for the first and third variables; no missing value is specified for the second variable. The means, standard deviations, sums of squares and cross-products about zero, and correlation-like coefficients for all three variables are then calculated and printed, omitting completely all cases containing missing values; cases 3 and 4 are therefore eliminated, leaving only three cases in the calculations.

Example program (C#): g02bee.cs

Example program data: g02bee.d

Example program results: g02bee.r

See Also

G02 Class
G02 Members


g02bf Method

[image]

NAG Library for .NET Release 2
G02..::g02bf Method
G02 Class See Also Send Feedback
g02bf computes means and standard deviations of variables, sums of squares and cross-products about zero and correlation-like coefficients for a set of data omitting cases with missing values from only those calculations involving the variables for which the values are missing.

Syntax

C#
public static void g02bf(
    int n,
    int m,
    double[,] x,
    int[] miss,
    double[] xmiss,
    double[] xbar,
    double[] std,
    double[,] sspz,
    double[,] rz,
    out int ncases,
    double[,] cnt,
    out int ifail
)
Visual Basic
Public Shared Sub g02bf ( _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    miss As Integer(), _
    xmiss As Double(), _
    xbar As Double(), _
    std As Double(), _
    sspz As Double(,), _
    rz As Double(,), _
    <OutAttribute> ByRef ncases As Integer, _
    cnt As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02bf(
    int n,
    int m,
    array<double,2>^ x,
    array<int>^ miss,
    array<double>^ xmiss,
    array<double>^ xbar,
    array<double>^ std,
    array<double,2>^ sspz,
    array<double,2>^ rz,
    [OutAttribute] int% ncases,
    array<double,2>^ cnt,
    [OutAttribute] int% ifail
)
F#
static member g02bf :
        n : int *
        m : int *
        x : float[,] *
        miss : int[] *
        xmiss : float[] *
        xbar : float[] *
        std : float[] *
        sspz : float[,] *
        rz : float[,] *
        ncases : int byref *
        cnt : float[,] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations or cases.
Constraint: n≥2.
m
Type: System..::..Int32
On entry: m, the number of variables.
Constraint: m≥2.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must be set to x ij, the value of the ith observation on the jth variable, for i=1,2,…,n and j=1,2,…,m.
miss
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: miss[j-1] must be set equal to 1 if a missing value, x mj, is to be specified for the jth variable in the array x, or set equal to 0 otherwise. Values of miss must be given for all m variables in the array x.
xmiss
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: xmiss[j-1] must be set to the missing value, x mj, to be associated with the jth variable in the array x, for those variables for which missing values are specified by means of the array miss (see [Accuracy]).
xbar
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: the mean value, x-j, of the jth variable, for j=1,2,…,m.
std
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: the standard deviation, sj, of the jth variable, for j=1,2,…,m.
sspz
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: sspz[j-1,k-1] is the cross-product about zero, S~jk, for j=1,2,…,m and k=1,2,…,m.
rz
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: rz[j-1,k-1] is the correlation-like coefficient, R~jk, between the jth and kth variables, for j=1,2,…,m and k=1,2,…,m.
ncases
Type: System..::..Int32 %
On exit: the minimum number of cases used in the calculation of any of the sums of squares and cross-products and correlation-like coefficients (when cases involving missing values have been eliminated).
cnt
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: cnt[j-1,k-1] is the number of cases, c jk, actually used in the calculation of S~jk, and R~jk, the sum of cross-products and correlation-like coefficient for the jth and kth variables, for j=1,2,…,m and k=1,2,…,m.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The input data consists of n observations for each of m variables, given as an array
x ij,  i=1,2,…,n n≥2,j=1,2,…,m m≥2,
where x ij is the ith observation on the jth variable. In addition, each of the m variables may optionally have associated with it a value which is to be considered as representing a missing observation for that variable; the missing value for the jth variable is denoted by xmj. Missing values need not be specified for all variables.
Let w ij=0 if the ith observation for the jth variable is a missing value, i.e., if a missing value, xmj, has been declared for the jth variable, and x ij=xmj (see also [Accuracy]); and w ij=1 otherwise, for i=1,2,…,n and j=1,2,…,m.
The quantities calculated are:
(a) Means:
x-j=∑i=1 n w ijx ij∑i=1 n w ij,  j=1,2,…,m.
(b) Standard deviations:
sj=∑i=1 n w ij x ij-x-j 2∑i=1 n w ij-1,  j=1,2,…,m.
(c) Sums of squares and cross-products about zero:
S~jk=∑i=1 n w ijw ikx ijx ik,  j,k=1,2,…,m.
(d) Correlation-like coefficients:
R~jk=S~jk S~jj k j k S~kk j,  j,k=1,2,…,m,
where S~jj k=∑i=1 n w ijw ik x ij 2 and S~kk j=∑i=1 n w ikw ij x ik 2
(i.e., the sums of squares about zero are based on the same set of observations as are used in the calculation of the numerator).
If S~jj k or S~kk j is zero, R~jk is set to zero.
(e) The number of cases used in the calculation of each of the correlation-like coefficients:
c jk=∑i=1 n w ijw ik,  j,k=1,2,…,m.
(The diagonal terms, c jj, for j=1,2,…,m, also give the number of cases used in the calculation of the means x-j and the standard deviations sj.)

References

None.

Error Indicators and Warnings

Note: g02bf may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDSSPZ, LDRZ, LDCNT) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, n<2.
ifail=2
On entry, m<2.
ifail=4
After observations with missing values were omitted, fewer than two cases remained for at least one pair of variables. (The pairs of variables involved can be determined by examination of the contents of the array cnt). All means, standard deviations, sums of squares and cross-products, and correlation-like coefficients based on two or more cases are returned by the method even if ifail=4.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

g02bf does not use additional precision arithmetic for the accumulation of scalar products, so there may be a loss of significant figures for large n.
You are warned of the need to exercise extreme care in your selection of missing values. g02bf treats all values in the inclusive range 1±0.1 x02be-2×xm j, where xm j is the missing value for variable j specified in xmiss.
You must therefore ensure that the missing value chosen for each variable is sufficiently different from all valid values for that variable so that none of the valid values fall within the range indicated above.

Parallelism and Performance

None.

Further Comments

The time taken by g02bf depends on n and m, and the occurrence of missing values.
The method uses a two-pass algorithm.

Example

This example reads in a set of data consisting of five observations on each of three variables. Missing values of 0.0, -1.0 and 0.0 are declared for the first, second and third variables respectively. The means, standard deviations, sums of squares and cross-products about zero, and correlation-like coefficients for all three variables are then calculated and printed, omitting cases with missing values from only those calculations involving the variables for which the values are missing. The program therefore omits cases 4 and 5 in calculating the correlation between the first and second variables, and cases 3 and 4 for the first and third variables, etc.

Example program (C#): g02bfe.cs

Example program data: g02bfe.d

Example program results: g02bfe.r

See Also

G02 Class
G02 Members


g02bg Method

[image]

NAG Library for .NET Release 2
G02..::g02bg Method
G02 Class See Also Send Feedback
g02bg computes means and standard deviations, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients for selected variables.

Syntax

C#
public static void g02bg(
    int n,
    int m,
    double[,] x,
    int nvars,
    int[] kvar,
    double[] xbar,
    double[] std,
    double[,] ssp,
    double[,] r,
    out int ifail
)
Visual Basic
Public Shared Sub g02bg ( _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    nvars As Integer, _
    kvar As Integer(), _
    xbar As Double(), _
    std As Double(), _
    ssp As Double(,), _
    r As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02bg(
    int n,
    int m,
    array<double,2>^ x,
    int nvars,
    array<int>^ kvar,
    array<double>^ xbar,
    array<double>^ std,
    array<double,2>^ ssp,
    array<double,2>^ r,
    [OutAttribute] int% ifail
)
F#
static member g02bg :
        n : int *
        m : int *
        x : float[,] *
        nvars : int *
        kvar : int[] *
        xbar : float[] *
        std : float[] *
        ssp : float[,] *
        r : float[,] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations or cases.
Constraint: n≥2.
m
Type: System..::..Int32
On entry: m, the number of variables.
Constraint: m≥2.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must be set to x ij, the value of the ith observation on the jth variable, for i=1,2,…,n and j=1,2,…,m.
nvars
Type: System..::..Int32
On entry: p, the number of variables for which information is required.
Constraint: 2≤nvars≤m.
kvar
Type: array< System..::..Int32 >[]()[][]
An array of size [nvars]
On entry: kvar[j] must be set to the column number in x of the jth variable for which information is required, for j=0,1,…,p-1.
Constraint: 1≤kvar[j]≤m, for j=0,1,…,p-1.
xbar
Type: array< System..::..Double >[]()[][]
An array of size [nvars]
On exit: the mean value, x-j, of the variable specified in kvar[j-1], for j=1,2,…,p.
std
Type: array< System..::..Double >[]()[][]
An array of size [nvars]
On exit: the standard deviation, sj, of the variable specified in kvar[j-1], for j=1,2,…,p.
ssp
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nvars]
Note: dim1 must satisfy the constraint: dim1≥nvars
On exit: ssp[j-1,k-1] is the cross-product of deviations, S jk, for the variables specified in kvar[j-1] and kvar[k-1], for j=1,2,…,p and k=1,2,…,p.
r
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nvars]
Note: dim1 must satisfy the constraint: dim1≥nvars
On exit: r[j-1,k-1] is the product-moment correlation coefficient, R jk, between the variables specified in kvar[j-1] and kvar[k-1], for j=1,2,…,p and k=1,2,…,p.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The input data consist of n observations for each of m variables, given as an array
x ij,  i=1,2,…,n n≥2,j=1,2,…,m m≥2,
where x ij is the ith observation on the jth variable, together with the subset of these variables, v 1,v 2,…,vp, for which information is required.
The quantities calculated are:
(a) Means:
x-j=1 n∑i=1 n x ij,  j=v 1,v 2,…,vp.
(b) Standard deviations:
sj=1 n-1∑i=1 n x ij-x-j 2,  j=v 1,v 2,…,vp.
(c) Sums of squares and cross-products of deviations from zero:
S jk=∑i=1 n x ij-x-jx ik-x-k,  j,k=v 1,v 2,…,vp.
(d) Pearson product-moment correlation coefficients:
R jk=S jk S jjS kk,  j,k=v 1,v 2,…vp.
If S jj or S kk is zero, R jk is set to zero.

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDSSP, LDR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, n<2.
ifail=2
On entry, | nvars<2,
or | nvars>m.
ifail=4
On entry, | kvar[j-1]<1,
or | kvar[j-1]>m for some j=1,2,…,nvars.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

g02bg does not use additional precision arithmetic for the accumulation of scalar products, so there may be a loss of significant figures for large n.

Parallelism and Performance

None.

Further Comments

The time taken by g02bg depends on n and p.
The method uses a two pass algorithm.

Example

This example reads in a set of data consisting of five observations on each of four variables. The means, standard deviations, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients for the fourth, first and second variables are then calculated and printed.

Example program (C#): g02bge.cs

Example program data: g02bge.d

Example program results: g02bge.r

See Also

G02 Class
G02 Members


g02bh Method

[image]

NAG Library for .NET Release 2
G02..::g02bh Method
G02 Class See Also Send Feedback
g02bh computes means and standard deviations, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients for selected variables omitting completely any cases with a missing observation for any variable (either over all variables in the dataset or over only those variables in the selected subset).

Syntax

C#
public static void g02bh(
    int n,
    int m,
    double[,] x,
    int[] miss,
    double[] xmiss,
    int mistyp,
    int nvars,
    int[] kvar,
    double[] xbar,
    double[] std,
    double[,] ssp,
    double[,] r,
    out int ncases,
    out int ifail
)
Visual Basic
Public Shared Sub g02bh ( _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    miss As Integer(), _
    xmiss As Double(), _
    mistyp As Integer, _
    nvars As Integer, _
    kvar As Integer(), _
    xbar As Double(), _
    std As Double(), _
    ssp As Double(,), _
    r As Double(,), _
    <OutAttribute> ByRef ncases As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02bh(
    int n,
    int m,
    array<double,2>^ x,
    array<int>^ miss,
    array<double>^ xmiss,
    int mistyp,
    int nvars,
    array<int>^ kvar,
    array<double>^ xbar,
    array<double>^ std,
    array<double,2>^ ssp,
    array<double,2>^ r,
    [OutAttribute] int% ncases,
    [OutAttribute] int% ifail
)
F#
static member g02bh :
        n : int *
        m : int *
        x : float[,] *
        miss : int[] *
        xmiss : float[] *
        mistyp : int *
        nvars : int *
        kvar : int[] *
        xbar : float[] *
        std : float[] *
        ssp : float[,] *
        r : float[,] *
        ncases : int byref *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations or cases.
Constraint: n≥2.
m
Type: System..::..Int32
On entry: m, the number of variables.
Constraint: m≥2.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must be set to x ij, the value of the ith observation on the jth variable, for i=1,2,…,n and j=1,2,…,m.
miss
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: miss[j-1] must be set equal to 1 if a missing value, x mj, is to be specified for the jth variable in the array x, or set equal to 0 otherwise. Values of miss must be given for all m variables in the array x.
On exit: the array miss is overwritten by the method, and the information it contained on entry is lost.
xmiss
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: xmiss[j-1] must be set to the missing value, x mj, to be associated with the jth variable in the array x, for those variables for which missing values are specified by means of the array miss (see [Accuracy]).
On exit: the array xmiss is overwritten by the method, and the information it contained on entry is lost.
mistyp
Type: System..::..Int32
On entry: indicates the manner in which missing observations are to be treated.
mistyp=1
A case is excluded if it contains a missing value for any of the variables 1,2,…,m.
mistyp=0
A case is excluded if it contains a missing value for any of the p≤m variables specified in the array kvar.
nvars
Type: System..::..Int32
On entry: p, the number of variables for which information is required.
Constraint: 2≤nvars≤m.
kvar
Type: array< System..::..Int32 >[]()[][]
An array of size [nvars]
On entry: kvar[j] must be set to the column number in x of the jth variable for which information is required, for j=0,1,…,p-1.
Constraint: 1≤kvar[j]≤m, for j=0,1,…,p-1.
xbar
Type: array< System..::..Double >[]()[][]
An array of size [nvars]
On exit: the mean value, of x-j, of the variable specified in kvar[j-1], for j=1,2,…,p.
std
Type: array< System..::..Double >[]()[][]
An array of size [nvars]
On exit: the standard deviation, sj, of the variable specified in kvar[j-1], for j=1,2,…,p.
ssp
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nvars]
Note: dim1 must satisfy the constraint: dim1≥nvars
On exit: ssp[j-1,k-1] is the cross-product of deviations, S jk, for the variables specified in kvar[j-1] and kvar[k-1], for j=1,2,…,p and k=1,2,…,p.
r
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nvars]
Note: dim1 must satisfy the constraint: dim1≥nvars
On exit: r[j-1,k-1] is the product-moment correlation coefficient, R jk, between the variables specified in kvar[j-1] and kvar[k-1], for j=1,2,…,p and k=1,2,…,p.
ncases
Type: System..::..Int32 %
On exit: the number of cases actually used in the calculations (when cases involving missing values have been eliminated).
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The input data consists of n observations for each of m variables, given as an array
x ij,  i=1,2,…,n n≥2,j=1,2,…,m m≥2,
where x ij is the ith observation on the jth variable, together with the subset of these variables, v 1,v 2,…,vp, for which information is required.
In addition, each of the m variables may optionally have associated with it a value which is to be considered as representing a missing observation for that variable; the missing value for the jth variable is denoted by xmj. Missing values need not be specified for all variables. The missing values can be utilized in two slightly different ways; you can indicate which scheme is required.
Firstly, let wi=0 if observation i contains a missing value for any of those variables in the set 1,2,…,m for which missing values have been declared, i.e., if x ij=xmj for any j (j=1,2,…,m) for which an xmj has been assigned (see also [Accuracy]); and wi=1 otherwise, for i=1,2,…,n.
Secondly, let wi=0 if observation i contains a missing value for any of those variables in the selected subset v 1,v 2,…,vp for which missing values have been declared, i.e., if x ij=xmj for any j (j=v 1,v 2,…,vp) for which an xmj has been assigned (see also [Accuracy]); and wi=1 otherwise, for i=1,2,…,n.
The quantities calculated are:
(a) Means:
x-j=∑i=1 n wix ij∑i=1 n wi,  j=v 1,v 2,…,vp.
(b) Standard deviations:
sj=∑i=1 n wi x ij-x-j 2∑i=1 n wi-1,  j=v 1,v 2,…,vp.
(c) Sums of squares and cross-products of deviations from means:
S jk=∑i=1 n wi x ij-x-jx ik-x-k,  j,k=v 1,v 2,…,vp.
(d) Pearson product-moment correlation coefficients:
R jk=S jk S jjS kk,  j,k=v 1,v 2,…,vp.
If S jj or S kk is zero, R jk is set to zero.

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDSSP, LDR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, n<2.
ifail=2
On entry, | nvars<2,
or | nvars>m.
ifail=4
On entry, | kvar[j-1]<1,
or | kvar[j-1]>m for some j=1,2,…,nvars.
ifail=5
On entry, mistyp≠1 or 0
ifail=6
After observations with missing values were omitted, no cases remained.
ifail=7
After observations with missing values were omitted, only one case remained.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

g02bh does not use additional precision arithmetic for the accumulation of scalar products, so there may be a loss of significant figures for large n.
You are warned of the need to exercise extreme care in your selection of missing values. g02bh treats all values in the inclusive range 1±0.1 x02be-2×xm j, where xm j is the missing value for variable j specified in xmiss.
You must therefore ensure that the missing value chosen for each variable is sufficiently different from all valid values for that variable so that none of the valid values fall within the range indicated above.

Parallelism and Performance

None.

Further Comments

The time taken by g02bh depends on n and p, and the occurrence of missing values.
The method uses a two-pass algorithm.

Example

This example reads in a set of data consisting of five observations on each of four variables. Missing values of 0.0 are declared for the second and fourth variables; no missing values are specified for the first and third variables. The means, standard deviations, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients for the fourth, first and second variables are then calculated and printed, omitting completely all cases containing missing values for these three selected variables; cases 3 and 4 are therefore eliminated, leaving only three cases in the calculations.

Example program (C#): g02bhe.cs

Example program data: g02bhe.d

Example program results: g02bhe.r

See Also

G02 Class
G02 Members


g02bj Method

[image]

NAG Library for .NET Release 2
G02..::g02bj Method
G02 Class See Also Send Feedback
g02bj computes means and standard deviations, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients for selected variables omitting cases with missing values from only those calculations involving the variables for which the values are missing.

Syntax

C#
public static void g02bj(
    int n,
    int m,
    double[,] x,
    int[] miss,
    double[] xmiss,
    int nvars,
    int[] kvar,
    double[] xbar,
    double[] std,
    double[,] ssp,
    double[,] r,
    out int ncases,
    double[,] cnt,
    out int ifail
)
Visual Basic
Public Shared Sub g02bj ( _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    miss As Integer(), _
    xmiss As Double(), _
    nvars As Integer, _
    kvar As Integer(), _
    xbar As Double(), _
    std As Double(), _
    ssp As Double(,), _
    r As Double(,), _
    <OutAttribute> ByRef ncases As Integer, _
    cnt As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02bj(
    int n,
    int m,
    array<double,2>^ x,
    array<int>^ miss,
    array<double>^ xmiss,
    int nvars,
    array<int>^ kvar,
    array<double>^ xbar,
    array<double>^ std,
    array<double,2>^ ssp,
    array<double,2>^ r,
    [OutAttribute] int% ncases,
    array<double,2>^ cnt,
    [OutAttribute] int% ifail
)
F#
static member g02bj :
        n : int *
        m : int *
        x : float[,] *
        miss : int[] *
        xmiss : float[] *
        nvars : int *
        kvar : int[] *
        xbar : float[] *
        std : float[] *
        ssp : float[,] *
        r : float[,] *
        ncases : int byref *
        cnt : float[,] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations or cases.
Constraint: n≥2.
m
Type: System..::..Int32
On entry: m, the number of variables.
Constraint: m≥2.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must be set to x ij, the value of the ith observation on the jth variable, for i=1,2,…,n and j=1,2,…,m.
miss
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: miss[j-1] must be set equal to 1 if a missing value, x mj, is to be specified for the jth variable in the array x, or set equal to 0 otherwise. Values of miss must be given for all m variables in the array x.
xmiss
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: xmiss[j-1] must be set to the missing value, x mj, to be associated with the jth variable in the array x, for those variables for which missing values are specified by means of the array miss (see [Accuracy]).
nvars
Type: System..::..Int32
On entry: p, the number of variables for which information is required.
Constraint: 2≤nvars≤m.
kvar
Type: array< System..::..Int32 >[]()[][]
An array of size [nvars]
On entry: kvar[j] must be set to the column number in x of the jth variable for which information is required, for j=0,1,…,p-1.
Constraint: 1≤kvar[j]≤m, for j=0,1,…,p-1.
xbar
Type: array< System..::..Double >[]()[][]
An array of size [nvars]
On exit: the mean value, x-j, of the variable specified in kvar[j-1], for j=1,2,…,p.
std
Type: array< System..::..Double >[]()[][]
An array of size [nvars]
On exit: the standard deviation, sj, of the variable specified in kvar[j-1], for j=1,2,…,p.
ssp
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nvars]
Note: dim1 must satisfy the constraint: dim1≥nvars
On exit: ssp[j-1,k-1] is the cross-product of deviations, S jk, for the variables specified in kvar[j-1] and kvar[k-1], for j=1,2,…,p and k=1,2,…,p.
r
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nvars]
Note: dim1 must satisfy the constraint: dim1≥nvars
On exit: r[j-1,k-1] is the product-moment correlation coefficient, R jk, between the variables specified in kvar[j-1] and kvar[k-1], for j=1,2,…,p and k=1,2,…,p.
ncases
Type: System..::..Int32 %
On exit: the minimum number of cases used in the calculation of any of the sums of squares and cross-products and correlation coefficients (when cases involving missing values have been eliminated).
cnt
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nvars]
Note: dim1 must satisfy the constraint: dim1≥nvars
On exit: cnt[j-1,k-1] is the number of cases, c jk, actually used in the calculation of S jk, and R jk, the sum of cross-products and correlation coefficient for the variables specified in kvar[j-1] and kvar[k-1], for j=1,2,…,p and k=1,2,…,p.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The input data consists of n observations for each of m variables, given as an array
x ij,  i=1,2,…,n n≥2,j=1,2,…,m m≥2,
where x ij is the ith observation on the jth variable, together with the subset of these variables, v 1,v 2,…,vp, for which information is required.
In addition, each of the m variables may optionally have associated with it a value which is to be considered as representing a missing observation for that variable; the missing value for the jth variable is denoted by xmj. Missing values need not be specified for all variables.
Let w ij=0 if the ith observation for the jth variable is a missing value, i.e., if a missing value, xmj, has been declared for the jth variable, and x ij=xmj (see also [Accuracy]); and w ij=1 otherwise, for i=1,2,…,n and j=1,2,…,m.
The quantities calculated are:
(a) Means:
x-j=∑i=1 n w ijx ij∑i=1 n w ij,  j=v 1,v 2,…,vp.
(b) Standard deviations:
sj=∑i=1 n w ij x ij-x-j 2∑i=1 n w ij-1,  j=v 1,v 2,…,vp.
(c) Sums of squares and cross-products of deviations from means:
S jk=∑i=1 n w ijw ik x ij-x-j kx ik-x-k j,  j,k=v 1,v 2,…,vp,
where
x-j k=∑i=1 n w ijw ikx ij∑i=1 n w ijw ik  and  x-k j=∑i=1 n w ikw ijx ik∑i=1 n w ikw ij,
(i.e., the means used in the calculation of the sum of squares and cross-products of deviations are based on the same set of observations as are the cross-products).
(d) Pearson product-moment correlation coefficients:
R jk=S jk S jj kS kk j,  j,k=v 1,v 2,…,vp,
where
S jj k=∑i=1 n w ijw ik x ij-x-j k 2  and  S kk j=∑i=1 n w ikw ij x ik-x-k j 2,
(i.e., the sums of squares of deviations used in the denominator are based on the same set of observations as are used in the calculation of the numerator).
If S jj k or S kk j is zero, R jk is set to zero.
(e) The number of cases used in the calculation of each of the correlation coefficients:
c jk=∑i=1 n w ijw ik,  j,k=v 1,v 2,…,vp.
(The diagonal terms, c jj, for j=v 1,v 2,…,vp, also give the number of cases used in the calculation of the means, x-j, and the standard deviations, sj.)

References

None.

Error Indicators and Warnings

Note: g02bj may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDSSP, LDR, LDCNT) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, n<2.
ifail=2
On entry, | nvars<2,
or | nvars>m.
ifail=4
On entry, | kvar[j-1]<1,
or | kvar[j-1]>m for some j=1,2,…,nvars.
ifail=5
After observations with missing values were omitted, fewer than two cases remained for at least one pair of variables. (The pairs of variables involved can be determined by examination of the contents of the array cnt.) All means, standard deviations, sums of squares and cross-products, and correlation coefficients based on two or more cases are returned by the method even if ifail=5.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

g02bj does not use additional precision arithmetic for the accumulation of scalar products, so there may be a loss of significant figures for large n.
You are warned of the need to exercise extreme care in your selection of missing values. g02bj treats all values in the inclusive range 1±0.1 x02be-2×xm j, where xm j is the missing value for variable j specified in xmiss.
You must therefore ensure that the missing value chosen for each variable is sufficiently different from all valid values for that variable so that none of the valid values fall within the range indicated above.

Parallelism and Performance

None.

Further Comments

The time taken by g02bj depends on n and p, and the occurrence of missing values.
The method uses a two-pass algorithm.

Example

This example reads in a set of data consisting of five observations on each of four variables. Missing values of -1.0, 0.0 and 0.0 are declared for the first, second and fourth variables respectively; no missing value is specified for the third variable. The means, standard deviations, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients for the fourth, first and second variables are then calculated and printed, omitting cases with missing values from only those calculations involving the variables for which the values are missing. The program therefore eliminates cases 4 and 5 in calculating the correlation between the fourth and first variables, and cases 3 and 4 for the fourth and second variables etc.

Example program (C#): g02bje.cs

Example program data: g02bje.d

Example program results: g02bje.r

See Also

G02 Class
G02 Members


g02bk Method

[image]

NAG Library for .NET Release 2
G02..::g02bk Method
G02 Class See Also Send Feedback
g02bk computes means and standard deviations, sums of squares and cross-products about zero, and correlation-like coefficients for selected variables.

Syntax

C#
public static void g02bk(
    int n,
    int m,
    double[,] x,
    int nvars,
    int[] kvar,
    double[] xbar,
    double[] std,
    double[,] sspz,
    double[,] rz,
    out int ifail
)
Visual Basic
Public Shared Sub g02bk ( _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    nvars As Integer, _
    kvar As Integer(), _
    xbar As Double(), _
    std As Double(), _
    sspz As Double(,), _
    rz As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02bk(
    int n,
    int m,
    array<double,2>^ x,
    int nvars,
    array<int>^ kvar,
    array<double>^ xbar,
    array<double>^ std,
    array<double,2>^ sspz,
    array<double,2>^ rz,
    [OutAttribute] int% ifail
)
F#
static member g02bk :
        n : int *
        m : int *
        x : float[,] *
        nvars : int *
        kvar : int[] *
        xbar : float[] *
        std : float[] *
        sspz : float[,] *
        rz : float[,] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations or cases.
Constraint: n≥2.
m
Type: System..::..Int32
On entry: m, the number of variables.
Constraint: m≥2.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must be set to x ij, the value of the ith observation on the jth variable, for i=1,2,…,n and j=1,2,…,m.
nvars
Type: System..::..Int32
On entry: p, the number of variables for which information is required.
Constraint: 2≤nvars≤m.
kvar
Type: array< System..::..Int32 >[]()[][]
An array of size [nvars]
On entry: kvar[j] must be set to the column number in x of the jth variable for which information is required, for j=0,1,…,p-1.
Constraint: 1≤kvar[j]≤m, for j=0,1,…,p-1.
xbar
Type: array< System..::..Double >[]()[][]
An array of size [nvars]
On exit: the mean value, x-j, of the variable specified in kvar[j-1], for j=1,2,…,p.
std
Type: array< System..::..Double >[]()[][]
An array of size [nvars]
On exit: the standard deviation, sj, of the variable specified in kvar[j-1], for j=1,2,…,p.
sspz
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nvars]
Note: dim1 must satisfy the constraint: dim1≥nvars
On exit: sspz[j-1,k-1] is the cross-product about zero, S~jk, for the variables specified in kvar[j-1] and kvar[k-1], for j=1,2,…,p and k=1,2,…,p.
rz
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nvars]
Note: dim1 must satisfy the constraint: dim1≥nvars
On exit: rz[j-1,k-1] is the correlation-like coefficient, R~jk, between the variables specified in kvar[j-1] and kvar[k-1], for j=1,2,…,p and k=1,2,…,p.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The input data consists of n observations for each of m variables, given as an array
x ij,  i=1,2,…,n n≥2,j=1,2,…,m m≥2,
where x ij is the ith observation on the jth variable, together with the subset of these variables, v 1,v 2,…,vp, for which information is required.
The quantities calculated are:
(a) Means:
x-j=∑i=1 n x ij n,  j=v 1,v 2,…,vp.
(b) Standard deviations:
sj=1 n-1∑i=1 n x ij-x-j 2,  j=v 1,v 2,…,vp.
(c) Sums of squares and cross-products about zero:
S~jk=∑i=1 n x ijx ik,  j,k=v 1,v 2,…,vp.
(d) Correlation-like coefficients:
R~jk=S~jk S~jjS~kk,  j,k=v 1,v 2,…,vp.
If S~jj or S~kk is zero, R~jk is set to zero.

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDSSPZ, LDRZ) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, n<2.
ifail=2
On entry, | nvars<2,
or | nvars>m.
ifail=4
On entry, | kvar[j-1]<1,
or | kvar[j-1]>m for some j=1,2,…,nvars.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

g02bk does not use additional precision arithmetic for the accumulation of scalar products, so there may be a loss of significant figures for large n.

Parallelism and Performance

None.

Further Comments

The time taken by g02bk depends on n and p.
The method uses a two-pass algorithm.

Example

This example reads in a set of data consisting of five observations on each of four variables. The means, standard deviations, sums of squares and cross-products about zero, and correlation-like coefficients for the fourth, first and second variables are then calculated and printed.

Example program (C#): g02bke.cs

Example program data: g02bke.d

Example program results: g02bke.r

See Also

G02 Class
G02 Members


g02bl Method

[image]

NAG Library for .NET Release 2
G02..::g02bl Method
G02 Class See Also Send Feedback
g02bl computes means and standard deviations, sums of squares and cross-products about zero, and correlation-like coefficients for selected variables omitting completely any cases with a missing observation for any variable (either over all variables in the dataset or over only those variables in the selected subset).

Syntax

C#
public static void g02bl(
    int n,
    int m,
    double[,] x,
    int[] miss,
    double[] xmiss,
    int mistyp,
    int nvars,
    int[] kvar,
    double[] xbar,
    double[] std,
    double[,] sspz,
    double[,] rz,
    out int ncases,
    out int ifail
)
Visual Basic
Public Shared Sub g02bl ( _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    miss As Integer(), _
    xmiss As Double(), _
    mistyp As Integer, _
    nvars As Integer, _
    kvar As Integer(), _
    xbar As Double(), _
    std As Double(), _
    sspz As Double(,), _
    rz As Double(,), _
    <OutAttribute> ByRef ncases As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02bl(
    int n,
    int m,
    array<double,2>^ x,
    array<int>^ miss,
    array<double>^ xmiss,
    int mistyp,
    int nvars,
    array<int>^ kvar,
    array<double>^ xbar,
    array<double>^ std,
    array<double,2>^ sspz,
    array<double,2>^ rz,
    [OutAttribute] int% ncases,
    [OutAttribute] int% ifail
)
F#
static member g02bl :
        n : int *
        m : int *
        x : float[,] *
        miss : int[] *
        xmiss : float[] *
        mistyp : int *
        nvars : int *
        kvar : int[] *
        xbar : float[] *
        std : float[] *
        sspz : float[,] *
        rz : float[,] *
        ncases : int byref *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations or cases.
Constraint: n≥2.
m
Type: System..::..Int32
On entry: m, the number of variables.
Constraint: m≥2.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must be set to x ij, the value of the ith observation on the jth variable, for i=1,2,…,n and j=1,2,…,m.
miss
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: miss[j-1] must be set equal to 1 if a missing value, x mj, is to be specified for the jth variable in the array x, or set equal to 0 otherwise. Values of miss must be given for all m variables in the array x.
On exit: the array miss is overwritten by the method, and the information it contained on entry is lost.
xmiss
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: xmiss[j-1] must be set to the missing value, x mj, to be associated with the jth variable in the array x, for those variables for which missing values are specified by means of the array miss (see [Accuracy]).
On exit: the array xmiss is overwritten by the method, and the information it contained on entry is lost.
mistyp
Type: System..::..Int32
On entry: indicates the manner in which missing observations are to be treated.
mistyp=1
A case is excluded if it contains a missing value for any of the variables 1,2,…,m.
mistyp=0
A case is excluded if it contains a missing value for any of the p≤m variables specified in the array kvar.
nvars
Type: System..::..Int32
On entry: p, the number of variables for which information is required.
Constraint: 2≤nvars≤m.
kvar
Type: array< System..::..Int32 >[]()[][]
An array of size [nvars]
On entry: kvar[j] must be set to the column number in x of the jth variable for which information is required, for j=0,1,…,p-1.
Constraint: 1≤kvar[j]≤m, for j=0,1,…,p-1.
xbar
Type: array< System..::..Double >[]()[][]
An array of size [nvars]
On exit: the mean value, x-j, of the variable specified in kvar[j-1], for j=1,2,…,p.
std
Type: array< System..::..Double >[]()[][]
An array of size [nvars]
On exit: the standard deviation, sj, of the variable specified in kvar[j-1], for j=1,2,…,p.
sspz
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nvars]
Note: dim1 must satisfy the constraint: dim1≥nvars
On exit: sspz[j-1,k-1] is the cross-product about zero, S~jk, for the variables specified in kvar[j-1] and kvar[k-1], for j=1,2,…,p and k=1,2,…,p.
rz
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nvars]
Note: dim1 must satisfy the constraint: dim1≥nvars
On exit: rz[j-1,k-1] is the correlation-like coefficient, R~jk, between the variables specified in kvar[j-1] and kvar[k-1], for j=1,2,…,p and k=1,2,…,p.
ncases
Type: System..::..Int32 %
On exit: the number of cases actually used in the calculations (when cases involving missing values have been eliminated).
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The input data consist of n observations for each of m variables, given as an array
x ij,  i=1,2,…,n n≥2​ and ​j=1,2,…,m m≥2,
where x ij is the ith observation on the jth variable, together with the subset of these variables, v 1,v 2,…,vp, for which information is required.
In addition, each of the m variables may optionally have associated with it a value which is to be considered as representing a missing observation for that variable; the missing value for the jth variable is denoted by xmj. Missing values need not be specified for all variables.
The missing values can be utilized in two slightly different ways, you can indicate which scheme is required.
Firstly, let wi=0 if observation i contains a missing value for any of those variables in the set 1,2,…,m for which missing values have been declared, i.e., if x ij=xmj for any j (j=1,2,…,m) for which an xmj has been assigned (see also [Accuracy]); and wi=1 otherwise, for i=1,2,…,n.
Secondly, let wi=0 if observation i contains a missing value for any of those variables in the selected subset v 1,v 2,…,vp for which missing values have been declared, i.e., if x ij=xmj for any j j=v 1,v 2,…,vp for which an xmj has been assigned (see also [Accuracy]); and wi=1 otherwise, for i=1,2,…,n.
The quantities calculated are:
(a) Means:
x-j=∑i=1 n wix ij∑i=1 n wi,  j=v 1,v 2,…,vp.
(b) Standard deviations:
Sj=∑i=1 n wi x ij-x-j 2∑i=1 n wi-1,  j=v 1,v 2,…,vp.
(c) Sums of squares and cross-products about zero:
S~jk=∑i=1 n wix ijx ik,  j,k=v 1,v 2,…,vp.
(d) Correlation-like coefficients:
R~jk=S~jk S~jjS~kk,  j,k=v 1,v 2,…,vp.
If S~jj or S~kk is zero, R~jk is set to zero.

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDSSPZ, LDRZ) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, n<2.
ifail=2
On entry, | nvars<2,
or | nvars>m.
ifail=4
On entry, | kvar[j-1]<1,
or | kvar[j-1]>m for some j=1,2,…,nvars.
ifail=5
On entry, mistyp≠1 or 0.
ifail=6
After observations with missing values were omitted, no cases remained.
ifail=7
After observations with missing values were omitted, only one case remained.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

g02bl does not use additional precision arithmetic for the accumulation of scalar products, so there may be a loss of significant figures for large n.
You are warned of the need to exercise extreme care in your selection of missing values. g02bl treats all values in the inclusive range 1±0.1 x02be-2×xm j, where xm j is the missing value for variable j specified in xmiss.
You must therefore ensure that the missing value chosen for each variable is sufficiently different from all valid values for that variable so that none of the valid values fall within the range indicated above.

Parallelism and Performance

None.

Further Comments

The time taken by g02bl depends on n and p, and the occurrence of missing values.
The method uses a two-pass algorithm.

Example

This example reads in a set of data consisting of five observations on each of four variables. Missing values of 0.0 are declared for the second and fourth variables; no missing values are specified for the first and third variables. The means, standard deviations, sums of squares and cross-products about zero, and correlation-like coefficients for the fourth, first and second variables are then calculated and printed, omitting completely all cases containing missing values for these three selected variables; cases 3 and 4 are therefore eliminated, leaving only three cases in the calculations.

Example program (C#): g02ble.cs

Example program data: g02ble.d

Example program results: g02ble.r

See Also

G02 Class
G02 Members


g02bm Method

[image]

NAG Library for .NET Release 2
G02..::g02bm Method
G02 Class See Also Send Feedback
g02bm computes means and standard deviations, sums of squares and cross-products about zero, and correlation-like coefficients for selected variables omitting cases with missing values from only those calculations involving the variables for which the values are missing.

Syntax

C#
public static void g02bm(
    int n,
    int m,
    double[,] x,
    int[] miss,
    double[] xmiss,
    int nvars,
    int[] kvar,
    double[] xbar,
    double[] std,
    double[,] sspz,
    double[,] rz,
    out int ncases,
    double[,] cnt,
    out int ifail
)
Visual Basic
Public Shared Sub g02bm ( _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    miss As Integer(), _
    xmiss As Double(), _
    nvars As Integer, _
    kvar As Integer(), _
    xbar As Double(), _
    std As Double(), _
    sspz As Double(,), _
    rz As Double(,), _
    <OutAttribute> ByRef ncases As Integer, _
    cnt As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02bm(
    int n,
    int m,
    array<double,2>^ x,
    array<int>^ miss,
    array<double>^ xmiss,
    int nvars,
    array<int>^ kvar,
    array<double>^ xbar,
    array<double>^ std,
    array<double,2>^ sspz,
    array<double,2>^ rz,
    [OutAttribute] int% ncases,
    array<double,2>^ cnt,
    [OutAttribute] int% ifail
)
F#
static member g02bm :
        n : int *
        m : int *
        x : float[,] *
        miss : int[] *
        xmiss : float[] *
        nvars : int *
        kvar : int[] *
        xbar : float[] *
        std : float[] *
        sspz : float[,] *
        rz : float[,] *
        ncases : int byref *
        cnt : float[,] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations or cases.
Constraint: n≥2.
m
Type: System..::..Int32
On entry: m, the number of variables.
Constraint: m≥2.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must be set to x ij, the value of the ith observation on the jth variable, for i=1,2,…,n and j=1,2,…,m.
miss
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: miss[j-1] must be set equal to 1 if a missing value, x mj, is to be specified for the jth variable in the array x, or set equal to 0 otherwise. Values of miss must be given for all m variables in the array x.
xmiss
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: xmiss[j-1] must be set to the missing value, x mj, to be associated with the jth variable in the array x, for those variables for which missing values are specified by means of the array miss (see [Accuracy]).
nvars
Type: System..::..Int32
On entry: p, the number of variables for which information is required.
Constraint: 2≤nvars≤m.
kvar
Type: array< System..::..Int32 >[]()[][]
An array of size [nvars]
On entry: kvar[j] must be set to the column number in x of the jth variable for which information is required, for j=0,1,…,p-1.
Constraint: 1≤kvar[j]≤m, for j=0,1,…,p-1.
xbar
Type: array< System..::..Double >[]()[][]
An array of size [nvars]
On exit: the mean value, x-j, of the variable specified in kvar[j-1], for j=1,2,…,p.
std
Type: array< System..::..Double >[]()[][]
An array of size [nvars]
On exit: the standard deviation, sj, of the variable specified in kvar[j-1], for j=1,2,…,p.
sspz
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nvars]
Note: dim1 must satisfy the constraint: dim1≥nvars
On exit: sspz[j-1,k-1] is the cross-product about zero, S~jk, for the variables specified in kvar[j-1] and kvar[k-1], for j=1,2,…,p and k=1,2,…,p.
rz
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nvars]
Note: dim1 must satisfy the constraint: dim1≥nvars
On exit: rz[j-1,k-1] is the correlation-like coefficient, R~jk, between the variables specified in kvar[j-1] and kvar[k-1], for j=1,2,…,p and k=1,2,…,p.
ncases
Type: System..::..Int32 %
On exit: the minimum number of cases used in the calculation of any of the sums of squares and cross-products and correlation-like coefficients (when cases involving missing values have been eliminated).
cnt
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nvars]
Note: dim1 must satisfy the constraint: dim1≥nvars
On exit: cnt[j-1,k-1] is the number of cases, c jk, actually used in the calculation of the sum of cross-product and correlation-like coefficient for the variables specified in kvar[j-1] and kvar[k-1], for j=1,2,…,p and k=1,2,…,p.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The input data consists of n observations for each of m variables, given as an array
x ij,  i=1,2,…,n n≥2,j=1,2,…,m m≥2,
where x ij is the ith observation on the jth variable, together with the subset of these variables, v 1,v 2,…,vp, for which information is required.
In addition, each of the m variables may optionally have associated with it a value which is to be considered as representing a missing observation for that variable; the missing value for the jth variable is denoted by xmj. Missing values need not be specified for all variables.
Let w ij=0, if the ith observation for the jth variable is a missing value, i.e., if a missing value, xmj, has been declared for the jth variable, and x ij=xmj (see also [Accuracy]); and w ij=1 otherwise, for i=1,2,…,n and j=1,2,…,m.
The quantities calculated are:
(a) Means:
x-j=∑i=1 n w ijx ij∑i=1 n w ij,  j=v 1,v 2,…,vp.
(b) Standard deviations:
sj=∑i=1 n w ij x ij-x-j 2∑i=1 n w ij-1,  j=v 1,v 2,…,vp.
(c) Sums of squares and cross-products about zero:
S~jk=∑i=1 n w ijw ikx ijx ik,  j,k=v 1,v 2,…,vp.
(d) Correlation-like coefficients:
R~jk=S~jk S~jj kS~kk j,  j,k=v 1,v 2,…,vp,
where S~jj k=∑i=1 n w ijw ik x ij 2 and S~kk j=∑i=1 n w ikw ij x ik 2
(i.e., the sums of squares about zero are based on the same set of observations as are used in the calculation of the numerator).
If S~jj k or S~kk j is zero, R~jk is set to zero.
(e) The number of cases used in the calculation of each of the correlation-like coefficients:
c jk=∑i=1 n w ijw ik,  j,k=v 1,v 2,…,vp.
(The diagonal terms, c jj, for j=1,2,…,n, also give the number of cases used in the calculation of the means x-j and the standard deviations sj.)

References

None.

Error Indicators and Warnings

Note: g02bm may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDSSPZ, LDRZ, LDCNT) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, n<2.
ifail=2
On entry, | nvars<2,
or | nvars>m.
ifail=4
On entry, | kvar[j-1]<1,
or | kvar[j-1]>m for some j=1,2,…,nvars.
ifail=5
After observations with missing values were omitted, fewer than two cases remained for at least one pair of variables. (The pairs of variables involved can be determined by examination of the contents of the array cnt.) All means, standard deviations, sums of squares and cross-products, and correlation-like coefficients based on two or more cases are returned by the method even if ifail=5.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

g02bm does not use additional precision arithmetic for the accumulation of scalar products, so there may be a loss of significant figures for large n.
You are warned of the need to exercise extreme care in your selection of missing values. g02bm treats all values in the inclusive range 1±0.1 x02be-2×xm j, where xm j is the missing value for variable j specified in xmiss.
You must therefore ensure that the missing value chosen for each variable is sufficiently different from all valid values for that variable so that none of the valid values fall within the range indicated above.

Parallelism and Performance

None.

Further Comments

The time taken by g02bm depends on n and p, and the occurrence of missing values.
The method uses a two-pass algorithm.

Example

This example reads in a set of data consisting of five observations on each of four variables. Missing values of -1.0, 0.0 and 0.0 are declared for the first, second and fourth variables respectively; no missing value is specified for the third variable. The means, standard deviations, sums of squares and cross-products about zero, and correlation-like coefficients for the fourth, first and second variables are then calculated and printed, omitting cases with missing values from only those calculations involving the variables for which the values are missing. The program therefore eliminates cases 4 and 5 in calculating the correlation between the fourth and first variable, and cases 3 and 4 for the fourth and second variables, etc.

Example program (C#): g02bme.cs

Example program data: g02bme.d

Example program results: g02bme.r

See Also

G02 Class
G02 Members


g02bn Method

[image]

NAG Library for .NET Release 2
G02..::g02bn Method
G02 Class See Also Send Feedback
g02bn computes Kendall and/or Spearman nonparametric rank correlation coefficients for a set of data; the data array is overwritten with the ranks of the observations.

Syntax

C#
public static void g02bn(
    int n,
    int m,
    double[,] x,
    int itype,
    double[,] rr,
    out int ifail
)
Visual Basic
Public Shared Sub g02bn ( _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    itype As Integer, _
    rr As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02bn(
    int n,
    int m,
    array<double,2>^ x,
    int itype,
    array<double,2>^ rr,
    [OutAttribute] int% ifail
)
F#
static member g02bn :
        n : int *
        m : int *
        x : float[,] *
        itype : int *
        rr : float[,] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations or cases.
Constraint: n≥2.
m
Type: System..::..Int32
On entry: m, the number of variables.
Constraint: m≥2.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must be set to x ij, the value of the ith observation on the jth variable, for i=1,2,…,n and j=1,2,…,m.
On exit: x[i-1,j-1] contains the rank y ij of the observation x ij, for i=1,2,…,n and j=1,2,…,m.
itype
Type: System..::..Int32
On entry: the type of correlation coefficients which are to be calculated.
itype=-1
Only Kendall's tau coefficients are calculated.
itype=0
Both Kendall's tau and Spearman's coefficients are calculated.
itype=1
Only Spearman's coefficients are calculated.
Constraint: itype=-1, 0 or 1.
rr
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: the requested correlation coefficients.
If only Kendall's tau coefficients are requested (itype=-1), rr[j-1,k-1] contains Kendall's tau for the jth and kth variables.
If only Spearman's coefficients are requested (itype=1), rr[j-1,k-1] contains Spearman's rank correlation coefficient for the jth and kth variables.
If both Kendall's tau and Spearman's coefficients are requested (itype=0), the upper triangle of rr contains the Spearman coefficients and the lower triangle the Kendall coefficients. That is, for the jth and kth variables, where j is less than k, rr[j-1,k-1] contains the Spearman rank correlation coefficient, and rr[k-1,j-1] contains Kendall's tau, for j=1,2,…,m and k=1,2,…,m.
(Diagonal terms, rr[j-1,j-1], are unity for all three values of itype.)
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The input data consists of n observations for each of m variables, given as an array
x ij,  i=1,2,…,n n≥2,j=1,2,…,m m≥2,
where x ij is the ith observation of the jth variable.
The quantities calculated are:
(a) Ranks
For a given variable, j say, each of the n observations, x 1 j,x 2 j,…,x nj, has associated with it an additional number, the ‘rank’ of the observation, which indicates the magnitude of that observation relative to the magnitudes of the other n-1 observations on that same variable.
The smallest observation for variable j is assigned the rank 1, the second smallest observation for variable j the rank 2, the third smallest the rank 3, and so on until the largest observation for variable j is given the rank n.
If a number of cases all have the same value for the given variable, j, then they are each given an ‘average’ rank, e.g., if in attempting to assign the rank h+1, k observations were found to have the same value, then instead of giving them the ranks
h+1,h+2,…,h+k,
all k observations would be assigned the rank
2 h+k+1 2
and the next value in ascending order would be assigned the rank
h+k+1.
The process is repeated for each of the m variables.
Let y ij be the rank assigned to the observation x ij when the jth variable is being ranked. The actual observations x ij are replaced by the ranks y ij.
(b) Nonparametric rank correlation coefficients
(i) Kendall's tau:
R jk=∑h=1 n∑i=1 n sign y hj-y ijsign y hk-y ikn n-1-Tjn n-1-Tk,  j,k=1,2,…,m,
where | sign u=1 if u>0,
 | sign u=0 if u=0,
 | sign u=-1 if u<0,
and Tj=∑tj tj-1, where tj is the number of ties of a particular value of variable j, and the summation is over all tied values of variable j.
(ii) Spearman's:
R jk*=n n 2-1-6∑i=1 n y ij-y ik 2-12 Tj*+Tk*n n 2-1-Tj*n n 2-1-Tk*,  j,k=1,2,…,m,
where Tj*=∑tj tj 2-1, tj being the number of ties of a particular value of variable j, and the summation being over all tied values of variable j.

References

Siegel S (1956) Non-parametric Statistics for the Behavioral Sciences McGraw–Hill

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDRR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, n<2.
ifail=2
On entry, m<2.
ifail=4
On entry, | itype<-1,
or | itype>1.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The method used is believed to be stable.

Parallelism and Performance

None.

Further Comments

The time taken by g02bn depends on n and m.

Example

This example reads in a set of data consisting of nine observations on each of three variables. The program then calculates and prints the rank of each observation, and both Kendall's tau and Spearman's rank correlation coefficients for all three variables.

Example program (C#): g02bne.cs

Example program data: g02bne.d

Example program results: g02bne.r

See Also

G02 Class
G02 Members


g02bp Method

[image]

NAG Library for .NET Release 2
G02..::g02bp Method
G02 Class See Also Send Feedback
g02bp computes Kendall and/or Spearman nonparametric rank correlation coefficients for a set of data omitting completely any cases with a missing observation for any variable; the data array is overwritten with the ranks of the observations.

Syntax

C#
public static void g02bp(
    int n,
    int m,
    double[,] x,
    int[] miss,
    double[] xmiss,
    int itype,
    double[,] rr,
    out int ncases,
    int[] incase,
    out int ifail
)
Visual Basic
Public Shared Sub g02bp ( _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    miss As Integer(), _
    xmiss As Double(), _
    itype As Integer, _
    rr As Double(,), _
    <OutAttribute> ByRef ncases As Integer, _
    incase As Integer(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02bp(
    int n,
    int m,
    array<double,2>^ x,
    array<int>^ miss,
    array<double>^ xmiss,
    int itype,
    array<double,2>^ rr,
    [OutAttribute] int% ncases,
    array<int>^ incase,
    [OutAttribute] int% ifail
)
F#
static member g02bp :
        n : int *
        m : int *
        x : float[,] *
        miss : int[] *
        xmiss : float[] *
        itype : int *
        rr : float[,] *
        ncases : int byref *
        incase : int[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations or cases.
Constraint: n≥2.
m
Type: System..::..Int32
On entry: m, the number of variables.
Constraint: m≥2.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must be set to x ij, the value of the ith observation on the jth variable, for i=1,2,…,n and j=1,2,…,m.
On exit: x[i-1,j-1] contains the rank y ij of the observation x ij, for i=1,2,…,n and j=1,2,…,m. (For those observations containing missing values, and therefore excluded from the calculation, y ij=0, for j=1,2,…,m.)
miss
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: miss[j-1] must be set to 1 if a missing value, x mj, is to be specified for the jth variable in the array x, or set equal to 0 otherwise. Values of miss must be given for all m variables in the array x.
On exit: the array miss is overwritten by the method, and the information it contained on entry is lost.
xmiss
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: xmiss[j-1] must be set to the missing value, x mj, to be associated with the jth variable in the array x, for those variables for which missing values are specified by means of the array miss (see [Accuracy]).
On exit: the array xmiss is overwritten by the method, and the information it contained on entry is lost.
itype
Type: System..::..Int32
On entry: the type of correlation coefficients which are to be calculated.
itype=-1
Only Kendall's tau coefficients are calculated.
itype=0
Both Kendall's tau and Spearman's coefficients are calculated.
itype=1
Only Spearman's coefficients are calculated.
Constraint: itype=-1, 0 or 1.
rr
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: the requested correlation coefficients.
If only Kendall's tau coefficients are requested (itype=-1), rr[j-1,k-1] contains Kendall's tau for the jth and kth variables.
If only Spearman's coefficients are requested (itype=1), rr[j-1,k-1] contains Spearman's rank correlation coefficient for the jth and kth variables.
If both Kendall's tau and Spearman's coefficients are requested (itype=0), the upper triangle of rr contains the Spearman coefficients and the lower triangle the Kendall coefficients. That is, for the jth and kth variables, where j is less than k, rr[j-1,k-1] contains the Spearman rank correlation coefficient, and rr[k-1,j-1] contains Kendall's tau, for j=1,2,…,m and k=1,2,…,m.
(Diagonal terms, rr[j-1,j-1], are unity for all three values of itype.)
ncases
Type: System..::..Int32 %
On exit: the number of cases, nc, actually used in the calculations (when cases involving missing values have been eliminated).
incase
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On exit: incase[i-1] holds the value 1 if the ith case was included in the calculations, and the value 0 if the ith case contained a missing value for at least one variable. That is, incase[i-1]=wi (see [Description]), for i=1,2,…,n.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The input data consists of n observations for each of m variables, given as an array
x ij,  i=1,2,…,n n≥2, j=1,2,…,m m≥2,
where x ij is the ith observation on the jth variable. In addition, each of the m variables may optionally have associated with it a value which is to be considered as representing a missing observation for that variable; the missing value for the jth variable is denoted by xmj. Missing values need not be specified for all variables.
Let wi=0 if observation i contains a missing value for any of those variables for which missing values have been declared; i.e., if x ij=xmj for any j for which an xmj has been assigned (see also [Accuracy]); and wi=1 otherwise, for i=1,2,…,n.
The quantities calculated are:
(a) Ranks
For a given variable, j say, each of the observations x ij for which wi=1, for i=1,2,…,n, has associated with it an additional number, the ‘rank’ of the observation, which indicates the magnitude of that observation relative to the magnitudes of the other observations on that same variable for which wi=1.
The smallest of these valid observations for variable j is assigned the rank 1, the second smallest observation for variable j the rank 2, the third smallest the rank 3, and so on until the largest such observation is given the rank nc, where nc=∑i=1 n wi.
If a number of cases all have the same value for the given variable, j, then they are each given an ‘average’ rank, e.g., if in attempting to assign the rank h+1, k observations for which wi=1 were found to have the same value, then instead of giving them the ranks
h+1,h+2,…,h+k,
all k observations would be assigned the rank
2 h+k+1 2
and the next value in ascending order would be assigned the rank
h+k+1.
The process is repeated for each of the m variables.
Let y ij be the rank assigned to the observation x ij when the jth variable is being ranked. For those observations, i, for which wi=0, y ij=0, for j=1,2,…,m.
The actual observations x ij are replaced by the ranks y ij, for i=1,2,…,n and j=1,2,…,m.
(b) Nonparametric rank correlation coefficients
(i) Kendall's tau:
R jk=∑h=1 n∑i=1 n whwi sign y hj-y ijsign y hk-y iknc nc-1-Tjnc nc-1-Tk,  j,k=1,2,…,m,
where | nc=∑i=1 n wi
and | sign u=1 if u>0
 | sign u=0 if u=0
 | sign u=-1 if u<0
and Tj=∑tj tj-1 where tj is the number of ties of a particular value of variable j, and the summation is over all tied values of variable j.
(ii) Spearman's:
R jk*=nc nc 2-1-6∑i=1 n wi y ij-y ik 2-12 Tj*+Tk*nc nc 2-1-Tj*nc nc 2-1-Tk*,  j,k=1,2,…,m,
where nc=∑i=1 n wi
and Tj*=∑tj tj 2-1 where tj is the number of ties of a particular value of variable j, and the summation is over all tied values of variable j.

References

Siegel S (1956) Non-parametric Statistics for the Behavioral Sciences McGraw–Hill

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDRR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, n<2.
ifail=2
On entry, m<2.
ifail=4
On entry, | itype<-1,
or | itype>1.
ifail=5
After observations with missing values were omitted, fewer than 2 cases remained.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

You are warned of the need to exercise extreme care in your selection of missing values. g02bp treats all values in the inclusive range 1±0.1 x02be-2×xm j, where xm j is the missing value for variable j specified in xmiss.
You must therefore ensure that the missing value chosen for each variable is sufficiently different from all valid values for that variable so that none of the valid values fall within the range indicated above.

Parallelism and Performance

None.

Further Comments

The time taken by g02bp depends on n and m, and the occurrence of missing values.

Example

This example reads in a set of data consisting of nine observations on each of three variables. Missing values of 0.99 and 0.0 are declared for the first and third variables respectively; no missing value is specified for the second variable. The program then calculates and prints the rank of each observation, and both Kendall's tau and Spearman's rank correlation coefficients for all three variables, omitting completely all cases containing missing values; cases 5, 8 and 9 are therefore eliminated, leaving only six cases in the calculations.

Example program (C#): g02bpe.cs

Example program data: g02bpe.d

Example program results: g02bpe.r

See Also

G02 Class
G02 Members


g02bq Method

[image]

NAG Library for .NET Release 2
G02..::g02bq Method
G02 Class See Also Send Feedback
g02bq computes Kendall and/or Spearman nonparametric rank correlation coefficients for a set of data; the data array is preserved, and the ranks of the observations are not available on exit from the method.

Syntax

C#
public static void g02bq(
    int n,
    int m,
    double[,] x,
    int itype,
    double[,] rr,
    out int ifail
)
Visual Basic
Public Shared Sub g02bq ( _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    itype As Integer, _
    rr As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02bq(
    int n,
    int m,
    array<double,2>^ x,
    int itype,
    array<double,2>^ rr,
    [OutAttribute] int% ifail
)
F#
static member g02bq :
        n : int *
        m : int *
        x : float[,] *
        itype : int *
        rr : float[,] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations or cases.
Constraint: n≥2.
m
Type: System..::..Int32
On entry: m, the number of variables.
Constraint: m≥2.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must be set to data value x ij, the value of the ith observation on the jth variable, for i=1,2,…,n and j=1,2,…,m.
itype
Type: System..::..Int32
On entry: the type of correlation coefficients which are to be calculated.
itype=-1
Only Kendall's tau coefficients are calculated.
itype=0
Both Kendall's tau and Spearman's coefficients are calculated.
itype=1
Only Spearman's coefficients are calculated.
Constraint: itype=-1, 0 or 1.
rr
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: the requested correlation coefficients.
If only Kendall's tau coefficients are requested (itype=-1), rr[j-1,k-1] contains Kendall's tau for the jth and kth variables.
If only Spearman's coefficients are requested (itype=1), rr[j-1,k-1] contains Spearman's rank correlation coefficient for the jth and kth variables.
If both Kendall's tau and Spearman's coefficients are requested (itype=0), the upper triangle of rr contains the Spearman coefficients and the lower triangle the Kendall coefficients. That is, for the jth and kth variables, where j is less than k, rr[j-1,k-1] contains the Spearman rank correlation coefficient, and rr[k-1,j-1] contains Kendall's tau, for j=1,2,…,m and k=1,2,…,m.
(Diagonal terms, rr[j-1,j-1], are unity for all three values of itype.)
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The input data consists of n observations for each of m variables, given as an array
x ij,  i=1,2,…,n n≥2,j=1,2,…,m m≥2,
where x ij is the ith observation on the jth variable.
The observations are first ranked, as follows.
For a given variable, j say, each of the n observations, x 1 j,x 2 j,…,x nj, has associated with it an additional number, the ‘rank’ of the observation, which indicates the magnitude of that observation relative to the magnitude of the other n-1 observations on that same variable.
The smallest observation for variable j is assigned the rank 1, the second smallest observation for variable j the rank 2, the third smallest the rank 3, and so on until the largest observation for variable j is given the rank n.
If a number of cases all have the same value for the given variable, j, then they are each given an ‘average’ rank – e.g., if in attempting to assign the rank h+1, k observations were found to have the same value, then instead of giving them the ranks
h+1,h+2,…,h+k,
all k observations would be assigned the rank
2 h+k+1 2
and the next value in ascending order would be assigned the rank
h+k+1.
The process is repeated for each of the m variables.
Let y ij be the rank assigned to the observation x ij when the jth variable is being ranked.
The quantities calculated are:
(a) Kendall's tau rank correlation coefficients:
R jk=∑h=1 n∑i=1 n sign y hj-y ijsign y hk-y ikn n-1-Tjn n-1-Tk,  j,k=1,2,…,m,
and | sign u=1 if u>0
 | sign u=0 if u=0
 | sign u=-1 if u<0
and Tj=∑tj tj-1, tj being the number of ties of a particular value of variable j, and the summation being over all tied values of variable j.
(b) Spearman's rank correlation coefficients:
R jk*=n n 2-1-6∑i=1 n y ij-y ik 2-12 Tj*+Tk*n n 2-1-Tj*n n 2-1-Tk*,  j,k=1,2,…,m,
where Tj*=∑tj tj 2-1 where tj is the number of ties of a particular value of variable j, and the summation is over all tied values of variable j.

References

Siegel S (1956) Non-parametric Statistics for the Behavioral Sciences McGraw–Hill

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDRR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, n<2.
ifail=2
On entry, m<2.
ifail=4
On entry, | itype<-1,
or | itype>1.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The method used is believed to be stable.

Parallelism and Performance

None.

Further Comments

The time taken by g02bq depends on n and m.

Example

This example reads in a set of data consisting of nine observations on each of three variables. The program then calculates and prints both Kendall's tau and Spearman's rank correlation coefficients for all three variables.

Example program (C#): g02bqe.cs

Example program data: g02bqe.d

Example program results: g02bqe.r

See Also

G02 Class
G02 Members


g02br Method

[image]

NAG Library for .NET Release 2
G02..::g02br Method
G02 Class See Also Send Feedback
g02br computes Kendall and/or Spearman nonparametric rank correlation coefficients for a set of data, omitting completely any cases with a missing observation for any variable; the data array is preserved, and the ranks of the observations are not available on exit from the method.

Syntax

C#
public static void g02br(
    int n,
    int m,
    double[,] x,
    int[] miss,
    double[] xmiss,
    int itype,
    double[,] rr,
    out int ncases,
    int[] incase,
    out int ifail
)
Visual Basic
Public Shared Sub g02br ( _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    miss As Integer(), _
    xmiss As Double(), _
    itype As Integer, _
    rr As Double(,), _
    <OutAttribute> ByRef ncases As Integer, _
    incase As Integer(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02br(
    int n,
    int m,
    array<double,2>^ x,
    array<int>^ miss,
    array<double>^ xmiss,
    int itype,
    array<double,2>^ rr,
    [OutAttribute] int% ncases,
    array<int>^ incase,
    [OutAttribute] int% ifail
)
F#
static member g02br :
        n : int *
        m : int *
        x : float[,] *
        miss : int[] *
        xmiss : float[] *
        itype : int *
        rr : float[,] *
        ncases : int byref *
        incase : int[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations or cases.
Constraint: n≥2.
m
Type: System..::..Int32
On entry: m, the number of variables.
Constraint: m≥2.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must be set to x ij, the value of the ith observation on the jth variable, where i=1,2,…,n and j=1,2,…,m.
miss
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: miss[j-1] must be set equal to 1 if a missing value, x mj, is to be specified for the jth variable in the array x, or set equal to 0 otherwise. Values of miss must be given for all m variables in the array x.
On exit: the array miss is overwritten by the method, and the information it contained on entry is lost.
xmiss
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: xmiss[j-1] must be set to the missing value, x mj, to be associated with the jth variable in the array x, for those variables for which missing values are specified by means of the array miss (see [Accuracy]).
On exit: the array xmiss is overwritten by the method, and the information it contained on entry is lost.
itype
Type: System..::..Int32
On entry: the type of correlation coefficients which are to be calculated.
itype=-1
Only Kendall's tau coefficients are calculated.
itype=0
Both Kendall's tau and Spearman's coefficients are calculated.
itype=1
Only Spearman's coefficients are calculated.
Constraint: itype=-1, 0 or 1.
rr
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: the requested correlation coefficients.
If only Kendall's tau coefficients are requested (itype=-1), rr[j-1,k-1] contains Kendall's tau for the jth and kth variables.
If only Spearman's coefficients are requested (itype=1), rr[j-1,k-1] contains Spearman's rank correlation coefficient for the jth and kth variables.
If both Kendall's tau and Spearman's coefficients are requested (itype=0), the upper triangle of rr contains the Spearman coefficients and the lower triangle the Kendall coefficients. That is, for the jth and kth variables, where j is less than k, rr[j-1,k-1] contains the Spearman rank correlation coefficient, and rr[k-1,j-1] contains Kendall's tau, for j=1,2,…,m and k=1,2,…,m.
(Diagonal terms, rr[j-1,j-1], are unity for all three values of itype.)
ncases
Type: System..::..Int32 %
On exit: the number of cases, nc, actually used in the calculations (when cases involving missing values have been eliminated).
incase
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On exit: incase[i-1] holds the value 1 if the ith case was included in the calculations, and the value 0 if the ith case contained a missing value for at least one variable. That is, incase[i-1]=wi (see [Description]), for i=1,2,…,n.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The input data consists of n observations for each of m variables, given as an array
x ij,  i=1,2,…,n n≥2,  j=1,2,…,m m≥2,
where x ij is the ith observation on the jth variable. In addition, each of the m variables may optionally have associated with it a value which is to be considered as representing a missing observation for that variable; the missing value for the jth variable is denoted by xmj. Missing values need not be specified for all variables.
Let wi=0 if observation i contains a missing value for any of those variables for which missing values have been declared, i.e., if x ij=xmj for any j for which an xmj has been assigned (see also [Accuracy]); and wi=1 otherwise, for i=1,2,…,n.
The observations are first ranked as follows.
For a given variable, j say, each of the observations x ij for which wi=1, (i=1,2,…,n) has associated with it an additional number, the ‘rank’ of the observation, which indicates the magnitude of that observation relative to the magnitudes of the other observations on that same variable for which wi=1.
The smallest of these valid observations for variable j is assigned the rank 1, the second smallest observation for variable j the rank 2, the third smallest the rank 3, and so on until the largest such observation is given the rank nc, where nc=∑i=1 n wi.
If a number of cases all have the same value for the given variable, j, then they are each given an ‘average’ rank, e.g., if in attempting to assign the rank h+1, k observations for which wi=1 were found to have the same value, then instead of giving them the ranks
h+1,h+2,…,h+k,
all k observations would be assigned the rank
2 h+k+1 2
and the next value in ascending order would be assigned the rank
h+k+1.
The process is repeated for each of the m variables.
Let y ij be the rank assigned to the observation x ij when the jth variable is being ranked. For those observations, i, for which wi=0, y ij=0, for j=1,2,…,m.
The quantities calculated are:
(a) Kendall's tau rank correlation coefficients:
R jk=∑h=1 n∑i=1 n whwi sign y hj-y ijsign y hk-y iknc nc-1-Tjnc nc-1-Tk,  j,k=1,2,…,m,
where | nc=∑i=1 n wi
and | sign u=1 if u>0
 | sign u=0 if u=0
 | sign u=-1 if u<0
and Tj=∑tj tj-1 where tj is the number of ties of a particular value of variable j, and the summation is over all tied values of variable j.
(b) Spearman's rank correlation coefficients:
R jk*=nc nc 2-1-6∑i=1 n wi y ij-y ik 2-12 Tj*+Tk*nc nc 2-1-Tj*nc nc 2-1-Tk*,  j,k=1,2,…,m,
where nc=∑i=1 n wi and Tj*=∑tj tj 2-1 where tj is the number of ties of a particular value of variable j, and the summation is over all tied values of variable j.

References

Siegel S (1956) Non-parametric Statistics for the Behavioral Sciences McGraw–Hill

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDRR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, n<2.
ifail=2
On entry, m<2.
ifail=4
On entry, | itype<-1,
or | itype>1.
ifail=5
After observations with missing values were omitted, fewer than 2 cases remained.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

You are warned of the need to exercise extreme care in your selection of missing values. g02br treats all values in the inclusive range 1±0.1 x02be-2×xm j, where xm j is the missing value for variable j specified in xmiss.
You must therefore ensure that the missing value chosen for each variable is sufficiently different from all valid values for that variable so that none of the valid values fall within the range indicated above.

Parallelism and Performance

None.

Further Comments

The time taken by g02br depends on n and m, and the occurrence of missing values.

Example

This example reads in a set of data consisting of nine observations on each of three variables. Missing values of 0.99 and 0.0 are declared for the first and third variables respectively; no missing value is specified for the second variable. The program then calculates and prints both Kendall's tau and Spearman's rank correlation coefficients for all three variables, omitting completely all cases containing missing values; cases 5, 8 and 9 are therefore eliminated, leaving only six cases in the calculations.

Example program (C#): g02bre.cs

Example program data: g02bre.d

Example program results: g02bre.r

See Also

G02 Class
G02 Members


g02bs Method

[image]

NAG Library for .NET Release 2
G02..::g02bs Method
G02 Class See Also Send Feedback
g02bs computes Kendall and/or Spearman nonparametric rank correlation coefficients for a set of data omitting cases with missing values from only those calculations involving the variables for which the values are missing; the data array is preserved, and the ranks of the observations are not available on exit from the method.

Syntax

C#
public static void g02bs(
    int n,
    int m,
    double[,] x,
    int[] miss,
    double[] xmiss,
    int itype,
    double[,] rr,
    out int ncases,
    double[,] cnt,
    out int ifail
)
Visual Basic
Public Shared Sub g02bs ( _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    miss As Integer(), _
    xmiss As Double(), _
    itype As Integer, _
    rr As Double(,), _
    <OutAttribute> ByRef ncases As Integer, _
    cnt As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02bs(
    int n,
    int m,
    array<double,2>^ x,
    array<int>^ miss,
    array<double>^ xmiss,
    int itype,
    array<double,2>^ rr,
    [OutAttribute] int% ncases,
    array<double,2>^ cnt,
    [OutAttribute] int% ifail
)
F#
static member g02bs :
        n : int *
        m : int *
        x : float[,] *
        miss : int[] *
        xmiss : float[] *
        itype : int *
        rr : float[,] *
        ncases : int byref *
        cnt : float[,] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations or cases.
Constraint: n≥2.
m
Type: System..::..Int32
On entry: m, the number of variables.
Constraint: m≥2.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must be set to x ij, the value of the ith observation on the jth variable, for i=1,2,…,n and j=1,2,…,m.
miss
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: miss[j-1] must be set equal to 1 if a missing value, x mj, is to be specified for the jth variable in the array x, or set equal to 0 otherwise. Values of miss must be given for all m variables in the array x.
xmiss
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: xmiss[j-1] must be set to the missing value, x mj, to be associated with the jth variable in the array x, for those variables for which missing values are specified by means of the array miss (see [Accuracy]).
itype
Type: System..::..Int32
On entry: the type of correlation coefficients which are to be calculated.
itype=-1
Only Kendall's tau coefficients are calculated.
itype=0
Both Kendall's tau and Spearman's coefficients are calculated.
itype=1
Only Spearman's coefficients are calculated.
Constraint: itype=-1, 0 or 1.
rr
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: the requested correlation coefficients.
If only Kendall's tau coefficients are requested (itype=-1), rr[j-1,k-1] contains Kendall's tau for the jth and kth variables.
If only Spearman's coefficients are requested (itype=1), rr[j-1,k-1] contains Spearman's rank correlation coefficient for the jth and kth variables.
If both Kendall's tau and Spearman's coefficients are requested (itype=0), the upper triangle of rr contains the Spearman coefficients and the lower triangle the Kendall coefficients. That is, for the jth and kth variables, where j is less than k, rr[j-1,k-1] contains the Spearman rank correlation coefficient, and rr[k-1,j-1] contains Kendall's tau, for j=1,2,…,m and k=1,2,…,m.
(Diagonal terms, rr[j-1,j-1], are unity for all three values of itype.)
ncases
Type: System..::..Int32 %
On exit: the minimum number of cases used in the calculation of any of the correlation coefficients (when cases involving missing values have been eliminated).
cnt
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: the number of cases, n jk, actually used in the calculation of the rank correlation coefficient for the jth and kth variables, for j=1,2,…,m and k=1,2,…,m.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The input data consists of n observations for each of m variables, given as an array
x ij,  i=1,2,…,n n≥2​ and ​j=1,2,…,m m≥2,
where x ij is the ith observation on the jth variable. In addition each of the m variables may optionally have associated with it a value which is to be considered as representing a missing observation for that variable; the missing value for the jth variable is denoted by xmj. Missing values need not be specified for all variables.
Let w ij=0 if the ith observation for the jth variable is a missing value, i.e., if a missing value, xmj, has been declared for the jth variable, and x ij=xmj (see also [Accuracy]); and w ij=1 otherwise, for i=1,2,…,n and j=1,2,…,m.
The observations are first ranked, a pair of variables at a time as follows:
For a given pair of variables, j and l say, each of the observations x ij for which the product w ijw il=1, for i=1,2,…,n, has associated with it an additional number, the ‘rank’ of the observation, which indicates the magnitude of that observation relative to the magnitude of the other observations on variable j for which w ijw il=1.
The smallest of these valid observations for variable j is assigned to rank 1, the second smallest valid observation for variable j the rank 2, the third smallest rank 3, and so on until the largest such observation is given the rank n jl, where
n jl=∑i=1 n w ijw il.
If a number of cases all have the same value for the variable j, then they are each given an ‘average’ rank, e.g., if in attempting to assign the rank h+1, k observations for which w ijw il=1 were found to have the same value, then instead of giving them the ranks
h+1,h+2,…,h+k,
all k observations would be assigned the rank
2 h+k+1 2
and the next value in ascending order would be assigned the rank
h+k+1.
The variable l is then ranked in a similar way. The process is then repeated for all pairs of variables j and l, for j=1,2,…,m and l=j,…,m. Let y ij l be the rank assigned to the observation x ij when the jth and lth variables are being ranked, and y il j be the rank assigned to the observation x il during the same process, for i=1,2,…,n, j=1,2,…,m and l=j,…,m.
The quantities calculated are:
(a) Kendall's tau rank correlation coefficients:
R jk=∑h=1 n∑i=1 n w hjw hkw ijw ik sign y hj k-y ij ksign y hk j-y ik jn jk n jk-1-T j kn jk n jk-1-T k j,  j,k=1,2,…,m,
where | n jk=∑i=1 n w ijw ik
and | sign u=1 if u>0
 | sign u=0 if u=0
 | sign u=-1 if u<0
and T j k=∑tj tj-1 where tj is the number of ties of a particular value of variable j when the jth and kth variables are being ranked, and the summation is over all tied values of variable j.
(b) Spearman's rank correlation coefficients:
R jk*=n jk n jk 2-1-6∑i=1 n w ijw ik y ij k-y ik j 2-12 T j k*+T k j*n jk n jk 2-1-T j k*n jk n jk 2-1-T k j*,  j,k=1,2,…,m,
where n jk=∑i=1 n w ijw ik
and T j k*=∑tj tj 2-1, where tj is the number of ties of a particular value of variable j when the jth and kth variables are being ranked, and the summation is over all tied values of variable j.

References

Siegel S (1956) Non-parametric Statistics for the Behavioral Sciences McGraw–Hill

Error Indicators and Warnings

Note: g02bs may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDRR, LDCNT) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, n<2.
ifail=2
On entry, m<2.
ifail=4
On entry, | itype<-1,
or | itype>1.
ifail=5
After observations with missing values were omitted, fewer than two cases remained for at least one pair of variables. (The pairs of variables involved can be determined by examination of the contents of the array cnt.) All correlation coefficients based on two or more cases are returned by the method even if ifail=5.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

You are warned of the need to exercise extreme care in your selection of missing values. g02bs treats all values in the inclusive range 1±0.1 x02be-2×xm j, where xm j is the missing value for variable j specified in xmiss.
You must therefore ensure that the missing value chosen for each variable is sufficiently different from all valid values for that variable so that none of the valid values fall within the range indicated above.

Parallelism and Performance

None.

Further Comments

The time taken by g02bs depends on n and m, and the occurrence of missing values.

Example

This example reads in a set of data consisting of nine observations on each of three variables. Missing values of 0.99, 9.0 and 0.0 are declared for the first, second and third variables respectively. The program then calculates and prints both Kendall's tau and Spearman's rank correlation coefficients for all three variables, omitting cases with missing values from only those calculations involving the variables for which the values are missing. The program therefore eliminates cases 4, 5, 7 and 9 in calculating and correlation between the first and second variables, cases 5, 8 and 9 for the first and third variables, and cases 4, 7 and 8 for the second and third variables.

Example program (C#): g02bse.cs

Example program data: g02bse.d

Example program results: g02bse.r

See Also

G02 Class
G02 Members


g02bt Method

[image]

NAG Library for .NET Release 2
G02..::g02bt Method
G02 Class See Also Send Feedback
g02bt updates the sample means and sums of squares and cross-products, or sums of squares and cross-products of deviations about the mean, for a new observation. The data may be weighted.

Syntax

C#
public static void g02bt(
    string mean,
    int m,
    double wt,
    double[] x,
    int incx,
    ref double sw,
    double[] xbar,
    double[] c,
    out int ifail
)
Visual Basic
Public Shared Sub g02bt ( _
    mean As String, _
    m As Integer, _
    wt As Double, _
    x As Double(), _
    incx As Integer, _
    ByRef sw As Double, _
    xbar As Double(), _
    c As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02bt(
    String^ mean,
    int m,
    double wt,
    array<double>^ x,
    int incx,
    double% sw,
    array<double>^ xbar,
    array<double>^ c,
    [OutAttribute] int% ifail
)
F#
static member g02bt :
        mean : string *
        m : int *
        wt : float *
        x : float[] *
        incx : int *
        sw : float byref *
        xbar : float[] *
        c : float[] *
        ifail : int byref -> unit

Parameters

mean
Type: System..::..String
On entry: indicates whether g02bt is to calculate sums of squares and cross-products, or sums of squares and cross-products of deviations about the mean.
mean="M"
The sums of squares and cross-products of deviations about the mean are calculated.
mean="Z"
The sums of squares and cross-products are calculated.
Constraint: mean="M" or "Z".
m
Type: System..::..Int32
On entry: m, the number of variables.
Constraint: m≥1.
wt
Type: System..::..Double
On entry: the weight to use for the current observation, wi.
For unweighted means and cross-products set wt=1.0. The use of a suitable negative value of wt, e.g., -wi will have the effect of deleting the observation.
x
Type: array< System..::..Double >[]()[][]
An array of size [m×incx]
On entry: x[j-1×incx] must contain the value of the jth variable for the current observation, j=1,2,…,m.
incx
Type: System..::..Int32
On entry: the increment of x.
If incx=ldx, for some positive integer ldx, the data values are to be found as a row of an array with first dimension ldx.
Constraint: incx>0.
sw
Type: System..::..Double %
On entry: the sum of weights for the previous observations, W i-1.
sw=0.0
The update procedure is initialized.
sw+wt=0.0
All elements of xbar and c are set to zero.
Constraint: sw≥0.0 and sw+wt≥0.0.
On exit: contains the updated sum of weights, Wi.
xbar
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: if sw=0.0, xbar is initialized, otherwise xbar[j-1] must contain the weighted mean of the jth variable for the previous i-1 observations, x-j i-1, for j=1,2,…,m.
On exit: xbar[j-1] contains the weighted mean of the jth variable, x-j i, for j=1,2,…,m.
c
Type: array< System..::..Double >[]()[][]
An array of size [m×m+m/2]
On entry: if sw≠0.0, c must contain the upper triangular part of the matrix of weighted sums of squares and cross-products or weighted sums of squares and cross-products of deviations about the mean. It is stored packed form by column, i.e., the cross-product between the jth and kth variable, k≥j, is stored in c[k×k-1/2+j-1].
On exit: the update sums of squares and cross-products stored as on input.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g02bt is an adaptation of West's WV2 algorithm; see West (1979). This method updates the weighted means of variables and weighted sums of squares and cross-products or weighted sums of squares and cross-products of deviations about the mean for observations on m variables Xj, for j=1,2,…,m. For the first i-1 observations let the mean of the jth variable be x-j i-1, the cross-product about the mean for the jth and kth variables be c jk i-1 and the sum of weights be W i-1. These are updated by the ith observation, x ij, for j=1,2,…,m, with weight wi as follows:
Wi=W i-1+wi,  x-j i=x-j i-1+wiWi xj-x-j i-1,  j=1,2,…,m
and
c jk i=c jk i-1+wiWi xj-x-j i-1xk-x-k i-1 W i-1,  j=1,2,…,m;k=j,j+1,2,…,m.
The algorithm is initialized by taking x-j 1=x 1 j, the first observation and c ij 1=0.0.
For the unweighted case wi=1 and Wi=i for all i.

References

Chan T F, Golub G H and Leveque R J (1982) Updating Formulae and a Pairwise Algorithm for Computing Sample Variances Compstat, Physica-Verlag
West D H D (1979) Updating mean and variance estimates: An improved method Comm. ACM 22 532–555

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | m<1,
or | incx<1.
ifail=2
On entry, sw<0.0.
ifail=3
On entry, sw+wt<0.0, the current weight causes the sum of weights to be less than 0.0.
ifail=4
On entry, mean≠"M" or "Z".
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

For a detailed discussion of the accuracy of this method see Chan et al. (1982) and West (1979).

Parallelism and Performance

None.

Further Comments

g02bt may be used to update the results returned by g02bu.
g02bw may be used to calculate the correlation matrix from the matrix of sums of squares and cross-products of deviations about the mean and the matrix may be scaled using (F06EDF not in this release) f06fd to produce a variance-covariance matrix.

Example

A program to calculate the means, the required sums of squares and cross-products matrix, and the variance matrix for a set of 3 observations of 3 variables.

Example program (C#): g02bte.cs

Example program data: g02bte.d

Example program results: g02bte.r

See Also

G02 Class
G02 Members


g02bu Method

[image]

NAG Library for .NET Release 2
G02..::g02bu Method
G02 Class See Also Send Feedback
g02bu calculates the sample means and sums of squares and cross-products, or sums of squares and cross-products of deviations from the mean, in a single pass for a set of data. The data may be weighted.

Syntax

C#
public static void g02bu(
    string mean,
    string weight,
    int n,
    int m,
    double[,] x,
    double[] wt,
    out double sw,
    double[] wmean,
    double[] c,
    out int ifail
)
Visual Basic
Public Shared Sub g02bu ( _
    mean As String, _
    weight As String, _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    wt As Double(), _
    <OutAttribute> ByRef sw As Double, _
    wmean As Double(), _
    c As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02bu(
    String^ mean,
    String^ weight,
    int n,
    int m,
    array<double,2>^ x,
    array<double>^ wt,
    [OutAttribute] double% sw,
    array<double>^ wmean,
    array<double>^ c,
    [OutAttribute] int% ifail
)
F#
static member g02bu :
        mean : string *
        weight : string *
        n : int *
        m : int *
        x : float[,] *
        wt : float[] *
        sw : float byref *
        wmean : float[] *
        c : float[] *
        ifail : int byref -> unit

Parameters

mean
Type: System..::..String
On entry: indicates whether g02bu is to calculate sums of squares and cross-products, or sums of squares and cross-products of deviations about the mean.
mean="M"
The sums of squares and cross-products of deviations about the mean are calculated.
mean="Z"
The sums of squares and cross-products are calculated.
Constraint: mean="M" or "Z".
weight
Type: System..::..String
On entry: indicates whether the data is weighted or not.
weight="U"
The calculations are performed on unweighted data.
weight="W"
The calculations are performed on weighted data.
Constraint: weight="W" or "U".
n
Type: System..::..Int32
On entry: n, the number of observations in the dataset.
Constraint: n≥1.
m
Type: System..::..Int32
On entry: m, the number of variables.
Constraint: m≥1.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must contain the ith observation on the jth variable, for i=1,2,…,n and j=1,2,…,m.
wt
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array wt must be at least n if weight="W", and at least 1 otherwise.
On entry: the optional weights of each observation.
If weight="U", wt is not referenced.
If weight="W", wt[i-1] must contain the weight for the ith observation.
Constraint: if weight="W", wt[i]≥0.0, for i=0,1,…,n-1.
sw
Type: System..::..Double %
On exit: the sum of weights.
If weight="U", sw contains the number of observations, n.
wmean
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: the sample means. wmean[j-1] contains the mean for the jth variable.
c
Type: array< System..::..Double >[]()[][]
An array of size [m×m+m/2]
On exit: the cross-products.
If mean="M", c contains the upper triangular part of the matrix of (weighted) sums of squares and cross-products of deviations about the mean.
If mean="Z", c contains the upper triangular part of the matrix of (weighted) sums of squares and cross-products.
These are stored packed by columns, i.e., the cross-product between the jth and kth variable, k≥j, is stored in c[k×k-1/2+j-1].
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g02bu is an adaptation of West's WV2 algorithm; see West (1979). This method calculates the (optionally weighted) sample means and (optionally weighted) sums of squares and cross-products or sums of squares and cross-products of deviations from the (weighted) mean for a sample of n observations on m variables Xj, for j=1,2,…,m. The algorithm makes a single pass through the data.
For the first i-1 observations let the mean of the jth variable be x-j i-1, the cross-product about the mean for the jth and kth variables be c jk i-1 and the sum of weights be W i-1. These are updated by the ith observation, x ij, for j=1,2,…,m, with weight wi as follows:
Wi=W i-1+wix-j i=x-j i-1+wiWi xj-x-j i-1,  j=1,2,…,m
and
c jk i=c jk i-1+wiWi xj-x-j i-1xk-x-k i-1 W i-1,  j=1,2,…,m​ and ​k=j,j+1,…,m.
The algorithm is initialized by taking x-j 1=x 1 j, the first observation, and c ij 1=0.0.
For the unweighted case wi=1 and Wi=i for all i.
Note that only the upper triangle of the matrix is calculated and returned packed by column.

References

Chan T F, Golub G H and Leveque R J (1982) Updating Formulae and a Pairwise Algorithm for Computing Sample Variances Compstat, Physica-Verlag
West D H D (1979) Updating mean and variance estimates: An improved method Comm. ACM 22 532–555

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | m<1,
or | n<1,
ifail=2
On entry, mean≠"M" or "Z".
ifail=3
On entry, weight≠"W" or "U".
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

For a detailed discussion of the accuracy of this algorithm see Chan et al. (1982) or West (1979).

Parallelism and Performance

None.

Further Comments

g02bw may be used to calculate the correlation coefficients from the cross-products of deviations about the mean. The cross-products of deviations about the mean may be scaled using (F06EDF not in this release) f06fd to give a variance-covariance matrix.
The means and cross-products produced by g02bu may be updated by adding or removing observations using g02bt.
Two sets of means and cross-products, as produced by g02bu, can be combined using (G02BZF not in this release).

Example

A program to calculate the means, the required sums of squares and cross-products matrix, and the variance matrix for a set of 3 observations of 3 variables.

Example program (C#): g02bue.cs

Example program data: g02bue.d

Example program results: g02bue.r

See Also

G02 Class
G02 Members


g02bw Method

[image]

NAG Library for .NET Release 2
G02..::g02bw Method
G02 Class See Also Send Feedback
g02bw calculates a matrix of Pearson product-moment correlation coefficients from sums of squares and cross-products of deviations about the mean.

Syntax

C#
public static void g02bw(
    int m,
    double[] r,
    out int ifail
)
Visual Basic
Public Shared Sub g02bw ( _
    m As Integer, _
    r As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02bw(
    int m,
    array<double>^ r,
    [OutAttribute] int% ifail
)
F#
static member g02bw :
        m : int *
        r : float[] *
        ifail : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: m, the number of variables.
Constraint: m≥1.
r
Type: array< System..::..Double >[]()[][]
An array of size [m×m+m/2]
On entry: contains the upper triangular part of the sums of squares and cross-products matrix of deviations from the mean. These are stored packed by column, i.e., the cross-product between variable j and k, k≥j, is stored in r[k×k-1/2+j-1].
On exit: Pearson product-moment correlation coefficients.
These are stored packed by column corresponding to the input cross-products.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g02bw calculates a matrix of Pearson product-moment correlation coefficients from sums of squares and cross-products about the mean for observations on m variables which can be computed by a single call to g02bu or a series of calls to g02bt. The sums of squares and cross-products are stored in an array packed by column and are overwritten by the correlation coefficients.
Let c jk be the cross-product of deviations from the mean, for j=1,2,…,m and k=j,…,m, then the product-moment correlation coefficient, r jk is given by
r jk=c jk c jjc kk.

References

None.

Error Indicators and Warnings

Note: g02bw may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail=1
On entry, m<1.
ifail=2
A variable has a zero variance. All correlations involving the variable with zero variance will be returned as zero.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The accuracy of g02bw is entirely dependent upon the accuracy of the elements of array r.

Parallelism and Performance

None.

Further Comments

g02bw may also be used to calculate the correlations between parameter estimates from the variance-covariance matrix of the parameter estimates as is given by several methods in this chapter.

Example

Example program (C#): g02bwe.cs

Example program data: g02bwe.d

Example program results: g02bwe.r

See Also

G02 Class
G02 Members


g02bx Method

[image]

NAG Library for .NET Release 2
G02..::g02bx Method
G02 Class See Also Send Feedback
g02bx calculates the sample means, the standard deviations, the variance-covariance matrix, and the matrix of Pearson product-moment correlation coefficients for a set of data. Weights may be used.

Syntax

C#
public static void g02bx(
    string weight,
    int n,
    int m,
    double[,] x,
    double[] wt,
    double[] xbar,
    double[] std,
    double[,] v,
    double[,] r,
    out int ifail
)
Visual Basic
Public Shared Sub g02bx ( _
    weight As String, _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    wt As Double(), _
    xbar As Double(), _
    std As Double(), _
    v As Double(,), _
    r As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02bx(
    String^ weight,
    int n,
    int m,
    array<double,2>^ x,
    array<double>^ wt,
    array<double>^ xbar,
    array<double>^ std,
    array<double,2>^ v,
    array<double,2>^ r,
    [OutAttribute] int% ifail
)
F#
static member g02bx :
        weight : string *
        n : int *
        m : int *
        x : float[,] *
        wt : float[] *
        xbar : float[] *
        std : float[] *
        v : float[,] *
        r : float[,] *
        ifail : int byref -> unit

Parameters

weight
Type: System..::..String
On entry: indicates whether weights are to be used.
weight="U"
Weights are not used and unit weights are assumed.
weight="W" or "V"
Weights are used and must be supplied in wt. The only difference between weight="W" or weight="V" is in computing the variance. If weight="W" the divisor for the variance is the sum of the weights minus one and if weight="V" the divisor is the number of observations with nonzero weights minus one. The former is useful if the weights represent the frequency of the observed values.
Constraint: weight="U", "V" or "W".
n
Type: System..::..Int32
On entry: the number of data observations in the sample.
Constraint: n>1.
m
Type: System..::..Int32
On entry: the number of variables.
Constraint: m≥1.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must contain the ith observation for the jth variable, for i=1,2,…,n and j=1,2,…,m.
wt
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array wt must be at least n if weight="W" or "V", and at least 1 otherwise.
On entry: w, the optional frequency weighting for each observation, with wt[i-1]=wi. Usually wi will be an integral value corresponding to the number of observations associated with the ith data value, or zero if the ith data value is to be ignored. If weight="U", wi is set to 1 for all i and wt is not referenced.
Constraint: if weight="W" or "V", ∑ i=0 n-1 wt[i]>1.0, wt[i]≥0.0, for i=0,1,…,n-1.
xbar
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: the sample means. xbar[j-1] contains the mean of the jth variable.
std
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: the standard deviations. std[j-1] contains the standard deviation for the jth variable.
v
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: the variance-covariance matrix. v[j-1,k-1] contains the covariance between variables j and k, for j=1,2,…,m and k=1,2,…,m.
r
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: the matrix of Pearson product-moment correlation coefficients. r[j-1,k-1] contains the correlation coefficient between variables j and k.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

For n observations on m variables the one-pass algorithm of West (1979) as implemented in g02bu is used to compute the means, the standard deviations, the variance-covariance matrix, and the Pearson product-moment correlation matrix for p selected variables. Suitables weights may be used to indicate multiple observations and to remove missing values. The quantities are defined by:
(a) The means
x-j=∑i=1 n wix ij∑i=1 n wi j=1,…,p
(b) The variance-covariance matrix
C jk=∑i=1 n wi x ij-x-jx ik-x-k∑i=1 n wi-1 j,k=1,…,p
(c) The standard deviations
sj=C jj j=1,…,p
(d) The Pearson product-moment correlation coefficients
R jk=C jk C jjC kk j,k=1,…,p
where x ij is the value of the ith observation on the jth variable and wi is the weight for the ith observation which will be 1 in the unweighted case.
Note that the denominator for the variance-covariance is ∑i=1 n wi-1, so the weights should be scaled so that the sum of weights reflects the true sample size.

References

Chan T F, Golub G H and Leveque R J (1982) Updating Formulae and a Pairwise Algorithm for Computing Sample Variances Compstat, Physica-Verlag
West D H D (1979) Updating mean and variance estimates: An improved method Comm. ACM 22 532–555

Error Indicators and Warnings

Note: g02bx may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDV) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | m<1,
or | n≤1,
ifail=2
On entry, weight≠"U", "V" or "W".
ifail=3
On entry, weight="W" or "V" and a value of wt<0.0.
ifail=4
weight="W" and the sum of weights is not greater than 1.0, or weight="V" and fewer than 2 observations have nonzero weights.
ifail=5
A variable has a zero variance. In this case v and std are returned as calculated but r will contain zero for any correlation involving a variable with zero variance.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

For a discussion of the accuracy of the one pass algorithm see Chan et al. (1982) and West (1979).

Parallelism and Performance

None.

Further Comments

None.

Example

The data are some of the results from 1988 Olympic Decathlon. They are the times (in seconds) for the 100m and 400m races and the distances (in metres) for the long jump, high jump and shot. Twenty observations are input and the correlation matrix is computed and printed.

Example program (C#): g02bxe.cs

Example program data: g02bxe.d

Example program results: g02bxe.r

See Also

G02 Class
G02 Members


g02by Method

[image]

NAG Library for .NET Release 2
G02..::g02by Method
G02 Class See Also Send Feedback
g02by computes a partial correlation/variance-covariance matrix from a correlation or variance-covariance matrix computed by g02bx.

Syntax

C#
public static void g02by(
    int m,
    int ny,
    int nx,
    int[] isz,
    double[,] r,
    double[,] p,
    out int ifail
)
Visual Basic
Public Shared Sub g02by ( _
    m As Integer, _
    ny As Integer, _
    nx As Integer, _
    isz As Integer(), _
    r As Double(,), _
    p As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02by(
    int m,
    int ny,
    int nx,
    array<int>^ isz,
    array<double,2>^ r,
    array<double,2>^ p,
    [OutAttribute] int% ifail
)
F#
static member g02by :
        m : int *
        ny : int *
        nx : int *
        isz : int[] *
        r : float[,] *
        p : float[,] *
        ifail : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: the number of variables in the variance-covariance/correlation matrix given in r.
Constraint: m≥3.
ny
Type: System..::..Int32
On entry: the number of Y variables, ny, for which partial correlation coefficients are to be computed.
Constraint: ny≥2.
nx
Type: System..::..Int32
On entry: the number of X variables, nx, which are to be considered as fixed.
Constraints:
  • nx≥1;
  • ny+nx≤m.
isz
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: indicates which variables belong to set X and Y.
isz[i-1]<0
The ith variable is a Y variable, for i=1,2,…,m.
isz[i-1]>0
The ith variable is a X variable.
isz[i-1]=0
The ith variable is not included in the computations.
Constraints:
  • exactly ny elements of isz must be <0;
  • exactly nx elements of isz must be >0.
r
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On entry: the variance-covariance or correlation matrix for the m variables as given by g02bx. Only the upper triangle need be given.
Note: the matrix must be a full rank variance-covariance or correlation matrix and so be positive definite. This condition is not directly checked by the method.
p
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, ny]
Note: dim1 must satisfy the constraint: dim1≥ny
On exit: the strict upper triangle of p contains the strict upper triangular part of the ny by ny partial correlation matrix. The lower triangle contains the lower triangle of the ny by ny partial variance-covariance matrix if the matrix given in r is a variance-covariance matrix. If the matrix given in r is a partial correlation matrix then the variance-covariance matrix is for standardized variables.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Partial correlation can be used to explore the association between pairs of random variables in the presence of other variables. For three variables, y 1, y 2 and x 3, the partial correlation coefficient between y 1 and y 2 given x 3 is computed as:
r 12-r 13r 231-r 1321-r 232,
where r ij is the product-moment correlation coefficient between variables with subscripts i and j. The partial correlation coefficient is a measure of the linear association between y 1 and y 2 having eliminated the effect due to both y 1 and y 2 being linearly associated with x 3. That is, it is a measure of association between y 1 and y 2 conditional upon fixed values of x 3. Like the full correlation coefficients the partial correlation coefficient takes a value in the range (-1,1) with the value 0 indicating no association.
In general, let a set of variables be partitioned into two groups Y and X with ny variables in Y and nx variables in X and let the variance-covariance matrix of all ny+nx variables be partitioned into,
Σ xxΣ xyΣ yxΣ yy.
The variance-covariance of Y conditional on fixed values of the X variables is given by:
Σ y∣x=Σ yy-Σ yx Σ xx-1 Σ xy.
The partial correlation matrix is then computed by standardizing Σ y∣x,
diag Σ y∣x-12 Σ y∣x diag Σ y∣x-12.
To test the hypothesis that a partial correlation is zero under the assumption that the data has an approximately Normal distribution a test similar to the test for the full correlation coefficient can be used. If r is the computed partial correlation coefficient then the appropriate t statistic is
r⁢n-nx-21-r 2,
which has approximately a Student's t-distribution with n-nx-2 degrees of freedom, where n is the number of observations from which the full correlation coefficients were computed.

References

Krzanowski W J (1990) Principles of Multivariate Analysis Oxford University Press
Morrison D F (1967) Multivariate Statistical Methods McGraw–Hill
Osborn J F (1979) Statistical Exercises in Medical Research Blackwell
Snedecor G W and Cochran W G (1967) Statistical Methods Iowa State University Press

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDR, LDP) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | m<3,
or | ny<2,
or | nx<1,
or | ny+nx>m,
ifail=2
On entry, | there are not exactly ny elements of isz<0,
or | there are not exactly nx elements of isz>0.
ifail=3
On entry, the variance-covariance/correlation matrix of the X variables, Σ xx, is not of full rank. Try removing some of the X variables by setting the appropriate element of isz=0.
ifail=4
Either a diagonal element of the partial variance-covariance matrix, Σ y∣x, is zero and/or a computed partial correlation coefficient is greater than one. Both indicate that the matrix input in r was not positive definite.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

g02by computes the partial variance-covariance matrix, Σ y∣x, by computing the Cholesky factorization of Σ xx. If Σ xx is not of full rank the computation will fail. For a statement on the accuracy of the Cholesky factorization see (F07GDF not in this release).

Parallelism and Performance

None.

Further Comments

Models that represent the linear associations given by partial correlations can be fitted using the multiple regression method g02da.

Example

Example program (C#): g02bye.cs

Example program data: g02bye.d

Example program results: g02bye.r

See Also

G02 Class
G02 Members


g02ca Method

[image]

NAG Library for .NET Release 2
G02..::g02ca Method
G02 Class See Also Send Feedback
g02ca performs a simple linear regression with dependent variable y and independent variable x.

Syntax

C#
public static void g02ca(
    int n,
    double[] x,
    double[] y,
    double[] result,
    out int ifail
)
Visual Basic
Public Shared Sub g02ca ( _
    n As Integer, _
    x As Double(), _
    y As Double(), _
    result As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02ca(
    int n,
    array<double>^ x,
    array<double>^ y,
    array<double>^ result,
    [OutAttribute] int% ifail
)
F#
static member g02ca :
        n : int *
        x : float[] *
        y : float[] *
        result : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of pairs of observations.
Constraint: n>2.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x[i-1] must contain xi, for i=1,2,…,n.
y
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: y[i-1] must contain yi, for i=1,2,…,n.
result
Type: array< System..::..Double >[]()[][]
An array of size [20]
On exit: the following information:
result[0] | x-, the mean value of the independent variable, x;
result[1] | y-, the mean value of the dependent variable, y;
result[2] | sx the standard deviation of the independent variable, x;
result[3] | sy the standard deviation of the dependent variable, y;
result[4] | r, the Pearson product-moment correlation between the independent variable x and the dependent variable y;
result[5] | b, the regression coefficient;
result[6] | a, the regression constant;
result[7] | se b, the standard error of the regression coefficient;
result[8] | se a, the standard error of the regression constant;
result[9] | t b, the t value for the regression coefficient;
result[10] | t a, the t value for the regression constant;
result[11] | SSR, the sum of squares attributable to the regression;
result[12] | DFR, the degrees of freedom attributable to the regression;
result[13] | MSR, the mean square attributable to the regression;
result[14] | F, the F value for the analysis of variance;
result[15] | SSD, the sum of squares of deviations about the regression;
result[16] | DFD, the degrees of freedom of deviations about the regression
result[17] | MSD, the mean square of deviations about the regression;
result[18] | SST, the total sum of squares;
result[19] | DFT, the total degrees of freedom.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g02ca fits a straight line of the form
y=a+bx
to the data points
x 1,y 1,x 2,y 2,…,xn,yn,
such that
yi=a+b xi+ei,  i=1,2,…,n n>2.
The method calculates the regression coefficient, b, the regression constant, a (and various other statistical quantities) by minimizing
∑i=1 n ei 2.
The input data consist of the n pairs of observations
x 1,y 1,x 2,y 2,…,xn,yn
on the independent variable x and the dependent variable y.
The quantities calculated are:
(a) Means:
x-=1 n∑i=1 n xi;  y-=1 n∑i=1 n yi.
(b) Standard deviations:
sx=1 n-1∑i=1 n xi-x-2;  sy=1 n-1∑i=1 n yi-y-2.
(c) Pearson product-moment correlation coefficient:
r=∑i=1 n xi-x-yi-y-∑i=1 n xi-x-2∑i=1 n yi-y-2.
(d) The regression coefficient, b, and the regression constant, a:
b=∑i=1 n xi-x-yi-y-∑i=1 n xi-x-2;a=y--b x-.
(e) The sum of squares attributable to the regression, SSR, the sum of squares of deviations about the regression, SSD, and the total sum of squares, SST:
SST=∑i=1 n yi-y-2;SSD=∑i=1 n yi-a-b xi 2;SSR=SST-SSD.
(f) The degrees of freedom attributable to the regression, DFR, the degrees of freedom of deviations about the regression, DFD, and the total degrees of freedom, DFT:
DFT=n-1; ​DFD=n-2; ​DFR=1.
(g) The mean square attributable to the regression, MSR, and the mean square of deviations about the regression, MSD:
MSR=SSR/DFR;MSD=SSD/DFD.
(h) The F value for the analysis of variance:
F=MSR/MSD.
(i) The standard error of the regression coefficient, se b, and the standard error of the regression constant, se a:
se b=MSD∑i=1 n xi-x-2;  se a=MSD 1 n+x-2∑i=1 n xi-x-2.
(j) The t value for the regression coefficient, t b, and the t value for the regression constant, t a:
t b=b se b;  t a=a se a.

References

Draper N R and Smith H (1985) Applied Regression Analysis (2nd Edition) Wiley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n≤2.
ifail=2
On entry, all n values of at least one of the variables x and y are identical.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

g02ca does not use additional precision arithmetic for the accumulation of scalar products, so there may be a loss of significant figures for large n.
If, in calculating F, t a or t b (see [Description]), the numbers involved are such that the result would be outside the range of numbers which can be stored by the machine, then the answer is set to the largest quantity which can be stored as a real variable, by means of a call to x02al.

Parallelism and Performance

None.

Further Comments

The time taken by g02ca depends on n.
The method uses a two-pass algorithm.

Example

This example reads in eight observations on each of two variables, and then performs a simple linear regression with the first variable as the independent variable, and the second variable as the dependent variable. Finally the results are printed.

Example program (C#): g02cae.cs

Example program data: g02cae.d

Example program results: g02cae.r

See Also

G02 Class
G02 Members


g02cb Method

[image]

NAG Library for .NET Release 2
G02..::g02cb Method
G02 Class See Also Send Feedback
g02cb performs a simple linear regression with no constant, with dependent variable y and independent variable x.

Syntax

C#
public static void g02cb(
    int n,
    double[] x,
    double[] y,
    double[] result,
    out int ifail
)
Visual Basic
Public Shared Sub g02cb ( _
    n As Integer, _
    x As Double(), _
    y As Double(), _
    result As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02cb(
    int n,
    array<double>^ x,
    array<double>^ y,
    array<double>^ result,
    [OutAttribute] int% ifail
)
F#
static member g02cb :
        n : int *
        x : float[] *
        y : float[] *
        result : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of pairs of observations.
Constraint: n>2.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x[i-1] must contain xi, for i=1,2,…,n.
y
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: y[i-1] must contain yi, for i=1,2,…,n.
result
Type: array< System..::..Double >[]()[][]
An array of size [20]
On exit: the following information:
result[0] | x-, the mean value of the independent variable, x;
result[1] | y-, the mean value of the dependent variable, y;
result[2] | sx, the standard deviation of the independent variable, x;
result[3] | sy, the standard deviation of the dependent variable, y;
result[4] | r, the Pearson product-moment correlation between the independent variable x and the dependent variable y;
result[5] | b, the regression coefficient;
result[6] | the value 0.0;
result[7] | se b, the standard error of the regression coefficient;
result[8] | the value 0.0;
result[9] | t b, the t value for the regression coefficient;
result[10] | the value 0.0;
result[11] | SSR, the sum of squares attributable to the regression;
result[12] | DFR, the degrees of freedom attributable to the regression;
result[13] | MSR, the mean square attributable to the regression;
result[14] | F, the F value for the analysis of variance;
result[15] | SSD, the sum of squares of deviations about the regression;
result[16] | DFD, the degrees of freedom of deviations about the regression;
result[17] | MSD, the mean square of deviations about the regression;
result[18] | SST, the total sum of squares;
result[19] | DFT, the total degrees of freedom.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g02cb fits a straight line of the form
y=bx
to the data points
x 1,y 1,x 2,y 2,…,xn,yn,
such that
yi=b xi+ei,  i=1,2,…,n n≥2.
The method calculates the regression coefficient, b, and the various other statistical quantities by minimizing
∑i=1 n ei 2.
The input data consists of the n pairs of observations x 1,y 1,x 2,y 2,…,xn,yn on the independent variable x and the dependent variable y.
The quantities calculated are:
(a) Means:
x-=1 n∑i=1 n xi;  y-=1 n∑i=1 n yi.
(b) Standard deviations:
sx=1 n-1∑i=1 n xi-x-2;  sy=1 n-1∑i=1 n yi-y-2.
(c) Pearson product-moment correlation coefficient:
r=∑i=1 n xi-x-yi-y-∑i=1 n xi-x-2∑i=1 n yi-y-2.
(d) The regression coefficient, b:
b=∑i=1 n xiyi∑i=1 n xi 2.
(e) The sum of squares attributable to the regression, SSR, the sum of squares of deviations about the regression, SSD, and the total sum of squares, SST:
SST=∑i=1 n yi 2;  SSD=∑i=1 n yi-b xi 2,  SSR=SST-SSD.
(f) The degrees of freedom attributable to the regression, DFR, the degrees of freedom of deviations about the regression, DFD, and the total degrees of freedom, DFT:
DFT=n;  DFD=n-1,  DFR=1.
(g) The mean square attributable to the regression, MSR, and the mean square of deviations about the regression, MSD.
MSR=SSR/DFR;  MSD=SSD/DFD.
(h) The F value for the analysis of variance:
F=MSR/MSD.
(i) The standard error of the regression coefficient:
se b=MSD∑i=1 n xi 2.
(j) The t value for the regression coefficient:
t b=b se b.

References

Draper N R and Smith H (1985) Applied Regression Analysis (2nd Edition) Wiley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<2.
ifail=2
On entry, all n values of at least one of the variables x and y are identical.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

g02cb does not use additional precision arithmetic for the accumulation of scalar products, so there may be a loss of significant figures for large n.
If, in calculating F or t b (see [Description]), the numbers involved are such that the result would be outside the range of numbers which can be stored by the machine, then the answer is set to the largest quantity which can be stored as a real variable, by means of a call to x02al.

Parallelism and Performance

None.

Further Comments

Computation time depends on n.
g02cb uses a two-pass algorithm.

Example

This example reads in eight observations on each of two variables, and then performs a simple linear regression with no constant with the first variable as the independent variable, and the second variable as the dependent variable. Finally the results are printed.

Example program (C#): g02cbe.cs

Example program data: g02cbe.d

Example program results: g02cbe.r

See Also

G02 Class
G02 Members


g02cc Method

[image]

NAG Library for .NET Release 2
G02..::g02cc Method
G02 Class See Also Send Feedback
g02cc performs a simple linear regression with dependent variable y and independent variable x, omitting cases involving missing values.

Syntax

C#
public static void g02cc(
    int n,
    double[] x,
    double[] y,
    double xmiss,
    double ymiss,
    double[] result,
    out int ifail
)
Visual Basic
Public Shared Sub g02cc ( _
    n As Integer, _
    x As Double(), _
    y As Double(), _
    xmiss As Double, _
    ymiss As Double, _
    result As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02cc(
    int n,
    array<double>^ x,
    array<double>^ y,
    double xmiss,
    double ymiss,
    array<double>^ result,
    [OutAttribute] int% ifail
)
F#
static member g02cc :
        n : int *
        x : float[] *
        y : float[] *
        xmiss : float *
        ymiss : float *
        result : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of pairs of observations.
Constraint: n>2.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x[i-1] must contain xi, for i=1,2,…,n.
y
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: y[i-1] must contain yi, for i=1,2,…,n.
xmiss
Type: System..::..Double
On entry: the value xm which is to be taken as the missing value for the variable x. See [Accuracy].
ymiss
Type: System..::..Double
On entry: the value ym which is to be taken as the missing value for the variable y. See [Accuracy].
result
Type: array< System..::..Double >[]()[][]
An array of size [21]
On exit: the following information:
result[0] | x-, the mean value of the independent variable, x;
result[1] | y-, the mean value of the dependent variable, y;
result[2] | sx, the standard deviation of the independent variable, x;
result[3] | sy, the standard deviation of the dependent variable, y;
result[4] | r, the Pearson product-moment correlation between the independent variable x and the dependent variable y
result[5] | b, the regression coefficient;
result[6] | a, the regression constant;
result[7] | se b, the standard error of the regression coefficient;
result[8] | se a, the standard error of the regression constant;
result[9] | t b, the t value for the regression coefficient;
result[10] | t a, the t value for the regression constant;
result[11] | SSR, the sum of squares attributable to the regression;
result[12] | DFR, the degrees of freedom attributable to the regression;
result[13] | MSR, the mean square attributable to the regression;
result[14] | F, the F value for the analysis of variance;
result[15] | SSD, the sum of squares of deviations about the regression;
result[16] | DFD, the degrees of freedom of deviations about the regression;
result[17] | MSD, the mean square of deviations about the regression;
result[18] | SST, the total sum of squares;
result[19] | DFT, the total degrees of freedom;
result[20] | nc, the number of observations used in the calculations.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g02cc fits a straight line of the form
y=a+bx
to those of the data points
x 1,y 1,x 2,y 2,…,xn,yn
that do not include missing values, such that
yi=a+b xi+ei
for those xi,yi, i=1,2,…,n n>2 which do not include missing values.
The method eliminates all pairs of observations xi,yi which contain a missing value for either x or y, and then calculates the regression coefficient, b, the regression constant, a, and various other statistical quantities, by minimizing the sum of the ei 2 over those cases remaining in the calculations.
The input data consists of the n pairs of observations x 1,y 1,x 2,y 2,…,xn,yn on the independent variable x and the dependent variable y.
In addition two values, xm and ym, are given which are considered to represent missing observations for x and y respectively. (See [Accuracy]).
Let wi=0 if the ith observation of either x or y is missing, i.e., if xi=xm and/or yi=ym; and wi=1 otherwise, for i=1,2,…,n.
The quantities calculated are:
(a) Means:
x-=∑i=1 n wixi∑i=1 n wi;  y-=∑i=1 n wiyi∑i=1 n wi.
(b) Standard deviations:
sx=∑i=1 n wi xi-x-2∑i=1 n wi-1;  sy=∑i=1 n wi yi-y-2∑i=1 n wi-1.
(c) Pearson product-moment correlation coefficient:
r=∑i=1 n wi xi-x-yi-y-∑i=1 n wi xi-x-2∑i=1 n wi yi-y-2.
(d) The regression coefficient, b, and the regression constant, a:
b=∑i=1 n wi xi-x-yi-y-∑i=1 n wi xi-x-2,  a=y--b x-.
(e) The sum of squares attributable to the regression, SSR, the sum of squares of deviations about the regression, SSD, and the total sum of squares, SST:
SST=∑i=1 n wi yi-y-2;  SSD=∑i=1 n wi yi-a-b xi 2;  SSR=SST-SSD.
(f) The degrees of freedom attributable to the regression, DFR, the degrees of freedom of deviations about the regression, DFD, and the total degrees of freedom, DFT:
DFT=∑i=1 n wi-1;  DFD=∑i=1 n wi-2;  DFR=1.
(g) The mean square attributable to the regression, MSR, and the mean square of deviations about the regression, MSD:
MSR=SSR/DFR;  MSD=SSD/DFD.
(h) The F value for the analysis of variance:
F=MSR/MSD.
(i) The standard error of the regression coefficient, se b, and the standard error of the regression constant, se a:
se b=MSD∑i=1 n wi xi-x-2;  se a=MSD 1∑i=1 n wi+x-2∑i=1 n wi xi-x-2.
(j) The t value for the regression coefficient, t b, and the t value for the regression constant, t a:
t b=b se b;  t a=a se a.
(k) The number of observations used in the calculations:
nc=∑i=1 n wi.

References

Draper N R and Smith H (1985) Applied Regression Analysis (2nd Edition) Wiley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n≤2.
ifail=2
After observations with missing values were omitted, two or fewer cases remained.
ifail=3
After observations with missing values were omitted, all remaining values of at least one of the variables x and y were identical.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

g02cc does not use additional precision arithmetic for the accumulation of scalar products, so there may be a loss of significant figures for large n.
You are warned of the need to exercise extreme care in your selection of missing values. g02cc treats all values in the inclusive range 1±0.1 x02be-2×xm j, where xm j is the missing value for variable j specified in xmiss.
You must therefore ensure that the missing value chosen for each variable is sufficiently different from all valid values for that variable so that none of the valid values fall within the range indicated above.
If, in calculating F or t a (see [Description]), the numbers involved are such that the result would be outside the range of numbers which can be stored by the machine, then the answer is set to the largest quantity which can be stored as a real variable, by means of a call to x02al.

Parallelism and Performance

None.

Further Comments

The time taken by g02cc depends on n and the number of missing observations.
The method uses a two-pass algorithm.

Example

This example reads in eight observations on each of two variables, and then performs a simple linear regression with the first variable as the independent variable, and the second variable as the dependent variable, omitting cases involving missing values (0.0 for the first variable, 99.0 for the second). Finally the results are printed.

Example program (C#): g02cce.cs

Example program data: g02cce.d

Example program results: g02cce.r

See Also

G02 Class
G02 Members


g02cd Method

[image]

NAG Library for .NET Release 2
G02..::g02cd Method
G02 Class See Also Send Feedback
g02cd performs a simple linear regression with no constant, with dependent variable y and independent variable x, omitting cases involving missing values.

Syntax

C#
public static void g02cd(
    int n,
    double[] x,
    double[] y,
    double xmiss,
    double ymiss,
    double[] result,
    out int ifail
)
Visual Basic
Public Shared Sub g02cd ( _
    n As Integer, _
    x As Double(), _
    y As Double(), _
    xmiss As Double, _
    ymiss As Double, _
    result As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02cd(
    int n,
    array<double>^ x,
    array<double>^ y,
    double xmiss,
    double ymiss,
    array<double>^ result,
    [OutAttribute] int% ifail
)
F#
static member g02cd :
        n : int *
        x : float[] *
        y : float[] *
        xmiss : float *
        ymiss : float *
        result : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of pairs of observations.
Constraint: n≥2.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x[i-1] must contain xi, for i=1,2,…,n.
y
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: y[i-1] must contain yi, for i=1,2,…,n.
xmiss
Type: System..::..Double
On entry: the value xm, which is to be taken as the missing value for the variable x (see [Accuracy]).
ymiss
Type: System..::..Double
On entry: the value ym, which is to be taken as the missing value for the variable y (see [Accuracy]).
result
Type: array< System..::..Double >[]()[][]
An array of size [21]
On exit: the following information:
result[0] | x-, the mean value of the independent variable, x;
result[1] | y-, the mean value of the dependent variable, y;
result[2] | sx, the standard deviation of the independent variable, x;
result[3] | sy, the standard deviation of the dependent variable, y;
result[4] | r, the Pearson product-moment correlation between the independent variable x and the dependent variable, y;
result[5] | b, the regression coefficient;
result[6] | the value 0.0;
result[7] | se b, the standard error of the regression coefficient;
result[8] | the value 0.0;
result[9] | t b, the t value for the regression coefficient;
result[10] | the value 0.0;
result[11] | SSR, the sum of squares attributable to the regression;
result[12] | DFR, the degrees of freedom attributable to the regression;
result[13] | MSR, the mean square attributable to the regression;
result[14] | F, the F value for the analysis of variance;
result[15] | SSD, the sum of squares of deviations about the regression;
result[16] | DFD, the degrees of freedom of deviations about the regression;
result[17] | MSD, the mean square of deviations about the regression;
result[18] | SST, the total sum of squares
result[19] | DFT, the total degrees of freedom;
result[20] | nc, the number of observations used in the calculations.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g02cd fits a straight line of the form
y=bx
to those of the data points
x 1,y 1,x 2,y 2,…,xn,yn
that do not include missing values, such that
yi=b xi+ei
for those xi,yi, for i=1,2,…,n n≥2 which do not include missing values.
The method eliminates all pairs of observations xi,yi which contain a missing value for either x or y, and then calculates the regression coefficient, b, and various other statistical quantities by minimizing the sum of the ei 2 over those cases remaining in the calculations.
The input data consists of the n pairs of observations x 1,y 1,x 2,y 2,…,xn,yn on the independent variable x and the dependent variable y.
In addition two values, xm and ym, are given which are considered to represent missing observations for x and y respectively. (See [Accuracy]).
Let wi=0, if the ith observation of either x or y is missing, i.e., if xi=xm and/or yi=ym; and wi=1 otherwise, for i=1,2,…,n.
The quantities calculated are:
(a) Means:
x-=∑i=1 n wixi∑i=1 n wi;  y-=∑i=1 n wiyi∑i=1 n wi.
(b) Standard deviations:
sx=∑i=1 n wi xi-x-2∑i=1 n wi-1;  sy=∑i=1 n wi yi-y-2∑i=1 n wi-1.
(c) Pearson product-moment correlation coefficient:
r=∑i=1 n wi xi-x-yi-y-∑i=1 n wi xi-x-2∑i=1 n wi yi-y-2.
(d) The regression coefficient, b:
b=∑i=1 n wixiyi∑i=1 n wi xi 2.
(e) The sum of squares attributable to the regression, SSR, the sum of squares of deviations about the regression, SSD, and the total sum of squares, SST:
SST=∑i=1 n wi yi 2;  SSD=∑i=1 n wi yi-b xi 2;  SSR=SST-SSD.
(f) The degrees of freedom attributable to the regression, DFR, the degrees of freedom of deviations about the regression, DFD, and the total degrees of freedom, DFT:
DFT=∑i=1 n wi;  DFD=∑i=1 n wi-1;  DFR=1.
(g) The mean square attributable to the regression, MSR, and the mean square of deviations about the regression, MSD:
MSR=SSR/DFR;  MSD=SSD/DFD.
(h) The F value for the analysis of variance:
F=MSR/MSD.
(i) The standard error of the regression coefficient:
se b=MSD∑i=1 n wi xi 2.
(j) The t value for the regression coefficient:
t b=b se b.
(k) The number of observations used in the calculations:
nc=∑i=1 n wi.

References

Draper N R and Smith H (1985) Applied Regression Analysis (2nd Edition) Wiley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<2.
ifail=2
After observations with missing values were omitted, fewer than two cases remained.
ifail=3
After observations with missing values were omitted, all remaining values of at least one of the variables x and y were identical.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

g02cd does not use additional precision arithmetic for the accumulation of scalar products, so there may be a loss of significant figures for large n.
You are warned of the need to exercise extreme care in your selection of missing values. g02cd treats all values in the inclusive range 1±0.1 x02be-2×xm j, where xm j is the missing value for variable j specified in xmiss.
You must therefore ensure that the missing value chosen for each variable is sufficiently different from all valid values for that variable so that none of the valid values fall within the range indicated above.
If, in calculating F or t b (see [Description]), the numbers involved are such that the result would be outside the range of numbers which can be stored by the machine, then the answer is set to the largest quantity which can be stored as a real variable, by means of a call to x02al.

Parallelism and Performance

None.

Further Comments

The time taken by g02cd depends on n and the number of missing observations.
The method uses a two-pass algorithm.

Example

This example reads in eight observations on each of two variables, and then performs a simple linear regression with no constant, with the first variable as the independent variable, and the second variable as the dependent variable, omitting cases involving missing values (0.0 for the first variable, 99.0 for the second). Finally the results are printed.

Example program (C#): g02cde.cs

Example program data: g02cde.d

Example program results: g02cde.r

See Also

G02 Class
G02 Members


g02ce Method

[image]

NAG Library for .NET Release 2
G02..::g02ce Method
G02 Class See Also Send Feedback
g02ce takes selected elements from two vectors (typically vectors of means and standard deviations) to form two smaller vectors, and selected rows and columns from two matrices (typically either matrices of sums of squares and cross-products of deviations from means and Pearson product-moment correlation coefficients, or matrices of sums of squares and cross-products about zero and correlation-like coefficients) to form two smaller matrices, allowing reordering of elements in the process.

Syntax

C#
public static void g02ce(
    int n,
    double[] xbar,
    double[] std,
    double[,] ssp,
    double[,] r,
    int m,
    int[] korder,
    double[] xbar2,
    double[] std2,
    double[,] ssp2,
    double[,] r2,
    out int ifail
)
Visual Basic
Public Shared Sub g02ce ( _
    n As Integer, _
    xbar As Double(), _
    std As Double(), _
    ssp As Double(,), _
    r As Double(,), _
    m As Integer, _
    korder As Integer(), _
    xbar2 As Double(), _
    std2 As Double(), _
    ssp2 As Double(,), _
    r2 As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02ce(
    int n,
    array<double>^ xbar,
    array<double>^ std,
    array<double,2>^ ssp,
    array<double,2>^ r,
    int m,
    array<int>^ korder,
    array<double>^ xbar2,
    array<double>^ std2,
    array<double,2>^ ssp2,
    array<double,2>^ r2,
    [OutAttribute] int% ifail
)
F#
static member g02ce :
        n : int *
        xbar : float[] *
        std : float[] *
        ssp : float[,] *
        r : float[,] *
        m : int *
        korder : int[] *
        xbar2 : float[] *
        std2 : float[] *
        ssp2 : float[,] *
        r2 : float[,] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of variables in the input data.
Constraint: n≥2.
xbar
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: xbar[i-1] must be set to x-i, the mean of variable i, for i=1,2,…,n.
std
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: std[i-1] must be set to si, the standard deviation of variable i, for i=1,2,…,n.
ssp
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: ssp[i-1,j-1] must be set to the sum of cross-products of deviations from means S ij (or about zero, S~ij) for variables i and j, for i=1,2,…,n and j=1,2,…,n.
r
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: r[i-1,j-1] must be set to the Pearson product-moment correlation coefficient R ij (or the correlation-like coefficient, R~ij) for variables i and j, for i=1,2,…,n and j=1,2,…,n.
m
Type: System..::..Int32
On entry: the number of variables m, required in the reduced vectors and matrices.
Constraint: 1≤m≤n.
korder
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: korder[i-1] must be set to the number of the original variable which is to be the ith variable in the output vectors and matrices, for i=1,2,…,m.
Constraint: 1≤korder[i]≤n, for i=0,1,…,m-1.
xbar2
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: the mean of variable i, xbar[i-1], where i=korder[k-1], for k=1,2,…,m. (The array xbar2 must differ from xbar and std.)
std2
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: the standard deviation of variable i, std[i-1], where i=korder[k-1], for k=1,2,…,m. (The array std2 must differ from both xbar and std.)
ssp2
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: ssp2[k-1,l-1] contains the value of ssp[i-1,j-1], where i=korder[k-1] and j=korder[l-1], for k=1,2,…,m and l=1,2,…,m. (The array ssp2 must differ from both ssp and r.)
That is to say: on exit, ssp2[k-1,l-1] contains the sum of cross-products of deviations from means S ij (or about zero, S~ij).
r2
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: r2[k-1,l-1] contains the value of r[i-1,j-1], where i=korder[k-1] and j=korder[l-1], for k=1,2,…,m and l=1,2,…,m. (The array r2 must differ from both ssp and r.)
That is to say: on exit, r2[k-1,l-1] contains the Pearson product-moment coefficient R ij (or the correlation-like coefficient, R~ij).
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Input to the method consists of:
(a) A vector of means:
x-1,x-2,x-3,…,x-n,
where n is the number of input variables.
(b) A vector of standard deviations:
s 1,s 2,s 3,…,sn.
(c) A matrix of sums of squares and cross-products of deviations from means:
S 11S 12S 13...S 1 nS 21S 22S 2 nS 31.......S n 1S n 2....S nn.
(d) A matrix of correlation coefficients:
R 11R 12R 13...R 1 nR 21R 22R 2 nR 31.......R n 1R n 2....R nn.
(e) The number of variables, m, in the required subset, and their row/column numbers in the input data, i 1,i 2,i 3,…,im,
i≤ik≤n  for k=1,2,…,m n≥2,m≥1 and m≤n.
New vectors and matrices are output containing the following information:
(i) A vector of means:
x-i 1,x-i 2,x-i 3,…,x-im.
(ii) A vector of standard deviations:
s i 1,s i 2,s i 3,…,s im.
(iii) A matrix of sums of squares and cross-products of deviations from means:
S i 1i 1S i 1i 2S i 1i 3...S i 1imS i 2i 1S i 2i 2.S i 3i 1.......S imi 1S imi 2....S imim.
(iv) A matrix of correlation coefficients:
R i 1i 1R i 1i 2R i 1i 3...R i 1imR i 2i 1R i 2i 2.R i 3i 1.......R imi 1R imi 2....R imim.
Note: for sums of squares of cross-products of deviations about zero and correlation-like coefficients S ij and R ij should be replaced by S~ij and R~ij in the description of the input and output above.

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDSSP, LDR, LDSSP2, LDR2) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | n<2,
or | m<1.
ifail=2
On entry, n<m.
ifail=4
On entry, | korder[i-1]<1,
or | korder[i-1]>n for some i=1,2,…,m.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

The time taken by g02ce depends on n and m.
The method is intended primarily for use when a subset of variables from a larger set of variables is to be used in a regression, and is described accordingly. There is however no reason why the method should not also be used to select specific rows and columns from vectors and arrays which contain any other non-statistical information; the matrices need not be symmetric.
The method may be used either with sums of squares and cross-products of deviations from means and Pearson product-moment correlation coefficients in connection with a regression involving a constant, or with sums of squares and cross-products about zero and correlation-like coefficients in connection with a regression with no constant.

Example

This example reads in the means, standard deviations, sums of squares and cross-products, and correlation coefficients for four variables. New vectors and matrices are created containing the means, standard deviations, sums of squares and cross-products, and correlation coefficients for the fourth, first and second variables (in that order). Finally these new vectors and matrices are printed.

Example program (C#): g02cee.cs

Example program data: g02cee.d

Example program results: g02cee.r

See Also

G02 Class
G02 Members


g02cf Method

[image]

NAG Library for .NET Release 2
G02..::g02cf Method
G02 Class See Also Send Feedback
g02cf reorders the elements in two vectors (typically vectors of means and standard deviations), and the rows and columns in two matrices (typically either matrices of sums of squares and cross-products of deviations from means and Pearson product-moment correlation coefficients, or matrices of sums of squares and cross-products about zero and correlation-like coefficients).

Syntax

C#
public static void g02cf(
    int n,
    int[] korder,
    double[] xbar,
    double[] std,
    double[,] ssp,
    double[,] r,
    out int ifail
)
Visual Basic
Public Shared Sub g02cf ( _
    n As Integer, _
    korder As Integer(), _
    xbar As Double(), _
    std As Double(), _
    ssp As Double(,), _
    r As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02cf(
    int n,
    array<int>^ korder,
    array<double>^ xbar,
    array<double>^ std,
    array<double,2>^ ssp,
    array<double,2>^ r,
    [OutAttribute] int% ifail
)
F#
static member g02cf :
        n : int *
        korder : int[] *
        xbar : float[] *
        std : float[] *
        ssp : float[,] *
        r : float[,] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of variables in the input data.
Constraint: n≥2.
korder
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On entry: korder[i-1] must be set to the number of the original variable which is to be the ith variable in the re-arranged data, for i=1,2,…,n.
Constraint: 1≤korder[i]≤n, for i=0,1,…,n-1.
xbar
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: xbar[i-1] must be set to the mean of variable i, for i=1,2,…,n.
On exit: xbar[i-1] contains the mean of variable k where k=korder[i-1], for i=1,2,…,n.
std
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: std[i-1] must be set to the standard deviation of variable i, for i=1,2,…,n.
On exit: std[i-1] contains the standard deviation of variable k where k=korder[i-1], for i=1,2,…,n.
ssp
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: ssp[i-1,j-1] must be set to the sum of cross-products of deviations from means S ij (or about zero S~ij) for variables i and j, for i=1,2,…,n and j=1,2,…,n.
On exit: ssp[i-1,j-1] contains the sum of cross-products of deviations from means S kl (or about zero S~kl) for variables k and l, where k=korder[i-1], and l=korder[j-1], i,j=1,2,…,n.
r
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: r[i-1,j-1] must be set to the Pearson product-moment correlation coefficient R ij (or the correlation-like coefficient R~ij) for variables i and j, for i=1,2,…,n and j=1,2,…,n.
On exit: r[i-1,j-1] contains the Pearson product-moment correlation coefficient R kl (or the correlation-like coefficient R~kl) for variables k and l, where k=korder[i-1] and l=korder[j-1], for i=1,2,…,n and j=1,2,…,n.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Input to the method consists of:
(a) A list of the order in which the n variables are to be arranged on exit:
i 1,i 2,i 3,…,in.
(b) A vector of means:
x-1,x-2,x-3,…,x-n.
(c) A vector of standard deviations:
s 1,s 2,s 3,…,sn.
(d) A matrix of sums of squares and cross-products of deviations from means:
S 11S 12S 13...S 1 nS 21S 22.S 31.......S n 1S n 2....S nn.
(e) A matrix of correlation coefficients:
R 11R 12R 13...R 1 nR 21R 22.R 31.......R n 1R n 2....R nn.
On exit from the method, these same vectors and matrices are reordered, in the manner specified, and contain the following information:
(i) The vector of means:
x-i 1,x-i 2,x-i 3,…,x-in.
(ii) The vector of standard deviations:
s i 1,s i 2,s i 3,…s in.
(iii) The matrix of sums of squares and cross-products of deviations from means:
S i 1i 1S i 1i 2S i 1i 3...S i 1inS i 2i 1S i 2i 2.S i 3i 1.......S ini 1S ini 2....S inin.
(iv) The matrix of correlation coefficients:
R i 1i 1R i 1i 2R i 1i 3...R i 1inR i 2i 1R i 2i 2.R i 3i 1.......R ini 1R ini 2....R inin.
Note: for sums of squares of cross-products of deviations about zero and correlation-like coefficients S ij and R ij should be replaced by S~ij and R~ij in the description of the input and output above.

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDSSP, LDR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, n<2.
ifail=3
On entry, | korder[i-1]<1,
or | korder[i-1]>n for some i=1,2,…,n.
ifail=4
On entry, there is not a one-to-one correspondence between the old variables and the new variables; at least one of the original variables is not included in the new set, and consequently at least one other variable has been included more than once.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

The time taken by g02cf depends on n and the amount of re-arrangement involved.
The method is intended primarily for use when a set of variables is to be reordered for use in a regression, and is described accordingly. There is however no reason why the method should not also be used to reorder vectors and matrices which contain any other non-statistical information; the matrices need not be symmetric.
The method may be used either with sums of squares and cross-products of deviations from means and Pearson product-moment correlation coefficients in connection with a regression involving a constant, or with sums of squares and cross-products about zero and correlation-like coefficients in connection with a regression with no constant.

Example

This example reads in the means, standard deviations, sums of squares and cross-products, and correlation coefficients for three variables. The vectors and matrices are reordered so that they contain the means, standard deviations, sums of squares and cross-products, and correlation coefficients for the first, third and second variables (in that order). Finally the reordered vectors and matrices are printed.

Example program (C#): g02cfe.cs

Example program data: g02cfe.d

Example program results: g02cfe.r

See Also

G02 Class
G02 Members


g02cg Method

[image]

NAG Library for .NET Release 2
G02..::g02cg Method
G02 Class See Also Send Feedback
g02cg performs a multiple linear regression on a set of variables whose means, sums of squares and cross-products of deviations from means, and Pearson product-moment correlation coefficients are given.

Syntax

C#
public static void g02cg(
    int n,
    int k1,
    int k,
    double[] xbar,
    double[,] ssp,
    double[,] r,
    double[] result,
    double[,] coef,
    double[] con,
    double[,] rinv,
    double[,] c,
    out int ifail
)
Visual Basic
Public Shared Sub g02cg ( _
    n As Integer, _
    k1 As Integer, _
    k As Integer, _
    xbar As Double(), _
    ssp As Double(,), _
    r As Double(,), _
    result As Double(), _
    coef As Double(,), _
    con As Double(), _
    rinv As Double(,), _
    c As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02cg(
    int n,
    int k1,
    int k,
    array<double>^ xbar,
    array<double,2>^ ssp,
    array<double,2>^ r,
    array<double>^ result,
    array<double,2>^ coef,
    array<double>^ con,
    array<double,2>^ rinv,
    array<double,2>^ c,
    [OutAttribute] int% ifail
)
F#
static member g02cg :
        n : int *
        k1 : int *
        k : int *
        xbar : float[] *
        ssp : float[,] *
        r : float[,] *
        result : float[] *
        coef : float[,] *
        con : float[] *
        rinv : float[,] *
        c : float[,] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: the number of cases n, used in calculating the sums of squares and cross-products and correlation coefficients.
k1
Type: System..::..Int32
On entry: the total number of variables, independent and dependent, k+1, in the regression.
Constraint: 2≤k1<n.
k
Type: System..::..Int32
On entry: the number of independent variables k in the regression.
Constraint: k=k1-1.
xbar
Type: array< System..::..Double >[]()[][]
An array of size [k1]
On entry: xbar[i-1] must be set to x-i, the mean value of the ith variable, for i=1,2,…,k+1; the mean of the dependent variable must be contained in xbar[k].
ssp
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, k1]
Note: dim1 must satisfy the constraint: dim1≥k1
On entry: ssp[i-1,j-1] must be set to S ij, the sum of cross-products of deviations from means for the ith and jth variables, for i=1,2,…,k+1 and j=1,2,…,k+1; terms involving the dependent variable appear in row k+1 and column k+1.
r
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, k1]
Note: dim1 must satisfy the constraint: dim1≥k1
On entry: r[i-1,j-1] must be set to R ij, the Pearson product-moment correlation coefficient for the ith and jth variables, for i=1,2,…,k+1 and j=1,2,…,k+1; terms involving the dependent variable appear in row k+1 and column k+1.
result
Type: array< System..::..Double >[]()[][]
An array of size [13]
On exit: the following information:
result[0] | SSR, the sum of squares attributable to the regression;
result[1] | DFR, the degrees of freedom attributable to the regression;
result[2] | MSR, the mean square attributable to the regression;
result[3] | F, the F value for the analysis of variance;
result[4] | SSD, the sum of squares of deviations about the regression;
result[5] | DFD, the degrees of freedom of deviations about the regression;
result[6] | MSD, the mean square of deviations about the regression;
result[7] | SST, the total sum of squares;
result[8] | DFT, the total degrees of freedom;
result[9] | s, the standard error estimate;
result[10] | R, the coefficient of multiple correlation;
result[11] | R 2, the coefficient of multiple determination;
result[12] | R-2, the coefficient of multiple determination corrected for the degrees of freedom.
coef
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, 3]
Note: dim1 must satisfy the constraint: dim1≥k
On exit: for i=1,2,…,k, the following information:
coef[i-1,0]
bi, the regression coefficient for the ith variable.
coef[i-1,1]
se bi, the standard error of the regression coefficient for the ith variable.
coef[i-1,2]
t bi, the t value of the regression coefficient for the ith variable.
con
Type: array< System..::..Double >[]()[][]
An array of size [3]
On exit: the following information:
con[0] | a, the regression constant;
con[1] | se a, the standard error of the regression constant;
con[2] | t a, the t value for the regression constant.
rinv
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, k]
Note: dim1 must satisfy the constraint: dim1≥k
On exit: the inverse of the matrix of correlation coefficients for the independent variables; that is, the inverse of the matrix consisting of the first k rows and columns of r.
c
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, k]
Note: dim1 must satisfy the constraint: dim1≥k
On exit: the modified inverse matrix, where
  • c[i-1,j-1]=r[i-1,j-1]×rinv[i-1,j-1]/ssp[i-1,j-1], for i=1,2,…,k and j=1,2,…,k.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g02cg fits a curve of the form
y=a+b 1x 1+b 2x 2+⋯+bkxk
to the data points
x 11,x 21,…,x k 1,y 1x 12,x 22,…,x k 2,y 2⋮x 1 n,x 2 n,…,x kn,yn
such that
yi=a+b 1x 1 i+b 2x 2 i+⋯+bkx ki+ei,  i=1,2,…,n.
The method calculates the regression coefficients, b 1,b 2,…,bk, the regression constant, a, and various other statistical quantities by minimizing
∑i=1 n ei 2.
The actual data values x 1 i,x 2 i,…,x ki,yi are not provided as input to the method. Instead, input consists of:
(i) | The number of cases, n, on which the regression is based.
(ii) | The total number of variables, dependent and independent, in the regression, k+1.
(iii) | The number of independent variables in the regression, k.
(iv) | The means of all k+1 variables in the regression, both the independent variables x 1,x 2,…,xk and the dependent variable y, which is the k+1th variable: i.e., x-1,x-2,…,x-k,y-.
(v) | The k+1 by k+1 matrix [S ij] of sums of squares and cross-products of deviations from means of all the variables in the regression; the terms involving the dependent variable, y, appear in the k+1th row and column.
(vi) | The k+1 by k+1 matrix [R ij] of the Pearson product-moment correlation coefficients for all the variables in the regression; the correlations involving the dependent variable, y, appear in the k+1th row and column.
The quantities calculated are:
(a) The inverse of the k by k partition of the matrix of correlation coefficients, [R ij], involving only the independent variables. The inverse is obtained using an accurate method which assumes that this sub-matrix is positive definite.
(b) The modified inverse matrix, C=c ij, where
c ij=R ijr ij S ij,  i,j=1,2,…,k,
where r ij is the i,jth element of the inverse matrix of [R ij] as described in (a) above. Each element of C is thus the corresponding element of the matrix of correlation coefficients multiplied by the corresponding element of the inverse of this matrix, divided by the corresponding element of the matrix of sums of squares and cross-products of deviations from means.
(c) The regression coefficients:
bi=∑j=i k c ijS j k+1,  i=1,2,…,k,
where S j k+1 is the sum of cross-products of deviations from means for the independent variable xj and the dependent variable y.
(d) The sum of squares attributable to the regression, SSR, the sum of squares of deviations about the regression, SSD, and the total sum of squares, SST:
  • SST=S k+1k+1, the sum of squares of deviations from the mean for the dependent variable, y;
  • SSR=∑j=1 k bjS j k+1;  SSD=SST-SSR
(e) The degrees of freedom attributable to the regression, DFR, the degrees of freedom of deviations about the regression, DFD, and the total degrees of freedom, DFT:
DFR=k;  DFD=n-k-1;  DFT=n-1.
(f) The mean square attributable to the regression, MSR, and the mean square of deviations about the regression, MSD:
MSR=SSR/DFR;  MSD=SSD/DFD.
(g) The F values for the analysis of variance:
F=MSR/MSD.
(h) The standard error estimate:
s=MSD.
(i) The coefficient of multiple correlation, R, the coefficient of multiple determination, R 2 and the coefficient of multiple determination corrected for the degrees of freedom, R-2;
R=1-SSDSST;  R 2=1-SSDSST;  R-2=1-SSD×DFTSST×DFD.
(j) The standard error of the regression coefficients:
se bi=MSD×c ii,  i=1,2,…,k.
(k) The t values for the regression coefficients:
t bi=bise bi,  i=1,2,…,k.
(l) The regression constant, a, its standard error, se a, and its t value, t a:
a=y--∑i=1 k bix-i;  se a=MSD×1 n+∑i=1 k∑j=1 k x-ic ijx-j;  t a=a se a.

References

Draper N R and Smith H (1985) Applied Regression Analysis (2nd Edition) Wiley

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDSSP, LDR, LDCOEF, LDRINV, LDC) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, k1<2.
ifail=2
On entry, k1≠k+1.
ifail=3
On entry, n≤k1.
ifail=4
On entry, ldwkz<k.
ifail=5
The k by k partition of the matrix R which is to be inverted is not positive definite.
ifail=6
The refinement following the actual inversion fails, indicating that the k by k partition of the matrix R, which is to be inverted, is ill-conditioned. The use of g02da, which employs a different numerical technique, may avoid this difficulty (an extra ‘variable’ representing the constant term must be introduced for g02da).
ifail=7
Unexpected error in (F04ABF not in this release).
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The accuracy of any regression method is almost entirely dependent on the accuracy of the matrix inversion method used. In g02cg, it is the matrix of correlation coefficients rather than that of the sums of squares and cross-products of deviations from means that is inverted; this means that all terms in the matrix for inversion are of a similar order, and reduces the scope for computational error. For details on absolute accuracy, the relevant section of the document describing the inversion method used, (F04ABF not in this release), should be consulted. g02da uses a different method, based on (F04AMF not in this release), and that method may well prove more reliable numerically. It does not handle missing values, nor does it provide the same output as this method. (In particular it is necessary to include explicitly the constant in the regression equation as another ‘variable’.)
If, in calculating F, t a, or any of the t bi (see [Description]), the numbers involved are such that the result would be outside the range of numbers which can be stored by the machine, then the answer is set to the largest quantity which can be stored as a real variable, by means of a call to x02al.

Parallelism and Performance

None.

Further Comments

The time taken by g02cg depends on k.
This method assumes that the matrix of correlation coefficients for the independent variables in the regression is positive definite; it fails if this is not the case.
This correlation matrix will in fact be positive definite whenever the correlation matrix and the sums of squares and cross-products (of deviations from means) matrix have been formed either without regard to missing values, or by eliminating completely any cases involving missing values, for any variable. If, however, these matrices are formed by eliminating cases with missing values from only those calculations involving the variables for which the values are missing, no such statement can be made, and the correlation matrix may or may not be positive definite. You should be aware of the possible dangers of using correlation matrices formed in this way (see the G02 class), but if they nevertheless wish to carry out regression using such matrices, this method is capable of handling the inversion of such matrices provided they are positive definite.
If a matrix is positive definite, its subsequent re-organisation by either g02ce or g02cf will not affect this property, and the new matrix can safely be used in this method. Thus correlation matrices produced by any of g02ba, g02bb, g02bg or g02bh, even if subsequently modified by either g02ce or g02cf, can be handled by this method.
It should be noted that in forming the sums of squares and cross-products matrix and the correlation matrix a column of constants should not be added to the data as an additional ‘variable’ in order to obtain a constant term in the regression. This method automatically calculates the regression constant, a, and any attempt to insert such a ‘dummy variable’ is likely to cause the method to fail.
It should also be noted that the method requires the dependent variable to be the last of the k+1 variables whose statistics are provided as input to the method. If this variable is not correctly positioned in the original data, the means, standard deviations, sums of squares and cross-products of deviations from means, and correlation coefficients can be manipulated by using g02ce or g02cf to reorder the variables as necessary.

Example

This example reads in the means, sums of squares and cross-products of deviations from means, and correlation coefficients for three variables. A multiple linear regression is then performed with the third and final variable as the dependent variable. Finally the results are printed.

Example program (C#): g02cge.cs

Example program data: g02cge.d

Example program results: g02cge.r

See Also

G02 Class
G02 Members


g02ch Method

[image]

NAG Library for .NET Release 2
G02..::g02ch Method
G02 Class See Also Send Feedback
g02ch performs a multiple linear regression with no constant on a set of variables whose sums of squares and cross-products about zero and correlation-like coefficients are given.

Syntax

C#
public static void g02ch(
    int n,
    int k1,
    int k,
    double[,] sspz,
    double[,] rz,
    double[] result,
    double[,] coef,
    double[,] rznv,
    double[,] cz,
    out int ifail
)
Visual Basic
Public Shared Sub g02ch ( _
    n As Integer, _
    k1 As Integer, _
    k As Integer, _
    sspz As Double(,), _
    rz As Double(,), _
    result As Double(), _
    coef As Double(,), _
    rznv As Double(,), _
    cz As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02ch(
    int n,
    int k1,
    int k,
    array<double,2>^ sspz,
    array<double,2>^ rz,
    array<double>^ result,
    array<double,2>^ coef,
    array<double,2>^ rznv,
    array<double,2>^ cz,
    [OutAttribute] int% ifail
)
F#
static member g02ch :
        n : int *
        k1 : int *
        k : int *
        sspz : float[,] *
        rz : float[,] *
        result : float[] *
        coef : float[,] *
        rznv : float[,] *
        cz : float[,] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of cases used in calculating the sums of squares and cross-products and correlation-like coefficients.
k1
Type: System..::..Int32
On entry: the total number of variables, independent and dependent k+1, in the regression.
Constraint: 2≤k1≤n.
k
Type: System..::..Int32
On entry: the number of independent variables k in the regression.
Constraint: k=k1-1.
sspz
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, k1]
Note: dim1 must satisfy the constraint: dim1≥k1
On entry: sspz[i-1,j-1] must be set to S~ij, the sum of cross-products about zero for the ith and jth variables, for i=1,2,…,k+1 and j=1,2,…,k+1; terms involving the dependent variable appear in row k+1 and column k+1.
rz
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, k1]
Note: dim1 must satisfy the constraint: dim1≥k1
On entry: rz[i-1,j-1] must be set to R~ij, the correlation-like coefficient for the ith and jth variables, for i=1,2,…,k+1 and j=1,2,…,k+1; coefficients involving the dependent variable appear in row k+1 and column k+1.
result
Type: array< System..::..Double >[]()[][]
An array of size [13]
On exit: the following information:
result[0] | SSR, the sum of squares attributable to the regression;
result[1] | DFR, the degrees of freedom attributable to the regression;
result[2] | MSR, the mean square attributable to the regression;
result[3] | F, the F value for the analysis of variance;
result[4] | SSD, the sum of squares of deviations about the regression;
result[5] | DFD, the degrees of freedom of deviations about the regression;
result[6] | MSD, the mean square of deviations about the regression;
result[7] | SST, the total sum of squares;
result[8] | DFT, the total degrees of freedom;
result[9] | s, the standard error estimate;
result[10] | R, the coefficient of multiple correlation;
result[11] | R 2, the coefficient of multiple determination;
result[12] | R-2, the coefficient of multiple determination corrected for the degrees of freedom.
coef
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, 3]
Note: dim1 must satisfy the constraint: dim1≥k
On exit: for i=1,2,…,k, the following information:
coef[i-1,0]
bi, the regression coefficient for the ith variable.
coef[i-1,1]
se bi, the standard error of the regression coefficient for the ith variable.
coef[i-1,2]
t bi, the t value of the regression coefficient for the ith variable.
rznv
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, k]
Note: dim1 must satisfy the constraint: dim1≥k
On exit: the inverse of the matrix of correlation-like coefficients for the independent variables; that is, the inverse of the matrix consisting of the first k rows and columns of rz.
cz
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, k]
Note: dim1 must satisfy the constraint: dim1≥k
On exit: the modified inverse matrix, C, where
cz[i-1,j-1]=rz[i-1,j-1]×rznv[i-1,j-1]sspz[i-1,j-1],  i,j=1,2,…,k.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g02ch fits a curve of the form
y=b 1x 1+b 2x 2+⋯+bkxk
to the data points
x 11,x 21,…,x k 1,y 1x 12,x 22,…,x k 2,y 2⋮x 1 n,x 2 n,…,x kn,yn
such that
yi=b 1x 1 i+b 2x 2 i+⋯+bkx ki+ei,  i=1,2,…,n.
The method calculates the regression coefficients, b 1,b 2,…,bk, (and various other statistical quantities) by minimizing
∑i=1 n ei 2.
The actual data values x 1 i,x 2 i,…,x ki,yi are not provided as input to the method. Instead, input to the method consists of:
(i) | The number of cases, n, on which the regression is based.
(ii) | The total number of variables, dependent and independent, in the regression, k+1.
(iii) | The number of independent variables in the regression, k.
(iv) | The k+1 by k+1 matrix S~ij of sums of squares and cross-products about zero of all the variables in the regression; the terms involving the dependent variable, y, appear in the k+1th row and column.
(v) | The k+1 by k+1 matrix R~ij of correlation-like coefficients for all the variables in the regression; the correlations involving the dependent variable, y, appear in the k+1th row and column.
The quantities calculated are:
(a) The inverse of the k by k partition of the matrix of correlation-like coefficients, R~ij, involving only the independent variables. The inverse is obtained using an accurate method which assumes that this sub-matrix is positive definite (see [Further Comments]).
(b) The modified matrix, C=c ij, where
c ij=R~ij r~ij S~ij,  i,j=1,2,…,k,
where r~ij is the i,jth element of the inverse matrix of R~ij as described in (a) above. Each element of C is thus the corresponding element of the matrix of correlation-like coefficients multiplied by the corresponding element of the inverse of this matrix, divided by the corresponding element of the matrix of sums of squares and cross-products about zero.
(c) The regression coefficients:
bi=∑j=1 k c ijS~j k+1,  i=1,2,…,k,
where S~j k+1 is the sum of cross-products about zero for the independent variable xj and the dependent variable y.
(d) The sum of squares attributable to the regression, SSR, the sum of squares of deviations about the regression, SSD, and the total sum of squares, SST:
  • SST=S~k+1k+1, the sum of squares about zero for the dependent variable, y;
  • SSR=∑j=1 k bjS~j k+1;  SSD=SST-SSR.
(e) The degrees of freedom attributable to the regression, DFR, the degrees of freedom of deviations about the regression, DFD, and the total degrees of freedom, DFT:
DFR=k;  DFD=n-k;  DFT=n.
(f) The mean square attributable to the regression, MSR, and the mean square of deviations about the regression, MSD:
MSR=SSR/DFR;  MSD=SSD/DFD.
(g) The F value for the analysis of variance:
F=MSR/MSD.
(h) The standard error estimate:
s=MSD.
(i) The coefficient of multiple correlation, R, the coefficient of multiple determination, R 2, and the coefficient of multiple determination corrected for the degrees of freedom, R-2:
R=1-SSDSST;  R 2=1-SSDSST;  R-2=1-SSD×DFTSST×DFD.
(j) The standard error of the regression coefficients:
se bi=MSD×c ii,  i=1,2,…,k.
(k) The t values for the regression coefficients:
t bi=bise bi,  i=1,2,…,k.

References

Draper N R and Smith H (1985) Applied Regression Analysis (2nd Edition) Wiley

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDSSPZ, LDRZ, LDCOEF, LDRZNV, LDCZ) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, k1<2.
ifail=2
On entry, k1≠k+1.
ifail=3
On entry, n<k1.
ifail=4
On entry, ldwkz<k.
ifail=5
This indicates that the k by k partition of the matrix held in rz, which is to be inverted, is not positive definite.
ifail=6
This indicates that the refinement following the actual inversion fails, indicating that the k by k partition of the matrix held in rz, which is to be inverted, is ill-conditioned. The use of g02da, which employs a different numerical technique, may avoid the difficulty.
ifail=7
Unexpected error in (F04ABF not in this release).
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The accuracy of any regression method is almost entirely dependent on the accuracy of the matrix inversion method used. In g02ch, it is the matrix of correlation-like coefficients rather than that of the sums of squares and cross-products about zero that is inverted; this means that all terms in the matrix for inversion are of a similar order, and reduces the scope for computational error. For details on absolute accuracy, the relevant section of the document describing the inversion method used, (F04ABF not in this release), should be consulted. g02da uses a different method, based on (F04AMF not in this release), and that method may well prove more reliable numerically. It does not handle missing values, nor does it provide the same output as this method.
If, in calculating F or any of the t bi (see [Description]), the numbers involved are such that the result would be outside the range of numbers which can be stored by the machine, then the answer is set to the largest quantity which can be stored as a real variable, by means of a call to x02al.

Parallelism and Performance

None.

Further Comments

The time taken by g02ch depends on k.
This method assumes that the matrix of correlation-like coefficients for the independent variables in the regression is positive definite; it fails if this is not the case.
This correlation matrix will in fact be positive definite whenever the correlation-like matrix and the sums of squares and cross-products (about zero) matrix have been formed either without regard to missing values, or by eliminating completely any cases involving missing values for any variable. If, however, these matrices are formed by eliminating cases with missing values from only those calculations involving the variables for which the values are missing, no such statement can be made, and the correlation-like matrix may or may not be positive definite. You should be aware of the possible dangers of using correlation matrices formed in this way (see the G02 class), but if they nevertheless wish to carry out regressions using such matrices, this method is capable of handling the inversion of such matrices, provided they are positive definite.
If a matrix is positive definite, its subsequent re-organisation by either of g02ce or g02cf will not affect this property and the new matrix can safely be used in this method. Thus correlation matrices produced by any of g02bd, g02be, g02bk or g02bl, even if subsequently modified by either g02ce or g02cf, can be handled by this method.
It should be noted that the method requires the dependent variable to be the last of the k+1 variables whose statistics are provided as input to the method. If this variable is not correctly positioned in the original data, the means, standard deviations, sums of squares and cross-products about zero, and correlation-like coefficients can be manipulated by using g02ce or g02cf to reorder the variables as necessary.

Example

This example reads in the sums of squares and cross-products about zero, and correlation-like coefficients for three variables. A multiple linear regression with no constant is then performed with the third and final variable as the dependent variable. Finally the results are printed.

Example program (C#): g02che.cs

Example program data: g02che.d

Example program results: g02che.r

See Also

G02 Class
G02 Members


g02da Method

[image]

NAG Library for .NET Release 2
G02..::g02da Method
G02 Class See Also Send Feedback
g02da performs a general multiple linear regression when the independent variables may be linearly dependent. Parameter estimates, standard errors, residuals and influence statistics are computed. g02da may be used to perform a weighted regression.

Syntax

C#
public static void g02da(
    string mean,
    string weight,
    int n,
    double[,] x,
    int m,
    int[] isx,
    int ip,
    double[] y,
    double[] wt,
    out double rss,
    out int idf,
    double[] b,
    double[] se,
    double[] cov,
    double[] res,
    double[] h,
    double[,] q,
    out bool svd,
    out int irank,
    double[] p,
    double tol,
    double[] wk,
    out int ifail
)
Visual Basic
Public Shared Sub g02da ( _
    mean As String, _
    weight As String, _
    n As Integer, _
    x As Double(,), _
    m As Integer, _
    isx As Integer(), _
    ip As Integer, _
    y As Double(), _
    wt As Double(), _
    <OutAttribute> ByRef rss As Double, _
    <OutAttribute> ByRef idf As Integer, _
    b As Double(), _
    se As Double(), _
    cov As Double(), _
    res As Double(), _
    h As Double(), _
    q As Double(,), _
    <OutAttribute> ByRef svd As Boolean, _
    <OutAttribute> ByRef irank As Integer, _
    p As Double(), _
    tol As Double, _
    wk As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02da(
    String^ mean,
    String^ weight,
    int n,
    array<double,2>^ x,
    int m,
    array<int>^ isx,
    int ip,
    array<double>^ y,
    array<double>^ wt,
    [OutAttribute] double% rss,
    [OutAttribute] int% idf,
    array<double>^ b,
    array<double>^ se,
    array<double>^ cov,
    array<double>^ res,
    array<double>^ h,
    array<double,2>^ q,
    [OutAttribute] bool% svd,
    [OutAttribute] int% irank,
    array<double>^ p,
    double tol,
    array<double>^ wk,
    [OutAttribute] int% ifail
)
F#
static member g02da :
        mean : string *
        weight : string *
        n : int *
        x : float[,] *
        m : int *
        isx : int[] *
        ip : int *
        y : float[] *
        wt : float[] *
        rss : float byref *
        idf : int byref *
        b : float[] *
        se : float[] *
        cov : float[] *
        res : float[] *
        h : float[] *
        q : float[,] *
        svd : bool byref *
        irank : int byref *
        p : float[] *
        tol : float *
        wk : float[] *
        ifail : int byref -> unit

Parameters

mean
Type: System..::..String
On entry: indicates if a mean term is to be included.
mean="M"
A mean term, intercept, will be included in the model.
mean="Z"
The model will pass through the origin, zero-point.
Constraint: mean="M" or "Z".
weight
Type: System..::..String
On entry: indicates if weights are to be used.
weight="U"
Least squares estimation is used.
weight="W"
Weighted least squares is used and weights must be supplied in array wt.
Constraint: weight="U" or "W".
n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n≥2.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must contain the ith observation for the jth independent variable, for i=1,2,…,n and j=1,2,…,m.
m
Type: System..::..Int32
On entry: m, the total number of independent variables in the dataset.
Constraint: m≥1.
isx
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: indicates which independent variables are to be included in the model.
isx[j-1]>0
The variable contained in the jth column of x is included in the regression model.
Constraints:
  • isx[j-1]≥0, for j=1,2,…,m;
  • if mean="M", exactly ip-1 values of isx must be >0;
  • if mean="Z", exactly ip values of isx must be >0.
ip
Type: System..::..Int32
On entry: the number of independent variables in the model, including the mean or intercept if present.
Constraints:
  • if mean="M", 1≤ip≤m+1;
  • if mean="Z", 1≤ip≤m;
  • otherwise 1≤ip≤n.
y
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: y, observations on the dependent variable.
wt
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array wt must be at least n if weight="W", and at least 1 otherwise.
On entry: if weight="W", wt must contain the weights to be used in the weighted regression.
If wt[i-1]=0.0, the ith observation is not included in the model, in which case the effective number of observations is the number of observations with nonzero weights. The values of res and h will be set to zero for observations with zero weights.
If weight="U", wt is not referenced and the effective number of observations is n.
Constraint: if weight="W", wt[i-1]≥0.0, for i=1,2,…,n.
rss
Type: System..::..Double %
On exit: the residual sum of squares for the regression.
idf
Type: System..::..Int32 %
On exit: the degrees of freedom associated with the residual sum of squares.
b
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On exit: b[i-1], i=1,2,…,ip contains the least squares estimates of the parameters of the regression model, β^.
If mean="M", b[0] will contain the estimate of the mean parameter and b[i] will contain the coefficient of the variable contained in column j of x, where isx[j-1] is the ith positive value in the array isx.
If mean="Z", b[i-1] will contain the coefficient of the variable contained in column j of x, where isx[j-1] is the ith positive value in the array isx.
se
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On exit: se[i-1], i=1,2,…,ip contains the standard errors of the ip parameter estimates given in b.
cov
Type: array< System..::..Double >[]()[][]
An array of size [ip×ip+1/2]
On exit: the first ip×ip+1/2 elements of cov contain the upper triangular part of the variance-covariance matrix of the ip parameter estimates given in b. They are stored packed by column, i.e., the covariance between the parameter estimate given in b[i-1] and the parameter estimate given in b[j-1], j≥i, is stored in cov[j×j-1/2+i-1].
res
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the (weighted) residuals, ri, for i=1,2,…,n.
h
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the diagonal elements of H, hi, for i=1,2,…,n.
q
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, ip+1]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: the results of the QR decomposition:
  • the first column of q contains c;
  • the upper triangular part of columns 2 to ip+1 contain the R matrix;
  • the strictly lower triangular part of columns 2 to ip+1 contain details of the Q matrix.
svd
Type: System..::..Boolean %
On exit: if a singular value decomposition has been performed then svd will be true, otherwise svd will be false.
irank
Type: System..::..Int32 %
On exit: the rank of the independent variables.
If svd=false, irank=ip.
If svd=true, irank is an estimate of the rank of the independent variables.
irank is calculated as the number of singular values greater that tol× (largest singular value). It is possible for the SVD to be carried out but irank to be returned as ip.
p
Type: array< System..::..Double >[]()[][]
An array of size [2×ip+ip×ip]
On exit: details of the QR decomposition and SVD if used.
If svd=false, only the first ip elements of p are used these will contain the zeta values for the QR decomposition (see (F08AEF not in this release) for details).
If svd=true, the first ip elements of p will contain the zeta values for the QR decomposition (see (F08AEF not in this release) for details) and the next ip elements of p contain singular values. The following ip by ip elements contain the matrix P* stored by columns.
tol
Type: System..::..Double
On entry: the value of tol is used to decide if the independent variables are of full rank and if not what is the rank of the independent variables. The smaller the value of tol the stricter the criterion for selecting the singular value decomposition. If tol=0.0, the singular value decomposition will never be used; this may cause run time errors or inaccurate results if the independent variables are not of full rank.
Suggested value: tol=0.000001.
Constraint: tol≥0.0.
wk
Type: array< System..::..Double >[]()[][]
An array of size [max 2,5×ip-1+ip×ip]
On exit: if on exit svd=true, wk contains information which is needed by g02dg; otherwise wk is used as workspace.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The general linear regression model is defined by
y=Xβ+ε,
where
  • y is a vector of n observations on the dependent variable,
  • X is an n by p matrix of the independent variables of column rank k,
  • β is a vector of length p of unknown parameters, and
  • ε is a vector of length n of unknown random errors such that var ε=V σ 2, where V is a known diagonal matrix.
If V=I, the identity matrix, then least squares estimation is used. If V≠I, then for a given weight matrix W∝V-1, weighted least squares estimation is used.
The least squares estimates β^ of the parameters β minimize y-Xβ T y-Xβ while the weighted least squares estimates minimize y-Xβ T W y-Xβ.
g02da finds a QR decomposition of X (or W 1/2 X in weighted case), i.e.,
X=Q R* or  W 1/2 X=Q R*,
where R*=R0 and R is a p by p upper triangular matrix and Q is an n by n orthogonal matrix. If R is of full rank, then β^ is the solution to
R β^=c 1,
where c=QT y (or QTW 1/2 y) and c 1 is the first p elements of c. If R is not of full rank a solution is obtained by means of a singular value decomposition (SVD) of R,
R=Q*D000 PT,
where D is a k by k diagonal matrix with nonzero diagonal elements, k being the rank of R, and Q* and P are p by p orthogonal matrices. This gives the solution
β^=P 1 D-1 Q*1 T c 1,
P 1 being the first k columns of P, i.e., P=P 1P 0, and Q*1 being the first k columns of Q*.
Details of the SVD, are made available, in the form of the matrix P*:
P*=D-1 P 1 TP 0 T.
This will be only one of the possible solutions. Other estimates may be obtained by applying constraints to the parameters. These solutions can be obtained by using g02dk after using g02da. Only certain linear combinations of the parameters will have unique estimates; these are known as estimable functions.
The fit of the model can be examined by considering the residuals, ri=yi-y^, where y^=X β^ are the fitted values. The fitted values can be written as Hy for an n by n matrix H. The ith diagonal elements of H, hi, give a measure of the influence of the ith values of the independent variables on the fitted regression model. The values hi are sometimes known as leverages. Both ri and hi are provided by g02da.
The output of g02da also includes β^, the residual sum of squares and associated degrees of freedom, n-k, the standard errors of the parameter estimates and the variance-covariance matrix of the parameter estimates.
In many linear regression models the first term is taken as a mean term or an intercept, i.e., X i,1=1, for i=1,2,…,n. This is provided as an option. Also only some of the possible independent variables are required to be included in a model, a facility to select variables to be included in the model is provided.
Details of the QR decomposition and, if used, the SVD, are made available. These allow the regression to be updated by adding or deleting an observation using g02dc, adding or deleting a variable using g02de and g02df or estimating and testing an estimable function using g02dn.

References

Cook R D and Weisberg S (1982) Residuals and Influence in Regression Chapman and Hall
Draper N R and Smith H (1985) Applied Regression Analysis (2nd Edition) Wiley
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Hammarling S (1985) The singular value decomposition in multivariate statistics SIGNUM Newsl. 20(3) 2–25
McCullagh P and Nelder J A (1983) Generalized Linear Models Chapman and Hall
Searle S R (1971) Linear Models Wiley

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDQ) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | n<2,
or | m<1,
or | tol<0.0,
or | ip≤0,
or | ip>n.
ifail=2
On entry, | mean≠"M" or "Z",
or | weight≠"W" or "U".
ifail=3
On entry, weight="W" and a value of wt<0.0.
ifail=4
On entry, | a value of isx<0,
or | the value of ip is incompatible with the values of mean and isx,
or | ip is greater than the effective number of observations.
ifail=5
The degrees of freedom for the residuals are zero, i.e., the designated number of parameters is equal to the effective number of observations. In this case the parameter estimates will be returned along with the diagonal elements of H, but neither standard errors nor the variance-covariance matrix will be calculated.
ifail=6
The singular value decomposition has failed to converge, see (F02WUF not in this release). This is an unlikely error.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The accuracy of g02da is closely related to the accuracy of (F08AEF not in this release) (F02WUF not in this release). These method documents should be consulted.

Parallelism and Performance

None.

Further Comments

Standardized residuals and further measures of influence can be computed using g02fa. g02fa requires, in particular, the results stored in res and h.

Example

Example program (C#): g02dae.cs

Example program data: g02dae.d

Example program results: g02dae.r

See Also

G02 Class
G02 Members


g02dc Method

[image]

NAG Library for .NET Release 2
G02..::g02dc Method
G02 Class See Also Send Feedback
g02dc adds or deletes an observation from a general regression model fitted by g02da.

Syntax

C#
public static void g02dc(
    string update,
    string mean,
    string weight,
    int m,
    int[] isx,
    double[,] q,
    int ip,
    double[] x,
    int ix,
    double y,
    double wt,
    ref double rss,
    out int ifail
)
Visual Basic
Public Shared Sub g02dc ( _
    update As String, _
    mean As String, _
    weight As String, _
    m As Integer, _
    isx As Integer(), _
    q As Double(,), _
    ip As Integer, _
    x As Double(), _
    ix As Integer, _
    y As Double, _
    wt As Double, _
    ByRef rss As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02dc(
    String^ update,
    String^ mean,
    String^ weight,
    int m,
    array<int>^ isx,
    array<double,2>^ q,
    int ip,
    array<double>^ x,
    int ix,
    double y,
    double wt,
    double% rss,
    [OutAttribute] int% ifail
)
F#
static member g02dc :
        update : string *
        mean : string *
        weight : string *
        m : int *
        isx : int[] *
        q : float[,] *
        ip : int *
        x : float[] *
        ix : int *
        y : float *
        wt : float *
        rss : float byref *
        ifail : int byref -> unit

Parameters

update
Type: System..::..String
On entry: indicates if an observation is to be added or deleted.
update="A"
The observation is added.
update="D"
The observation is deleted.
Constraint: update="A" or "D".
mean
Type: System..::..String
On entry: indicates if a mean has been used in the model.
mean="M"
A mean term or intercept will have been included in the model by g02da.
mean="Z"
A model with no mean term or intercept will have been fitted by g02da.
Constraint: mean="M" or "Z".
weight
Type: System..::..String
On entry: indicates if a weight is to be used.
weight="U"
The new observation is unweighted.
weight="W"
The new observation is to be weighted and the weight must be supplied in wt.
Constraint: weight="U" or "W".
m
Type: System..::..Int32
On entry: m, the total number of independent variables in the dataset.
Constraint: m≥1.
isx
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: if isx[j-1] is greater than 0, the value contained in x[j-1×ix] is to be included as a value of xT, for j=1,2,…,m.
Constraint: if mean="M", exactly ip-1 elements of isx must be >0 and if mean="Z", exactly ip elements of isx must be >0.
q
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, ip+1]
Note: dim1 must satisfy the constraint: dim1≥ip
On entry: must be array q as output by g02da g02de g02df (G02EEF not in this release), or a previous call to g02dc.
On exit: the first ip elements of the first column of q will contain c 1* the upper triangular part of columns 2 to ip+1 will contain R* the remainder is unchanged.
ip
Type: System..::..Int32
On entry: the number of linear terms in general linear regression model (including mean if there is one).
Constraint: ip≥1.
x
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array x must be at least m-1×ix+1.
On entry: the ip values for the dependent variables of the new observation, xT. The positions will depend on the value of ix.
ix
Type: System..::..Int32
On entry: the increment for elements of x.
Constraint: ix≥1.
y
Type: System..::..Double
On entry: the value of the dependent variable for the new observation, y new.
wt
Type: System..::..Double
On entry: if weight="W" , wt must contain the weight to be used with the new observation.
If wt=0.0, the observation is not included in the model.
If weight="U", wt is not referenced.
Constraint: if wt≥0.0, weight="W".
rss
Type: System..::..Double %
On entry: the value of the residual sums of squares for the original set of observations.
Constraint: rss≥0.0.
On exit: the updated values of the residual sums of squares.
Note: this will only be valid if the model is of full rank.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g02da fits a general linear regression model to a dataset. You may wish to change the model by either adding or deleting an observation from the dataset. g02dc takes the results from g02da and makes the required changes to the vector c and the upper triangular matrix R produced by g02da. The regression coefficients, standard errors and the variance-covariance matrix of the regression coefficients can be obtained from g02dd after all required changes to the dataset have been made.
g02da performs a QR decomposition on the (weighted) X matrix of independent variables. To add a new observation to a model with p parameters, the upper triangular matrix R and vector c 1 (the first p elements of c) are augmented by the new observation on independent variables in xT and dependent variable y new. Givens rotations are then used to restore the upper triangular form.
R:c 1x:y new→R*:c 1*0:y new*.
Note: only R and the upper part of c are updated the remainder of the Q matrix is unchanged.

References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Hammarling S (1985) The singular value decomposition in multivariate statistics SIGNUM Newsl. 20(3) 2–25

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDQ) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | ip<1,
or | m<1,
or | ix<1,
or | rss<0.0,
or | update≠"A" or "D",
or | mean≠"M" or "Z",
or | weight≠"U" or "W",
or | mean="M" and there are not exactly ip-1 nonzero values of isx,
or | mean="Z" and there are not exactly ip nonzero values of isx,
ifail=2
On entry, weight="W" and wt<0.0.
ifail=3
The R matrix could not be updated. This may occur if an attempt is made to delete an observation which was not in the original dataset or to add an observation to a R matrix with a zero diagonal element. This error is also possible when removing an observation which reduces the rank of design matrix. In such cases the model should be recomputed using g02da.
ifail=4
The residual sums of squares cannot be updated. This will occur if the input residual sum of squares is less than the calculated decrease in residual sum of squares when the new observation is deleted.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Higher accuracy is achieved by updating the R matrix rather than the traditional methods of updating X′X.

Parallelism and Performance

None.

Further Comments

Care should be taken with the use of g02dc.
(a) | It is possible to delete observations which were not included in the original model.
(b) | If several additions/deletions have been performed you are advised to recompute the regression using g02da.
(c) | Adding or deleting observations can alter the rank of the model. Such changes will only be detected when a call to g02dd has been made. g02dd should also be used to compute the new residual sum of squares when the model is not of full rank.
g02dc may also be used after g02de g02df (G02EEF not in this release).

Example

Example program (C#): g02dce.cs

Example program data: g02dce.d

Example program results: g02dce.r

See Also

G02 Class
G02 Members


g02dd Method

[image]

NAG Library for .NET Release 2
G02..::g02dd Method
G02 Class See Also Send Feedback
g02dd calculates the regression parameters for a general linear regression model. It is intended to be called after g02dc, g02de or g02df.

Syntax

C#
public static void g02dd(
    int n,
    int ip,
    double[,] q,
    ref double rss,
    out int idf,
    double[] b,
    double[] se,
    double[] cov,
    out bool svd,
    out int irank,
    double[] p,
    double tol,
    out int ifail
)
Visual Basic
Public Shared Sub g02dd ( _
    n As Integer, _
    ip As Integer, _
    q As Double(,), _
    ByRef rss As Double, _
    <OutAttribute> ByRef idf As Integer, _
    b As Double(), _
    se As Double(), _
    cov As Double(), _
    <OutAttribute> ByRef svd As Boolean, _
    <OutAttribute> ByRef irank As Integer, _
    p As Double(), _
    tol As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02dd(
    int n,
    int ip,
    array<double,2>^ q,
    double% rss,
    [OutAttribute] int% idf,
    array<double>^ b,
    array<double>^ se,
    array<double>^ cov,
    [OutAttribute] bool% svd,
    [OutAttribute] int% irank,
    array<double>^ p,
    double tol,
    [OutAttribute] int% ifail
)
F#
static member g02dd :
        n : int *
        ip : int *
        q : float[,] *
        rss : float byref *
        idf : int byref *
        b : float[] *
        se : float[] *
        cov : float[] *
        svd : bool byref *
        irank : int byref *
        p : float[] *
        tol : float *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: the number of observations.
Constraint: n≥1.
ip
Type: System..::..Int32
On entry: p, the number of terms in the regression model.
Constraint: ip≥1.
q
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, ip+1]
Note: dim1 must satisfy the constraint:
  • if rss≤0.0, dim1≥n;
  • otherwise dim1≥ip.
On entry: must be the array q as output by g02dc g02de g02df (G02EEF not in this release). If on entry rss≤0.0 then all n elements of c are needed. This is provided by methods g02de g02df (G02EEF not in this release).
rss
Type: System..::..Double %
On entry: either the residual sum of squares or a value less than or equal to 0.0 to indicate that the residual sum of squares is to be calculated by the method.
On exit: if rss≤0.0 on entry, then on exit rss will contain the residual sum of squares as calculated by g02dd.
If rss was positive on entry, it will be unchanged.
idf
Type: System..::..Int32 %
On exit: the degrees of freedom associated with the residual sum of squares.
b
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On exit: the estimates of the p parameters, β^.
se
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On exit: the standard errors of the p parameters given in b.
cov
Type: array< System..::..Double >[]()[][]
An array of size [ip×ip+1/2]
On exit: the upper triangular part of the variance-covariance matrix of the p parameter estimates given in b. They are stored packed by column, i.e., the covariance between the parameter estimate given in b[i-1] and the parameter estimate given in b[j-1], j≥i, is stored in cov[j×j-1/2+i-1].
svd
Type: System..::..Boolean %
On exit: if a singular value decomposition has been performed, svd=true, otherwise svd=false.
irank
Type: System..::..Int32 %
On exit: the rank of the independent variables.
If svd=false, irank=ip.
If svd=true, irank is an estimate of the rank of the independent variables.
irank is calculated as the number of singular values greater than tol× (largest singular value). It is possible for the SVD to be carried out but irank to be returned as ip.
p
Type: array< System..::..Double >[]()[][]
An array of size [ip×ip+2×ip]
On exit: contains details of the singular value decomposition if used.
If svd=false, p is not referenced.
If svd=true, the first ip elements of p will not be referenced, the next ip values contain the singular values. The following ip×ip values contain the matrix P* stored by columns.
tol
Type: System..::..Double
On entry: the value of tol is used to decide if the independent variables are of full rank and, if not, what is the rank of the independent variables. The smaller the value of tol the stricter the criterion for selecting the singular value decomposition. If tol=0.0, the singular value decomposition will never be used, this may cause run time errors or inaccuracies if the independent variables are not of full rank.
Suggested value: tol=0.000001.
Constraint: tol≥0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

A general linear regression model fitted by g02da may be adjusted by adding or deleting an observation using g02dc, adding a new independent variable using g02de or deleting an existing independent variable using g02df. Alternatively a model may be constructed by a forward selection procedure using (G02EEF not in this release). These methods compute the vector c and the upper triangular matrix R. g02dd takes these basic results and computes the regression coefficients, β^, their standard errors and their variance-covariance matrix.
If R is of full rank, then β^ is the solution to
R β^=c 1,
where c 1 is the first p elements of c.
If R is not of full rank a solution is obtained by means of a singular value decomposition (SVD) of R,
R=Q*D000 PT,
where D is a k by k diagonal matrix with nonzero diagonal elements, k being the rank of R, and Q* and P are p by p orthogonal matrices. This gives the solution
β^=P 1 D-1 Q*1 T c 1.
P 1 being the first k columns of P, i.e., P=P 1P 0, and Q*1 being the first k columns of Q*.
Details of the SVD are made available in the form of the matrix P*:
P*=D-1 P 1 TP 0 T.
This will be only one of the possible solutions. Other estimates may be obtained by applying constraints to the parameters. These solutions can be obtained by calling g02dk after calling g02dd. Only certain linear combinations of the parameters will have unique estimates; these are known as estimable functions. These can be estimated using g02dn.
The residual sum of squares required to calculate the standard errors and the variance-covariance matrix can either be input or can be calculated if additional information on c for the whole sample is provided.

References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Hammarling S (1985) The singular value decomposition in multivariate statistics SIGNUM Newsl. 20(3) 2–25
Searle S R (1971) Linear Models Wiley

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDQ) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | n<1,
or | ip<1,
or | tol<0.0.
ifail=2
The degrees of freedom for error are less than or equal to 0. In this case the estimates of β are returned but not the standard errors or covariances.
ifail=3
The singular value decomposition, if used, has failed to converge, see (F02WUF not in this release). This is an unlikely error exit.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The accuracy of the results will depend on the accuracy of the input R matrix, which may lose accuracy if a large number of observations or variables have been dropped.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g02dde.cs

Example program data: g02dde.d

Example program results: g02dde.r

See Also

G02 Class
G02 Members


g02de Method

[image]

NAG Library for .NET Release 2
G02..::g02de Method
G02 Class See Also Send Feedback
g02de adds a new independent variable to a general linear regression model.

Syntax

C#
public static void g02de(
    string weight,
    int n,
    int ip,
    double[,] q,
    double[] p,
    double[] wt,
    double[] x,
    out double rss,
    double tol,
    out int ifail
)
Visual Basic
Public Shared Sub g02de ( _
    weight As String, _
    n As Integer, _
    ip As Integer, _
    q As Double(,), _
    p As Double(), _
    wt As Double(), _
    x As Double(), _
    <OutAttribute> ByRef rss As Double, _
    tol As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02de(
    String^ weight,
    int n,
    int ip,
    array<double,2>^ q,
    array<double>^ p,
    array<double>^ wt,
    array<double>^ x,
    [OutAttribute] double% rss,
    double tol,
    [OutAttribute] int% ifail
)
F#
static member g02de :
        weight : string *
        n : int *
        ip : int *
        q : float[,] *
        p : float[] *
        wt : float[] *
        x : float[] *
        rss : float byref *
        tol : float *
        ifail : int byref -> unit

Parameters

weight
Type: System..::..String
On entry: indicates if weights are to be used.
weight="U"
Least squares estimation is used.
weight="W"
Weighted least squares is used and weights must be supplied in array wt.
Constraint: weight="U" or "W".
n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n≥1.
ip
Type: System..::..Int32
On entry: p, the number of independent variables already in the model.
Constraint: ip≥0 and ip<n.
q
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, ip+2]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: if ip≠0, q must contain the results of the QR decomposition for the model with p parameters as returned by g02da or a previous call to g02de.
If ip=0, the first column of q should contain the n values of the dependent variable, y.
On exit: the results of the QR decomposition for the model with p+1 parameters:
  • the first column of q contains the updated value of c;
  • the columns 2 to ip+1 are unchanged;
  • the first ip+1 elements of column ip+2 contain the new column of R, while the remaining n-ip-1 elements contain details of the matrix Q p+1.
p
Type: array< System..::..Double >[]()[][]
An array of size [ip+1]
On entry: contains further details of the QR decomposition used. The first ip elements of p must contain the zeta values for the QR decomposition (see (F08AEF not in this release) for details).
The first ip elements of array p are provided by g02da or by previous calls to g02de.
On exit: the first ip elements of p are unchanged and the ip+1th element contains the zeta value for Q p+1.
wt
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array wt must be at least n if weight="W", and at least 1 otherwise.
On entry: if weight="W" , wt must contain the weights to be used.
If wt[i-1]=0.0, the ith observation is not included in the model, in which case the effective number of observations is the number of observations with nonzero weights.
If weight="U", wt is not referenced and the effective number of observations is n.
Constraint: if weight="W", wt[i-1]≥0.0, for i=1,2,…,n.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: x, the new independent variable.
rss
Type: System..::..Double %
On exit: the residual sum of squares for the new fitted model.
Note: this will only be valid if the model is of full rank, see [Further Comments].
tol
Type: System..::..Double
On entry: the value of tol is used to decide if the new independent variable is linearly related to independent variables already included in the model. If the new variable is linearly related then c is not updated. The smaller the value of tol the stricter the criterion for deciding if there is a linear relationship.
Suggested value: tol=0.000001.
Constraint: tol>0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

A linear regression model may be built up by adding new independent variables to an existing model. g02de updates the QR decomposition used in the computation of the linear regression model. The QR decomposition may come from g02da or a previous call to g02de. The general linear regression model is defined by
y=Xβ+ε,
where | y is a vector of n observations on the dependent variable,
 | X is an n by p matrix of the independent variables of column rank k,
 | β is a vector of length p of unknown parameters,
and | ε is a vector of length n of unknown random errors such that var ε=V σ 2, where V is a known diagonal matrix.
If V=I, the identity matrix, then least squares estimation is used. If V≠I, then for a given weight matrix W∝V-1, weighted least squares estimation is used.
The least squares estimates, β^ of the parameters β minimize y-Xβ T y-Xβ while the weighted least squares estimates, minimize y-Xβ T W y-Xβ.
The parameter estimates may be found by computing a QR decomposition of X (or W 12 X in the weighted case), i.e.,
X=Q R* or  W 12 X=Q R*,
where R*=R0 and R is a p by p upper triangular matrix and Q is an n by n orthogonal matrix.
If R is of full rank, then β^ is the solution to
R β^=c 1,
where c=QT y (or QTW 12 y) and c 1 is the first p elements of c.
If R is not of full rank a solution is obtained by means of a singular value decomposition (SVD) of R.
To add a new independent variable, x p+1, R and c have to be updated. The matrix Q p+1 is found such that Q p+1 T R:QT x p+1 (or Q p+1 T R:QTW 12 x p+1) is upper triangular. The vector c is then updated by multiplying by Q p+1 T.
The new independent variable is tested to see if it is linearly related to the existing independent variables by checking that at least one of the values QT x p+1 i, for i=p+2,…,n, is nonzero.
The new parameter estimates, β^, can then be obtained by a call to g02dd.
The method can be used with p=0, in which case R and c are initialized.

References

Draper N R and Smith H (1985) Applied Regression Analysis (2nd Edition) Wiley
Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Hammarling S (1985) The singular value decomposition in multivariate statistics SIGNUM Newsl. 20(3) 2–25
McCullagh P and Nelder J A (1983) Generalized Linear Models Chapman and Hall
Searle S R (1971) Linear Models Wiley

Error Indicators and Warnings

Note: g02de may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDQ) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | n<1,
or | ip<0,
or | ip≥n,
or | tol≤0.0,
or | weight≠"U" or "W".
ifail=3
The new independent variable is a linear combination of existing variables. The ip+2th column of q will therefore be null.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The accuracy is closely related to the accuracy of f08ag which should be consulted for further details.

Parallelism and Performance

None.

Further Comments

It should be noted that the residual sum of squares produced by g02de may not be correct if the model to which the new independent variable is added is not of full rank. In such a case g02dd should be used to calculate the residual sum of squares.

Example

Example program (C#): g02dee.cs

Example program data: g02dee.d

Example program results: g02dee.r

See Also

G02 Class
G02 Members


g02df Method

[image]

NAG Library for .NET Release 2
G02..::g02df Method
G02 Class See Also Send Feedback
g02df deletes an independent variable from a general linear regression model.

Syntax

C#
public static void g02df(
    int ip,
    double[,] q,
    int indx,
    ref double rss,
    out int ifail
)
Visual Basic
Public Shared Sub g02df ( _
    ip As Integer, _
    q As Double(,), _
    indx As Integer, _
    ByRef rss As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02df(
    int ip,
    array<double,2>^ q,
    int indx,
    double% rss,
    [OutAttribute] int% ifail
)
F#
static member g02df :
        ip : int *
        q : float[,] *
        indx : int *
        rss : float byref *
        ifail : int byref -> unit

Parameters

ip
Type: System..::..Int32
On entry: p, the number of independent variables already in the model.
Constraint: ip≥1.
q
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, ip+1]
Note: dim1 must satisfy the constraint: dim1≥ip
On entry: the results of the QR decomposition as returned by methods g02da g02dc g02de (G02EEF not in this release), or previous calls to g02df.
On exit: the updated QR decomposition.
indx
Type: System..::..Int32
On entry: indicates which independent variable is to be deleted from the model.
Constraint: 1≤indx≤ip.
rss
Type: System..::..Double %
On entry: the residual sum of squares for the full regression.
Constraint: rss≥0.0.
On exit: the residual sum of squares with the (indx)th variable removed. Note that the residual sum of squares will only be valid if the regression is of full rank, otherwise the residual sum of squares should be obtained using g02dd.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

When selecting a linear regression model it is sometimes useful to drop independent variables from the model and to examine the resulting sub-model. g02df updates the QR decomposition used in the computation of the linear regression model. The QR decomposition may come from g02da or g02de, or a previous call to g02df.
For the general linear regression model with p independent variables fitted g02da or g02de compute a QR decomposition of the (weighted) independent variables and form an upper triangular matrix R and a vector c. To remove an independent variable R and c have to be updated. The column of R corresponding to the variable to be dropped is removed and the matrix is then restored to upper triangular form by applying a series of Givens rotations. The rotations are then applied to c. Note only the first p elements of c are affected.
The method used means that while the updated values of R and c are computed an updated value of Q from the QR decomposition is not available so a call to g02de cannot be made after a call to g02df.
g02dd can be used to calculate the parameter estimates, β^, from the information provided by g02df.

References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Hammarling S (1985) The singular value decomposition in multivariate statistics SIGNUM Newsl. 20(3) 2–25

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDQ) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | ip<1,
or | indx<1,
or | indx>ip,
or | rss<0.0.
ifail=2
On entry, a diagonal element of R is zero.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

There will inevitably be some loss in accuracy in fitting a model by dropping terms from a more complex model rather than fitting it afresh using g02da.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g02dfe.cs

Example program data: g02dfe.d

Example program results: g02dfe.r

See Also

G02 Class
G02 Members


g02dg Method

[image]

NAG Library for .NET Release 2
G02..::g02dg Method
G02 Class See Also Send Feedback
g02dg calculates the estimates of the parameters of a general linear regression model for a new dependent variable after a call to g02da.

Syntax

C#
public static void g02dg(
    string weight,
    int n,
    double[] wt,
    ref double rss,
    int ip,
    int irank,
    double[] cov,
    double[,] q,
    bool svd,
    double[] p,
    double[] y,
    double[] b,
    double[] se,
    double[] res,
    double[] wk,
    out int ifail
)
Visual Basic
Public Shared Sub g02dg ( _
    weight As String, _
    n As Integer, _
    wt As Double(), _
    ByRef rss As Double, _
    ip As Integer, _
    irank As Integer, _
    cov As Double(), _
    q As Double(,), _
    svd As Boolean, _
    p As Double(), _
    y As Double(), _
    b As Double(), _
    se As Double(), _
    res As Double(), _
    wk As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02dg(
    String^ weight,
    int n,
    array<double>^ wt,
    double% rss,
    int ip,
    int irank,
    array<double>^ cov,
    array<double,2>^ q,
    bool svd,
    array<double>^ p,
    array<double>^ y,
    array<double>^ b,
    array<double>^ se,
    array<double>^ res,
    array<double>^ wk,
    [OutAttribute] int% ifail
)
F#
static member g02dg :
        weight : string *
        n : int *
        wt : float[] *
        rss : float byref *
        ip : int *
        irank : int *
        cov : float[] *
        q : float[,] *
        svd : bool *
        p : float[] *
        y : float[] *
        b : float[] *
        se : float[] *
        res : float[] *
        wk : float[] *
        ifail : int byref -> unit

Parameters

weight
Type: System..::..String
On entry: indicates if weights are to be used.
weight="U"
Least squares estimation is used.
weight="W"
Weighted least squares is used and weights must be supplied in array wt.
Constraint: weight="U" or "W".
n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n≥ip.
wt
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array wt must be at least n if weight="W", and at least 1 otherwise.
On entry: if weight="W" >, wt must contain the weights to be used in the weighted regression.
If wt[i-1]=0.0, the ith observation is not included in the model, in which case the effective number of observations is the number of observations with nonzero weights.
If weight="U", wt is not referenced and the effective number of observations is n.
Constraint: if weight="W", wt[i]≥0.0, for i=0,1,…,n-1.
rss
Type: System..::..Double %
On entry: the residual sum of squares for the original dependent variable.
On exit: the residual sum of squares for the new dependent variable.
Constraint: rss>0.0.
ip
Type: System..::..Int32
On entry: p, the number of independent variables (including the mean if fitted).
Constraint: 1≤ip≤n.
irank
Type: System..::..Int32
On entry: the rank of the independent variables, as given by g02da.
Constraint: irank>0, and if svd=false, then irank=ip, else irank≤ip.
cov
Type: array< System..::..Double >[]()[][]
An array of size [ip×ip+1/2]
On entry: the covariance matrix of the parameter estimates as given by g02da.
On exit: the upper triangular part of the variance-covariance matrix of the ip parameter estimates given in b. They are stored packed by column, i.e., the covariance between the parameter estimate given in b[i-1] and the parameter estimate given in b[j-1], j≥i, is stored in cov[j×j-1/2+i-1].
q
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, ip+1]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: the results of the QR decomposition as returned by g02da.
On exit: the first column of q contains the new values of c, the remainder of q will be unchanged.
svd
Type: System..::..Boolean
On entry: indicates if a singular value decomposition was used by g02da.
svd=true
A singular value decomposition was used by g02da.
svd=false
A singular value decomposition was not used by g02da.
p
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array p must be at least ip if svd=false, and at least ip×ip+2×ip otherwise.
On entry: details of the QR decomposition and SVD, if used, as returned in array p by g02da.
If svd=false, only the first ip elements of p are used; these contain the zeta values for the QR decomposition (see (F08AEF not in this release) for details).
If svd=true, the first ip elements of p contain the zeta values for the QR decomposition (see (F08AEF not in this release) for details) and the next ip×ip+ip elements of p contain details of the singular value decomposition.
y
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the new dependent variable, y new.
b
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On exit: the least squares estimates of the parameters of the regression model, β^.
se
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On exit: the standard error of the estimates of the parameters.
res
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the residuals for the new regression model.
wk
Type: array< System..::..Double >[]()[][]
An array of size [5×ip-1+ip×ip]
On entry: if svd=true, wk must be unaltered from the previous call to g02da or g02dg.
If svd=false, wk is used as workspace.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g02dg uses the results given by g02da to fit the same set of independent variables to a new dependent variable.
g02da computes a QR decomposition of the matrix of p independent variables and also, if the model is not of full rank, a singular value decomposition (SVD). These results can be used to compute estimates of the parameters for a general linear model with a new dependent variable. The QR decomposition leads to the formation of an upper triangular p by p matrix R and an n by n orthogonal matrix Q. In addition the vector c=QT y (or QTW 1/2 y) is computed. For a new dependent variable, ynew, g02dg computes a new value of c=QT y new or QTW 1/2 y new.
If R is of full rank, then the least squares parameter estimates, β^, are the solution to
R β^=c 1,
where c 1 is the first p elements of c.
If R is not of full rank, then g02da will have computed an SVD of R,
R=Q*D000 PT,
where D is a k by k diagonal matrix with nonzero diagonal elements, k being the rank of R, and Q* and P are p by p orthogonal matrices. This gives the solution
β^=P 1 D-1 Q*1 T c 1,
P 1 being the first k columns of P, i.e., P=P 1P 0, and Q*1 being the first k columns of Q*. Details of the SVD are made available by g02da in the form of the matrix P*:
P*=D-1 P 1 TP 0 T.
The matrix Q* is made available through the workspace of g02da.
In addition to parameter estimates, the new residuals are computed and the variance-covariance matrix of the parameter estimates are found by scaling the variance-covariance matrix for the original regression.

References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Hammarling S (1985) The singular value decomposition in multivariate statistics SIGNUM Newsl. 20(3) 2–25
Searle S R (1971) Linear Models Wiley

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDQ) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | ip<1,
or | n<ip,
or | irank≤0,
or | svd=false and irank≠ip,
or | svd=true and irank>ip,
or | rss≤0.0,
or | weight≠"U" or "W".
ifail=2
On entry, weight="W" and a value of wt<0.0.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The same accuracy as g02da is obtained.

Parallelism and Performance

None.

Further Comments

The values of the leverages, hi, are unaltered by a change in the dependent variable so a call to g02fa can be made using the value of h from g02da.

Example

Example program (C#): g02dge.cs

Example program data: g02dge.d

Example program results: g02dge.r

See Also

G02 Class
G02 Members


g02dk Method

[image]

NAG Library for .NET Release 2
G02..::g02dk Method
G02 Class See Also Send Feedback
g02dk calculates the estimates of the parameters of a general linear regression model for given constraints from the singular value decomposition results.

Syntax

C#
public static void g02dk(
    int ip,
    int iconst,
    double[] p,
    double[,] c,
    double[] b,
    double rss,
    int idf,
    double[] se,
    double[] cov,
    out int ifail
)
Visual Basic
Public Shared Sub g02dk ( _
    ip As Integer, _
    iconst As Integer, _
    p As Double(), _
    c As Double(,), _
    b As Double(), _
    rss As Double, _
    idf As Integer, _
    se As Double(), _
    cov As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02dk(
    int ip,
    int iconst,
    array<double>^ p,
    array<double,2>^ c,
    array<double>^ b,
    double rss,
    int idf,
    array<double>^ se,
    array<double>^ cov,
    [OutAttribute] int% ifail
)
F#
static member g02dk :
        ip : int *
        iconst : int *
        p : float[] *
        c : float[,] *
        b : float[] *
        rss : float *
        idf : int *
        se : float[] *
        cov : float[] *
        ifail : int byref -> unit

Parameters

ip
Type: System..::..Int32
On entry: p, the number of terms in the linear model.
Constraint: ip≥1.
iconst
Type: System..::..Int32
On entry: the number of constraints to be imposed on the parameters, nc.
Constraint: 0<iconst<ip.
p
Type: array< System..::..Double >[]()[][]
An array of size [ip×ip+2×ip]
On entry: as returned by g02da and g02dd.
c
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, iconst]
Note: dim1 must satisfy the constraint: dim1≥ip
On entry: the iconst constraints stored by column, i.e., the ith constraint is stored in the ith column of c.
b
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On entry: the parameter estimates computed by using the singular value decomposition, β^svd.
On exit: the parameter estimates of the parameters with the constraints imposed, β^c.
rss
Type: System..::..Double
On entry: the residual sum of squares as returned by g02da or g02dd.
Constraint: rss>0.0.
idf
Type: System..::..Int32
On entry: the degrees of freedom associated with the residual sum of squares as returned by g02da or g02dd.
Constraint: idf>0.
se
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On exit: the standard error of the parameter estimates in b.
cov
Type: array< System..::..Double >[]()[][]
An array of size [ip×ip+1/2]
On exit: the upper triangular part of the variance-covariance matrix of the ip parameter estimates given in b. They are stored packed by column, i.e., the covariance between the parameter estimate given in b[i-1] and the parameter estimate given in b[j-1], j≥i, is stored in cov[j×j-1/2+i-1].
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g02dk computes the estimates given a set of linear constraints for a general linear regression model which is not of full rank. It is intended for use after a call to g02da or g02dd.
In the case of a model not of full rank the methods use a singular value decomposition (SVD) to find the parameter estimates, β^svd, and their variance-covariance matrix. Details of the SVD are made available in the form of the matrix P*:
P*=D-1 P 1 TP 0 T,
as described by g02da and g02dd.
Alternative solutions can be formed by imposing constraints on the parameters. If there are p parameters and the rank of the model is k, then nc=p-k constraints will have to be imposed to obtain a unique solution.
Let C be a p by nc matrix of constraints, such that
CT β=0
then the new parameter estimates β^c are given by
β^c=A β^svd;=I-P 0 CT P 0-1 β^svd,
where I is the identity matrix, and the variance-covariance matrix is given by
A P 1 D-2 P 1 T AT,
provided CT P 0-1 exists.

References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Hammarling S (1985) The singular value decomposition in multivariate statistics SIGNUM Newsl. 20(3) 2–25
Searle S R (1971) Linear Models Wiley

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDC) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | ip<1,
or | iconst≤0,
or | iconst≥ip,
or | rss≤0.0,
or | idf≤0.
ifail=2
c does not give a model of full rank.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

It should be noted that due to rounding errors a parameter that should be zero when the constraints have been imposed may be returned as a value of order machine precision.

Parallelism and Performance

None.

Further Comments

g02dk is intended for use in situations in which dummy (0–1) variables have been used such as in the analysis of designed experiments when you do not wish to change the parameters of the model to give a full rank model. The method is not intended for situations in which the relationships between the independent variables are only approximate.

Example

Example program (C#): g02dke.cs

Example program data: g02dke.d

Example program results: g02dke.r

See Also

G02 Class
G02 Members


g02dn Method

[image]

NAG Library for .NET Release 2
G02..::g02dn Method
G02 Class See Also Send Feedback
g02dn gives the estimate of an estimable function along with its standard error.

Syntax

C#
public static void g02dn(
    int ip,
    int irank,
    double[] b,
    double[] cov,
    double[] p,
    double[] f,
    out bool est,
    out double stat,
    out double sestat,
    out double t,
    double tol,
    out int ifail
)
Visual Basic
Public Shared Sub g02dn ( _
    ip As Integer, _
    irank As Integer, _
    b As Double(), _
    cov As Double(), _
    p As Double(), _
    f As Double(), _
    <OutAttribute> ByRef est As Boolean, _
    <OutAttribute> ByRef stat As Double, _
    <OutAttribute> ByRef sestat As Double, _
    <OutAttribute> ByRef t As Double, _
    tol As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02dn(
    int ip,
    int irank,
    array<double>^ b,
    array<double>^ cov,
    array<double>^ p,
    array<double>^ f,
    [OutAttribute] bool% est,
    [OutAttribute] double% stat,
    [OutAttribute] double% sestat,
    [OutAttribute] double% t,
    double tol,
    [OutAttribute] int% ifail
)
F#
static member g02dn :
        ip : int *
        irank : int *
        b : float[] *
        cov : float[] *
        p : float[] *
        f : float[] *
        est : bool byref *
        stat : float byref *
        sestat : float byref *
        t : float byref *
        tol : float *
        ifail : int byref -> unit

Parameters

ip
Type: System..::..Int32
On entry: p, the number of terms in the linear model.
Constraint: ip≥1.
irank
Type: System..::..Int32
On entry: k, the rank of the independent variables.
Constraint: 1≤irank≤ip.
b
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On entry: the ip values of the estimates of the parameters of the model, β^.
cov
Type: array< System..::..Double >[]()[][]
An array of size [ip×ip+1/2]
On entry: the upper triangular part of the variance-covariance matrix of the ip parameter estimates given in b. They are stored packed by column, i.e., the covariance between the parameter estimate given in b[i-1] and the parameter estimate given in b[j-1], j≥i, is stored in cov[j×j-1/2+i-1].
p
Type: array< System..::..Double >[]()[][]
An array of size [ip×ip+2×ip]
On entry: as returned by g02da and g02dd.
f
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On entry: f, the linear function to be estimated.
est
Type: System..::..Boolean %
On exit: indicates if the function was estimable.
est=true
The function is estimable.
est=false
The function is not estimable and stat, sestat and t are not set.
stat
Type: System..::..Double %
On exit: if est=true, stat contains the estimate of the function, fT β^.
sestat
Type: System..::..Double %
On exit: if est=true, sestat contains the standard error of the estimate of the function, se F.
t
Type: System..::..Double %
On exit: if est=true, t contains the t-statistic for the test of the function being equal to zero.
tol
Type: System..::..Double
On entry: η, the tolerance value used in the check for estimability.
tol≤0.0
ε, where ε is the machine precision, is used instead.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g02dn computes the estimates of an estimable function for a general linear regression model which is not of full rank. It is intended for use after a call to g02da or g02dd. An estimable function is a linear combination of the parameters such that it has a unique estimate. For a full rank model all linear combinations of parameters are estimable.
In the case of a model not of full rank the methods use a singular value decomposition (SVD) to find the parameter estimates, β^, and their variance-covariance matrix. Given the upper triangular matrix R obtained from the QR decomposition of the independent variables the SVD gives
R=Q*D000 PT,
where D is a k by k diagonal matrix with nonzero diagonal elements, k being the rank of R, and Q* and P are p by p orthogonal matrices. This gives the solution
β^=P 1 D-1 Q*1 T c 1,
P 1 being the first k columns of P, i.e., P=P 1P 0, Q*1 being the first k columns of Q*, and c 1 being the first p elements of c.
Details of the SVD are made available in the form of the matrix P*:
P*=D-1 P 1 TP 0 T,
as given by g02da and g02dd.
A linear function of the parameters, F=fT β, can be tested to see if it is estimable by computing ζ=P 0 T f. If ζ is zero, then the function is estimable; if not, the function is not estimable. In practice ζ is tested against some small quantity η.
Given that F is estimable it can be estimated by fT β^ and its standard error calculated from the variance-covariance matrix of β^, Cβ, as
se F=fT Cβ f.
Also a t-statistic,
t=fT β^se F,
can be computed. The t-statistic will have a Student's t-distribution with degrees of freedom as given by the degrees of freedom for the residual sum of squares for the model.

References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
Hammarling S (1985) The singular value decomposition in multivariate statistics SIGNUM Newsl. 20(3) 2–25
Searle S R (1971) Linear Models Wiley

Error Indicators and Warnings

Note: g02dn may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail=1
On entry, | ip<1,
or | irank<1,
or | irank>ip.
ifail=2
On entry, irank=ip. In this case est is returned as true and all statistics are calculated.
ifail=3
Standard error of statistic =0.0; this may be due to rounding errors if the standard error is very small or due to mis-specified inputs cov and f.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The computations are believed to be stable.

Parallelism and Performance

None.

Further Comments

The value of estimable functions is independent of the solution chosen from the many possible solutions. While g02dn may be used to estimate functions of the parameters of the model as computed by g02dk, βc, these must be expressed in terms of the original parameters, β. The relation between the two sets of parameters may not be straightforward.

Example

Example program (C#): g02dne.cs

Example program data: g02dne.d

Example program results: g02dne.r

See Also

G02 Class
G02 Members


g02ef Method

[image]

NAG Library for .NET Release 2
G02..::g02ef Method
G02 Class See Also Send Feedback
g02ef calculates a full stepwise selection from p variables by using Clarke's sweep algorithm on the correlation matrix of a design and data matrix, Z. The (weighted) variance-covariance, (weighted) means and sum of weights of Z must be supplied.

Syntax

C#
public static void g02ef(
    int m,
    int n,
    double[] wmean,
    double[] c,
    double sw,
    int[] isx,
    double fin,
    double fout,
    double tau,
    double[] b,
    double[] se,
    out double rsq,
    out double rms,
    out int df,
    int monlev,
    G02..::..G02EF_MONFUN monfun,
    out int ifail
)
Visual Basic
Public Shared Sub g02ef ( _
    m As Integer, _
    n As Integer, _
    wmean As Double(), _
    c As Double(), _
    sw As Double, _
    isx As Integer(), _
    fin As Double, _
    fout As Double, _
    tau As Double, _
    b As Double(), _
    se As Double(), _
    <OutAttribute> ByRef rsq As Double, _
    <OutAttribute> ByRef rms As Double, _
    <OutAttribute> ByRef df As Integer, _
    monlev As Integer, _
    monfun As G02..::..G02EF_MONFUN, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02ef(
    int m,
    int n,
    array<double>^ wmean,
    array<double>^ c,
    double sw,
    array<int>^ isx,
    double fin,
    double fout,
    double tau,
    array<double>^ b,
    array<double>^ se,
    [OutAttribute] double% rsq,
    [OutAttribute] double% rms,
    [OutAttribute] int% df,
    int monlev,
    G02..::..G02EF_MONFUN^ monfun,
    [OutAttribute] int% ifail
)
F#
static member g02ef :
        m : int *
        n : int *
        wmean : float[] *
        c : float[] *
        sw : float *
        isx : int[] *
        fin : float *
        fout : float *
        tau : float *
        b : float[] *
        se : float[] *
        rsq : float byref *
        rms : float byref *
        df : int byref *
        monlev : int *
        monfun : G02..::..G02EF_MONFUN *
        ifail : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: the number of explanatory variables available in the design matrix, Z.
Constraint: m>1.
n
Type: System..::..Int32
On entry: the number of observations used in the calculations.
Constraint: n>1.
wmean
Type: array< System..::..Double >[]()[][]
An array of size [m+1]
On entry: the mean of the design matrix, Z.
c
Type: array< System..::..Double >[]()[][]
An array of size [m+1×m+2/2]
On entry: the upper-triangular variance-covariance matrix packed by column for the design matrix, Z. Because the method computes the correlation matrix R from c, the variance-covariance matrix need only be supplied up to a scaling factor.
sw
Type: System..::..Double
On entry: if weights were used to calculate c then sw is the sum of positive weight values; otherwise sw is the number of observations used to calculate c.
Constraint: sw>1.0.
isx
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: the value of isx[j-1] determines the set of variables used to perform full stepwise model selection, for j=1,2,…,m.
isx[j-1]=-1
To exclude the variable corresponding to the jth column of X from the final model.
isx[j-1]=1
To consider the variable corresponding to the jth column of X for selection in the final model.
isx[j-1]=2
To force the inclusion of the variable corresponding to the jth column of X in the final model.
Constraint: isx[j-1]=-1,1​ or ​2, for j=1,2,…,m.
On exit: the value of isx[j-1] indicates the status of the jth explanatory variable in the model.
isx[j-1]=-1
Forced exclusion.
isx[j-1]=0
Excluded.
isx[j-1]=1
Selected.
isx[j-1]=2
Forced selection.
fin
Type: System..::..Double
On entry: the value of the variance ratio which an explanatory variable must exceed to be included in a model.
Suggested value: fin=4.0
Constraint: fin>0.0.
fout
Type: System..::..Double
On entry: the explanatory variable in a model with the lowest variance ratio value is removed from the model if its value is less than fout. fout is usually set equal to the value of fin; a value less than fin is occasionally preferred.
Suggested value: fout=fin
Constraint: 0.0≤fout≤fin.
tau
Type: System..::..Double
On entry: the tolerance, τ, for detecting collinearities between variables when adding or removing an explanatory variable from a model. Explanatory variables deemed to be collinear are excluded from the final model.
Suggested value: tau=1.0×10-6
Constraint: tau>0.0.
b
Type: array< System..::..Double >[]()[][]
An array of size [m+1]
On exit: b[0] contains the estimate for the intercept term in the fitted model. If isx[j-1]≠0 then b[j+1-1] contains the estimate for the jth explanatory variable in the fitted model; otherwise b[j+1-1]=0.
se
Type: array< System..::..Double >[]()[][]
An array of size [m+1]
On exit: se[j-1] contains the standard error for the estimate of b[j-1], for j=1,2,…,m+1.
rsq
Type: System..::..Double %
On exit: the R 2-statistic for the fitted regression model.
rms
Type: System..::..Double %
On exit: the mean square of residuals for the fitted regression model.
df
Type: System..::..Int32 %
On exit: the number of degrees of freedom for the sum of squares of residuals.
monlev
Type: System..::..Int32
On entry: if a submethod is provided by you to monitor the model selection process, set monlev to 1; otherwise set monlev to 0.
Constraint: monlev=0 or 1.
monfun
Type: NagLibrary..::..G02..::..G02EF_MONFUN
You may define your own function or specify the NAG defined default function G02EFH.

A delegate of type G02EF_MONFUN.

ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The general multiple linear regression model is defined by
y=β 0+Xβ+ε,
where
  • y is a vector of n observations on the dependent variable,
  • β 0 is an intercept coefficient,
  • X is an n by p matrix of p explanatory variables,
  • β is a vector of p unknown coefficients, and
  • ε is a vector of length n of unknown, Normally distributed, random errors.
g02ef employs a full stepwise regression to select a subset of explanatory variables from the p available variables (the intercept is included in the model) and computes regression coefficients and their standard errors, and various other statistical quantities, by minimizing the sum of squares of residuals. The method applies repeatedly a forward selection step followed by a backward elimination step and halts when neither step updates the current model.
The criterion used to update a current model is the variance ratio of residual sum of squares. Let s 1 and s 2 be the residual sum of squares of the current model and this model after undergoing a single update, with degrees of freedom q 1 and q 2, respectively. Then the condition:
s 2-s 1/q 2-q 1s 1/q 1>f 1,
must be satisfied if a variable k will be considered for entry to the current model, and the condition:
s 1-s 2/q 1-q 2s 1/q 1<f 2,
must be satisfied if a variable k will be considered for removal from the current model, where f 1 and f 2 are user-supplied values and f 2≤f 1.
In the entry step the entry statistic is computed for each variable not in the current model. If no variable is associated with a test value that exceeds f 1 then this step is terminated; otherwise the variable associated with the largest value for the entry statistic is entered into the model.
In the removal step the removal statistic is computed for each variable in the current model. If no variable is associated with a test value less than f 2 then this step is terminated; otherwise the variable associated with the smallest value for the removal statistic is removed from the model.
The data values X and y are not provided as input to the method. Instead, summary statistics of the design and data matrix Z=X∣y are required.
Explanatory variables are entered into and removed from the current model by using sweep operations on the correlation matrix R of Z, given by:
R=1…r 1 pr 1 y⋮⋱⋮⋮r p 1…1r pyr y 1…r yp1,
where r ij is the correlation between the explanatory variables i and j, for i=1,2,…,p and j=1,2,…,p, and r yi (and r iy) is the correlation between the response variable y and the ith explanatory variable, for i=1,2,…,p.
A sweep operation on the kth row and column (k≤p) of R replaces:
r kk​ by ​-1/r kk;r ik​ by ​r ik/r kk, i=1,2,…,p+1​ ​i≠k;r kj​ by ​r kj/r kk, j=1,2,…,p+1​ ​j≠k;r ij​ by ​r ij-r ikr kj/r kk,  ​i=1,2,…,p+1​ ​i≠k; ​j=1,2,…,p+1​ ​j≠k.
The kth explanatory variable is eligible for entry into the current model if it satisfies the collinearity tests: r kk>τ and
r ii-r ikr kir kk τ≤1,
for a user-supplied value (>0) of τ and where the index i runs over explanatory variables in the current model. The sweep operation is its own inverse, therefore pivoting on an explanatory variable k in the current model has the effect of removing it from the model.
Once the stepwise model selection procedure is finished, the method calculates:
(a) | the least squares estimate for the ith explanatory variable included in the fitted model;
(b) | standard error estimates for each coefficient in the final model;
(c) | the square root of the mean square of residuals and its degrees of freedom;
(d) | the multiple correlation coefficient.
The method makes use of the symmetry of the sweep operations and correlation matrix which reduces by almost one half the storage and computation required by the sweep algorithm, see Clarke (1981) for details.

References

Clarke M R B (1981) Algorithm AS 178: the Gauss–Jordan sweep operator with detection of collinearity Appl. Statist. 31 166–169
Dempster A P (1969) Elements of Continuous Multivariate Analysis Addison–Wesley
Draper N R and Smith H (1985) Applied Regression Analysis (2nd Edition) Wiley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | m≤1,
or | n≤1,
or | sw≤1.0,
or | fin≤0.0,
or | fout<0.0,
or | fout>fin,
or | tau≤0.0.
ifail=2
On entry, | at least one element of isx was set incorrectly,
or | there are no explanatory variables to select from isx[i-1]≠1, for i=1,2,…,m,
or | invalid value for monlev.
ifail=3
Warning: the design and data matrix Z is not positive definite, results may be inaccurate.
ifail=4
All variables are collinear, there is no model to select.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

g02ef returns a warning if the design and data matrix is not positive definite.

Parallelism and Performance

None.

Further Comments

Although the condition for removing or adding a variable to the current model is based on a ratio of variances, these values should not be interpreted as F-statistics with the usual interpretation of significance unless the probability levels are adjusted to account for correlations between variables under consideration and the number of possible updates (see, e.g., Draper and Smith (1985)).
g02ef allocates internally O 4×m+m+1×m+2/2+2 of real storage.

Example

Example program (C#): g02efe.cs

Example program data: g02efe.d

Example program results: g02efe.r

See Also

G02 Class
G02 Members


g02fa Method

[image]

NAG Library for .NET Release 2
G02..::g02fa Method
G02 Class See Also Send Feedback
g02fa calculates two types of standardized residuals and two measures of influence for a linear regression.

Syntax

C#
public static void g02fa(
    int n,
    int ip,
    int nres,
    double[] res,
    double[] h,
    double rms,
    double[,] sres,
    out int ifail
)
Visual Basic
Public Shared Sub g02fa ( _
    n As Integer, _
    ip As Integer, _
    nres As Integer, _
    res As Double(), _
    h As Double(), _
    rms As Double, _
    sres As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02fa(
    int n,
    int ip,
    int nres,
    array<double>^ res,
    array<double>^ h,
    double rms,
    array<double,2>^ sres,
    [OutAttribute] int% ifail
)
F#
static member g02fa :
        n : int *
        ip : int *
        nres : int *
        res : float[] *
        h : float[] *
        rms : float *
        sres : float[,] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations included in the regression.
Constraint: n>ip+1.
ip
Type: System..::..Int32
On entry: p, the number of linear parameters estimated in the regression model.
Constraint: ip≥1.
nres
Type: System..::..Int32
On entry: the number of residuals.
Constraint: 1≤nres≤n.
res
Type: array< System..::..Double >[]()[][]
An array of size [nres]
On entry: the residuals, ri.
h
Type: array< System..::..Double >[]()[][]
An array of size [nres]
On entry: the diagonal elements of H, hi, corresponding to the residuals in res.
Constraint: 0.0<h[i]<1.0, for i=0,1,…,nres-1.
rms
Type: System..::..Double
On entry: the estimate of σ 2 based on all n observations, s 2, i.e., the residual mean square.
Constraint: rms>0.0.
sres
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, 4]
Note: dim1 must satisfy the constraint: dim1≥nres
On exit: the standardized residuals and influence statistics.
For the observation with residual, ri, given in res[i-1].
sres[i-1,0]
Is the internally standardized residual, RIi.
sres[i-1,1]
Is the externally standardized residual, REi.
sres[i-1,2]
Is Cook's D statistic, Di.
sres[i-1,3]
Is Atkinson's T statistic, Ti.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

For the general linear regression model
y=Xβ+ε,
where | y is a vector of length n of the dependent variable,
 | X is an n by p matrix of the independent variables,
 | β is a vector of length p of unknown parameters,
and | ε is a vector of length n of unknown random errors such that var ε=σ 2 I.
The residuals are given by
r=y-y^=y-X β^
and the fitted values, y^=X β^, can be written as Hy for an n by n matrix H. The ith diagonal elements of H, hi, give a measure of the influence of the ith values of the independent variables on the fitted regression model. The values of r and the hi are returned by g02da.
g02fa calculates statistics which help to indicate if an observation is extreme and having an undue influence on the fit of the regression model. Two types of standardized residual are calculated:
(i) The ith residual is standardized by its variance when the estimate of σ 2, s 2, is calculated from all the data; this is known as internal Studentization.
R Ii=ri s⁢1-hi.
(ii) The ith residual is standardized by its variance when the estimate of σ 2, s-i 2 is calculated from the data excluding the ith observation; this is known as external Studentization.
R Ei=ri s-i 1-hi=ri n-p-1n-p-R Ii 2.
The two measures of influence are:
(i) Cook's D
Di=1 p R Ei 2 hi 1-hi.
(ii) Atkinson's T
Ti=R Ei n-p phi 1-hi.

References

Atkinson A C (1981) Two graphical displays for outlying and influential observations in regression Biometrika 68 13–20
Cook R D and Weisberg S (1982) Residuals and Influence in Regression Chapman and Hall

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDSRES) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | ip<1,
or | n≤ip+1,
or | nres<1,
or | nres>n,
or | rms≤0.0.
ifail=2
On entry, h[i-1]≤0.0 or ≥1.0, for some i=1,2,…,nres.
ifail=3
On entry, the value of a residual is too large for the given value of rms.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Accuracy is sufficient for all practical purposes.

Parallelism and Performance

None.

Further Comments

None.

Example

A set of 24 residuals and hi values from a 11 parameter model fitted to the cloud seeding data considered in Cook and Weisberg (1982) are input and the standardized residuals etc calculated and printed for the first 10 observations.

Example program (C#): g02fae.cs

Example program data: g02fae.d

Example program results: g02fae.r

See Also

G02 Class
G02 Members


g02fc Method

[image]

NAG Library for .NET Release 2
G02..::g02fc Method
G02 Class See Also Send Feedback
g02fc calculates the Durbin–Watson statistic, for a set of residuals, and the upper and lower bounds for its significance.

Syntax

C#
public static void g02fc(
    int n,
    int ip,
    double[] res,
    out double d,
    out double pdl,
    out double pdu,
    out int ifail
)
Visual Basic
Public Shared Sub g02fc ( _
    n As Integer, _
    ip As Integer, _
    res As Double(), _
    <OutAttribute> ByRef d As Double, _
    <OutAttribute> ByRef pdl As Double, _
    <OutAttribute> ByRef pdu As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02fc(
    int n,
    int ip,
    array<double>^ res,
    [OutAttribute] double% d,
    [OutAttribute] double% pdl,
    [OutAttribute] double% pdu,
    [OutAttribute] int% ifail
)
F#
static member g02fc :
        n : int *
        ip : int *
        res : float[] *
        d : float byref *
        pdl : float byref *
        pdu : float byref *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of residuals.
Constraint: n>ip.
ip
Type: System..::..Int32
On entry: p, the number of independent variables in the regression model, including the mean.
Constraint: ip≥1.
res
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the residuals, r 1,r 2,…,rn.
Constraint: the mean of the residuals ≤ε, where ε=machine precision.
d
Type: System..::..Double %
On exit: the Durbin–Watson statistic, d.
pdl
Type: System..::..Double %
On exit: lower bound for the significance of the Durbin–Watson statistic, pl.
pdu
Type: System..::..Double %
On exit: upper bound for the significance of the Durbin–Watson statistic, pu.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

For the general linear regression model
y=Xβ+ε,
where | y is a vector of length n of the dependent variable, X is a n by p matrix of the independent variables, β is a vector of length p of unknown parameters,
and | ε is a vector of length n of unknown random errors.
The residuals are given by
r=y-y^=y-X β^
and the fitted values, y^=X β^, can be written as Hy for a n by n matrix H. Note that when a mean term is included in the model the sum of the residuals is zero. If the observations have been taken serially, that is y 1,y 2,…,yn can be considered as a time series, the Durbin–Watson test can be used to test for serial correlation in the εi, see Durbin and Watson (1950), Durbin and Watson (1951) and Durbin and Watson (1971).
The Durbin–Watson statistic is
d=∑i=1n-1 r i+1-ri 2∑i=1 n ri 2.
Positive serial correlation in the εi will lead to a small value of d while for independent errors d will be close to 2. Durbin and Watson show that the exact distribution of d depends on the eigenvalues of the matrix HA where the matrix A is such that d can be written as
d=rT ArrT r
and the eigenvalues of the matrix A are λj=1-cos πj/n, for j=1,2,…,n-1.
However bounds on the distribution can be obtained, the lower bound being
dl=∑i=1n-p λi ui 2∑i=1n-p ui 2
and the upper bound being
du=∑i=1n-p λ i-1+p ui 2∑i=1n-p ui 2,
where the ui are independent standard Normal variables. The lower tail probabilities associated with these bounds, pl and pu, are computed by g01ep. The interpretation of the bounds is that, for a test of size (significance) α, if pl≤α the test is significant, if pu>α the test is not significant, while if pl>α and pu≤α no conclusion can be reached.
The above probabilities are for the usual test of positive auto-correlation. If the alternative of negative auto-correlation is required, then a call to g01ep should be made with the parameter d taking the value of 4-d; see Newbold (1988).

References

Durbin J and Watson G S (1950) Testing for serial correlation in least squares regression. I Biometrika 37 409–428
Durbin J and Watson G S (1951) Testing for serial correlation in least squares regression. II Biometrika 38 159–178
Durbin J and Watson G S (1971) Testing for serial correlation in least squares regression. III Biometrika 58 1–19
Granger C W J and Newbold P (1986) Forecasting Economic Time Series (2nd Edition) Academic Press
Newbold P (1988) Statistics for Business and Economics Prentice–Hall

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | n≤ip,
or | ip<1.
ifail=2
On entry, the mean of the residuals was >ε, where ε=machine precision.
ifail=3
On entry, all residuals are identical.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The probabilities are computed to an accuracy of at least 4 decimal places.

Parallelism and Performance

None.

Further Comments

If the exact probabilities are required, then the first n-p eigenvalues of HA can be computed and g01jd used to compute the required probabilities with the parameter c set to 0.0 and the parameter d set to the Durbin–Watson statistic d.

Example

A set of 10 residuals are read in and the Durbin–Watson statistic along with the probability bounds are computed and printed.

Example program (C#): g02fce.cs

Example program data: g02fce.d

Example program results: g02fce.r

See Also

G02 Class
G02 Members


g02ga Method

[image]

NAG Library for .NET Release 2
G02..::g02ga Method
G02 Class See Also Send Feedback
g02ga fits a generalized linear model with normal errors.

Syntax

C#
public static void g02ga(
    string link,
    string mean,
    string offset,
    string weight,
    int n,
    double[,] x,
    int m,
    int[] isx,
    int ip,
    double[] y,
    double[] wt,
    ref double s,
    double a,
    out double rss,
    out int idf,
    double[] b,
    out int irank,
    double[] se,
    double[] cov,
    double[,] v,
    double tol,
    int maxit,
    int iprint,
    double eps,
    out int ifail
)
Visual Basic
Public Shared Sub g02ga ( _
    link As String, _
    mean As String, _
    offset As String, _
    weight As String, _
    n As Integer, _
    x As Double(,), _
    m As Integer, _
    isx As Integer(), _
    ip As Integer, _
    y As Double(), _
    wt As Double(), _
    ByRef s As Double, _
    a As Double, _
    <OutAttribute> ByRef rss As Double, _
    <OutAttribute> ByRef idf As Integer, _
    b As Double(), _
    <OutAttribute> ByRef irank As Integer, _
    se As Double(), _
    cov As Double(), _
    v As Double(,), _
    tol As Double, _
    maxit As Integer, _
    iprint As Integer, _
    eps As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02ga(
    String^ link,
    String^ mean,
    String^ offset,
    String^ weight,
    int n,
    array<double,2>^ x,
    int m,
    array<int>^ isx,
    int ip,
    array<double>^ y,
    array<double>^ wt,
    double% s,
    double a,
    [OutAttribute] double% rss,
    [OutAttribute] int% idf,
    array<double>^ b,
    [OutAttribute] int% irank,
    array<double>^ se,
    array<double>^ cov,
    array<double,2>^ v,
    double tol,
    int maxit,
    int iprint,
    double eps,
    [OutAttribute] int% ifail
)
F#
static member g02ga :
        link : string *
        mean : string *
        offset : string *
        weight : string *
        n : int *
        x : float[,] *
        m : int *
        isx : int[] *
        ip : int *
        y : float[] *
        wt : float[] *
        s : float byref *
        a : float *
        rss : float byref *
        idf : int byref *
        b : float[] *
        irank : int byref *
        se : float[] *
        cov : float[] *
        v : float[,] *
        tol : float *
        maxit : int *
        iprint : int *
        eps : float *
        ifail : int byref -> unit

Parameters

link
Type: System..::..String
On entry: indicates which link function is to be used.
link="E"
An exponent link is used.
link="I"
An identity link is used. You are advised not to use g02ga with an identity link as g02da provides a more efficient way of fitting such a model.
link="L"
A log link is used.
link="S"
A square root link is used.
link="R"
A reciprocal link is used.
Constraint: link="E", "I", "L", "S" or "R".
mean
Type: System..::..String
On entry: indicates if a mean term is to be included.
mean="M"
A mean term, intercept, will be included in the model.
mean="Z"
The model will pass through the origin, zero-point.
Constraint: mean="M" or "Z".
offset
Type: System..::..String
On entry: indicates if an offset is required.
offset="Y"
An offset is required and the offsets must be supplied in the seventh column of v.
offset="N"
No offset is required.
Constraint: offset="N" or "Y".
weight
Type: System..::..String
On entry: indicates if prior weights are to be used.
weight="U"
No prior weights are used.
weight="W"
Prior weights are used and weights must be supplied in wt.
Constraint: weight="U" or "W".
n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n≥2.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must contain the ith observation for the jth independent variable, for i=1,2,…,n and j=1,2,…,m.
m
Type: System..::..Int32
On entry: m, the total number of independent variables.
Constraint: m≥1.
isx
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: indicates which independent variables are to be included in the model.
If isx[j-1]>0, the variable contained in the jth column of x is included in the regression model.
Constraints:
  • isx[j-1]≥0, for i=0,1,…,m-1;
  • if mean="M", exactly ip-1 values of isx must be >0;
  • if mean="Z", exactly ip values of isx must be >0.
ip
Type: System..::..Int32
On entry: the number of independent variables in the model, including the mean or intercept if present.
Constraint: ip>0.
y
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the observations on the dependent variable, yi, for i=1,2,…,n.
wt
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array wt must be at least n if weight="W", and at least 1 otherwise.
On entry: if weight="W", wt must contain the weights to be used with the model, ωi. If wt[i-1]=0.0, the ith observation is not included in the model, in which case the effective number of observations is the number of observations with nonzero weights.
If weight="U", wt is not referenced and the effective number of observations is n.
Constraint: if weight="W", wt[i]≥0.0, for i=0,1,…,n-1.
s
Type: System..::..Double %
On entry: the scale parameter for the model, σ 2.
If s=0.0, the scale parameter is estimated with the method using the residual mean square.
On exit: if on input s=0.0, s contains the estimated value of the scale parameter, σ^2.
If on input s≠0.0, s is unchanged on exit.
Constraint: s≥0.0.
a
Type: System..::..Double
On entry: if link="E", a must contain the power of the exponential.
If link≠"E", a is not referenced.
Constraint: if link="E", a≠0.0.
rss
Type: System..::..Double %
On exit: the residual sum of squares for the fitted model.
idf
Type: System..::..Int32 %
On exit: the degrees of freedom associated with the residual sum of squares for the fitted model.
b
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On exit: the estimates of the parameters of the generalized linear model, β^.
If mean="M", b[0] will contain the estimate of the mean parameter and b[i] will contain the coefficient of the variable contained in column j of x, where isx[j-1] is the ith positive value in the array isx.
If mean="Z", b[i-1] will contain the coefficient of the variable contained in column j of x, where isx[j-1] is the ith positive value in the array isx.
irank
Type: System..::..Int32 %
On exit: the rank of the independent variables.
If the model is of full rank, irank=ip.
If the model is not of full rank, irank is an estimate of the rank of the independent variables. irank is calculated as the number of singular values greater than eps× (largest singular value). It is possible for the SVD to be carried out but for irank to be returned as ip.
se
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On exit: the standard errors of the linear parameters.
se[i-1] contains the standard error of the parameter estimate in b[i-1], for i=1,2,…,ip.
cov
Type: array< System..::..Double >[]()[][]
An array of size [ip×ip+1/2]
On exit: the upper triangular part of the variance-covariance matrix of the ip parameter estimates given in b. They are stored packed by column, i.e., the covariance between the parameter estimate given in b[i-1] and the parameter estimate given in b[j-1], j≥i, is stored in cov[j×j-1/2+i-1].
v
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, ip+7]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: if offset="N", v need not be set.
If offset="Y", v[i-1,6], for i=1,2,…,n, must contain the offset values oi. All other values need not be set.
On exit: auxiliary information on the fitted model.
v[i-1,0] | contains the linear predictor value, ηi, for i=1,2,…,n.
v[i-1,1] | contains the fitted value, μ^i, for i=1,2,…,n.
v[i-1,2] | is only included for consistency with other methods. v[i-1,2]=1.0, for i=1,2,…,n.
v[i-1,3] | contains the square root of the working weight, wi 12, for i=1,2,…,n.
v[i-1,4] | contains the residual, ri, for i=1,2,…,n.
v[i-1,5] | contains the leverage, hi, for i=1,2,…,n.
v[i-1,6] | contains the offset, for i=1,2,…,n. If offset="N", all values will be zero.
v[i-1,j-1], | for j=8,…,ip+7, contains the results of the QR decomposition or the singular value decomposition.
If the model is not of full rank, i.e., irank<ip, the first ip rows of columns 8 to ip+7 contain the P* matrix.
tol
Type: System..::..Double
On entry: indicates the accuracy required for the fit of the model.
The iterative weighted least squares procedure is deemed to have converged if the absolute change in deviance between interactions is less than tol×1.0+current residual sum of squares. This is approximately an absolute precision if the residual sum of squares is small and a relative precision if the residual sum of squares is large.
If 0.0≤tol<machine precision, g02ga will use 10×machine precision.
Constraint: tol≥0.0.
maxit
Type: System..::..Int32
On entry: the maximum number of iterations for the iterative weighted least squares.
If maxit=0, a default value of 10 is used.
Constraint: maxit≥0.
iprint
Type: System..::..Int32
On entry: indicates if the printing of information on the iterations is required.
iprint≤0
There is no printing.
iprint>0
Every iprint iteration, the following is printed:
the deviance,
the current estimates,
and if the weighted least squares equations are singular then this is indicated.
When printing occurs the output is directed to the current advisory message unit (see (X04ABF not in this release)).
eps
Type: System..::..Double
On entry: the value of eps is used to decide if the independent variables are of full rank and, if not, what is the rank of the independent variables. The smaller the value of eps the stricter the criterion for selecting the singular value decomposition.
If 0.0≤eps<machine precision, the method will use machine precision instead.
Constraint: eps≥0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

A generalized linear model with Normal errors consists of the following elements:
(a) a set of n observations, yi, from a Normal distribution with probability density function:
1 2 π σ exp-y-μ 2 2 σ 2,
where μ is the mean and σ 2 is the variance.
(b) | X, a set of p independent variables for each observation, x 1,x 2,…,xp.
(c) a linear model:
η=∑βjxj.
(d) a link between the linear predictor, η, and the mean of the distribution, μ, i.e., η=g μ. The possible link functions are:
(i) | exponent link: η=μa, for a constant a,
(ii) | identity link: η=μ,
(iii) | log link: η=log μ,
(iv) | square root link: η=μ,
(v) | reciprocal link: η=1 μ.
(e) | a measure of fit, the residual sum of squares =∑yi-μ^i 2.
The linear parameters are estimated by iterative weighted least squares. An adjusted dependent variable, z, is formed:
z=η+y-μ dηdμ
and a working weight, w,
w=dηdμ 2.
At each iteration an approximation to the estimate of β, β^, is found by the weighted least squares regression of z on X with weights w.
g02ga finds a QR decomposition of w 12 X, i.e., w 12 X=QR where R is a p by p triangular matrix and Q is an n by p column orthogonal matrix.
If R is of full rank, then β^ is the solution to
R β^=QTw 12 z.
If R is not of full rank a solution is obtained by means of a singular value decomposition (SVD) of R.
R=Q*D000 PT,
where D is a k by k diagonal matrix with nonzero diagonal elements, k being the rank of R and w 12 X.
This gives the solution
β^=P 1 D-1 Q*00I QTw 12 z
P 1 being the first k columns of P, i.e., P=P 1P 0.
The iterations are continued until there is only a small change in the residual sum of squares.
The initial values for the algorithm are obtained by taking
η^=g y.
The fit of the model can be assessed by examining and testing the residual sum of squares, in particular comparing the difference in residual sums of squares between nested models, i.e., when one model is a sub-model of the other.
Let RSSf be the residual sum of squares for the full model with degrees of freedom νf and let RSSs be the residual sum of squares for the sub-model with degrees of freedom νs then:
F=RSSs-RSSf/νs-νfRSSf/νf,
has, approximately, an F-distribution with (νs-νf), νf degrees of freedom.
The parameter estimates, β^, are asymptotically Normally distributed with variance-covariance matrix:
  • C=R-1R-1 Tσ 2 in the full rank case,
  • otherwise C=P 1 D-2 P 1 T σ 2
The residuals and influence statistics can also be examined.
The estimated linear predictor η^=X β^, can be written as H w 12 z for an n by n matrix H. The ith diagonal elements of H, hi, give a measure of the influence of the ith values of the independent variables on the fitted regression model. These are sometimes known as leverages.
The fitted values are given by μ^=g-1 η^.
g02ga also computes the residuals, r:
ri=yi-μ^i.
An option allows prior weights ωi to be used; this gives a model with:
σi 2=σ 2 ωi.
In many linear regression models the first term is taken as a mean term or an intercept, i.e., x i,1=1, for i=1,2,…,n; this is provided as an option.
Often only some of the possible independent variables are included in a model, the facility to select variables to be included in the model is provided.
If part of the linear predictor can be represented by a variable with a known coefficient, then this can be included in the model by using an offset, o:
η=o+∑βjxj.
If the model is not of full rank the solution given will be only one of the possible solutions. Other estimates may be obtained by applying constraints to the parameters. These solutions can be obtained by using g02gk after using g02ga. Only certain linear combinations of the parameters will have unique estimates; these are known as estimable functions and can be estimated and tested using g02gn.
Details of the SVD are made available, in the form of the matrix P*:
P*=D-1 P 1 TP 0 T.

References

Cook R D and Weisberg S (1982) Residuals and Influence in Regression Chapman and Hall
McCullagh P and Nelder J A (1983) Generalized Linear Models Chapman and Hall

Error Indicators and Warnings

Note: g02ga may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDV) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | n<2,
or | m<1,
or | ip<1,
or | link≠"E","I","L","S" or "R",
or | s<0.0,
or | link="E" and a=0.0,
or | mean≠"M" or "Z",
or | weight≠"U" or "W",
or | offset≠"N" or "Y",
or | maxit<0,
or | tol<0.0,
or | eps<0.0.
ifail=3
On entry, | a value of isx<0,
or | the value of ip is incompatible with the values of mean and isx,
or | ip is greater than the effective number of observations.
ifail=4
A fitted value is at a boundary. This will only occur with link="L", "R" or "E". This may occur if there are small values of y and the model is not suitable for the data. The model should be reformulated with, perhaps, some observations dropped.
ifail=5
The singular value decomposition has failed to converge. This is an unlikely error exit, see (F02WUF not in this release).
ifail=6
The iterative weighted least squares has failed to converge in maxit (or default 10) iterations. The value of maxit could be increased but it may be advantageous to examine the convergence using the iprint option. This may indicate that the convergence is slow because the solution is at a boundary in which case it may be better to reformulate the model.
ifail=7
The rank of the model has changed during the weighted least squares iterations. The estimate for β returned may be reasonable, but you should check how the deviance has changed during iterations.
ifail=8
The degrees of freedom for error are 0. A saturated model has been fitted.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The accuracy is determined by tol as described in [Parameters]. As the residual sum of squares is a function of μ 2 the accuracy of the β^ will depend on the link used and may be of the order tol.

Parallelism and Performance

None.

Further Comments

None.

Example

The model:
y=1 β 1+β 2 x+ε
for a sample of five observations.

Example program (C#): g02gae.cs

Example program data: g02gae.d

Example program results: g02gae.r

See Also

G02 Class
G02 Members


g02gb Method

[image]

NAG Library for .NET Release 2
G02..::g02gb Method
G02 Class See Also Send Feedback
g02gb fits a generalized linear model with binomial errors.

Syntax

C#
public static void g02gb(
    string link,
    string mean,
    string offset,
    string weight,
    int n,
    double[,] x,
    int m,
    int[] isx,
    int ip,
    double[] y,
    double[] t,
    double[] wt,
    out double dev,
    out int idf,
    double[] b,
    out int irank,
    double[] se,
    double[] cov,
    double[,] v,
    double tol,
    int maxit,
    int iprint,
    double eps,
    out int ifail
)
Visual Basic
Public Shared Sub g02gb ( _
    link As String, _
    mean As String, _
    offset As String, _
    weight As String, _
    n As Integer, _
    x As Double(,), _
    m As Integer, _
    isx As Integer(), _
    ip As Integer, _
    y As Double(), _
    t As Double(), _
    wt As Double(), _
    <OutAttribute> ByRef dev As Double, _
    <OutAttribute> ByRef idf As Integer, _
    b As Double(), _
    <OutAttribute> ByRef irank As Integer, _
    se As Double(), _
    cov As Double(), _
    v As Double(,), _
    tol As Double, _
    maxit As Integer, _
    iprint As Integer, _
    eps As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02gb(
    String^ link,
    String^ mean,
    String^ offset,
    String^ weight,
    int n,
    array<double,2>^ x,
    int m,
    array<int>^ isx,
    int ip,
    array<double>^ y,
    array<double>^ t,
    array<double>^ wt,
    [OutAttribute] double% dev,
    [OutAttribute] int% idf,
    array<double>^ b,
    [OutAttribute] int% irank,
    array<double>^ se,
    array<double>^ cov,
    array<double,2>^ v,
    double tol,
    int maxit,
    int iprint,
    double eps,
    [OutAttribute] int% ifail
)
F#
static member g02gb :
        link : string *
        mean : string *
        offset : string *
        weight : string *
        n : int *
        x : float[,] *
        m : int *
        isx : int[] *
        ip : int *
        y : float[] *
        t : float[] *
        wt : float[] *
        dev : float byref *
        idf : int byref *
        b : float[] *
        irank : int byref *
        se : float[] *
        cov : float[] *
        v : float[,] *
        tol : float *
        maxit : int *
        iprint : int *
        eps : float *
        ifail : int byref -> unit

Parameters

link
Type: System..::..String
On entry: indicates which link function is to be used.
link="G"
A logistic link is used.
link="P"
A probit link is used.
link="C"
A complementary log-log link is used.
Constraint: link="G", "P" or "C".
mean
Type: System..::..String
On entry: indicates if a mean term is to be included.
mean="M"
A mean term, intercept, will be included in the model.
mean="Z"
The model will pass through the origin, zero-point.
Constraint: mean="M" or "Z".
offset
Type: System..::..String
On entry: indicates if an offset is required.
offset="Y"
An offset is required and the offsets must be supplied in the seventh column of v.
offset="N"
No offset is required.
Constraint: offset="N" or "Y".
weight
Type: System..::..String
On entry: indicates if prior weights are to be used.
weight="U"
No prior weights are used.
weight="W"
Prior weights are used and weights must be supplied in wt.
Constraint: weight="U" or "W".
n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n≥2.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must contain the ith observation for the jth independent variable, for i=1,2,…,n and j=1,2,…,m.
m
Type: System..::..Int32
On entry: m, the total number of independent variables.
Constraint: m≥1.
isx
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: indicates which independent variables are to be included in the model.
isx[j-1]>0
The variable contained in the jth column of x is included in the regression model.
Constraints:
  • isx[j]≥0, for j=0,1,…,m-1;
  • if mean="M", exactly ip-1 values of isx must be >0;
  • if mean="Z", exactly ip values of isx must be >0.
ip
Type: System..::..Int32
On entry: the number of independent variables in the model, including the mean or intercept if present.
Constraint: ip>0.
y
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the observations on the dependent variable, yi, for i=1,2,…,n.
Constraint: 0.0≤y[i]≤t[i], for i=0,1,…,n-1.
t
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: t, the binomial denominator.
Constraint: t[i]≥0.0, for i=0,1,…,n-1.
wt
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array wt must be at least n if weight="W", and at least 1 otherwise.
On entry: if weight="W", wt must contain the weights to be used in the weighted regression. If wt[i-1]=0.0, the ith observation is not included in the model, in which case the effective number of observations is the number of observations with nonzero weights.
If weight="U", wt is not referenced and the effective number of observations is n.
Constraint: if weight="W", wt[i]≥0.0, for i=0,1,…,n-1.
dev
Type: System..::..Double %
On exit: the deviance for the fitted model.
idf
Type: System..::..Int32 %
On exit: the degrees of freedom associated with the deviance for the fitted model.
b
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On exit: the estimates of the parameters of the generalized linear model, β^.
If mean="M", the first element of b will contain the estimate of the mean parameter and b[i] will contain the coefficient of the variable contained in column j of x, where isx[j-1] is the ith positive value in the array isx.
If mean="Z", b[i-1] will contain the coefficient of the variable contained in column j of x, where isx[j-1] is the ith positive value in the array isx.
irank
Type: System..::..Int32 %
On exit: the rank of the independent variables.
If the model is of full rank, irank=ip.
If the model is not of full rank, irank is an estimate of the rank of the independent variables. irank is calculated as the number of singular values greater that eps×(largest singular value).
It is possible for the SVD to be carried out but for irank to be returned as ip.
se
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On exit: the standard errors of the linear parameters.
se[i-1] contains the standard error of the parameter estimate in b[i-1], for i=1,2,…,ip.
cov
Type: array< System..::..Double >[]()[][]
An array of size [ip×ip+1/2]
On exit: the upper triangular part of the variance-covariance matrix of the ip parameter estimates given in b. They are stored in packed form by column, i.e., the covariance between the parameter estimate given in b[i-1] and the parameter estimate given in b[j-1], j≥i, is stored in cov[j×j-1/2+i-1].
v
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, ip+7]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: if offset="N", v need not be set.
If offset="Y", v[i-1,6], for i=1,2,…,n must contain the offset values oi. All other values need not be set.
On exit: auxiliary information on the fitted model.
v[i-1,0] | contains the linear predictor value, ηi, for i=1,2,…,n.
v[i-1,1] | contains the fitted value, μ^i, for i=1,2,…,n.
v[i-1,2] | contains the variance standardization, 1 τi, for i=1,2,…,n.
v[i-1,3] | contains the square root of the working weight, wi 12, for i=1,2,…,n.
v[i-1,4] | contains the deviance residual, ri, for i=1,2,…,n.
v[i-1,5] | contains the leverage, hi, for i=1,2,…,n.
v[i-1,6] | contains the offset, oi, for i=1,2,…,n. If offset="N", all values will be zero.
v[i-1,j-1] | for j=8,…,ip+7, contains the results of the QR decomposition or the singular value decomposition.
If the model is not of full rank, i.e., irank<ip, the first ip rows of columns 8 to ip+7 contain the P* matrix.
tol
Type: System..::..Double
On entry: indicates the accuracy required for the fit of the model.
The iterative weighted least squares procedure is deemed to have converged if the absolute change in deviance between iterations is less than tol×1.0+Current Deviance. This is approximately an absolute precision if the deviance is small and a relative precision if the deviance is large.
If 0.0≤tol<machine precision, the method will use 10×machine precision instead.
Constraint: tol≥0.0.
maxit
Type: System..::..Int32
On entry: the maximum number of iterations for the iterative weighted least squares.
If maxit=0, a default value of 10 is used.
Constraint: maxit≥0.
iprint
Type: System..::..Int32
On entry: indicates if the printing of information on the iterations is required.
iprint≤0
There is no printing.
iprint>0
The following is printed every iprint iterations:
  • the deviance,
  • the current estimates,
  • and if the weighted least squares equations are singular, then this is indicated.
When printing occurs the output is directed to the current advisory message unit (see (X04ABF not in this release)).
eps
Type: System..::..Double
On entry: the value of eps is used to decide if the independent variables are of full rank and, if not, what is the rank of the independent variables. The smaller the value of eps the stricter the criterion for selecting the singular value decomposition.
If 0.0≤eps<machine precision, the method will use machine precision instead.
Constraint: eps≥0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

A generalized linear model with binomial errors consists of the following elements:
(a) a set of n observations, yi, from a binomial distribution:
ty πy1-π t-y.
(b) X, a set of p independent variables for each observation, x 1,x 2,…,xp.
(c) a linear model:
η=∑βjxj.
(d) a link between the linear predictor, η, and the mean of the distribution, μ=πt, the link function, η=g μ. The possible link functions are:
(i) | logistic link: η=log μ t-μ,
(ii) | probit link: η=Φ-1 μt,
(iii) | complementary log-log link: log-log 1-μt.
(e) a measure of fit, the deviance:
∑i=1 n dev yi,μ^i=∑i=1 n 2 yi log yiμ^i+ti-yi log ti-yiti-μ^i.
The linear parameters are estimated by iterative weighted least squares. An adjusted dependent variable, z, is formed:
z=η+y-μ dηdμ
and a working weight, w,
w=τ dηdμ 2,   where ​τ=t μ t-μ.
At each iteration an approximation to the estimate of β, β^, is found by the weighted least squares regression of z on X with weights w.
g02gb finds a QR decomposition of w 1/2 X, i.e., w 1/2 X=QR where R is a p by p triangular matrix and Q is an n by p column orthogonal matrix.
If R is of full rank, then β^ is the solution to
R β^=QTw 1/2 z.
If R is not of full rank a solution is obtained by means of a singular value decomposition (SVD) of R.
R=Q*D000 PT,
where D is a k by k diagonal matrix with nonzero diagonal elements, k being the rank of R and w 1/2 X.
This gives the solution
β^=P 1 D-1 Q*00I QTw 1/2 z,
P 1 being the first k columns of P, i.e., P=P 1P 0.
The iterations are continued until there is only a small change in the deviance.
The initial values for the algorithm are obtained by taking
η^=g y.
The fit of the model can be assessed by examining and testing the deviance, in particular by comparing the difference in deviance between nested models, i.e., when one model is a sub-model of the other. The difference in deviance between two nested models has, asymptotically, a χ 2-distribution with degrees of freedom given by the difference in the degrees of freedom associated with the two deviances.
The parameters estimates, β^, are asymptotically Normally distributed with variance-covariance matrix
  • C=R-1R-1 T in the full rank case, otherwise
  • C=P 1 D-2 P 1 T.
The residuals and influence statistics can also be examined.
The estimated linear predictor η^=X β^, can be written as H w 1/2 z for an n by n matrix H. The ith diagonal elements of H, hi, give a measure of the influence of the ith values of the independent variables on the fitted regression model. These are sometimes known as leverages.
The fitted values are given by μ^=g-1 η^.
g02gb also computes the deviance residuals, r:
ri=sign yi-μ^i dev yi,μ^i.
An option allows the use of prior weights in the model.
In many linear regression models the first term is taken as a mean term or an intercept, i.e., x i,1=1, for i=1,2,…,n. This is provided as an option.
Often only some of the possible independent variables are included in a model; the facility to select variables to be included in the model is provided.
If part of the linear predictor can be represented by variables with a known coefficient then this can be included in the model by using an offset, o:
η=o+∑βjxj.
If the model is not of full rank the solution given will be only one of the possible solutions. Other estimates may be obtained by applying constraints to the parameters. These solutions can be obtained by using g02gk after using g02gb. Only certain linear combinations of the parameters will have unique estimates, these are known as estimable functions and can be estimated and tested using g02gn.
Details of the SVD are made available in the form of the matrix P*:
P*=D-1 P 1 TP 0 T.

References

Cook R D and Weisberg S (1982) Residuals and Influence in Regression Chapman and Hall
Cox D R (1983) Analysis of Binary Data Chapman and Hall
McCullagh P and Nelder J A (1983) Generalized Linear Models Chapman and Hall

Error Indicators and Warnings

Note: g02gb may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDV) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | n<2,
or | m<1,
or | ip<1,
or | link≠"G", "P" or "C".
or | mean≠"M" or "Z".
or | weight≠"U" or "W".
or | offset≠"N" or "Y".
or | maxit<0,
or | tol<0.0,
or | eps<0.0.
ifail=2
On entry, weight="W" and a value of wt<0.0.
ifail=3
On entry, | a value of isx<0,
or | the value of ip is incompatible with the values of mean and isx,
or | ip is greater than the effective number of observations.
ifail=4
On entry, t[i-1]<0 for some i=1,2,…,n.
ifail=5
On entry, | y[i-1]<0.0,
or | y[i-1]>t[i-1] for some i=1,2,…,n.
ifail=6
A fitted value is at the boundary, i.e., 0.0 or 1.0. This may occur if there are y values of 0.0 or t and the model is too complex for the data. The model should be reformulated with, perhaps, some observations dropped.
ifail=7
The singular value decomposition has failed to converge. This is an unlikely error exit.
ifail=8
The iterative weighted least squares has failed to converge in maxit (or default 10) iterations. The value of maxit could be increased but it may be advantageous to examine the convergence using the iprint option. This may indicate that the convergence is slow because the solution is at a boundary in which case it may be better to reformulate the model.
ifail=9
The rank of the model has changed during the weighted least squares iterations. The estimate for β returned may be reasonable, but you should check how the deviance has changed during iterations.
ifail=10
The degrees of freedom for error are 0. A saturated model has been fitted.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The accuracy will depend on the value of tol as described in [Parameters]. As the deviance is a function of log μ the accuracy of the β^ will be only a function of tol, so tol should be set smaller than the required accuracy for β^.

Parallelism and Performance

None.

Further Comments

None.

Example

A linear trend x=-1,0,1 is fitted to data relating the incidence of carriers of Streptococcus pyogenes to size of tonsils. The data is described in Cox (1983).

Example program (C#): g02gbe.cs

Example program data: g02gbe.d

Example program results: g02gbe.r

See Also

G02 Class
G02 Members


g02gc Method

[image]

NAG Library for .NET Release 2
G02..::g02gc Method
G02 Class See Also Send Feedback
g02gc fits a generalized linear model with Poisson errors.

Syntax

C#
public static void g02gc(
    string link,
    string mean,
    string offset,
    string weight,
    int n,
    double[,] x,
    int m,
    int[] isx,
    int ip,
    double[] y,
    double[] wt,
    double a,
    out double dev,
    out int idf,
    double[] b,
    out int irank,
    double[] se,
    double[] cov,
    double[,] v,
    double tol,
    int maxit,
    int iprint,
    double eps,
    out int ifail
)
Visual Basic
Public Shared Sub g02gc ( _
    link As String, _
    mean As String, _
    offset As String, _
    weight As String, _
    n As Integer, _
    x As Double(,), _
    m As Integer, _
    isx As Integer(), _
    ip As Integer, _
    y As Double(), _
    wt As Double(), _
    a As Double, _
    <OutAttribute> ByRef dev As Double, _
    <OutAttribute> ByRef idf As Integer, _
    b As Double(), _
    <OutAttribute> ByRef irank As Integer, _
    se As Double(), _
    cov As Double(), _
    v As Double(,), _
    tol As Double, _
    maxit As Integer, _
    iprint As Integer, _
    eps As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02gc(
    String^ link,
    String^ mean,
    String^ offset,
    String^ weight,
    int n,
    array<double,2>^ x,
    int m,
    array<int>^ isx,
    int ip,
    array<double>^ y,
    array<double>^ wt,
    double a,
    [OutAttribute] double% dev,
    [OutAttribute] int% idf,
    array<double>^ b,
    [OutAttribute] int% irank,
    array<double>^ se,
    array<double>^ cov,
    array<double,2>^ v,
    double tol,
    int maxit,
    int iprint,
    double eps,
    [OutAttribute] int% ifail
)
F#
static member g02gc :
        link : string *
        mean : string *
        offset : string *
        weight : string *
        n : int *
        x : float[,] *
        m : int *
        isx : int[] *
        ip : int *
        y : float[] *
        wt : float[] *
        a : float *
        dev : float byref *
        idf : int byref *
        b : float[] *
        irank : int byref *
        se : float[] *
        cov : float[] *
        v : float[,] *
        tol : float *
        maxit : int *
        iprint : int *
        eps : float *
        ifail : int byref -> unit

Parameters

link
Type: System..::..String
On entry: indicates which link function is to be used.
link="E"
An exponent link is used.
link="I"
An identity link is used.
link="L"
A log link is used;
link="S"
A square root link is used.
link="R"
A reciprocal link is used.
Constraint: link="E", "I", "L", "S" or "R".
mean
Type: System..::..String
On entry: indicates if a mean term is to be included.
mean="M"
A mean term, intercept, will be included in the model.
mean="Z"
The model will pass through the origin, zero-point.
Constraint: mean="M" or "Z".
offset
Type: System..::..String
On entry: indicates if an offset is required.
offset="Y"
An offset is required and the offsets must be supplied in the seventh column of v.
offset="N"
No offset is required.
Constraint: offset="N" or "Y".
weight
Type: System..::..String
On entry: indicates if prior weights are to be used.
weight="U"
No prior weights are used.
weight="W"
Prior weights are used and weights must be supplied in wt.
Constraint: weight="U" or "W".
n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n≥2.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: the matrix of all possible independent variables. x[i-1,j-1] must contain the ijth element of x, for i=1,2,…,n and j=1,2,…,m.
m
Type: System..::..Int32
On entry: m, the total number of independent variables.
Constraint: m≥1.
isx
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: indicates which independent variables are to be included in the model.
isx[j-1]>0
The variable contained in the jth column of x is included in the regression model.
Constraints:
  • isx[j]≥0, for j=0,1,…,m-1;
  • if mean="M", exactly ip-1 values of isx must be >0;
  • if mean="Z", exactly ip values of isx must be >0.
ip
Type: System..::..Int32
On entry: the number of independent variables in the model, including the mean or intercept if present.
Constraint: ip>0.
y
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: y, observations on the dependent variable.
Constraint: y[i]≥0.0, for i=0,1,…,n-1.
wt
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array wt must be at least n if weight="W", and at least 1 otherwise.
On entry: if weight="W" >, wt must contain the weights to be used in the weighted regression.
If wt[i-1]=0.0, the ith observation is not included in the model, in which case the effective number of observations is the number of observations with nonzero weights.
If weight="U", wt is not referenced and the effective number of observations is n.
Constraint: if weight="W", wt[i]≥0.0, for i=0,1,…,n-1.
a
Type: System..::..Double
On entry: if link="E", a must contain the power of the exponential.
If link≠"E", a is not referenced.
Constraint: if a≠0.0, link="E".
dev
Type: System..::..Double %
On exit: the deviance for the fitted model.
idf
Type: System..::..Int32 %
On exit: the degrees of freedom asociated with the deviance for the fitted model.
b
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On exit: the estimates of the parameters of the generalized linear model, β^.
If mean="M", the first element of b will contain the estimate of the mean parameter and b[i] will contain the coefficient of the variable contained in column j of x, where isx[j-1] is the ith positive value in the array isx.
If mean="Z", b[i-1] will contain the coefficient of the variable contained in column j of x, where isx[j-1] is the ith positive value in the array isx.
irank
Type: System..::..Int32 %
On exit: the rank of the independent variables.
If the model is of full rank, irank=ip.
If the model is not of full rank, irank is an estimate of the rank of the independent variables. irank is calculated as the number of singular values greater that eps×(largest singular value). It is possible for the SVD to be carried out but for irank to be returned as ip.
se
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On exit: the standard errors of the linear parameters.
se[i-1] contains the standard error of the parameter estimate in b[i-1], for i=1,2,…,ip.
cov
Type: array< System..::..Double >[]()[][]
An array of size [ip×ip+1/2]
On exit: the upper triangular part of the variance-covariance matrix of the ip parameter estimates given in b. They are stored packed by column, i.e., the covariance between the parameter estimate given in b[i-1] and the parameter estimate given in b[j-1], j≥i, is stored in cov[j×j-1/2+i-1].
v
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, ip+7]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: if offset="N", v need not be set.
If offset="Y", v[i-1,6], for i=1,2,…,n must contain the offset values oi. All other values need not be set.
On exit: auxiliary information on the fitted model.
v[i-1,0] | contains the linear predictor value, ηi, for i=1,2,…,n.
v[i-1,1] | contains the fitted value, μ^i, for i=1,2,…,n.
v[i-1,2] | contains the variance standardization, 1 τi, for i=1,2,…,n.
v[i-1,3] | contains the square root of the working weight, wi 12, for i=1,2,…,n.
v[i-1,4] | contains the deviance residual, ri, for i=1,2,…,n.
v[i-1,5] | contains the leverage, hi, for i=1,2,…,n.
v[i-1,6] | contains the offset, oi, for i=1,2,…,n. If offset="N", all values will be zero.
v[i-1,j-1] | for j=8,…,ip+7, contains the results of the QR decomposition or the singular value decomposition.
If the model is not of full rank, i.e., irank<ip, the first ip rows of columns 8 to ip+7 contain the P* matrix.
tol
Type: System..::..Double
On entry: indicates the accuracy required for the fit of the model.
The iterative weighted least squares procedure is deemed to have converged if the absolute change in deviance between iterations is less than tol×1.0+Current Deviance. This is approximately an absolute precision if the deviance is small and a relative precision if the deviance is large.
If 0.0≤tol<machine precision, the method will use 10×machine precision instead.
Constraint: tol≥0.0.
maxit
Type: System..::..Int32
On entry: the maximum number of iterations for the iterative weighted least squares.
If maxit=0, a default value of 10 is used.
Constraint: maxit≥0.
iprint
Type: System..::..Int32
On entry: indicates if the printing of information on the iterations is required.
iprint≤0
There is no printing.
iprint>0
Every iprint iteration, the following are printed:
  • the deviance;
  • the current estimates;
  • and if the weighted least squares equations are singular then this is indicated.
When printing occurs the output is directed to the current advisory message unit (see (X04ABF not in this release)).
eps
Type: System..::..Double
On entry: the value of eps is used to decide if the independent variables are of full rank and, if not, what is the rank of the independent variables. The smaller the value of eps the stricter the criterion for selecting the singular value decomposition.
If 0.0≤eps<machine precision, the method will use machine precision instead.
Constraint: eps≥0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

A generalized linear model with Poisson errors consists of the following elements:
(a) a set of n observations, yi, from a Poisson distribution:
μye-μy!.
(b) X, a set of p independent variables for each observation, x 1,x 2,…,xp.
(c) a linear model:
η=∑βjxj.
(d) a link between the linear predictor, η, and the mean of the distribution, μ, η=g μ. The possible link functions are:
(i) | exponent link: η=μa, for a constant a,
(ii) | identity link: η=μ,
(iii) | log link: η=log μ,
(iv) | square root link: η=μ,
(v) | reciprocal link: η=1 μ.
(e) a measure of fit, the deviance:
∑i=1 n dev yi,μ^i=∑i=1 n 2 yi log yiμ^i-yi-μ^i.
The linear parameters are estimated by iterative weighted least squares. An adjusted dependent variable, z, is formed:
z=η+y-μ dηdμ
and a working weight, w,
w=τd dηdμ 2,
where τ=μ.
At each iteration an approximation to the estimate of β, β^, is found by the weighted least squares regression of z on X with weights w.
g02gc finds a QR decomposition of w 1/2 X, i.e., w 1/2 X=QR where R is a p by p triangular matrix and Q is an n by p column orthogonal matrix.
If R is of full rank, then β^ is the solution to:
R β^=QTw 1/2 z.
If R is not of full rank a solution is obtained by means of a singular value decomposition (SVD) of R.
R=Q*D000 PT,
where D is a k by k diagonal matrix with nonzero diagonal elements, k being the rank of R and w 1/2 X.
This gives the solution
β^=P 1 D-1 Q*00I QTw 1/2 z,
P 1 being the first k columns of P, i.e., P=P 1P 0.
The iterations are continued until there is only a small change in the deviance.
The initial values for the algorithm are obtained by taking
η^=g y.
The fit of the model can be assessed by examining and testing the deviance, in particular by comparing the difference in deviance between nested models, i.e., when one model is a sub-model of the other. The difference in deviance between two nested models has, asymptotically, a χ 2-distribution with degrees of freedom given by the difference in the degrees of freedom associated with the two deviances.
The parameters estimates, β^, are asymptotically Normally distributed with variance-covariance matrix
  • C=R-1R-1 T in the full rank case, otherwise
  • C=P 1 D-2 P 1 T.
The residuals and influence statistics can also be examined.
The estimated linear predictor η^=X β^, can be written as H w 1/2 z for an n by n matrix H. The ith diagonal elements of H, hi, give a measure of the influence of the ith values of the independent variables on the fitted regression model. These are known as leverages.
The fitted values are given by μ^=g-1 η^.
g02gc also computes the deviance residuals, r:
ri=sign yi-μ^i dev yi,μ^i.
An option allows prior weights to be used with the model.
In many linear regression models the first term is taken as a mean term or an intercept, i.e., x i,1=1, for i=1,2,…,n. This is provided as an option.
Often only some of the possible independent variables are included in a model; the facility to select variables to be included in the model is provided.
If part of the linear predictor can be represented by a variables with a known coefficient then this can be included in the model by using an offset, o:
η=o+∑βjxj.
If the model is not of full rank the solution given will be only one of the possible solutions. Other estimates may be obtained by applying constraints to the parameters. These solutions can be obtained by using g02gk after using g02gc. Only certain linear combinations of the parameters will have unique estimates, these are known as estimable functions, these can be estimated and tested using g02gn.
Details of the SVD are made available in the form of the matrix P*:
P*=D-1 P 1 TP 0 T.
The generalized linear model with Poisson errors can be used to model contingency table data; see Cook and Weisberg (1982) and McCullagh and Nelder (1983).

References

Cook R D and Weisberg S (1982) Residuals and Influence in Regression Chapman and Hall
McCullagh P and Nelder J A (1983) Generalized Linear Models Chapman and Hall
Plackett R L (1974) The Analysis of Categorical Data Griffin

Error Indicators and Warnings

Note: g02gc may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDV) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | n<2,
or | m<1,
or | ip<1,
or | link≠"E", "I", "L", "S" or "R",
or | link="E" and a=0.0,
or | mean≠"M" or "Z",
or | weight≠"U" or "W",
or | offset≠"N" or "Y",
or | maxit<0,
or | tol<0.0,
or | eps<0.0.
ifail=2
On entry, weight="W" and a value of wt<0.0.
ifail=3
On entry, | a value of isx<0,
or | the value of ip is incompatible with the values of mean and isx,
or | ip is greater than the effective number of observations.
ifail=4
On entry, y[i-1]<0.0 for some i=1,2,…,n.
ifail=5
A fitted value is at the boundary, i.e., μ^=0.0. This may occur if there are y values of 0.0 and the model is too complex for the data. The model should be reformulated with, perhaps, some observations dropped.
ifail=6
The singular value decomposition has failed to converge. This is an unlikely error exit.
ifail=7
The iterative weighted least squares has failed to converge in maxit (or default 10) iterations. The value of maxit could be increased but it may be advantageous to examine the convergence using the iprint option. This may indicate that the convergence is slow because the solution is at a boundary in which case it may be better to reformulate the model.
ifail=8
The rank of the model has changed during the weighted least squares iterations. The estimate for β returned may be reasonable, but you should check how the deviance has changed during iterations.
ifail=9
The degrees of freedom for error are 0. A saturated model has been fitted.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The accuracy depends on the value of tol as described in [Parameters]. As the deviance is a function of log μ the accuracy of the β^ will only be a function of tol. tol should therefore be set smaller than the accuracy required for β^.

Parallelism and Performance

None.

Further Comments

None.

Example

A 3 by 5 contingency table given by Plackett (1974) is analysed by fitting terms for rows and columns. The table is:
1416711479391316614372353614382816.

Example program (C#): g02gce.cs

Example program data: g02gce.d

Example program results: g02gce.r

See Also

G02 Class
G02 Members


g02gd Method

[image]

NAG Library for .NET Release 2
G02..::g02gd Method
G02 Class See Also Send Feedback
g02gd fits a generalized linear model with gamma errors.

Syntax

C#
public static void g02gd(
    string link,
    string mean,
    string offset,
    string weight,
    int n,
    double[,] x,
    int m,
    int[] isx,
    int ip,
    double[] y,
    double[] wt,
    ref double s,
    double a,
    out double dev,
    out int idf,
    double[] b,
    out int irank,
    double[] se,
    double[] cov,
    double[,] v,
    double tol,
    int maxit,
    int iprint,
    double eps,
    out int ifail
)
Visual Basic
Public Shared Sub g02gd ( _
    link As String, _
    mean As String, _
    offset As String, _
    weight As String, _
    n As Integer, _
    x As Double(,), _
    m As Integer, _
    isx As Integer(), _
    ip As Integer, _
    y As Double(), _
    wt As Double(), _
    ByRef s As Double, _
    a As Double, _
    <OutAttribute> ByRef dev As Double, _
    <OutAttribute> ByRef idf As Integer, _
    b As Double(), _
    <OutAttribute> ByRef irank As Integer, _
    se As Double(), _
    cov As Double(), _
    v As Double(,), _
    tol As Double, _
    maxit As Integer, _
    iprint As Integer, _
    eps As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02gd(
    String^ link,
    String^ mean,
    String^ offset,
    String^ weight,
    int n,
    array<double,2>^ x,
    int m,
    array<int>^ isx,
    int ip,
    array<double>^ y,
    array<double>^ wt,
    double% s,
    double a,
    [OutAttribute] double% dev,
    [OutAttribute] int% idf,
    array<double>^ b,
    [OutAttribute] int% irank,
    array<double>^ se,
    array<double>^ cov,
    array<double,2>^ v,
    double tol,
    int maxit,
    int iprint,
    double eps,
    [OutAttribute] int% ifail
)
F#
static member g02gd :
        link : string *
        mean : string *
        offset : string *
        weight : string *
        n : int *
        x : float[,] *
        m : int *
        isx : int[] *
        ip : int *
        y : float[] *
        wt : float[] *
        s : float byref *
        a : float *
        dev : float byref *
        idf : int byref *
        b : float[] *
        irank : int byref *
        se : float[] *
        cov : float[] *
        v : float[,] *
        tol : float *
        maxit : int *
        iprint : int *
        eps : float *
        ifail : int byref -> unit

Parameters

link
Type: System..::..String
On entry: indicates which link function is to be used.
link="E"
An exponential link is used.
link="I"
An identity link is used.
link="L"
A log link is used.
link="S"
A square root link is used.
link="R"
A reciprocal link is used.
Constraint: link="E", "I", "L", "S" or "R".
mean
Type: System..::..String
On entry: indicates if a mean term is to be included.
mean="M"
A mean term, intercept, will be included in the model.
mean="Z"
The model will pass through the origin, zero-point.
Constraint: mean="M" or "Z".
offset
Type: System..::..String
On entry: indicates if an offset is required.
offset="Y"
An offset is required and the offsets must be supplied in the seventh column of v.
offset="N"
No offset is required.
Constraint: offset="N" or "Y".
weight
Type: System..::..String
On entry: indicates if prior weights are to be used.
weight="U"
No prior weights are used.
weight="W"
Prior weights are used and weights must be supplied in wt.
Constraint: weight="U" or "W".
n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n≥2.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must contain the ith observation for the jth independent variable, for i=1,2,…,n and j=1,2,…,m.
m
Type: System..::..Int32
On entry: m, the total number of independent variables.
Constraint: m≥1.
isx
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: indicates which independent variables are to be included in the model.
If isx[j-1]>0, the variable contained in the jth column of x is included in the regression model.
Constraints:
  • isx[j-1]≥0, for i=0,1,…,m-1;
  • if mean="M", exactly ip-1 values of isx must be >0;
  • if mean="Z", exactly ip values of isx must be >0.
ip
Type: System..::..Int32
On entry: the number of independent variables in the model, including the mean or intercept if present.
Constraint: ip>0.
y
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: y, the dependent variable.
Constraint: y[i]≥0.0, for i=0,1,…,n-1.
wt
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array wt must be at least n if weight="W", and at least 1 otherwise.
On entry: if weight="W", wt must contain the weights to be used in the weighted regression. If wt[i-1]=0.0, the ith observation is not included in the model, in which case the effective number of observations is the number of observations with nonzero weights.
If weight="U", wt is not referenced and the effective number of observations is n.
Constraint: if weight="W", wt[i]≥0.0, for i=0,1,…,n-1.
s
Type: System..::..Double %
On entry: the scale parameter for the gamma model, ν-1.
s=0.0
The scale parameter is estimated with the method using the formula described in [Description].
Constraint: s≥0.0.
On exit: if on input s=0.0, s contains the estimated value of the scale parameter, ν^-1.
If on input s≠0.0, s is unchanged on exit.
a
Type: System..::..Double
On entry: if link="E", a must contain the power of the exponential.
If link≠"E", a is not referenced.
Constraint: if link="E", a≠0.0.
dev
Type: System..::..Double %
On exit: the adjusted deviance for the fitted model.
idf
Type: System..::..Int32 %
On exit: the degrees of freedom asociated with the deviance for the fitted model.
b
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On exit: the estimates of the parameters of the generalized linear model, β^.
If mean="M", the first element of b will contain the estimate of the mean parameter and b[i] will contain the coefficient of the variable contained in column j of x, where isx[j-1] is the ith positive value in the array isx.
If mean="Z", b[i-1] will contain the coefficient of the variable contained in column j of x, where isx[j-1] is the ith positive value in the array isx.
irank
Type: System..::..Int32 %
On exit: the rank of the independent variables.
If the model is of full rank then irank=ip.
If the model is not of full rank then irank is an estimate of the rank of the independent variables. irank is calculated as the number of singular values greater that eps×(largest singular value). It is possible for the SVD to be carried out but for irank to be returned as ip.
se
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On exit: the standard errors of the linear parameters.
se[i-1] contains the standard error of the parameter estimate in b[i-1], for i=1,2,…,ip.
cov
Type: array< System..::..Double >[]()[][]
An array of size [ip×ip+1/2]
On exit: the upper triangular part of the variance-covariance matrix of the ip parameter estimates given in b. They are stored in packed form by column, i.e., the covariance between the parameter estimate given in b[i-1] and the parameter estimate given in b[j-1], j≥i, is stored in cov[j×j-1/2+i-1].
v
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, ip+7]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: if offset="N", v need not be set.
If offset="Y", v[i-1,6], for i=1,2,…,n, must contain the offset values oi. All other values need not be set.
On exit: auxiliary information on the fitted model.
v[i-1,0] | contains the linear predictor value, ηi, for i=1,2,…,n.
v[i-1,1] | contains the fitted value, μ^i, for i=1,2,…,n.
v[i-1,2] | contains the variance standardization, 1 τi, for i=1,2,…,n.
v[i-1,3] | contains the square root of the working weight, wi 12, for i=1,2,…,n.
v[i-1,4] | contains the Anscombe residual, ri, for i=1,2,…,n.
v[i-1,5] | contains the leverage, hi, for i=1,2,…,n.
v[i-1,6] | contains the offset, oi, for i=1,2,…,n. If offset="N", all values will be zero.
v[i-1,j-1], | for j=8,…,ip+7, contains the results of the QR decomposition or the singular value decomposition.
If the model is not of full rank, i.e., irank<ip, the first ip rows of columns 8 to ip+7 contain the P* matrix.
tol
Type: System..::..Double
On entry: indicates the accuracy required for the fit of the model.
The iterative weighted least squares procedure is deemed to have converged if the absolute change in deviance between iterations is less than tol×1.0+Current Deviance. This is approximately an absolute precision if the deviance is small and a relative precision if the deviance is large.
If 0.0≤tol<machine precision then the method will use 10×machine precision instead.
Constraint: tol≥0.0.
maxit
Type: System..::..Int32
On entry: the maximum number of iterations for the iterative weighted least squares.
maxit=0
A default value of 10 is used.
Constraint: maxit≥0.
iprint
Type: System..::..Int32
On entry: indicates if the printing of information on the iterations is required.
iprint≤0
There is no printing.
iprint>0
Every iprint iteration, the following are printed:
  • the deviance;
  • the current estimates;
  • and if the weighted least squares equations are singular then this is indicated.
When printing occurs the output is directed to the current advisory message unit (see (X04ABF not in this release)).
eps
Type: System..::..Double
On entry: the value of eps is used to decide if the independent variables are of full rank and, if not, what is the rank of the independent variables. The smaller the value of eps the stricter the criterion for selecting the singular value decomposition.
If 0.0≤eps<machine precision then the method will use machine precision instead.
Constraint: eps≥0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

A generalized linear model with gamma errors consists of the following elements:
(a) a set of n observations, yi, from a gamma distribution with probability density function:
1 Γ ν νy μ ν exp-νy μ 1 y
ν being constant for the sample.
(b) X, a set of p independent variables for each observation, x 1,x 2,…,xp.
(c) a linear model:
η=∑βjxj.
(d) a link between the linear predictor, η, and the mean of the distribution, μ, η=g μ. The possible link functions are:
(i) | exponent link: η=μa, for a constant a,
(ii) | identity link: η=μ,
(iii) | log link: η=log μ,
(iv) | square root link: η=μ,
(v) | reciprocal link: η=1 μ.
(e) a measure of fit, an adjusted deviance. This is a function related to the deviance, but defined for y=0:
∑i=1 n dev*yi,μ^i=∑i=1 n 2 log μ^i+yiμ^i.
The linear parameters are estimated by iterative weighted least squares. An adjusted dependent variable, z, is formed:
z=η+y-μ dηdμ
and a working weight, w,
w=τ dηdμ 2,   where  τ=1 μ.
At each iteration an approximation to the estimate of β, β^ is found by the weighted least squares regression of z on X with weights w.
g02gd finds a QR decomposition of w 12 X, i.e.,
  • w 12 X=QR where R is a p by p triangular matrix and Q is an n by p column orthogonal matrix.
If R is of full rank then β^ is the solution to:
  • R β^=QTw 12 z
If R is not of full rank a solution is obtained by means of a singular value decomposition (SVD) of R.
R=Q*D000 PT.
where D is a k by k diagonal matrix with nonzero diagonal elements, k being the rank of R and w 12 X.
This gives the solution
β^=P 1 D-1 Q*00I QTw 12 z,
where P 1 is the first k columns of P, i.e., P=P 1P 0.
The iterations are continued until there is only a small change in the deviance.
The initial values for the algorithm are obtained by taking
η^=g y.
The scale parameter, ν-1 is estimated by a moment estimator:
ν^-1=∑i=1 n yi-μ^i/μ^2 n-k.
The fit of the model can be assessed by examining and testing the deviance, in particular, by comparing the difference in deviance between nested models, i.e., when one model is a sub-model of the other. The difference in deviance or adjusted deviance between two nested models with known ν has, asymptotically, a χ 2-distribution with degrees of freedom given by the difference in the degrees of freedom associated with the two deviances.
The parameters estimates, β^, are asymptotically Normally distributed with variance-covariance matrix:
  • C=R-1R-1 Tν-1 in the full rank case, otherwise
  • C=P 1 D-2 P 1 T ν-1.
The residuals and influence statistics can also be examined.
The estimated linear predictor η^=X β^, can be written as H w 12 z for an n by n matrix H. The ith diagonal elements of H, hi, give a measure of the influence of the ith values of the independent variables on the fitted regression model. These are known as leverages.
The fitted values are given by μ^=g-1 η^.
g02gd also computes the Anscombe residuals, r:
ri=3 yi 13-μ^i 13μ^i 13.
An option allows the use of prior weights, ωi. This gives a model with:
νi=ν ωi.
In many linear regression models the first term is taken as a mean term or an intercept, i.e., x i,1=1, for i=1,2,…,n. This is provided as an option.
Often only some of the possible independent variables are included in a model, the facility to select variables to be included in the model is provided.
If part of the linear predictor can be represented by a variables with a known coefficient then this can be included in the model by using an offset, o:
η=o+∑βjxj.
If the model is not of full rank the solution given will be only one of the possible solutions. Other estimates may be obtained by applying constraints to the parameters. These solutions can be obtained by using g02gk after using g02gd. Only certain linear combinations of the parameters will have unique estimates, these are known as estimable functions, and can be estimated and tested using g02gn.
Details of the SVD are made available in the form of the matrix P*:
P*=D-1 P 1 TP 0 T.

References

Cook R D and Weisberg S (1982) Residuals and Influence in Regression Chapman and Hall
McCullagh P and Nelder J A (1983) Generalized Linear Models Chapman and Hall

Error Indicators and Warnings

Note: g02gd may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDV) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | n<2,
or | m<1,
or | ip<1,
or | link≠"E","I","L","S" or "R",
or | s<0.0,
or | link="E" and a=0.0,
or | mean≠"M" or "Z",
or | weight≠"U" or "W",
or | offset≠"N" or "Y",
or | maxit<0,
or | tol<0.0,
or | eps<0.0.
ifail=3
On entry, | a value of isx<0,
or | the value of ip is incompatible with the values of mean and isx,
or | ip is greater than the effective number of observations.
ifail=4
On entry, y[i-1]<0.0 for some i=1,2,…,n.
ifail=5
A fitted value is at the boundary, i.e., μ^=0.0. This may occur if there are small values of y and the model is not suitable for the data. The model should be reformulated with, perhaps, some observations dropped.
ifail=6
The singular value decomposition has failed to converge. This is an unlikely error exit.
ifail=7
The iterative weighted least squares has failed to converge in maxit (or default 10) iterations. The value of maxit could be increased but it may be advantageous to examine the convergence using the iprint option. This may indicate that the convergence is slow because the solution is at a boundary in which case it may be better to reformulate the model.
ifail=8
The rank of the model has changed during the weighted least squares iterations. The estimate for β returned may be reasonable, but you should check how the deviance has changed during iterations.
ifail=9
The degrees of freedom for error are 0. A saturated model has been fitted.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The accuracy depends on tol as described in [Parameters]. As the adjusted deviance is a function of log μ, the accuracy of the β^s will be a function of tol, so tol should be set to a smaller value than the accuracy required for β^.

Parallelism and Performance

None.

Further Comments

None.

Example

A set of 10 observations from two groups is input and a model for the two groups is fitted.

Example program (C#): g02gde.cs

Example program data: g02gde.d

Example program results: g02gde.r

See Also

G02 Class
G02 Members


g02gk Method

[image]

NAG Library for .NET Release 2
G02..::g02gk Method
G02 Class See Also Send Feedback
g02gk calculates the estimates of the parameters of a generalized linear model for given constraints from the singular value decomposition results.

Syntax

C#
public static void g02gk(
    int ip,
    int iconst,
    double[,] v,
    double[,] c,
    double[] b,
    double s,
    double[] se,
    double[] cov,
    out int ifail
)
Visual Basic
Public Shared Sub g02gk ( _
    ip As Integer, _
    iconst As Integer, _
    v As Double(,), _
    c As Double(,), _
    b As Double(), _
    s As Double, _
    se As Double(), _
    cov As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02gk(
    int ip,
    int iconst,
    array<double,2>^ v,
    array<double,2>^ c,
    array<double>^ b,
    double s,
    array<double>^ se,
    array<double>^ cov,
    [OutAttribute] int% ifail
)
F#
static member g02gk :
        ip : int *
        iconst : int *
        v : float[,] *
        c : float[,] *
        b : float[] *
        s : float *
        se : float[] *
        cov : float[] *
        ifail : int byref -> unit

Parameters

ip
Type: System..::..Int32
On entry: p, the number of terms in the linear model.
Constraint: ip≥1.
iconst
Type: System..::..Int32
On entry: the number of constraints to be imposed on the parameters, nc.
Constraint: 0<iconst<ip.
v
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, ip+7]
Note: dim1 must satisfy the constraint: dim1≥ip.
dim1 should be as supplied to g02ga, g02gb, g02gc or g02gd
dim1≥ip
On entry: the array v as returned by g02ga, g02gb, g02gc or g02gd.
c
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, iconst]
Note: dim1 must satisfy the constraint: dim1≥ip
On entry: contains the iconst constraints stored by column, i.e., the ith constraint is stored in the ith column of c.
b
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On entry: the parameter estimates computed by using the singular value decomposition, β^svd.
On exit: the parameter estimates of the parameters with the constraints imposed, β^c.
s
Type: System..::..Double
On entry: the estimate of the scale parameter.
For results from g02ga and g02gd then s is the scale parameter for the model.
For results from g02gb and g02gc then s should be set to 1.0.
Constraint: s>0.0.
se
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On exit: the standard error of the parameter estimates in b.
cov
Type: array< System..::..Double >[]()[][]
An array of size [ip×ip+1/2]
On exit: the upper triangular part of the variance-covariance matrix of the ip parameter estimates given in b. They are stored packed by column, i.e., the covariance between the parameter estimate given in b[i-1] and the parameter estimate given in b[j-1], j≥i, is stored in cov[j×j-1/2+i-1].
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g02gk computes the estimates given a set of linear constraints for a generalized linear model which is not of full rank. It is intended for use after a call to g02ga, g02gb, g02gc or g02gd.
In the case of a model not of full rank the methods use a singular value decomposition to find the parameter estimates, β^svd, and their variance-covariance matrix. Details of the SVD are made available in the form of the matrix P*:
P*=D-1 P 1 TP 0 T
as described by g02ga, g02gb, g02gc and g02gd. Alternative solutions can be formed by imposing constraints on the parameters. If there are p parameters and the rank of the model is k then nc=p-k constraints will have to be imposed to obtain a unique solution.
Let C be a p by nc matrix of constraints, such that
CT β=0,
then the new parameter estimates β^c are given by:
β^c=A β^svd=I-P 0 CT P 0-1 β^svd,   where ​I​ is the identity matrix,
and the variance-covariance matrix is given by
A P 1 D-2 P 1 T AT
provided CT P 0-1 exists.

References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
McCullagh P and Nelder J A (1983) Generalized Linear Models Chapman and Hall
Searle S R (1971) Linear Models Wiley

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDV, LDC) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | ip<1.
or | iconst≥ip,
or | iconst≤0,
or | s≤0.0.
ifail=2
c does not give a model of full rank.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

It should be noted that due to rounding errors a parameter that should be zero when the constraints have been imposed may be returned as a value of order machine precision.

Parallelism and Performance

None.

Further Comments

g02gk is intended for use in situations in which dummy (0–1) variables have been used such as in the analysis of designed experiments when you do not wish to change the parameters of the model to give a full rank model. The method is not intended for situations in which the relationships between the independent variables are only approximate.

Example

Example program (C#): g02gke.cs

Example program data: g02gke.d

Example program results: g02gke.r

See Also

G02 Class
G02 Members


g02gn Method

[image]

NAG Library for .NET Release 2
G02..::g02gn Method
G02 Class See Also Send Feedback
g02gn gives the estimate of an estimable function along with its standard error from the results from fitting a generalized linear model.

Syntax

C#
public static void g02gn(
    int ip,
    int irank,
    double[] b,
    double[] cov,
    double[,] v,
    double[] f,
    out bool est,
    out double stat,
    out double sestat,
    out double z,
    double tol,
    out int ifail
)
Visual Basic
Public Shared Sub g02gn ( _
    ip As Integer, _
    irank As Integer, _
    b As Double(), _
    cov As Double(), _
    v As Double(,), _
    f As Double(), _
    <OutAttribute> ByRef est As Boolean, _
    <OutAttribute> ByRef stat As Double, _
    <OutAttribute> ByRef sestat As Double, _
    <OutAttribute> ByRef z As Double, _
    tol As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02gn(
    int ip,
    int irank,
    array<double>^ b,
    array<double>^ cov,
    array<double,2>^ v,
    array<double>^ f,
    [OutAttribute] bool% est,
    [OutAttribute] double% stat,
    [OutAttribute] double% sestat,
    [OutAttribute] double% z,
    double tol,
    [OutAttribute] int% ifail
)
F#
static member g02gn :
        ip : int *
        irank : int *
        b : float[] *
        cov : float[] *
        v : float[,] *
        f : float[] *
        est : bool byref *
        stat : float byref *
        sestat : float byref *
        z : float byref *
        tol : float *
        ifail : int byref -> unit

Parameters

ip
Type: System..::..Int32
On entry: p, the number of terms in the linear model.
Constraint: ip≥1.
irank
Type: System..::..Int32
On entry: k, the rank of the dependent variables.
Constraint: 1≤irank≤ip.
b
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On entry: the ip values of the estimates of the parameters of the model, β^.
cov
Type: array< System..::..Double >[]()[][]
An array of size [ip×ip+1/2]
On entry: the upper triangular part of the variance-covariance matrix of the ip parameter estimates given in b. They are stored packed by column, i.e., the covariance between the parameter estimate given in b[i-1] and the parameter estimate given in b[j-1], j≥i, is stored in cov[j×j-1/2+i-1].
v
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, ip+7]
Note: dim1 must satisfy the constraint: dim1≥ip
On entry: as returned by g02ga, g02gb, g02gc and g02gd.
f
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On entry: f, the linear function to be estimated.
est
Type: System..::..Boolean %
On exit: indicates if the function was estimable.
est=true
The function is estimable.
est=false
The function is not estimable and stat, sestat and z are not set.
stat
Type: System..::..Double %
On exit: if est=true, stat contains the estimate of the function, fT β^
sestat
Type: System..::..Double %
On exit: if est=true, sestat contains the standard error of the estimate of the function, se F.
z
Type: System..::..Double %
On exit: if est=true, z contains the z statistic for the test of the function being equal to zero.
tol
Type: System..::..Double
On entry: the tolerance value used in the check for estimability, η.
If tol≤0.0 then ε, where ε is the machine precision, is used instead.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g02gn computes the estimates of an estimable function for a generalized linear model which is not of full rank. It is intended for use after a call to g02ga, g02gb, g02gc or g02gd. An estimable function is a linear combination of the parameters such that it has a unique estimate. For a full rank model all linear combinations of parameters are estimable.
In the case of a model not of full rank the methods use a singular value decomposition (SVD) to find the parameter estimates, β^, and their variance-covariance matrix. Given the upper triangular matrix R obtained from the QR decomposition of the independent variables the SVD gives
R=Q*D000 PT,
where D is a k by k diagonal matrix with nonzero diagonal elements, k being the rank of R, and Q* and P are p by p orthogonal matrices. This leads to a solution:
β^=P 1 D-1 Q*1 T c 1,
P 1 being the first k columns of P, i.e., P=P 1P 0; Q*1 being the first k columns of Q*, and c 1 being the first p elements of c.
Details of the SVD are made available in the form of the matrix P*:
P*=D-1 P 1 TP 0 T
as described by g02ga, g02gb, g02gc and g02gd.
A linear function of the parameters, F=fT β, can be tested to see if it is estimable by computing ζ=P 0 T f. If ζ is zero, then the function is estimable, if not; the function is not estimable. In practice ζ is tested against some small quantity η.
Given that F is estimable it can be estimated by fT β^ and its standard error calculated from the variance-covariance matrix of β^, Cβ, as
se F=fT Cβ f.
Also a z statistic
z=fT β^se F,
can be computed. The distribution of z will be approximately Normal.

References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore
McCullagh P and Nelder J A (1983) Generalized Linear Models Chapman and Hall
Searle S R (1971) Linear Models Wiley

Error Indicators and Warnings

Note: g02gn may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDV) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | ip<1,
or | irank<1,
or | irank>ip,
ifail=2
On entry, irank=ip. In this case est is returned as true and all statistics are calculated.
ifail=3
Standard error of statistic =0.0; this may be due to rounding errors if the standard error is very small or due to mis-specified inputs cov and f.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The computations are believed to be stable.

Parallelism and Performance

None.

Further Comments

The value of estimable functions is independent of the solution chosen from the many possible solutions. While g02gn may be used to estimate functions of the parameters of the model as computed by g02gk, βc, these must be expressed in terms of the original parameters, β. The relation between the two sets of parameters may not be straightforward.

Example

Example program (C#): g02gne.cs

Example program data: g02gne.d

Example program results: g02gne.r

See Also

G02 Class
G02 Members


g02gp Method

[image]

NAG Library for .NET Release 2
G02..::g02gp Method
G02 Class See Also Send Feedback
g02gp allows prediction from a generalized linear model fit via g02ga, g02gb, g02gc or g02gd.

Syntax

C#
public static void g02gp(
    string errfn,
    string link,
    string mean,
    string offset,
    string weight,
    int n,
    double[,] x,
    int m,
    int[] isx,
    int ip,
    double[] t,
    double[] off,
    double[] wt,
    double s,
    double a,
    double[] b,
    double[] cov,
    bool vfobs,
    double[] eta,
    double[] seeta,
    double[] pred,
    double[] sepred,
    out int ifail
)
Visual Basic
Public Shared Sub g02gp ( _
    errfn As String, _
    link As String, _
    mean As String, _
    offset As String, _
    weight As String, _
    n As Integer, _
    x As Double(,), _
    m As Integer, _
    isx As Integer(), _
    ip As Integer, _
    t As Double(), _
    off As Double(), _
    wt As Double(), _
    s As Double, _
    a As Double, _
    b As Double(), _
    cov As Double(), _
    vfobs As Boolean, _
    eta As Double(), _
    seeta As Double(), _
    pred As Double(), _
    sepred As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02gp(
    String^ errfn,
    String^ link,
    String^ mean,
    String^ offset,
    String^ weight,
    int n,
    array<double,2>^ x,
    int m,
    array<int>^ isx,
    int ip,
    array<double>^ t,
    array<double>^ off,
    array<double>^ wt,
    double s,
    double a,
    array<double>^ b,
    array<double>^ cov,
    bool vfobs,
    array<double>^ eta,
    array<double>^ seeta,
    array<double>^ pred,
    array<double>^ sepred,
    [OutAttribute] int% ifail
)
F#
static member g02gp :
        errfn : string *
        link : string *
        mean : string *
        offset : string *
        weight : string *
        n : int *
        x : float[,] *
        m : int *
        isx : int[] *
        ip : int *
        t : float[] *
        off : float[] *
        wt : float[] *
        s : float *
        a : float *
        b : float[] *
        cov : float[] *
        vfobs : bool *
        eta : float[] *
        seeta : float[] *
        pred : float[] *
        sepred : float[] *
        ifail : int byref -> unit

Parameters

errfn
Type: System..::..String
On entry: indicates the distribution used to model the dependent variable, y.
errfn="B"
The binomial distribution is used.
errfn="G"
The gamma distribution is used.
errfn="N"
The Normal (Gaussian) distribution is used.
errfn="P"
The Poisson distribution is used.
Constraint: errfn="B", "G", "N" or "P".
link
Type: System..::..String
On entry: indicates which link function to be used.
link="C"
A complementary log-log link is used.
link="E"
An exponent link is used.
link="G"
A logistic link is used.
link="I"
An identity link is used.
link="L"
A log link is used.
link="P"
A probit link is used.
link="R"
A reciprocal link is used.
link="S"
A square root link is used.
Details on the functional form of the different links can be found in the G02 class.
Constraints:
  • if errfn="B", link="C", "G" or "P";
  • otherwise link="E", "I", "L", "R" or "S".
mean
Type: System..::..String
On entry: indicates if a mean term is to be included.
mean="M"
A mean term, intercept, will be included in the model.
mean="Z"
The model will pass through the origin, zero-point.
Constraint: mean="M" or "Z".
offset
Type: System..::..String
On entry: indicates if an offset is required.
offset="Y"
An offset must be supplied in off.
offset="N"
off is not referenced.
Constraint: offset="Y" or "N".
weight
Type: System..::..String
On entry: if vfobs=true indicates if weights are used, otherwise weight is not referenced.
weight="U"
No weights are used.
weight="W"
Weights are used and must be supplied in wt.
Constraint: if vfobs=true, weight="U" or "W".
n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n≥1.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥n
Note: the second dimension of the array x must be at least m.
On entry: x[i-1,j-1] must contain the ith observation for the jth independent variable, for i=1,2,…,n and j=1,2,…,m.
m
Type: System..::..Int32
On entry: m, the total number of independent variables.
Constraint: m≥1.
isx
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: indicates which independent variables are to be included in the model.
If isx[j-1]>0, the jth independent variable is included in the regression model.
Constraints:
  • isx[j-1]≥0, for i=1,2,…,m;
  • if mean="M", exactly ip-1 values of isx must be >0;
  • if mean="Z", exactly ip values of isx must be >0.
ip
Type: System..::..Int32
On entry: the number of independent variables in the model, including the mean or intercept if present.
Constraint: ip>0.
t
Type: array< System..::..Double >[]()[][]
An array of size [_lt]
Note: the dimension of the array must be at least n if errfn="B", and at least 1 otherwise.
On entry: if errfn="B", t[i-1] must contain the binomial denominator, ti, for the ith observation.
Otherwise t is not referenced.
Constraint: if errfn="B", t[i-1]≥0.0, for i=1,2,…,n.
off
Type: array< System..::..Double >[]()[][]
An array of size [_lof]
Note: the dimension of the array must be at least n if offset="Y", and at least 1 otherwise.
On entry: if offset="Y", off[i-1] must contain the offset oi, for the ith observation.
Otherwise off is not referenced.
wt
Type: array< System..::..Double >[]()[][]
An array of size [_lwt]
Note: the dimension of the array must be at least n if weight="W" and vfobs=true, and at least 1 otherwise.
On entry: if weight="W" and vfobs=true, wt[i-1] must contain the weight, wi, for the ith observation.
If the variance of future observations is not included in the standard error of the predicted variable, wt is not referenced.
Constraint: if vfobs=true and weight="W", wt[i-1]≥0., for i=1,2,…,i.
s
Type: System..::..Double
On entry: if errfn="N" or "G" and vfobs=true, the scale parameter, ϕ.
Otherwise s is not referenced and ϕ=1.
Constraint: if errfn="N" or "G" and vfobs=true, s>0.0.
a
Type: System..::..Double
On entry: if link="E", a must contain the power of the exponential.
If link≠"E", a is not referenced.
Constraint: if link="E", a≠0.0.
b
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On entry: the model parameters, β.
If mean="M", b[0] must contain the mean parameter and b[i] the coefficient of the variable contained in the jth independent x, where isx[j-1] is the ith positive value in the array isx.
If mean="Z", b[i-1] must contain the coefficient of the variable contained in the jth independent x, where isx[j-1] is the ith positive value in the array isx.
cov
Type: array< System..::..Double >[]()[][]
An array of size [ip×ip+1/2]
On entry: the upper triangular part of the variance-covariance matrix, C, of the model parameters. This matrix should be supplied packed by column, i.e., the covariance between parameters βi and βj, that is the values stored in b[i-1] and b[j-1], should be supplied in cov[j×j-1/2+i-1], for i=1,2,…,ip and j=i,…,ip.
Constraint: the matrix represented in cov must be a valid variance-covariance matrix.
vfobs
Type: System..::..Boolean
On entry: if vfobs=true, the variance of future observations is included in the standard error of the predicted variable (i.e., Ifobs=1), otherwise Ifobs=0.
eta
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the linear predictor, η.
seeta
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the standard error of the linear predictor, se η.
pred
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the predicted value, y^.
sepred
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the standard error of the predicted value, se y^. If pred[i-1] could not be calculated, then g02gp returns ifail=22, and sepred[i-1] is set to -99.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

A generalized linear model consists of the following elements:
(i) | A suitable distribution for the dependent variable y.
(ii) | A linear model, with linear predictor η=Xβ, where X is a matrix of independent variables and β a column vector of p parameters.
(iii) | A link function g. between the expected value of y and the linear predictor, that is E y=μ=g η.
In order to predict from a generalized linear model, that is estimate a value for the dependent variable, y, given a set of independent variables X, the matrix X must be supplied, along with values for the parameters β and their associated variance-covariance matrix, C. Suitable values for β and C are usually estimated by first fitting the prediction model to a training dataset with known responses, using for example g02ga, g02gb, g02gc or g02gd. The predicted variable, and its standard error can then be obtained from:
y^=g-1 η,  se y^=δ g-1 xδx η se η+Ifobs Var y
where
η=o+Xβ,  se η=diag XC XT,
o is a vector of offsets and Ifobs=0, if the variance of future observations is not taken into account, and 1 otherwise. Here diag A indicates the diagonal elements of matrix A.
If required, the variance for the ith future observation, Var yi, can be calculated as:
Var yi=ϕV θwi
where wi is a weight, ϕ is the scale (or dispersion) parameter, and V θ is the variance function. Both the scale parameter and the variance function depend on the distribution used for the y, with:
Poisson | V θ=μi, ϕ=1
binomial | V θ=μi ti-μiti, ϕ=1
Normal | V θ=1
gamma | V θ=μi 2
In the cases of a Normal and gamma error structure, the scale parameter (ϕ), is supplied by you. This value is usually obtained from the method used to fit the prediction model. In many cases, for a Normal error structure, ϕ=σ^2, i.e., the estimated variance.

References

McCullagh P and Nelder J A (1983) Generalized Linear Models Chapman and Hall

Error Indicators and Warnings

Note: g02gp may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, errfn≠"B", "P", "G" or "N".
ifail=2
On entry, errfn="B" and link≠"G", "P" or "C" or errfn≠"B" and link≠"E", "I", "L", "R" or "S".
ifail=3
On entry, mean≠"M" or "Z".
ifail=4
On entry, offset≠"Y" or "N".
ifail=5
On entry, vfobs=true and weight≠"U" or "W".
ifail=6
On entry, n<1.
ifail=8
On entry, ldx<n.
ifail=9
On entry, m≤0.
ifail=10
On entry, number of nonzero elements in isx is not consistent with ip.
ifail=11
On entry, ip<1.
ifail=12
On entry, errfn="B" and t[i-1]<0.0 for at least one i=1,2,…,n.
ifail=14
On entry, vfobs=true, weight="W" and wt[i-1]<0.0 for at least one i=1,2,…,n.
ifail=15
On entry, vfobs=true, errfn="G" or "N" and s≤0.0.
ifail=16
On entry, link="E" and a=0.0.
ifail=18
On entry, supplied covariance matrix has at least one diagonal element <0.0.
ifail=22
On exit, at least one predicted value could not be calculated as required. sepred is set to -99.0 for affected predicted values.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

The model
y=1 β 1+β 2 x+ε
is fitted to a training dataset with five observations. The resulting model is then used to predict the response for two new observations.

Example program (C#): g02gpe.cs

Example program data: g02gpe.d

Example program results: g02gpe.r

See Also

G02 Class
G02 Members


g02ha Method

[image]

NAG Library for .NET Release 2
G02..::g02ha Method
G02 Class See Also Send Feedback
g02ha performs bounded influence regression (M-estimates). Several standard methods are available.

Syntax

C#
public static void g02ha(
    int indw,
    int ipsi,
    int isigma,
    int indc,
    int n,
    int m,
    double[,] x,
    double[] y,
    double cpsi,
    double h1,
    double h2,
    double h3,
    double cucv,
    double dchi,
    double[] theta,
    ref double sigma,
    double[,] c,
    double[] rs,
    double[] wgt,
    double tol,
    int maxit,
    int nitmon,
    double[] stat,
    out int ifail
)
Visual Basic
Public Shared Sub g02ha ( _
    indw As Integer, _
    ipsi As Integer, _
    isigma As Integer, _
    indc As Integer, _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    y As Double(), _
    cpsi As Double, _
    h1 As Double, _
    h2 As Double, _
    h3 As Double, _
    cucv As Double, _
    dchi As Double, _
    theta As Double(), _
    ByRef sigma As Double, _
    c As Double(,), _
    rs As Double(), _
    wgt As Double(), _
    tol As Double, _
    maxit As Integer, _
    nitmon As Integer, _
    stat As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02ha(
    int indw,
    int ipsi,
    int isigma,
    int indc,
    int n,
    int m,
    array<double,2>^ x,
    array<double>^ y,
    double cpsi,
    double h1,
    double h2,
    double h3,
    double cucv,
    double dchi,
    array<double>^ theta,
    double% sigma,
    array<double,2>^ c,
    array<double>^ rs,
    array<double>^ wgt,
    double tol,
    int maxit,
    int nitmon,
    array<double>^ stat,
    [OutAttribute] int% ifail
)
F#
static member g02ha :
        indw : int *
        ipsi : int *
        isigma : int *
        indc : int *
        n : int *
        m : int *
        x : float[,] *
        y : float[] *
        cpsi : float *
        h1 : float *
        h2 : float *
        h3 : float *
        cucv : float *
        dchi : float *
        theta : float[] *
        sigma : float byref *
        c : float[,] *
        rs : float[] *
        wgt : float[] *
        tol : float *
        maxit : int *
        nitmon : int *
        stat : float[] *
        ifail : int byref -> unit

Parameters

indw
Type: System..::..Int32
On entry: specifies the type of regression to be performed.
indw<0
Mallows type regression with Maronna's proposed weights.
indw=0
Huber type regression.
indw>0
Schweppe type regression with Krasker–Welsch weights.
ipsi
Type: System..::..Int32
On entry: specifies which ψ function is to be used.
ipsi=0
ψ t=t, i.e., least squares.
ipsi=1
Huber's function.
ipsi=2
Hampel's piecewise linear function.
ipsi=3
Andrew's sine wave.
ipsi=4
Tukey's bi-weight.
Constraint: 0≤ipsi≤4.
isigma
Type: System..::..Int32
On entry: specifies how σ is to be estimated.
isigma<0
σ is estimated by median absolute deviation of residuals.
isigma=0
σ is held constant at its initial value.
isigma>0
σ is estimated using the χ function.
indc
Type: System..::..Int32
On entry: if indw≠0, indc specifies the approximations used in estimating the covariance matrix of θ^.
indc=1
Averaging over residuals.
indc≠1
Replacing expected by observed.
indw=0
indc is not referenced.
n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n>1.
m
Type: System..::..Int32
On entry: m, the number of independent variables.
Constraint: 1≤m<n.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: the values of the X matrix, i.e., the independent variables. x[i-1,j-1] must contain the ijth element of X, for i=1,2,…,n and j=1,2,…,m.
If indw<0, then during calculations the elements of x will be transformed as described in [Description]. Before exit the inverse transformation will be applied. As a result there may be slight differences between the input x and the output x.
On exit: unchanged, except as described above.
y
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the data values of the dependent variable.
y[i-1] must contain the value of y for the ith observation, for i=1,2,…,n.
If indw<0, then during calculations the elements of y will be transformed as described in [Description]. Before exit the inverse transformation will be applied. As a result there may be slight differences between the input y and the output y.
On exit: unchanged, except as described above.
cpsi
Type: System..::..Double
On entry: if ipsi=1, cpsi must specify the parameter, c, of Huber's ψ function.
If ipsi≠1 on entry, cpsi is not referenced.
Constraint: if cpsi>0.0, ipsi=1.
h1
Type: System..::..Double
On entry: if ipsi=2, h1, h2, and h3 must specify the parameters h 1, h 2, and h 3, of Hampel's piecewise linear ψ function. h1, h2, and h3 are not referenced if ipsi≠2.
Constraint: if ipsi=2, 0.0≤h1≤h2≤h3 and h3>0.0.
h2
Type: System..::..Double
On entry: if ipsi=2, h1, h2, and h3 must specify the parameters h 1, h 2, and h 3, of Hampel's piecewise linear ψ function. h1, h2, and h3 are not referenced if ipsi≠2.
Constraint: if ipsi=2, 0.0≤h1≤h2≤h3 and h3>0.0.
h3
Type: System..::..Double
On entry: if ipsi=2, h1, h2, and h3 must specify the parameters h 1, h 2, and h 3, of Hampel's piecewise linear ψ function. h1, h2, and h3 are not referenced if ipsi≠2.
Constraint: if ipsi=2, 0.0≤h1≤h2≤h3 and h3>0.0.
cucv
Type: System..::..Double
On entry: if indw<0, must specify the value of the constant, c, of the function u for Maronna's proposed weights.
If indw>0, must specify the value of the function u for the Krasker–Welsch weights.
If indw=0, is not referenced.
Constraints:
  • if indw<0, cucv≥m;
  • if indw>0, cucv≥m.
dchi
Type: System..::..Double
On entry: d, the constant of the χ function. dchi is not referenced if ipsi=0, or if isigma≤0.
Constraint: if ipsi≠0 and isigma>0, dchi>0.0.
theta
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: starting values of the parameter vector θ. These may be obtained from least squares regression. Alternatively if isigma<0 and sigma=1 or if isigma>0 and sigma approximately equals the standard deviation of the dependent variable, y, then theta[i-1]=0.0, for i=1,2,…,m may provide reasonable starting values.
On exit: theta[i-1] contains the M-estimate of θi, for i=1,2,…,m.
sigma
Type: System..::..Double %
On entry: a starting value for the estimation of σ. sigma should be approximately the standard deviation of the residuals from the model evaluated at the value of θ given by theta on entry.
Constraint: sigma>0.0.
On exit: contains the final estimate of σ if isigma≠0 or the value assigned on entry if isigma=0.
c
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: the diagonal elements of c contain the estimated asymptotic standard errors of the estimates of θ, i.e., c[i-1,i-1] contains the estimated asymptotic standard error of the estimate contained in theta[i-1].
The elements above the diagonal contain the estimated asymptotic correlation between the estimates of θ, i.e., c[i-1,j-1], 1≤i<j≤m contains the asymptotic correlation between the estimates contained in theta[i-1] and theta[j-1].
The elements below the diagonal contain the estimated asymptotic covariance between the estimates of θ, i.e., c[i-1,j-1], 1≤j<i≤m contains the estimated asymptotic covariance between the estimates contained in theta[i-1] and theta[j-1].
rs
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the residuals from the model evaluated at final value of theta, i.e., rs contains the vector y-X θ^.
wgt
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the vector of weights. wgt[i-1] contains the weight for the ith observation, for i=1,2,…,n.
tol
Type: System..::..Double
On entry: the relative precision for the calculation of A (if indw≠0), the estimates of θ and the estimate of σ (if isigma≠0). Convergence is assumed when the relative change in all elements being considered is less than tol.
If indw<0 and isigma<0, tol is also used to determine the precision of β 1.
It is advisable for tol to be greater than 100×machine precision.
Constraint: tol>0.0.
maxit
Type: System..::..Int32
On entry: the maximum number of iterations that should be used in the calculation of A (if indw≠0), and of the estimates of θ and σ, and of β 1 (if indw<0 and isigma<0).
A value of maxit=50 should be adequate for most uses.
Constraint: maxit>0.
nitmon
Type: System..::..Int32
On entry: the amount of information that is printed on each iteration.
nitmon=0
No information is printed.
nitmon≠0
The current estimate of θ, the change in θ during the current iteration and the current value of σ are printed on the first and every abs nitmon iterations.
Also, if indw≠0 and nitmon>0 then information on the iterations to calculate A is printed. This is the current estimate of A and the maximum value of S ij (see [Description]).
When printing occurs the output is directed to the current advisory message unit (see (X04ABF not in this release)).
stat
Type: array< System..::..Double >[]()[][]
An array of size [4]
On exit: the following values are assigned to stat:
  • stat[0]=β 1 if isigma<0, or stat[0]=β 2 if isigma>0.
  • stat[1]= number of iterations used to calculate A.
  • stat[2]= number of iterations used to calculate final estimates of θ and σ.
  • stat[3]=k, the rank of the weighted least-squares equations.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

For the linear regression model
y=Xθ+ε,
where | y is a vector of length n of the dependent variable,
 | X is a n by m matrix of independent variables of column rank k,
 | θ is a vector of length m of unknown parameters,
and | ε is a vector of length n of unknown errors with var εi=σ 2,
g02ha calculates the M-estimates given by the solution, θ^, to the equation
∑i=1 n ψ ri/σ wi wix ij=0,  j=1,2,…,m, (1)
where ri is the ith residual, i.e., the ith element of r=y-X θ^,
ψ is a suitable weight function,
wi are suitable weights,
and σ may be estimated at each iteration by the median absolute deviation of the residuals
σ^=medi ri/β 1
or as the solution to
∑i=1 n χ ri/σ^wi wi 2=n-k β 2
for suitable weight function χ, where β 1 and β 2 are constants, chosen so that the estimator of σ is asymptotically unbiased if the errors, εi, have a Normal distribution. Alternatively σ may be held at a constant value.
The above describes the Schweppe type regression. If the wi are assumed to equal 1 for all i then Huber type regression is obtained. A third type, due to Mallows, replaces (1) by
∑i=1 n ψ ri/σ wix ij=0,  j=1,2,…,m.
This may be obtained by use of the transformations
wi*←wiyi*←yi wix ij*←x ij wi,j=1,2,…,m
(see Section 3 of Marazzi (1987a)).
For Huber and Schweppe type regressions, β 1 is the 75th percentile of the standard Normal distribution. For Mallows type regression β 1 is the solution to
1 n∑i=1 n Φ β 1/wi=0.75,
where Φ is the standard Normal cumulative distribution function (see s15ab).
β 2 is given by
β 2=∫-∞∞χ z ϕ z dzin the Huber case;β 2=1 n∑i=1 n wi∫-∞∞χ z ϕ z dzin the Mallows case;β 2=1 n∑i=1 n wi 2∫-∞∞χ z/wi ϕ z dzin the Schweppe case;
where ϕ is the standard Normal density, i.e., 1 2 π exp-12 x 2.
The calculation of the estimates of θ can be formulated as an iterative weighted least squares problem with a diagonal weight matrix G given by
G ii=ψ ri/σ wiri/σ wi,ri≠0ψ′0,ri=0,
where ψ′t is the derivative of ψ at the point t.
The value of θ at each iteration is given by the weighted least squares regression of y on X. This is carried out by first transforming the y and X by
y~i=yi G iix~ij=x ij G ii,j=1,2,…,m
and then using (F04JGF not in this release). If X is of full column rank then an orthogonal-triangular (QR) decomposition is used; if not, a singular value decomposition is used.
The following functions are available for ψ and χ in g02ha.
(a) Unit Weights
ψ t=t,  χ t=t 2 2.
This gives least squares regression.
(b) Huber's Function
ψ t=max-c,min c,t,  χ t=t 2 2,t≤dd 2 2,t>d
(c) Hampel's Piecewise Linear Function
ψ h 1,h 2,h 3 t=-ψ h 1,h 2,h 3-t=t,0≤t≤h 1h 1,h 1≤t≤h 2h 1 h 3-t/h 3-h 2,h 2≤t≤h 30,h 3<t
χ t=t 2 2,t≤dd 2 2,t>d
(d) Andrew's Sine Wave Function
ψ t=sin t,-π≤t≤π0,t>π χ t=t 2 2,t≤dd 2 2,t>d
(e) Tukey's Bi-weight
ψ t=t 1-t 2 2,t≤10,t>1 χ t=t 2 2,t≤dd 2 2,t>d
where c, h 1, h 2, h 3, and d are given constants.
Several schemes for calculating weights have been proposed, see Hampel et al. (1986) and Marazzi (1987a). As the different independent variables may be measured on different scales, one group of proposed weights aims to bound a standardized measure of influence. To obtain such weights the matrix A has to be found such that:
1 n∑i=1 n u zi 2 zi ziT=I
and
zi=A xi,
where | xi is a vector of length m containing the ith row of X,
 | A is an m by m lower triangular matrix,
and | u is a suitable function.
The weights are then calculated as
wi=f zi 2
for a suitable function f.
g02ha finds A using the iterative procedure
Ak=Sk+I A k-1,
where Sk=s jl,
s jl=-min max h jl/n,-BL,BL,j>l-min max 12 h jj/n-1,-BD,BD,j=l
and
h jl=∑i=1 n u zi 2 z ijz il
and BL and BD are bounds set at 0.9.
Two weights are available in g02ha:
(i) Krasker–Welsch Weights
u t=g 1 ct,
where | g 1 t=t 2+1-t 22 Φ t-1-2 tϕ t,
 | Φ t is the standard Normal cumulative distribution function,
 | ϕ t is the standard Normal probability density function,
and | f t=1 t.
These are for use with Schweppe type regression.
(ii) Maronna's Proposed Weights
u t=c t 2t>c1t≤cf t=u t.
These are for use with Mallows type regression.
Finally the asymptotic variance-covariance matrix, C, of the estimates θ is calculated.
For Huber type regression
C=fH XT X-1σ^2,
where
fH=1 n-m∑i=1 n ψ 2 ri/σ^1 n∑i=1 n ψ′ri σ^2 κ 2
κ 2=1+mn1 n∑i=1 n ψ′ri/σ^-1 n∑i=1 n ψ′ri/σ^2 1 n∑i=1 n ψ′ri σ^2.
See Huber (1981) and Marazzi (1987b).
For Mallows and Schweppe type regressions C is of the form
σ^n 2 S 1-1 S 2 S 1-1,
where S 1=1 n XT DX and S 2=1 n XT PX.
D is a diagonal matrix such that the ith element approximates E ψ′ri/σ wi in the Schweppe case and E ψ′ri/σ wi in the Mallows case.
P is a diagonal matrix such that the ith element approximates E ψ 2 ri/σ wi wi 2 in the Schweppe case and E ψ 2 ri/σ wi 2 in the Mallows case.
Two approximations are available in g02ha:
1. Average over the ri
SchweppeMallowsDi=1 n∑j=1 n ψ′rj σ^wi wi Di=1 n∑j=1 n ψ′rj σ^wiPi=1 n∑j=1 n ψ 2 rj σ^wi wi 2 Pi=1 n∑j=1 n ψ 2 rj σ^wi 2
2. Replace expected value by observed
SchweppeMallowsDi=ψ′ri σ^wi wi Di=ψ′ri σ^wiPi=ψ 2 ri σ^wi wi 2 Pi=ψ 2 ri σ^wi 2.
See Hampel et al. (1986) and Marazzi (1987b).
Note: there is no explicit provision in the method for a constant term in the regression model. However, the addition of a dummy variable whose value is 1.0 for all observations will produce a value of θ^ corresponding to the usual constant term.
g02ha is based on routines in ROBETH; see Marazzi (1987a).

References

Hampel F R, Ronchetti E M, Rousseeuw P J and Stahel W A (1986) Robust Statistics. The Approach Based on Influence Functions Wiley
Huber P J (1981) Robust Statistics Wiley
Marazzi A (1987a) Weights for bounded influence regression in ROBETH Cah. Rech. Doc. IUMSP, No. 3 ROB 3 Institut Universitaire de Médecine Sociale et Préventive, Lausanne
Marazzi A (1987b) Subroutines for robust and bounded influence regression in ROBETH Cah. Rech. Doc. IUMSP, No. 3 ROB 2 Institut Universitaire de Médecine Sociale et Préventive, Lausanne

Error Indicators and Warnings

Note: g02ha may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDC, WORK) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | n≤1,
or | m<1,
or | n≤m,
ifail=2
On entry, | ipsi<0,
or | ipsi>4.
ifail=3
On entry, | sigma≤0.0,
or | ipsi=1 and cpsi≤0.0,
or | ipsi=2 and h1<0.0,
or | ipsi=2 and h1>h2,
or | ipsi=2 and h2>h3,
or | ipsi=2 and h1=h2=h3=0.0,
or | ipsi≠0 and isigma>0 and dchi≤0.0,
or | indw>0 and cucv<m,
or | indw<0 and cucv<m.
ifail=4
On entry, | tol≤0.0,
or | maxit≤0.
ifail=5
The number of iterations required to calculate the weights exceeds maxit. (Only if indw≠0.)
ifail=6
The number of iterations required to calculate β 1 exceeds maxit. (Only if indw<0 and isigma<0.)
ifail=7
Either the number of iterations required to calculate θ and σ exceeds maxit (note that, in this case _work[2]=maxit on exit), or the iterations to solve the weighted least squares equations failed to converge. The latter is an unlikely error exit.
ifail=8
The weighted least squares equations are not of full rank.
ifail=9
If indw=0 then XT X is almost singular.
If indw≠0 then S 1 is singular or almost singular. This may be due to too many diagonal elements of the matrix being zero, see [Further Comments].
ifail=10
In calculating the correlation factor for the asymptotic variance-covariance matrix either the value of
1 n∑i=1 n ψ′ri/σ^=0,   or  κ=0,   or  ∑i=1 n ψ 2 ri/σ^=0.
See [Further Comments]. In this case c is returned as XT X.
(Only if indw=0.)
ifail=11
The estimated variance for an element of θ≤0.
In this case the diagonal element of c will contain the negative variance and the above diagonal elements in the row and column corresponding to the element will be returned as zero.
This error may be caused by rounding errors or too many of the diagonal elements of P being zero, where P is defined in [Description]. See [Further Comments].
ifail=12
The degrees of freedom for error, n-k≤0 (this is an unlikely error exit), or the estimated value of σ was 0 during an iteration.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The precision of the estimates is determined by tol. As a more stable method is used to calculate the estimates of θ than is used to calculate the covariance matrix, it is possible for the least squares equations to be of full rank but the XT X matrix to be too nearly singular to be inverted.

Parallelism and Performance

None.

Further Comments

In cases when isigma≥0 it is important for the value of sigma to be of a reasonable magnitude. Too small a value may cause too many of the winsorized residuals, i.e., ψ ri/σ, to be zero or a value of ψ′ri/σ, used to estimate the asymptotic covariance matrix, to be zero. This can lead to errors ifail=8 or 9 (if indw≠0), ifail=10 (if indw=0) and ifail=11.
g02hb, g02hd and g02hf together carry out the same calculations as g02ha but for user-supplied functions for ψ, χ, ψ′ and u.

Example

The number of observations and the number of x variables are read in followed by the data. The option parameters are then read in (in this case giving Schweppe type regression with Hampel's ψ function and Huber's χ function and then using the ‘replace expected by observed’ option in calculating the covariances). Finally a set of values for the constants are read in.
After a call to g02ha, θ^, its standard error and σ^ are printed. In addition the weight and residual for each observation is printed.

Example program (C#): g02hae.cs

Example program data: g02hae.d

Example program results: g02hae.r

See Also

G02 Class
G02 Members


g02hb Method

[image]

NAG Library for .NET Release 2
G02..::g02hb Method
G02 Class See Also Send Feedback
g02hb finds, for a real matrix X of full column rank, a lower triangular matrix A such that AT A-1 is proportional to a robust estimate of the covariance of the variables. g02hb is intended for the calculation of weights of bounded influence regression using g02hd.

Syntax

C#
public static void g02hb(
    G02..::..G02HB_UCV ucv,
    int n,
    int m,
    double[,] x,
    double[] a,
    double[] z,
    double bl,
    double bd,
    double tol,
    int maxit,
    int nitmon,
    out int nit,
    out int ifail
)
Visual Basic
Public Shared Sub g02hb ( _
    ucv As G02..::..G02HB_UCV, _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    a As Double(), _
    z As Double(), _
    bl As Double, _
    bd As Double, _
    tol As Double, _
    maxit As Integer, _
    nitmon As Integer, _
    <OutAttribute> ByRef nit As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02hb(
    G02..::..G02HB_UCV^ ucv,
    int n,
    int m,
    array<double,2>^ x,
    array<double>^ a,
    array<double>^ z,
    double bl,
    double bd,
    double tol,
    int maxit,
    int nitmon,
    [OutAttribute] int% nit,
    [OutAttribute] int% ifail
)
F#
static member g02hb :
        ucv : G02..::..G02HB_UCV *
        n : int *
        m : int *
        x : float[,] *
        a : float[] *
        z : float[] *
        bl : float *
        bd : float *
        tol : float *
        maxit : int *
        nitmon : int *
        nit : int byref *
        ifail : int byref -> unit

Parameters

ucv
Type: NagLibrary..::..G02..::..G02HB_UCV
ucv must return the value of the function u for a given value of its argument. The value of u must be non-negative.

A delegate of type G02HB_UCV.

n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n>1.
m
Type: System..::..Int32
On entry: m, the number of independent variables.
Constraint: 1≤m≤n.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: the real matrix X, i.e., the independent variables. x[i-1,j-1] must contain the ijth element of x, for i=1,2,…,n and j=1,2,…,m.
a
Type: array< System..::..Double >[]()[][]
An array of size [m×m+1/2]
On entry: an initial estimate of the lower triangular real matrix A. Only the lower triangular elements must be given and these should be stored row-wise in the array.
The diagonal elements must be ≠0, although in practice will usually be >0. If the magnitudes of the columns of X are of the same order the identity matrix will often provide a suitable initial value for A. If the columns of X are of different magnitudes, the diagonal elements of the initial value of A should be approximately inversely proportional to the magnitude of the columns of X.
On exit: the lower triangular elements of the matrix A, stored row-wise.
z
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the value zi 2, for i=1,2,…,n.
bl
Type: System..::..Double
On entry: the magnitude of the bound for the off-diagonal elements of Sk.
Suggested value: bl=0.9.
Constraint: bl>0.0.
bd
Type: System..::..Double
On entry: the magnitude of the bound for the diagonal elements of Sk.
Suggested value: bd=0.9.
Constraint: bd>0.0.
tol
Type: System..::..Double
On entry: the relative precision for the final value of A. Iteration will stop when the maximum value of s jl is less than tol.
Constraint: tol>0.0.
maxit
Type: System..::..Int32
On entry: the maximum number of iterations that will be used during the calculation of A.
A value of maxit=50 will often be adequate.
Constraint: maxit>0.
nitmon
Type: System..::..Int32
On entry: determines the amount of information that is printed on each iteration.
nitmon>0
The value of A and the maximum value of s jl will be printed at the first and every nitmon iterations.
nitmon≤0
No iteration monitoring is printed.
When printing occurs the output is directed to the current advisory message unit (see (X04ABF not in this release)).
nit
Type: System..::..Int32 %
On exit: the number of iterations performed.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

In fitting the linear regression model
y=Xθ+ε,
where | y is a vector of length n of the dependent variable,
 | X is an n by m matrix of independent variables,
 | θ is a vector of length m of unknown parameters,
and | ε is a vector of length n of unknown errors,
it may be desirable to bound the influence of rows of the X matrix. This can be achieved by calculating a weight for each observation. Several schemes for calculating weights have been proposed (see Hampel et al. (1986) and Marazzi (1987)). As the different independent variables may be measured on different scales one group of proposed weights aims to bound a standardized measure of influence. To obtain such weights the matrix A has to be found such that
1 n∑i=1 n u zi 2 zi ziT=I​  I​ is the identity matrix
and
zi=A xi,
where | xi is a vector of length m containing the elements of the ith row of X,
 | A is an m by m lower triangular matrix,
 | zi is a vector of length m,
and | u is a suitable function.
The weights for use with g02hd may then be computed using
wi=f zi 2
for a suitable user-supplied function f.
g02hb finds A using the iterative procedure
Ak=Sk+I A k-1,
where Sk=s jl, for j=1,2,…,m and l=1,2,…,m, is a lower triangular matrix such that
  • s jl=-min max h jl/n,-BL,BL,j>l-min max 12 h jj/n-1,-BD,BD,j=l
  • h jl=∑i=1 n u zi 2 z ijz il
and BD and BL are suitable bounds.
In addition the values of zi 2, for i=1,2,…,n, are calculated.
g02hb is based on routines in ROBETH; see Marazzi (1987).

References

Hampel F R, Ronchetti E M, Rousseeuw P J and Stahel W A (1986) Robust Statistics. The Approach Based on Influence Functions Wiley
Huber P J (1981) Robust Statistics Wiley
Marazzi A (1987) Weights for bounded influence regression in ROBETH Cah. Rech. Doc. IUMSP, No. 3 ROB 3 Institut Universitaire de Médecine Sociale et Préventive, Lausanne

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | n≤1,
or | m<1,
or | n<m,
ifail=2
On entry, | tol≤0.0,
or | maxit≤0,
or | diagonal element of a=0.0,
or | bl≤0.0,
or | bd≤0.0.
ifail=3
Value returned by ucv<0.
ifail=4
The method has failed to converge in maxit iterations.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

On successful exit the accuracy of the results is related to the value of tol; see [Parameters].

Parallelism and Performance

None.

Further Comments

The existence of A will depend upon the function u; (see Hampel et al. (1986) and Marazzi (1987)), also if X is not of full rank a value of A will not be found. If the columns of X are almost linearly related then convergence will be slow.

Example

This example reads in a matrix of real numbers and computes the Krasker–Welsch weights (see Marazzi (1987)). The matrix A and the weights are then printed.

Example program (C#): g02hbe.cs

Example program data: g02hbe.d

Example program results: g02hbe.r

See Also

G02 Class
G02 Members


g02hd Method

[image]

NAG Library for .NET Release 2
G02..::g02hd Method
G02 Class See Also Send Feedback
g02hd performs bounded influence regression (M-estimates) using an iterative weighted least squares algorithm.

Syntax

C#
public static void g02hd(
    G02..::..G02HD_CHI chi,
    G02..::..G02HD_PSI psi,
    double psip0,
    double beta,
    int indw,
    int isigma,
    int n,
    int m,
    double[,] x,
    double[] y,
    double[] wgt,
    double[] theta,
    out int k,
    ref double sigma,
    double[] rs,
    double tol,
    double eps,
    int maxit,
    int nitmon,
    out int nit,
    out int ifail
)
Visual Basic
Public Shared Sub g02hd ( _
    chi As G02..::..G02HD_CHI, _
    psi As G02..::..G02HD_PSI, _
    psip0 As Double, _
    beta As Double, _
    indw As Integer, _
    isigma As Integer, _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    y As Double(), _
    wgt As Double(), _
    theta As Double(), _
    <OutAttribute> ByRef k As Integer, _
    ByRef sigma As Double, _
    rs As Double(), _
    tol As Double, _
    eps As Double, _
    maxit As Integer, _
    nitmon As Integer, _
    <OutAttribute> ByRef nit As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02hd(
    G02..::..G02HD_CHI^ chi,
    G02..::..G02HD_PSI^ psi,
    double psip0,
    double beta,
    int indw,
    int isigma,
    int n,
    int m,
    array<double,2>^ x,
    array<double>^ y,
    array<double>^ wgt,
    array<double>^ theta,
    [OutAttribute] int% k,
    double% sigma,
    array<double>^ rs,
    double tol,
    double eps,
    int maxit,
    int nitmon,
    [OutAttribute] int% nit,
    [OutAttribute] int% ifail
)
F#
static member g02hd :
        chi : G02..::..G02HD_CHI *
        psi : G02..::..G02HD_PSI *
        psip0 : float *
        beta : float *
        indw : int *
        isigma : int *
        n : int *
        m : int *
        x : float[,] *
        y : float[] *
        wgt : float[] *
        theta : float[] *
        k : int byref *
        sigma : float byref *
        rs : float[] *
        tol : float *
        eps : float *
        maxit : int *
        nitmon : int *
        nit : int byref *
        ifail : int byref -> unit

Parameters

chi
Type: NagLibrary..::..G02..::..G02HD_CHI
If isigma>0, chi must return the value of the weight function χ for a given value of its argument. The value of χ must be non-negative.

A delegate of type G02HD_CHI.

If isigma≤0, the actual parameter chi may be the dummy method G02HDZ. (G02HDZ is included in the NAG Library.)
psi
Type: NagLibrary..::..G02..::..G02HD_PSI
psi must return the value of the weight function ψ for a given value of its argument.

A delegate of type G02HD_PSI.

psip0
Type: System..::..Double
On entry: the value of ψ′0.
beta
Type: System..::..Double
On entry: if isigma<0, beta must specify the value of β 1.
For Huber and Schweppe type regressions, β 1 is the 75th percentile of the standard Normal distribution (see g01fa). For Mallows type regression β 1 is the solution to
1 n∑i=1 n Φ β 1/wi=0.75,
where Φ is the standard Normal cumulative distribution function (see s15ab).
If isigma>0, beta must specify the value of β 2.
β 2=∫-∞∞χ z ϕ z dz,in the Huber case;β 2=1 n∑i=1 n wi∫-∞∞χ z ϕ z dz,in the Mallows case;β 2=1 n∑i=1 n wi 2∫-∞∞χ z/wi ϕ z dz,in the Schweppe case;
where ϕ is the standard normal density, i.e., 1 2 π exp-12 x 2.
If isigma=0, beta is not referenced.
Constraint: if isigma≠0, beta>0.0.
indw
Type: System..::..Int32
On entry: determines the type of regression to be performed.
indw=0
Huber type regression.
indw<0
Mallows type regression.
indw>0
Schweppe type regression.
Constraint: indw=-1, 0 or 1.
isigma
Type: System..::..Int32
On entry: determines how σ is to be estimated.
isigma=0
σ is held constant at its initial value.
isigma<0
σ is estimated by median absolute deviation of residuals.
isigma>0
σ is estimated using the χ function.
Constraint: isigma=-1, 0 or 1.
n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n>1.
m
Type: System..::..Int32
On entry: m, the number of independent variables.
Constraint: 1≤m<n.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: the values of the X matrix, i.e., the independent variables. x[i-1,j-1] must contain the ijth element of x, for i=1,2,…,n and j=1,2,…,m.
If indw<0, during calculations the elements of x will be transformed as described in [Description]. Before exit the inverse transformation will be applied. As a result there may be slight differences between the input x and the output x.
On exit: unchanged, except as described above.
y
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the data values of the dependent variable.
y[i-1] must contain the value of y for the ith observation, for i=1,2,…,n.
If indw<0, during calculations the elements of y will be transformed as described in [Description]. Before exit the inverse transformation will be applied. As a result there may be slight differences between the input y and the output y.
On exit: unchanged, except as described above.
wgt
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the weight for the ith observation, for i=1,2,…,n.
If indw<0, during calculations elements of wgt will be transformed as described in [Description]. Before exit the inverse transformation will be applied. As a result there may be slight differences between the input wgt and the output wgt.
If wgt[i-1]≤0, the ith observation is not included in the analysis.
If indw=0, wgt is not referenced.
On exit: unchanged, except as described above.
theta
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: starting values of the parameter vector θ. These may be obtained from least squares regression. Alternatively if isigma<0 and sigma=1 or if isigma>0 and sigma approximately equals the standard deviation of the dependent variable, y, then theta[i-1]=0.0, for i=1,2,…,m may provide reasonable starting values.
On exit: the M-estimate of θi, for i=1,2,…,m.
k
Type: System..::..Int32 %
On exit: the column rank of the matrix X.
sigma
Type: System..::..Double %
On entry: a starting value for the estimation of σ. sigma should be approximately the standard deviation of the residuals from the model evaluated at the value of θ given by theta on entry.
Constraint: sigma>0.0.
On exit: the final estimate of σ if isigma≠0 or the value assigned on entry if isigma=0.
rs
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the residuals from the model evaluated at final value of theta, i.e., rs contains the vector y-X θ^.
tol
Type: System..::..Double
On entry: the relative precision for the final estimates. Convergence is assumed when both the relative change in the value of sigma and the relative change in the value of each element of theta are less than tol.
It is advisable for tol to be greater than 100×machine precision.
Constraint: tol>0.0.
eps
Type: System..::..Double
On entry: a relative tolerance to be used to determine the rank of X. See (F04JGF not in this release) for further details.
If eps<machine precision or eps>1.0 then machine precision will be used in place of tol.
A reasonable value for eps is 5.0×10-6 where this value is possible.
maxit
Type: System..::..Int32
On entry: the maximum number of iterations that should be used during the estimation.
A value of maxit=50 should be adequate for most uses.
Constraint: maxit>0.
nitmon
Type: System..::..Int32
On entry: determines the amount of information that is printed on each iteration.
nitmon≤0
No information is printed.
nitmon>0
On the first and every nitmon iterations the values of sigma, theta and the change in theta during the iteration are printed.
When printing occurs the output is directed to the current advisory message unit (see (X04ABF not in this release)).
nit
Type: System..::..Int32 %
On exit: the number of iterations that were used during the estimation.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

For the linear regression model
y=Xθ+ε,
where | y is a vector of length n of the dependent variable,
 | X is a n by m matrix of independent variables of column rank k,
 | θ is a vector of length m of unknown parameters,
and | ε is a vector of length n of unknown errors with var εi=σ 2,
g02hd calculates the M-estimates given by the solution, θ^, to the equation
∑i=1 n ψ ri/σ wi wix ij=0,  j=1,2,…,m, (1)
where | ri is the ith residual, i.e., the ith element of the vector r=y-X θ^,
 | ψ is a suitable weight function,
 | wi are suitable weights such as those that can be calculated by using output from g02hb,
and | σ may be estimated at each iteration by the median absolute deviation of the residuals σ^=medi ri/β 1
or as the solution to
∑i=1 n χ ri/σ^wi wi 2=n-k β 2
for a suitable weight function χ, where β 1 and β 2 are constants, chosen so that the estimator of σ is asymptotically unbiased if the errors, εi, have a Normal distribution. Alternatively σ may be held at a constant value.
The above describes the Schweppe type regression. If the wi are assumed to equal 1 for all i, then Huber type regression is obtained. A third type, due to Mallows, replaces (1) by
∑i=1 n ψ ri/σ wix ij=0,  j=1,2,…,m.
This may be obtained by use of the transformations
wi*←wiyi*←yi wix ij*←x ij wi,  j=1,2,…,m
(see Marazzi (1987)).
The calculation of the estimates of θ can be formulated as an iterative weighted least squares problem with a diagonal weight matrix G given by
G ii=ψ ri/σ wiri/σ wi,ri≠0ψ′0,ri=0..
The value of θ at each iteration is given by the weighted least squares regression of y on X. This is carried out by first transforming the y and X by
y~i=yi G iix~ij=x ij G ii,  j=1,2,…,m
and then using (F04JGF not in this release) . If X is of full column rank then an orthogonal-triangular (QR) decomposition is used; if not, a singular value decomposition is used.
Observations with zero or negative weights are not included in the solution.
Note: there is no explicit provision in the method for a constant term in the regression model. However, the addition of a dummy variable whose value is 1.0 for all observations will produce a value of θ^ corresponding to the usual constant term.
g02hd is based on routines in ROBETH, see Marazzi (1987).

References

Hampel F R, Ronchetti E M, Rousseeuw P J and Stahel W A (1986) Robust Statistics. The Approach Based on Influence Functions Wiley
Huber P J (1981) Robust Statistics Wiley
Marazzi A (1987) Subroutines for robust and bounded influence regression in ROBETH Cah. Rech. Doc. IUMSP, No. 3 ROB 2 Institut Universitaire de Médecine Sociale et Préventive, Lausanne

Error Indicators and Warnings

Note: g02hd may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | n≤1,
or | m<1,
or | n≤m,
ifail=2
On entry, | beta≤0.0, and isigma≠0,
or | sigma≤0.0.
ifail=3
On entry, | tol≤0.0,
or | maxit≤0.
ifail=4
A value returned by the chi function is negative.
ifail=5
During iterations a value of sigma≤0.0 was encountered.
ifail=6
A failure occurred in (F04JGF not in this release) . This is an extremely unlikely error. If it occurs, please contact NAG.
ifail=7
The weighted least squares equations are not of full rank. This may be due to the X matrix not being of full rank, in which case the results will be valid. It may also occur if some of the G ii values become very small or zero, see [Further Comments]. The rank of the equations is given by k. If the matrix just fails the test for nonsingularity then the result ifail=7 and k=m is possible (see (F04JGF not in this release)).
ifail=8
The method has failed to converge in maxit iterations.
ifail=9
Having removed cases with zero weight, the value of n-k≤0, i.e., no degree of freedom for error. This error will only occur if isigma>0.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The accuracy of the results is controlled by tol. For the accuracy of the weighted least squares see (F04JGF not in this release).

Parallelism and Performance

None.

Further Comments

In cases when isigma≠0 it is important for the value of sigma to be of a reasonable magnitude. Too small a value may cause too many of the winsorized residuals, i.e., ψ ri/σ, to be zero, which will lead to convergence problems and may trigger the ifail=7 error.
By suitable choice of the functions chi and psi this method may be used for other applications of iterative weighted least squares.
For the variance-covariance matrix of θ see g02hf.

Example

Having input X, Y and the weights, a Schweppe type regression is performed using Huber's ψ function. The method BETCAL calculates the appropriate value of β 2.

Example program (C#): g02hde.cs

Example program data: g02hde.d

Example program results: g02hde.r

See Also

G02 Class
G02 Members


g02hdz Method

[image]

NAG Library for .NET Release 2
G02..::g02hdz Method
G02 Class See Also Send Feedback
Auxiliary for use as a delegate parameter

Syntax

C#
public static double g02hdz(
    double t
)
Visual Basic
Public Shared Function g02hdz ( _
    t As Double _
) As Double
Visual C++
public:
static double g02hdz(
    double t
)
F#
static member g02hdz :
        t : float -> float

Parameters

t
Type: System..::..Double
On entry: the argument for which _chi must be evaluated.

Return Value

Auxiliary for use as a delegate parameter

Description

Auxiliary for use as a delegate parameter

References

None.

Error Indicators and Warnings

None.

Accuracy

Not applicable.

Further Comments

None.

Example

None.

See Also

G02 Class
G02 Members


g02hf Method

[image]

NAG Library for .NET Release 2
G02..::g02hf Method
G02 Class See Also Send Feedback
g02hf calculates an estimate of the asymptotic variance-covariance matrix for the bounded influence regression estimates (M-estimates). It is intended for use with g02hd.

Syntax

C#
public static void g02hf(
    G02..::..G02HF_PSI psi,
    G02..::..G02HF_PSP psp,
    int indw,
    int indc,
    double sigma,
    int n,
    int m,
    double[,] x,
    double[] rs,
    double[] wgt,
    double[,] c,
    double[] diag_d,
    double[] diag_p,
    out int ifail
)
Visual Basic
Public Shared Sub g02hf ( _
    psi As G02..::..G02HF_PSI, _
    psp As G02..::..G02HF_PSP, _
    indw As Integer, _
    indc As Integer, _
    sigma As Double, _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    rs As Double(), _
    wgt As Double(), _
    c As Double(,), _
    diag_d As Double(), _
    diag_p As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02hf(
    G02..::..G02HF_PSI^ psi,
    G02..::..G02HF_PSP^ psp,
    int indw,
    int indc,
    double sigma,
    int n,
    int m,
    array<double,2>^ x,
    array<double>^ rs,
    array<double>^ wgt,
    array<double,2>^ c,
    array<double>^ diag_d,
    array<double>^ diag_p,
    [OutAttribute] int% ifail
)
F#
static member g02hf :
        psi : G02..::..G02HF_PSI *
        psp : G02..::..G02HF_PSP *
        indw : int *
        indc : int *
        sigma : float *
        n : int *
        m : int *
        x : float[,] *
        rs : float[] *
        wgt : float[] *
        c : float[,] *
        diag_d : float[] *
        diag_p : float[] *
        ifail : int byref -> unit

Parameters

psi
Type: NagLibrary..::..G02..::..G02HF_PSI
psi must return the value of the ψ function for a given value of its argument.

A delegate of type G02HF_PSI.

psp
Type: NagLibrary..::..G02..::..G02HF_PSP
psp must return the value of ψ′t=d dt ψ t for a given value of its argument.

A delegate of type G02HF_PSP.

indw
Type: System..::..Int32
On entry: the type of regression for which the asymptotic variance-covariance matrix is to be calculated.
indw=-1
Mallows type regression.
indw=0
Huber type regression.
indw=1
Schweppe type regression.
indc
Type: System..::..Int32
On entry: if indw≠0, indc must specify the approximation to be used.
If indc=1, averaging over residuals.
If indc=0, replacing expected by observed.
If indw=0, indc is not referenced.
sigma
Type: System..::..Double
On entry: the value of σ^, as given by g02hd.
Constraint: sigma>0.0.
n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n>1.
m
Type: System..::..Int32
On entry: m, the number of independent variables.
Constraint: 1≤m<n.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: the values of the X matrix, i.e., the independent variables. x[i-1,j-1] must contain the ijth element of X, for i=1,2,…,n and j=1,2,…,m.
rs
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the residuals from the bounded influence regression. These are given by g02hd.
wgt
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: if indw≠0, wgt must contain the vector of weights used by the bounded influence regression. These should be used with g02hd.
If indw=0, wgt is not referenced.
c
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: the estimate of the variance-covariance matrix.
diag_d
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: diag_d will contain the diagonal elements of the matrix _d
diag_p
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: diag_p will contain the diagonal elements of the matrix _p
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

For a description of bounded influence regression see g02hd. Let θ be the regression parameters and let C be the asymptotic variance-covariance matrix of θ^. Then for Huber type regression
C=fH XT X-1σ^2,
where
fH=1 n-m∑i=1 n ψ 2 ri/σ^1 n∑ψ′ri σ^2 κ 2
κ 2=1+mn1 n∑i=1 n ψ′ri/σ^-1 n∑i=1 n ψ′ri/σ^2 1 n∑i=1 n ψ′ri σ^2,
see Huber (1981) and Marazzi (1987).
For Mallows and Schweppe type regressions, C is of the form
σ^n 2 S 1-1 S 2 S 1-1,
where S 1=1 n XT DX and S 2=1 n XT PX.
D is a diagonal matrix such that the ith element approximates E ψ′ri/σ wi in the Schweppe case and E ψ′ri/σ wi in the Mallows case.
P is a diagonal matrix such that the ith element approximates E ψ 2 ri/σ wi wi 2 in the Schweppe case and E ψ 2 ri/σ wi 2 in the Mallows case.
Two approximations are available in g02hf:
1. Average over the ri
SchweppeMallowsDi=1 n∑j=1 n ψ′rj σ^wi wi Di=1 n∑j=1 n ψ′rj σ^wiPi=1 n∑j=1 n ψ 2 rj σ^wi wi 2 Pi=1 n∑j=1 n ψ 2 rj σ^wi 2
2. Replace expected value by observed
SchweppeMallowsDi=ψ′ri σ^wi wi Di=ψ′ri σ^wiPi=ψ 2 ri σ^wi wi 2 Pi=ψ 2 ri σ^wi 2
See Hampel et al. (1986) and Marazzi (1987).
In all cases σ^ is a robust estimate of σ.
g02hf is based on routines in ROBETH; see Marazzi (1987).

References

Hampel F R, Ronchetti E M, Rousseeuw P J and Stahel W A (1986) Robust Statistics. The Approach Based on Influence Functions Wiley
Huber P J (1981) Robust Statistics Wiley
Marazzi A (1987) Subroutines for robust and bounded influence regression in ROBETH Cah. Rech. Doc. IUMSP, No. 3 ROB 2 Institut Universitaire de Médecine Sociale et Préventive, Lausanne

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDC, WK) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | n≤1,
or | m<1,
or | n≤m,
ifail=2
On entry, sigma≤0.0.
ifail=3
If indw=0 then the matrix XT X is either not positive definite, possibly due to rounding errors, or is ill-conditioned.
If indw≠0 then the matrix S 1 is singular or almost singular. This may be due to many elements of D being zero.
ifail=4
Either the value of 1 n∑i=1 n ψ′ri σ^=0,
or κ=0,
or ∑i=1 n ψ 2 ri σ^=0.
In this situation g02hf returns C as XT X-1.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

In general, the accuracy of the variance-covariance matrix will depend primarily on the accuracy of the results from g02hd.

Parallelism and Performance

None.

Further Comments

g02hf is only for situations in which X has full column rank.
Care has to be taken in the choice of the ψ function since if ψ′t=0 for too wide a range then either the value of fH will not exist or too many values of Di will be zero and it will not be possible to calculate C.

Example

The asymptotic variance-covariance matrix is calculated for a Schweppe type regression. The values of X, σ^ and the residuals and weights are read in. The averaging over residuals approximation is used.

Example program (C#): g02hfe.cs

Example program data: g02hfe.d

Example program results: g02hfe.r

See Also

G02 Class
G02 Members


g02hk Method

[image]

NAG Library for .NET Release 2
G02..::g02hk Method
G02 Class See Also Send Feedback
g02hk computes a robust estimate of the covariance matrix for an expected fraction of gross errors.

Syntax

C#
public static void g02hk(
    int n,
    int m,
    double[,] x,
    double eps,
    double[] cov,
    double[] theta,
    int maxit,
    int nitmon,
    double tol,
    out int nit,
    out int ifail
)
Visual Basic
Public Shared Sub g02hk ( _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    eps As Double, _
    cov As Double(), _
    theta As Double(), _
    maxit As Integer, _
    nitmon As Integer, _
    tol As Double, _
    <OutAttribute> ByRef nit As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02hk(
    int n,
    int m,
    array<double,2>^ x,
    double eps,
    array<double>^ cov,
    array<double>^ theta,
    int maxit,
    int nitmon,
    double tol,
    [OutAttribute] int% nit,
    [OutAttribute] int% ifail
)
F#
static member g02hk :
        n : int *
        m : int *
        x : float[,] *
        eps : float *
        cov : float[] *
        theta : float[] *
        maxit : int *
        nitmon : int *
        tol : float *
        nit : int byref *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n>1.
m
Type: System..::..Int32
On entry: m, the number of columns of the matrix X, i.e., number of independent variables.
Constraint: 1≤m≤n.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must contain the ith observation for the jth variable, for i=1,2,…,n and j=1,2,…,m.
eps
Type: System..::..Double
On entry: ε, the expected fraction of gross errors expected in the sample.
Constraint: 0.0≤eps<1.0.
cov
Type: array< System..::..Double >[]()[][]
An array of size [m×m+1/2]
On exit: a robust estimate of the covariance matrix, C. The upper triangular part of the matrix C is stored packed by columns. C ij is returned in cov[j×j-1/2+i-1], i≤j.
theta
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: the robust estimate of the location parameters θj, for j=1,2,…,m.
maxit
Type: System..::..Int32
On entry: the maximum number of iterations that will be used during the calculation of the covariance matrix.
Constraint: maxit>0.
nitmon
Type: System..::..Int32
On entry: indicates the amount of information on the iteration that is printed.
nitmon>0
The value of A, θ and δ (see [Accuracy]) will be printed at the first and every nitmon iterations.
nitmon≤0
No iteration monitoring is printed.
When printing occurs the output is directed to the current advisory message unit (see (X04ABF not in this release)).
tol
Type: System..::..Double
On entry: the relative precision for the final estimates of the covariance matrix.
Constraint: tol>0.0.
nit
Type: System..::..Int32 %
On exit: the number of iterations performed.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

For a set of n observations on m variables in a matrix X, a robust estimate of the covariance matrix, C, and a robust estimate of location, θ, are given by
C=τ 2AT A-1,
where τ 2 is a correction factor and A is a lower triangular matrix found as the solution to the following equations:
zi=A xi-θ,
1 n∑i=1 n w zi 2 zi=0,
and
1 n∑i=1 n u zi 2 zi ziT-I=0,
where | xi is a vector of length m containing the elements of the ith row of x,
 | zi is a vector of length m,
 | I is the identity matrix and 0 is the zero matrix,
and | w and u are suitable functions.
g02hk uses weight functions:
u t=au t 2,if ​t<au 2u t=1,if ​au 2≤t≤bu 2u t=bu t 2,if ​t>bu 2
and
w t=1,if ​t≤cww t=cw t,if ​t>cw
for constants au, bu and cw.
These functions solve a minimax problem considered by Huber (see Huber (1981)). The values of au, bu and cw are calculated from the expected fraction of gross errors, ε (see Huber (1981) and Marazzi (1987)). The expected fraction of gross errors is the estimated proportion of outliers in the sample.
In order to make the estimate asymptotically unbiased under a Normal model a correction factor, τ 2, is calculated, (see Huber (1981) and Marazzi (1987)).
The matrix C is calculated using g02hl. Initial estimates of θj, for j=1,2,…,m, are given by the median of the jth column of X and the initial value of A is based on the median absolute deviation (see Marazzi (1987)). g02hk is based on routines in ROBETH; see Marazzi (1987).

References

Huber P J (1981) Robust Statistics Wiley
Marazzi A (1987) Weights for bounded influence regression in ROBETH Cah. Rech. Doc. IUMSP, No. 3 ROB 3 Institut Universitaire de Médecine Sociale et Préventive, Lausanne

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | n≤1,
or | m<1,
or | n<m,
or | eps<0.0,
or | eps≥1.0,
or | tol≤0.0,
or | maxit≤0.
ifail=2
On entry, a variable has a constant value, i.e., all elements in a column of X are identical.
ifail=3
The iterative procedure to find C has failed to converge in maxit iterations.
ifail=4
The iterative procedure to find C has become unstable. This may happen if the value of eps is too large for the sample.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

On successful exit the accuracy of the results is related to the value of tol; see [Parameters]. At an iteration let
(i) | d 1= the maximum value of the absolute relative change in A
(ii) | d 2= the maximum absolute change in u zi 2
(iii) | d 3= the maximum absolute relative change in θj
and let δ=max d 1,d 2,d 3. Then the iterative procedure is assumed to have converged when δ<tol.

Parallelism and Performance

None.

Further Comments

The existence of A, and hence C, will depend upon the function u (see Marazzi (1987)); also if X is not of full rank a value of A will not be found. If the columns of X are almost linearly related, then convergence will be slow.

Example

A sample of 10 observations on three variables is read in and the robust estimate of the covariance matrix is computed assuming 10% gross errors are to be expected. The robust covariance is then printed.

Example program (C#): g02hke.cs

Example program data: g02hke.d

Example program results: g02hke.r

See Also

G02 Class
G02 Members


g02hl Method

[image]

NAG Library for .NET Release 2
G02..::g02hl Method
G02 Class See Also Send Feedback
g02hl calculates a robust estimate of the covariance matrix for user-supplied weight functions and their derivatives.

Syntax

C#
public static void g02hl(
    G02..::..G02HL_UCV ucv,
    int indm,
    int n,
    int m,
    double[,] x,
    double[] cov,
    double[] a,
    double[] wt,
    double[] theta,
    double bl,
    double bd,
    int maxit,
    int nitmon,
    double tol,
    out int nit,
    out int ifail
)
Visual Basic
Public Shared Sub g02hl ( _
    ucv As G02..::..G02HL_UCV, _
    indm As Integer, _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    cov As Double(), _
    a As Double(), _
    wt As Double(), _
    theta As Double(), _
    bl As Double, _
    bd As Double, _
    maxit As Integer, _
    nitmon As Integer, _
    tol As Double, _
    <OutAttribute> ByRef nit As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02hl(
    G02..::..G02HL_UCV^ ucv,
    int indm,
    int n,
    int m,
    array<double,2>^ x,
    array<double>^ cov,
    array<double>^ a,
    array<double>^ wt,
    array<double>^ theta,
    double bl,
    double bd,
    int maxit,
    int nitmon,
    double tol,
    [OutAttribute] int% nit,
    [OutAttribute] int% ifail
)
F#
static member g02hl :
        ucv : G02..::..G02HL_UCV *
        indm : int *
        n : int *
        m : int *
        x : float[,] *
        cov : float[] *
        a : float[] *
        wt : float[] *
        theta : float[] *
        bl : float *
        bd : float *
        maxit : int *
        nitmon : int *
        tol : float *
        nit : int byref *
        ifail : int byref -> unit

Parameters

ucv
Type: NagLibrary..::..G02..::..G02HL_UCV
ucv must return the values of the functions u and w and their derivatives for a given value of its argument.

A delegate of type G02HL_UCV.

indm
Type: System..::..Int32
On entry: indicates which form of the function v will be used.
indm=1
v=1.
indm≠1
v=u.
n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n>1.
m
Type: System..::..Int32
On entry: m, the number of columns of the matrix X, i.e., number of independent variables.
Constraint: 1≤m≤n.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must contain the ith observation on the jth variable, for i=1,2,…,n and j=1,2,…,m.
cov
Type: array< System..::..Double >[]()[][]
An array of size [m×m+1/2]
On exit: contains a robust estimate of the covariance matrix, C. The upper triangular part of the matrix C is stored packed by columns (lower triangular stored by rows), C ij is returned in cov[j×j-1/2+i-1], i≤j.
a
Type: array< System..::..Double >[]()[][]
An array of size [m×m+1/2]
On entry: an initial estimate of the lower triangular real matrix A. Only the lower triangular elements must be given and these should be stored row-wise in the array.
The diagonal elements must be ≠0, and in practice will usually be >0. If the magnitudes of the columns of X are of the same order, the identity matrix will often provide a suitable initial value for A. If the columns of X are of different magnitudes, the diagonal elements of the initial value of A should be approximately inversely proportional to the magnitude of the columns of X.
Constraint: a[j×j-1/2+j]≠0.0, for j=0,1,…,m-1.
On exit: the lower triangular elements of the inverse of the matrix A, stored row-wise.
wt
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: wt[i-1] contains the weights, wti=u zi 2, for i=1,2,…,n.
theta
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: an initial estimate of the location parameter, θj, for j=1,2,…,m.
In many cases an initial estimate of θj=0, for j=1,2,…,m, will be adequate. Alternatively medians may be used as given by (G07DAF not in this release).
On exit: contains the robust estimate of the location parameter, θj, for j=1,2,…,m.
bl
Type: System..::..Double
On entry: the magnitude of the bound for the off-diagonal elements of Sk, BL.
Suggested value: bl=0.9.
Constraint: bl>0.0.
bd
Type: System..::..Double
On entry: the magnitude of the bound for the diagonal elements of Sk, BD.
Suggested value: bd=0.9.
Constraint: bd>0.0.
maxit
Type: System..::..Int32
On entry: the maximum number of iterations that will be used during the calculation of A.
Suggested value: maxit=150.
Constraint: maxit>0.
nitmon
Type: System..::..Int32
On entry: indicates the amount of information on the iteration that is printed.
nitmon>0
The value of A, θ and δ (see [Accuracy]) will be printed at the first and every nitmon iterations.
nitmon≤0
No iteration monitoring is printed.
When printing occurs the output is directed to the current advisory message unit (see (X04ABF not in this release)).
tol
Type: System..::..Double
On entry: the relative precision for the final estimates of the covariance matrix. Iteration will stop when maximum δ (see [Accuracy]) is less than tol.
Constraint: tol>0.0.
nit
Type: System..::..Int32 %
On exit: the number of iterations performed.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

For a set of n observations on m variables in a matrix X, a robust estimate of the covariance matrix, C, and a robust estimate of location, θ, are given by:
C=τ 2AT A-1,
where τ 2 is a correction factor and A is a lower triangular matrix found as the solution to the following equations.
zi=A xi-θ
1 n∑i=1 n w zi 2 zi=0
and
1 n∑i=1 n u zi 2 zi ziT-v zi 2 I=0,
where | xi is a vector of length m containing the elements of the ith row of X,
 | zi is a vector of length m,
 | I is the identity matrix and 0 is the zero matrix,
and | w and u are suitable functions.
g02hl covers two situations:
(i) | v t=1 for all t,
(ii) | v t=u t.
The robust covariance matrix may be calculated from a weighted sum of squares and cross-products matrix about θ using weights wti=u zi. In case (i) a divisor of n is used and in case (ii) a divisor of ∑i=1 n wti is used. If w.=u., then the robust covariance matrix can be calculated by scaling each row of X by wti and calculating an unweighted covariance matrix about θ.
In order to make the estimate asymptotically unbiased under a Normal model a correction factor, τ 2, is needed. The value of the correction factor will depend on the functions employed (see Huber (1981) and Marazzi (1987)).
g02hl finds A using the iterative procedure as given by Huber.
Ak=Sk+I A k-1
and
θ jk=bj D 1+θ j k-1,
where Sk=s jl, for j=1,2,…,m and l=1,2,…,m, is a lower triangular matrix such that:
s jl=-min max h jl/D 3,-BL,BL,j>l-min max h jj/2 D 3-D 4/D 2,-BD,BD,j=l,
where
  • D 1=∑i=1 n w zi 2+1 m w′zi 2 zi 2
  • D 2=∑i=1 n 1 p u′zi 2 zi 2+2 u zi 2 zi 2-v′zi 2 zi 2
  • D 3=1 m+2∑i=1 n 1 m u′zi 2 zi 2+2 u zi 2+u zi 2 zi 2 2
  • D 4=∑i=1 n 1 m u zi 2 zi 2 2-v zi 2 2
  • h jl=∑i=1 n u zi 2 z ijz il, for j>l
  • h jj=∑i=1 n u zi 2z ij 2-z ij 2 2/m
  • bj=∑i=1 n w zi 2x ij-bj
  • and BD and BL are suitable bounds.
g02hl is based on routines in ROBETH; see Marazzi (1987).

References

Huber P J (1981) Robust Statistics Wiley
Marazzi A (1987) Weights for bounded influence regression in ROBETH Cah. Rech. Doc. IUMSP, No. 3 ROB 3 Institut Universitaire de Médecine Sociale et Préventive, Lausanne

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | n≤1,
or | m<1,
or | n<m,
ifail=2
On entry, | tol≤0.0,
or | maxit≤0,
or | diagonal element of a=0.0,
or | bl≤0.0,
or | bd≤0.0.
ifail=3
A column of x has a constant value.
ifail=4
Value of u or w returned by ucv<0.
ifail=5
The method has failed to converge in maxit iterations.
ifail=6
One of the following is zero: D 1, D 2 or D 3.
This may be caused by the functions u or w being too strict for the current estimate of A (or C). You should try either a larger initial estimate of A or make u and w less strict.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

On successful exit the accuracy of the results is related to the value of tol; see [Parameters]. At an iteration let
(i) | d 1= the maximum value of s jl
(ii) | d 2= the maximum absolute change in wt i
(iii) | d 3= the maximum absolute relative change in θj
and let δ=max d 1,d 2,d 3. Then the iterative procedure is assumed to have converged when δ<tol.

Parallelism and Performance

None.

Further Comments

The existence of A will depend upon the function u (see Marazzi (1987)); also if X is not of full rank a value of A will not be found. If the columns of X are almost linearly related, then convergence will be slow.

Example

A sample of 10 observations on three variables is read in along with initial values for A and theta and parameter values for the u and w functions, cu and cw. The covariance matrix computed by g02hl is printed along with the robust estimate of θ. ucv computes the Huber's weight functions:
u t=1,if  t≤cu 2u t=cu t 2,if  t>cu 2
and
w t=1,if  t≤cww t=cw t,if  t>cw
and their derivatives.

Example program (C#): g02hle.cs

Example program data: g02hle.d

Example program results: g02hle.r

See Also

G02 Class
G02 Members


g02hm Method

[image]

NAG Library for .NET Release 2
G02..::g02hm Method
G02 Class See Also Send Feedback
g02hm computes a robust estimate of the covariance matrix for user-supplied weight functions. The derivatives of the weight functions are not required.

Syntax

C#
public static void g02hm(
    G02..::..G02HM_UCV ucv,
    int indm,
    int n,
    int m,
    double[,] x,
    double[] cov,
    double[] a,
    double[] wt,
    double[] theta,
    double bl,
    double bd,
    int maxit,
    int nitmon,
    double tol,
    out int nit,
    out int ifail
)
Visual Basic
Public Shared Sub g02hm ( _
    ucv As G02..::..G02HM_UCV, _
    indm As Integer, _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    cov As Double(), _
    a As Double(), _
    wt As Double(), _
    theta As Double(), _
    bl As Double, _
    bd As Double, _
    maxit As Integer, _
    nitmon As Integer, _
    tol As Double, _
    <OutAttribute> ByRef nit As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02hm(
    G02..::..G02HM_UCV^ ucv,
    int indm,
    int n,
    int m,
    array<double,2>^ x,
    array<double>^ cov,
    array<double>^ a,
    array<double>^ wt,
    array<double>^ theta,
    double bl,
    double bd,
    int maxit,
    int nitmon,
    double tol,
    [OutAttribute] int% nit,
    [OutAttribute] int% ifail
)
F#
static member g02hm :
        ucv : G02..::..G02HM_UCV *
        indm : int *
        n : int *
        m : int *
        x : float[,] *
        cov : float[] *
        a : float[] *
        wt : float[] *
        theta : float[] *
        bl : float *
        bd : float *
        maxit : int *
        nitmon : int *
        tol : float *
        nit : int byref *
        ifail : int byref -> unit

Parameters

ucv
Type: NagLibrary..::..G02..::..G02HM_UCV
ucv must return the values of the functions u and w for a given value of its argument.

A delegate of type G02HM_UCV.

indm
Type: System..::..Int32
On entry: indicates which form of the function v will be used.
indm=1
v=1.
indm≠1
v=u.
n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n>1.
m
Type: System..::..Int32
On entry: m, the number of columns of the matrix X, i.e., number of independent variables.
Constraint: 1≤m≤n.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must contain the ith observation on the jth variable, for i=1,2,…,n and j=1,2,…,m.
cov
Type: array< System..::..Double >[]()[][]
An array of size [m×m+1/2]
On exit: a robust estimate of the covariance matrix, C. The upper triangular part of the matrix C is stored packed by columns (lower triangular stored by rows), that is C ij is returned in cov[j×j-1/2+i-1], i≤j.
a
Type: array< System..::..Double >[]()[][]
An array of size [m×m+1/2]
On entry: an initial estimate of the lower triangular real matrix A. Only the lower triangular elements must be given and these should be stored row-wise in the array.
The diagonal elements must be ≠0, and in practice will usually be >0. If the magnitudes of the columns of X are of the same order, the identity matrix will often provide a suitable initial value for A. If the columns of X are of different magnitudes, the diagonal elements of the initial value of A should be approximately inversely proportional to the magnitude of the columns of X.
Constraint: a[j×j-1/2+j]≠0.0, for j=0,1,…,m-1.
On exit: the lower triangular elements of the inverse of the matrix A, stored row-wise.
wt
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: wt[i-1] contains the weights, wti=u zi 2, for i=1,2,…,n.
theta
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: an initial estimate of the location parameter, θj, for j=1,2,…,m.
In many cases an initial estimate of θj=0, for j=1,2,…,m, will be adequate. Alternatively medians may be used as given by (G07DAF not in this release).
On exit: contains the robust estimate of the location parameter, θj, for j=1,2,…,m.
bl
Type: System..::..Double
On entry: the magnitude of the bound for the off-diagonal elements of Sk, BL.
Suggested value: bl=0.9.
Constraint: bl>0.0.
bd
Type: System..::..Double
On entry: the magnitude of the bound for the diagonal elements of Sk, BD.
Suggested value: bd=0.9.
Constraint: bd>0.0.
maxit
Type: System..::..Int32
On entry: the maximum number of iterations that will be used during the calculation of A.
Suggested value: maxit=150.
Constraint: maxit>0.
nitmon
Type: System..::..Int32
On entry: indicates the amount of information on the iteration that is printed.
nitmon>0
The value of A, θ and δ (see [Accuracy]) will be printed at the first and every nitmon iterations.
nitmon≤0
No iteration monitoring is printed.
tol
Type: System..::..Double
On entry: the relative precision for the final estimate of the covariance matrix. Iteration will stop when maximum δ (see [Accuracy]) is less than tol.
Constraint: tol>0.0.
nit
Type: System..::..Int32 %
On exit: the number of iterations performed.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

For a set of n observations on m variables in a matrix X, a robust estimate of the covariance matrix, C, and a robust estimate of location, θ, are given by
C=τ 2AT A-1,
where τ 2 is a correction factor and A is a lower triangular matrix found as the solution to the following equations.
zi=A xi-θ
1 n∑i=1 n w zi 2 zi=0
and
1 n∑i=1 n u zi 2 zi ziT-v zi 2 I=0,
where | xi is a vector of length m containing the elements of the ith row of X,
 | zi is a vector of length m,
 | I is the identity matrix and 0 is the zero matrix.
and | w and u are suitable functions.
g02hm covers two situations:
(i) | v t=1 for all t,
(ii) | v t=u t.
The robust covariance matrix may be calculated from a weighted sum of squares and cross-products matrix about θ using weights wti=u zi. In case (i) a divisor of n is used and in case (ii) a divisor of ∑i=1 n wti is used. If w.=u., then the robust covariance matrix can be calculated by scaling each row of X by wti and calculating an unweighted covariance matrix about θ.
In order to make the estimate asymptotically unbiased under a Normal model a correction factor, τ 2, is needed. The value of the correction factor will depend on the functions employed (see Huber (1981) and Marazzi (1987)).
g02hm finds A using the iterative procedure as given by Huber; see Huber (1981).
Ak=Sk+I A k-1
and
θ jk=bj D 1+θ j k-1,
where Sk=s jl, for j=1,2,…,m and l=1,2,…,m is a lower triangular matrix such that
s jl=-min max h jl/D 2,-BL,BL,j>l-min max 12 h jj/D 2-1,-BD,BD,j=l,
where
  • D 1=∑i=1 n w zi 2
  • D 2=∑i=1 n u zi 2
  • h jl=∑i=1 n u zi 2 z ijz il, for j≥l
  • bj=∑i=1 n w zi 2x ij-bj
and BD and BL are suitable bounds.
The value of τ may be chosen so that C is unbiased if the observations are from a given distribution.
g02hm is based on routines in ROBETH; see Marazzi (1987).

References

Huber P J (1981) Robust Statistics Wiley
Marazzi A (1987) Weights for bounded influence regression in ROBETH Cah. Rech. Doc. IUMSP, No. 3 ROB 3 Institut Universitaire de Médecine Sociale et Préventive, Lausanne

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | n≤1,
or | m<1,
or | n<m,
ifail=2
On entry, | tol≤0.0,
or | maxit≤0,
or | diagonal element of a=0.0,
or | bl≤0.0,
or | bd≤0.0.
ifail=3
A column of x has a constant value.
ifail=4
Value of u or w returned by ucv<0.
ifail=5
The method has failed to converge in maxit iterations.
ifail=6
Either the sum D 1 or the sum D 2 is zero. This may be caused by the functions u or w being too strict for the current estimate of A (or C). You should either try a larger initial estimate of A or make the u and w functions less strict.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

On successful exit the accuracy of the results is related to the value of tol; see [Parameters]. At an iteration let
(i) | d 1= the maximum value of s jl
(ii) | d 2= the maximum absolute change in wt i
(iii) | d 3= the maximum absolute relative change in θj
and let δ=max d 1,d 2,d 3. Then the iterative procedure is assumed to have converged when δ<tol.

Parallelism and Performance

None.

Further Comments

The existence of A will depend upon the function u (see Marazzi (1987)); also if X is not of full rank a value of A will not be found. If the columns of X are almost linearly related, then convergence will be slow.
If derivatives of the u and w functions are available then the method used in g02hl will usually give much faster convergence.

Example

A sample of 10 observations on three variables is read in along with initial values for A and θ and parameter values for the u and w functions, cu and cw. The covariance matrix computed by g02hm is printed along with the robust estimate of θ.
ucv computes the Huber's weight functions:
u t=1,if  t≤cu 2u t=cu t 2,if  t>cu 2
and
w t=1,if  t≤cww t=cw t,if  t>cw.

Example program (C#): g02hme.cs

Example program data: g02hme.d

Example program results: g02hme.r

See Also

G02 Class
G02 Members


g02ja Method

[image]

NAG Library for .NET Release 2
G02..::g02ja Method
G02 Class See Also Send Feedback
g02ja fits a linear mixed effects regression model using restricted maximum likelihood (REML).

Syntax

C#
public static void g02ja(
    int n,
    int ncol,
    double[,] dat,
    int[] levels,
    int yvid,
    int cwid,
    int nfv,
    int[] fvid,
    int fint,
    int nrv,
    int[] rvid,
    int nvpr,
    int[] vpr,
    int rint,
    int svid,
    double[] gamma,
    out int nff,
    out int nrf,
    out int df,
    out double reml,
    double[] b,
    double[] se,
    int maxit,
    double tol,
    out int warn,
    out int ifail
)
Visual Basic
Public Shared Sub g02ja ( _
    n As Integer, _
    ncol As Integer, _
    dat As Double(,), _
    levels As Integer(), _
    yvid As Integer, _
    cwid As Integer, _
    nfv As Integer, _
    fvid As Integer(), _
    fint As Integer, _
    nrv As Integer, _
    rvid As Integer(), _
    nvpr As Integer, _
    vpr As Integer(), _
    rint As Integer, _
    svid As Integer, _
    gamma As Double(), _
    <OutAttribute> ByRef nff As Integer, _
    <OutAttribute> ByRef nrf As Integer, _
    <OutAttribute> ByRef df As Integer, _
    <OutAttribute> ByRef reml As Double, _
    b As Double(), _
    se As Double(), _
    maxit As Integer, _
    tol As Double, _
    <OutAttribute> ByRef warn As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02ja(
    int n,
    int ncol,
    array<double,2>^ dat,
    array<int>^ levels,
    int yvid,
    int cwid,
    int nfv,
    array<int>^ fvid,
    int fint,
    int nrv,
    array<int>^ rvid,
    int nvpr,
    array<int>^ vpr,
    int rint,
    int svid,
    array<double>^ gamma,
    [OutAttribute] int% nff,
    [OutAttribute] int% nrf,
    [OutAttribute] int% df,
    [OutAttribute] double% reml,
    array<double>^ b,
    array<double>^ se,
    int maxit,
    double tol,
    [OutAttribute] int% warn,
    [OutAttribute] int% ifail
)
F#
static member g02ja :
        n : int *
        ncol : int *
        dat : float[,] *
        levels : int[] *
        yvid : int *
        cwid : int *
        nfv : int *
        fvid : int[] *
        fint : int *
        nrv : int *
        rvid : int[] *
        nvpr : int *
        vpr : int[] *
        rint : int *
        svid : int *
        gamma : float[] *
        nff : int byref *
        nrf : int byref *
        df : int byref *
        reml : float byref *
        b : float[] *
        se : float[] *
        maxit : int *
        tol : float *
        warn : int byref *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n≥1.
ncol
Type: System..::..Int32
On entry: the number of columns in the data matrix, dat.
Constraint: ncol≥1.
dat
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥n
Note: the second dimension of the array dat must be at least ncol if _sorder=1, and at least n otherwise.
On entry: array containing all of the data. For the ith observation:
  • dat[i-1,yvid-1] holds the dependent variable, y;
  • if cwid≠0, dat[i-1,cwid-1] holds the case weights;
  • if svid≠0, dat[i-1,svid-1] holds the subject variable.
The remaining columns hold the values of the independent variables.
Constraints:
  • if cwid≠0, dat[i-1,cwid-1]≥0.0;
  • if levels[j-1]≠1, 1≤dat[i-1,j-1]≤levels[j-1].
levels
Type: array< System..::..Int32 >[]()[][]
An array of size [ncol]
On entry: levels[i-1] contains the number of levels associated with the ith variable of the data matrix dat. If this variable is continuous or binary (i.e., only takes the values zero or one) then levels[i-1] should be 1; if the variable is discrete then levels[i-1] is the number of levels associated with it and dat[j-1,i-1] is assumed to take the values 1 to levels[i-1], for j=1,2,…,n.
Constraint: levels[i-1]≥1, for i=1,2,…,ncol.
yvid
Type: System..::..Int32
On entry: the column of dat holding the dependent, y, variable.
Constraint: 1≤yvid≤ncol.
cwid
Type: System..::..Int32
On entry: the column of dat holding the case weights.
If cwid=0, no weights are used.
Constraint: 0≤cwid≤ncol.
nfv
Type: System..::..Int32
On entry: the number of independent variables in the model which are to be treated as being fixed.
Constraint: 0≤nfv<ncol.
fvid
Type: array< System..::..Int32 >[]()[][]
An array of size [nfv]
On entry: the columns of the data matrix dat holding the fixed independent variables with fvid[i-1] holding the column number corresponding to the ith fixed variable.
Constraint: 1≤fvid[i-1]≤ncol, for i=1,2,…,nfv.
fint
Type: System..::..Int32
On entry: flag indicating whether a fixed intercept is included (fint=1).
Constraint: fint=0 or 1.
nrv
Type: System..::..Int32
On entry: the number of independent variables in the model which are to be treated as being random.
Constraints:
  • 0≤nrv<ncol;
  • nrv+rint>0.
rvid
Type: array< System..::..Int32 >[]()[][]
An array of size [nrv]
On entry: the columns of the data matrix dat holding the random independent variables with rvid[i-1] holding the column number corresponding to the ith random variable.
Constraint: 1≤rvid[i-1]≤ncol, for i=1,2,…,nrv.
nvpr
Type: System..::..Int32
On entry: if rint=1 and svid≠0, nvpr is the number of variance components being estimated-2, (g-1), else nvpr=g.
If nrv=0, nvpr is not referenced.
Constraint: if nrv≠0, 1≤nvpr≤nrv.
vpr
Type: array< System..::..Int32 >[]()[][]
An array of size [nrv]
On entry: vpr[i-1] holds a flag indicating the variance of the ith random variable. The variance of the ith random variable is σj 2, where j=vpr[i-1]+1 if rint=1 and svid≠0 and j=vpr[i-1] otherwise. Random variables with the same value of j are assumed to be taken from the same distribution.
Constraint: 1≤vpr[i-1]≤nvpr, for i=1,2,…,nrv.
rint
Type: System..::..Int32
On entry: flag indicating whether a random intercept is included (rint=1).
If svid=0, rint is not referenced.
Constraint: rint=0 or 1.
svid
Type: System..::..Int32
On entry: the column of dat holding the subject variable.
If svid=0, no subject variable is used.
Specifying a subject variable is equivalent to specifying the interaction between that variable and all of the random-effects. Letting the notation Z 1×ZS denote the interaction between variables Z 1 and ZS, fitting a model with rint=0, random-effects Z 1+Z 2 and subject variable ZS is equivalent to fitting a model with random-effects Z 1×ZS+Z 2×ZS and no subject variable. If rint=1 the model is equivalent to fitting ZS+Z 1×ZS+Z 2×ZS and no subject variable.
Constraint: 0≤svid≤ncol.
gamma
Type: array< System..::..Double >[]()[][]
An array of size [nvpr+2]
On entry: holds the initial values of the variance components, γ 0, with gamma[i-1] the initial value for σi 2/σR 2, for i=1,2,…,g. If rint=1 and svid≠0, g=nvpr+1, else g=nvpr.
If gamma[0]=-1.0, the remaining elements of gamma are ignored and the initial values for the variance components are estimated from the data using MIVQUE0.
On exit: gamma[i-1], for i=1,2,…,g, holds the final estimate of σi 2 and gamma[g] holds the final estimate for σR 2.
Constraint: gamma[0]=-1.0​ or ​gamma[i-1]≥0.0, for i=1,2,…,g.
nff
Type: System..::..Int32 %
On exit: the number of fixed effects estimated (i.e., the number of columns, p, in the design matrix X).
nrf
Type: System..::..Int32 %
On exit: the number of random effects estimated (i.e., the number of columns, q, in the design matrix Z).
df
Type: System..::..Int32 %
On exit: the degrees of freedom.
reml
Type: System..::..Double %
On exit: -2 lR γ^ where lR is the log of the restricted maximum likelihood calculated at γ^, the estimated variance components returned in gamma.
b
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: dim1 must satisfy the constraint: _lb≥fint+∑i=1 nfv max levels[fvid[i-1]-1]-1,1+LS×rint+∑i=1 nrv levels[rvid[i-1]-1] where LS=levels[svid-1] if svid≠0 and 1 otherwise
On exit: the parameter estimates, β,ν, with the first nff elements of b containing the fixed effect parameter estimates, β and the next nrf elements of b containing the random effect parameter estimates, ν.
Fixed effects
If fint=1, b[0] contains the estimate of the fixed intercept. Let Li denote the number of levels associated with the ith fixed variable, that is Li=levels[fvid[i-1]-1]. Define
  • if fint=1, F 1=2 else if fint=0, F 1=1;
  • F i+1=Fi+max Li-1,1, i≥1.
Then for i=1,2,…,nfv:
  • if Li>1, b[Fi+j-3] contains the parameter estimate for the jth level of the ith fixed variable, for j=2,3,…,Li;
  • if Li≤1, b[Fi-1] contains the parameter estimate for the ith fixed variable.
Random effects
Redefining Li to denote the number of levels associated with the ith random variable, that is Li=levels[rvid[i-1]-1]. Define
  • if rint=1, R 1=2 else if rint=0, R 1=1;
    R i+1=Ri+Li, i≥1.
Then for i=1,2,…,nrv:
  • if svid=0,
    • if Li>1, b[nff+Ri+j-2] contains the parameter estimate for the jth level of the ith random variable, for j=1,2,…,Li;
    • if Li≤1, b[nff+Ri-1] contains the parameter estimate for the ith random variable;
  • if svid≠0,
    • let LS denote the number of levels associated with the subject variable, that is LS=levels[svid-1];
    • if Li>1, b[nff+s-1 LS+Ri+j-2] contains the parameter estimate for the interaction between the sth level of the subject variable and the jth level of the ith random variable, for s=1,2,…,LS and j=1,2,…,Li;
    • if Li≤1, b[nff+s-1 LS+Ri-1] contains the parameter estimate for the interaction between the sth level of the subject variable and the ith random variable, for s=1,2,…,LS;
    • if rint=1, b[nff] contains the estimate of the random intercept.
se
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: dim1 must satisfy the constraint: _lb≥fint+∑i=1 nfv max levels[fvid[i-1]-1]-1,1+LS×rint+∑i=1 nrv levels[rvid[i-1]-1] where LS=levels[svid-1] if svid≠0 and 1 otherwise
On exit: the standard errors of the parameter estimates given in b.
maxit
Type: System..::..Int32
On entry: the maximum number of iterations.
If maxit<0, the default value of 100 is used.
If maxit=0, the parameter estimates β,ν and corresponding standard errors are calculated based on the value of γ 0 supplied in gamma.
tol
Type: System..::..Double
On entry: the tolerance used to assess convergence.
If tol≤0.0, the default value of ε 0.7 is used, where ε is the machine precision.
warn
Type: System..::..Int32 %
On exit: is set to 1 if a variance component was estimated to be a negative value during the fitting process. Otherwise warn is set to 0.
If warn=1, the negative estimate is set to zero and the estimation process allowed to continue.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g02ja fits a model of the form:
y=Xβ+Zν+ε
where
  • y is a vector of n observations on the dependent variable,
  • X is a known n by p design matrix for the fixed independent variables,
  • β is a vector of length p of unknown fixed effects,
  • Z is a known n by q design matrix for the random independent variables,
  • ν is a vector of length q of unknown random effects,
and
  • ε is a vector of length n of unknown random errors.
Both ν and ε are assumed to have a Gaussian distribution with expectation zero and
Var νε=G00R
where R=σR 2 I, I is the n×n identity matrix and G is a diagonal matrix. It is assumed that the random variables, Z, can be subdivided into g≤q groups with each group being identically distributed with expectations zero and variance σi 2. The diagonal elements of matrix G therefore take one of the values σi 2:i=1,2,…,g, depending on which group the associated random variable belongs to.
The model therefore contains three sets of unknowns, the fixed effects, β, the random effects ν and a vector of g+1 variance components, γ, where γ=σ1 2,σ2 2,…,σ g-1 2,σg2,σR2. Rather than working directly with γ, g02ja uses an iterative process to estimate γ*=σ1 2/σR2,σ2 2/σR2,…,σ g-1 2/σR2,σg2/σR2,1. Due to the iterative nature of the estimation a set of initial values, γ 0, for γ* is required. g02ja allows these initial values either to be supplied by you or calculated from the data using the minimum variance quadratic unbiased estimators (MIVQUE0) suggested by Rao (1972).
g02ja fits the model using a quasi-Newton algorithm to maximize the restricted log-likelihood function:
-2 lR=log V+n-p log r′V-1 r+log X′V-1 X+n-p1+log 2 π/n-p
where
V=ZG Z′+R,  r=y-Xb  and  b=X′V-1 X-1X′V-1 y.
Once the final estimates for γ* have been obtained, the value of σR 2 is given by:
σR 2=r′V-1 r/n-p.
Case weights, Wc, can be incorporated into the model by replacing X′X and Z′Z with X′Wc X and Z′Wc Z respectively, for a diagonal weight matrix Wc.
The log-likelihood, lR, is calculated using the sweep algorithm detailed in Wolfinger et al. (1994).

References

Goodnight J H (1979) A tutorial on the SWEEP operator The American Statistician 33(3) 149–158
Harville D A (1977) Maximum likelihood approaches to variance component estimation and to related problems JASA 72 320–340
Rao C R (1972) Estimation of variance and covariance components in a linear model J. Am. Stat. Assoc. 67 112–115
Stroup W W (1989) Predictable functions and prediction space in the mixed model procedure Applications of Mixed Models in Agriculture and Related Disciplines Southern Cooperative Series Bulletin No. 343 39–48
Wolfinger R, Tobias R and Sall J (1994) Computing Gaussian likelihoods and their derivatives for general linear mixed models SIAM Sci. Statist. Comput. 15 1294–1310

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDDAT, LB) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | n<2,
or | ncol<1,
or | yvid<1 or yvid>ncol,
or | cwid<0 or cwid>ncol,
or | nfv<0 or nfv≥ncol,
or | fint≠0 and fint≠1,
or | nrv<0 or nrv>ncol or nrv+rint≤0,
or | nvpr≤0 or nvpr>nrv,
or | rint≠0 and rint≠1,
or | svid<0 or svid>ncol,
ifail=2
On entry, | levels[i-1]<1, for at least one i,
or | fvid[i-1]<1, or fvid[i-1]>ncol, for at least one i,
or | rvid[i-1]<1, or rvid[i-1]>ncol, for at least one i,
or | vpr[i-1]<1 or vpr[i-1]>nvpr, for at least one i,
or | at least one discrete variable in array dat has a value less than 1.0 or greater than that specified in levels,
or | gamma[i-1]<0.0, for at least one i, and gamma[0]≠-1.0.
ifail=3
Degrees of freedom <1. The number of parameters exceed the effective number of observations.
ifail=4
The method failed to converge to the specified tolerance in maxit iterations. See [Further Comments] for advice.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The accuracy of the results can be adjusted through the use of the tol parameter.

Parallelism and Performance

None.

Further Comments

Wherever possible any block structure present in the design matrix Z should be modelled through a subject variable, specified via svid, rather than being explicitly entered into dat.
g02ja uses an iterative process to fit the specified model and for some problems this process may fail to converge (see ifail=4). If the method fails to converge then the maximum number of iterations (see maxit) or tolerance (see tol) may require increasing; try a different starting estimate in gamma. Alternatively, the model can be fit using maximum likelihood (see g02jb) or using the noniterative MIVQUE0.
To fit the model just using MIVQUE0, the first element of gamma should be set to -1.0 and maxit should be set to zero.
Although the quasi-Newton algorithm used in g02ja tends to require more iterations before converging compared to the Newton–Raphson algorithm recommended by Wolfinger et al. (1994), it does not require the second derivatives of the likelihood function to be calculated and consequentially takes significantly less time per iteration.

Example

The following dataset is taken from Stroup (1989) and arises from a balanced split-plot design with the whole plots arranged in a randomized complete block-design.
In this example the full design matrix for the random independent variable, Z, is given by:
Z=110000000000000010100000000000001001000000000000000011000000000000001010000000000000100100000000000000001100000000000000101000000000000010010000000000000000110000000000000010100000000000001001110000000000000010100000000000001001000000000000000011000000000000001010000000000000100100000000000000001100000000000000101000000000000010010000000000000000110000000000000010100000000000001001
=A0000A0000A0000AA0000A0000A0000A, (1)
where
A=110010101001.
The block structure evident in (1) is modelled by specifying a four-level subject variable, taking the values 1,1,1,2,2,2,3,3,3,4,4,4,1,1,1,2,2,2,3,3,3,4,4,4. The first column of 1 s is added to A by setting rint=1. The remaining columns of A are specified by a three level factor, taking the values, 1,2,3,1,2,3,1,….

Example program (C#): g02jae.cs

Example program data: g02jae.d

Example program results: g02jae.r

See Also

G02 Class
G02 Members


g02jb Method

[image]

NAG Library for .NET Release 2
G02..::g02jb Method
G02 Class See Also Send Feedback
g02jb fits a linear mixed effects regression model using maximum likelihood (ML).

Syntax

C#
public static void g02jb(
    int n,
    int ncol,
    double[,] dat,
    int[] levels,
    int yvid,
    int cwid,
    int nfv,
    int[] fvid,
    int fint,
    int nrv,
    int[] rvid,
    int nvpr,
    int[] vpr,
    int rint,
    int svid,
    double[] gamma,
    out int nff,
    out int nrf,
    out int df,
    out double ml,
    double[] b,
    double[] se,
    int maxit,
    double tol,
    out int warn,
    out int ifail
)
Visual Basic
Public Shared Sub g02jb ( _
    n As Integer, _
    ncol As Integer, _
    dat As Double(,), _
    levels As Integer(), _
    yvid As Integer, _
    cwid As Integer, _
    nfv As Integer, _
    fvid As Integer(), _
    fint As Integer, _
    nrv As Integer, _
    rvid As Integer(), _
    nvpr As Integer, _
    vpr As Integer(), _
    rint As Integer, _
    svid As Integer, _
    gamma As Double(), _
    <OutAttribute> ByRef nff As Integer, _
    <OutAttribute> ByRef nrf As Integer, _
    <OutAttribute> ByRef df As Integer, _
    <OutAttribute> ByRef ml As Double, _
    b As Double(), _
    se As Double(), _
    maxit As Integer, _
    tol As Double, _
    <OutAttribute> ByRef warn As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02jb(
    int n,
    int ncol,
    array<double,2>^ dat,
    array<int>^ levels,
    int yvid,
    int cwid,
    int nfv,
    array<int>^ fvid,
    int fint,
    int nrv,
    array<int>^ rvid,
    int nvpr,
    array<int>^ vpr,
    int rint,
    int svid,
    array<double>^ gamma,
    [OutAttribute] int% nff,
    [OutAttribute] int% nrf,
    [OutAttribute] int% df,
    [OutAttribute] double% ml,
    array<double>^ b,
    array<double>^ se,
    int maxit,
    double tol,
    [OutAttribute] int% warn,
    [OutAttribute] int% ifail
)
F#
static member g02jb :
        n : int *
        ncol : int *
        dat : float[,] *
        levels : int[] *
        yvid : int *
        cwid : int *
        nfv : int *
        fvid : int[] *
        fint : int *
        nrv : int *
        rvid : int[] *
        nvpr : int *
        vpr : int[] *
        rint : int *
        svid : int *
        gamma : float[] *
        nff : int byref *
        nrf : int byref *
        df : int byref *
        ml : float byref *
        b : float[] *
        se : float[] *
        maxit : int *
        tol : float *
        warn : int byref *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n≥1.
ncol
Type: System..::..Int32
On entry: the number of columns in the data matrix, dat.
Constraint: ncol≥1.
dat
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥n
Note: the second dimension of the array dat must be at least ncol if _sorder=1, and at least n otherwise.
On entry: array containing all of the data. For the ith observation:
  • dat[i-1,yvid-1] holds the dependent variable, y;
  • if cwid≠0, dat[i-1,cwid-1] holds the case weights;
  • if svid≠0, dat[i-1,svid-1] holds the subject variable.
The remaining columns hold the values of the independent variables.
Constraints:
  • if cwid≠0, dat[i-1,cwid-1]≥0.0;
  • if levels[j-1]≠1, 1≤dat[i-1,j-1]≤levels[j-1].
levels
Type: array< System..::..Int32 >[]()[][]
An array of size [ncol]
On entry: levels[i-1] contains the number of levels associated with the ith variable of the data matrix dat. If this variable is continuous or binary (i.e., only takes the values zero or one) then levels[i-1] should be 1; if the variable is discrete then levels[i-1] is the number of levels associated with it and dat[j-1,i-1] is assumed to take the values 1 to levels[i-1], for j=1,2,…,n.
Constraint: levels[i-1]≥1, for i=1,2,…,ncol.
yvid
Type: System..::..Int32
On entry: the column of dat holding the dependent, y, variable.
Constraint: 1≤yvid≤ncol.
cwid
Type: System..::..Int32
On entry: the column of dat holding the case weights.
If cwid=0, no weights are used.
Constraint: 0≤cwid≤ncol.
nfv
Type: System..::..Int32
On entry: the number of independent variables in the model which are to be treated as being fixed.
Constraint: 0≤nfv<ncol.
fvid
Type: array< System..::..Int32 >[]()[][]
An array of size [nfv]
On entry: the columns of the data matrix dat holding the fixed independent variables with fvid[i-1] holding the column number corresponding to the ith fixed variable.
Constraint: 1≤fvid[i-1]≤ncol, for i=1,2,…,nfv.
fint
Type: System..::..Int32
On entry: flag indicating whether a fixed intercept is included (fint=1).
Constraint: fint=0 or 1.
nrv
Type: System..::..Int32
On entry: the number of independent variables in the model which are to be treated as being random.
Constraints:
  • 0≤nrv<ncol;
  • nrv+rint>0.
rvid
Type: array< System..::..Int32 >[]()[][]
An array of size [nrv]
On entry: the columns of the data matrix dat holding the random independent variables with rvid[i-1] holding the column number corresponding to the ith random variable.
Constraint: 1≤rvid[i-1]≤ncol, for i=1,2,…,nrv.
nvpr
Type: System..::..Int32
On entry: if rint=1 and svid≠0, nvpr is the number of variance components being estimated-2, (g-1), else nvpr=g.
If nrv=0, nvpr is not referenced.
Constraint: if nrv≠0, 1≤nvpr≤nrv.
vpr
Type: array< System..::..Int32 >[]()[][]
An array of size [nrv]
On entry: vpr[i-1] holds a flag indicating the variance of the ith random variable. The variance of the ith random variable is σj 2, where j=vpr[i-1]+1 if rint=1 and svid≠0 and j=vpr[i-1] otherwise. Random variables with the same value of j are assumed to be taken from the same distribution.
Constraint: 1≤vpr[i-1]≤nvpr, for i=1,2,…,nrv.
rint
Type: System..::..Int32
On entry: flag indicating whether a random intercept is included (rint=1).
If svid=0, rint is not referenced.
Constraint: rint=0 or 1.
svid
Type: System..::..Int32
On entry: the column of dat holding the subject variable.
If svid=0, no subject variable is used.
Specifying a subject variable is equivalent to specifying the interaction between that variable and all of the random-effects. Letting the notation Z 1×ZS denote the interaction between variables Z 1 and ZS, fitting a model with rint=0, random-effects Z 1+Z 2 and subject variable ZS is equivalent to fitting a model with random-effects Z 1×ZS+Z 2×ZS and no subject variable. If rint=1 the model is equivalent to fitting ZS+Z 1×ZS+Z 2×ZS and no subject variable.
Constraint: 0≤svid≤ncol.
gamma
Type: array< System..::..Double >[]()[][]
An array of size [nvpr+2]
On entry: holds the initial values of the variance components, γ 0, with gamma[i-1] the initial value for σi 2/σR 2, for i=1,2,…,g. If rint=1 and svid≠0, g=nvpr+1, else g=nvpr.
If gamma[0]=-1.0, the remaining elements of gamma are ignored and the initial values for the variance components are estimated from the data using MIVQUE0.
On exit: gamma[i-1], for i=1,2,…,g, holds the final estimate of σi 2 and gamma[g] holds the final estimate for σR 2.
Constraint: gamma[0]=-1.0​ or ​gamma[i-1]≥0.0, for i=1,2,…,g.
nff
Type: System..::..Int32 %
On exit: the number of fixed effects estimated (i.e., the number of columns, p, in the design matrix X).
nrf
Type: System..::..Int32 %
On exit: the number of random effects estimated (i.e., the number of columns, q, in the design matrix Z).
df
Type: System..::..Int32 %
On exit: the degrees of freedom.
ml
Type: System..::..Double %
On exit: -2 lR γ^ where lR is the log of the maximum likelihood calculated at γ^, the estimated variance components returned in gamma.
b
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: dim1 must satisfy the constraint: _lb≥fint+∑i=1 nfv max levels[fvid[i-1]-1]-1,1+LS×rint+∑i=1 nrv levels[rvid[i-1]-1] where LS=levels[svid-1] if svid≠0 and 1 otherwise
On exit: the parameter estimates, β,ν, with the first nff elements of b containing the fixed effect parameter estimates, β and the next nrf elements of b containing the random effect parameter estimates, ν.
Fixed effects
If fint=1, b[0] contains the estimate of the fixed intercept. Let Li denote the number of levels associated with the ith fixed variable, that is Li=levels[fvid[i-1]-1]. Define
  • if fint=1, F 1=2 else if fint=0, F 1=1;
  • F i+1=Fi+max Li-1,1, i≥1.
Then for i=1,2,…,nfv:
  • if Li>1, b[Fi+j-3] contains the parameter estimate for the jth level of the ith fixed variable, for j=2,3,…,Li;
  • if Li≤1, b[Fi-1] contains the parameter estimate for the ith fixed variable.
Random effects
Redefining Li to denote the number of levels associated with the ith random variable, that is Li=levels[rvid[i-1]-1]. Define
  • if rint=1, R 1=2 else if rint=0, R 1=1;
    R i+1=Ri+Li, i≥1.
Then for i=1,2,…,nrv:
  • if svid=0,
    • if Li>1, b[nff+Ri+j-2] contains the parameter estimate for the jth level of the ith random variable, for j=1,2,…,Li;
    • if Li≤1, b[nff+Ri-1] contains the parameter estimate for the ith random variable;
  • if svid≠0,
    • let LS denote the number of levels associated with the subject variable, that is LS=levels[svid-1];
    • if Li>1, b[nff+s-1 LS+Ri+j-2] contains the parameter estimate for the interaction between the sth level of the subject variable and the jth level of the ith random variable, for s=1,2,…,LS and j=1,2,…,Li;
    • if Li≤1, b[nff+s-1 LS+Ri-1] contains the parameter estimate for the interaction between the sth level of the subject variable and the ith random variable, for s=1,2,…,LS;
    • if rint=1, b[nff] contains the estimate of the random intercept.
se
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: dim1 must satisfy the constraint: _lb≥fint+∑i=1 nfv max levels[fvid[i-1]-1]-1,1+LS×rint+∑i=1 nrv levels[rvid[i-1]-1] where LS=levels[svid-1] if svid≠0 and 1 otherwise
On exit: the standard errors of the parameter estimates given in b.
maxit
Type: System..::..Int32
On entry: the maximum number of iterations.
If maxit<0, the default value of 100 is used.
If maxit=0, the parameter estimates β,ν and corresponding standard errors are calculated based on the value of γ 0 supplied in gamma.
tol
Type: System..::..Double
On entry: the tolerance used to assess convergence.
If tol≤0.0, the default value of ε 0.7 is used, where ε is the machine precision.
warn
Type: System..::..Int32 %
On exit: is set to 1 if a variance component was estimated to be a negative value during the fitting process. Otherwise warn is set to 0.
If warn=1, the negative estimate is set to zero and the estimation process allowed to continue.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g02jb fits a model of the form:
y=Xβ+Zν+ε
where
  • y is a vector of n observations on the dependent variable,
  • X is a known n by p design matrix for the fixed independent variables,
  • β is a vector of length p of unknown fixed effects,
  • Z is a known n by q design matrix for the random independent variables,
  • ν is a vector of length q of unknown random effects;
and
  • ε is a vector of length n of unknown random errors.
Both ν and ε are assumed to have a Gaussian distribution with expectation zero and
Var νε=G00R
where R=σR 2 I, I is the n×n identity matrix and G is a diagonal matrix. It is assumed that the random variables, Z, can be subdivided into g≤q groups with each group being identically distributed with expectations zero and variance σi 2. The diagonal elements of matrix G therefore take one of the values σi 2:i=1,2,…,g, depending on which group the associated random variable belongs to.
The model therefore contains three sets of unknowns, the fixed effects, β, the random effects ν and a vector of g+1 variance components, γ, where γ=σ1 2,σ2 2,…,σ g-1 2,σg2,σR2. Rather than working directly with γ, g02jb uses an iterative process to estimate γ*=σ1 2/σR2,σ2 2/σR2,…,σ g-1 2/σR2,σg2/σR2,1. Due to the iterative nature of the estimation a set of initial values, γ 0, for γ* is required. g02jb allows these initial values either to be supplied by you or calculated from the data using the minimum variance quadratic unbiased estimators (MIVQUE0) suggested by Rao (1972).
g02jb fits the model using a quasi-Newton algorithm to maximize the log-likelihood function:
-2 lR=log V+n log r′V-1 r+log 2 π/n
where
V=ZG Z′+R,  r=y-Xb  and  b=X′V-1 X-1X′V-1 y.
Once the final estimates for γ* have been obtained, the value of σR 2 is given by:
σR 2=r′V-1 r/n-p.
Case weights, Wc, can be incorporated into the model by replacing X′X and Z′Z with X′Wc X and Z′Wc Z respectively, for a diagonal weight matrix Wc.
The log-likelihood, lR, is calculated using the sweep algorithm detailed in Wolfinger et al. (1994).

References

Goodnight J H (1979) A tutorial on the SWEEP operator The American Statistician 33(3) 149–158
Harville D A (1977) Maximum likelihood approaches to variance component estimation and to related problems JASA 72 320–340
Rao C R (1972) Estimation of variance and covariance components in a linear model J. Am. Stat. Assoc. 67 112–115
Stroup W W (1989) Predictable functions and prediction space in the mixed model procedure Applications of Mixed Models in Agriculture and Related Disciplines Southern Cooperative Series Bulletin No. 343 39–48
Wolfinger R, Tobias R and Sall J (1994) Computing Gaussian likelihoods and their derivatives for general linear mixed models SIAM Sci. Statist. Comput. 15 1294–1310

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDDAT, LB) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | n<2,
or | ncol<1,
or | yvid<1 or yvid>ncol,
or | cwid<0 or cwid>ncol,
or | nfv<0 or nfv≥ncol,
or | fint≠0 and fint≠1,
or | nrv<0 or nrv>ncol or nrv+rint<1,
or | nvpr<0 or nvpr>nrv,
or | rint≠0 and rint≠1,
or | svid<0 or svid>ncol,
ifail=2
On entry, | levels[i-1]<1, for at least one i,
or | fvid[i-1]<1, or fvid[i-1]>ncol, for at least one i,
or | rvid[i-1]<1, or rvid[i-1]>ncol, for at least one i,
or | vpr[i-1]<1 or vpr[i-1]>nvpr, for at least one i,
or | at least one discrete variable in array dat has a value greater than that specified in levels,
or | gamma[i-1]<0, for at least one i, and gamma[0]≠-1.
ifail=3
Degrees of freedom <1. The number of parameters exceed the effective number of observations.
ifail=4
The method failed to converge to the specified tolerance in maxit iterations. See [Further Comments] for advice.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The accuracy of the results can be adjusted through the use of the tol parameter.

Parallelism and Performance

None.

Further Comments

Wherever possible any block structure present in the design matrix Z should be modelled through a subject variable, specified via svid, rather than being explicitly entered into dat.
g02jb uses an iterative process to fit the specified model and for some problems this process may fail to converge (see ifail=4). If the method fails to converge then the maximum number of iterations (see maxit) or tolerance (see tol) may require increasing; try a different starting estimate in gamma. Alternatively, the model can be fit using restricted maximum likelihood (see g02ja) or using the noniterative MIVQUE0.
To fit the model just using MIVQUE0, the first element of gamma should be set to -1 and maxit should be set to zero.
Although the quasi-Newton algorithm used in g02jb tends to require more iterations before converging compared to the Newton–Raphson algorithm recommended by Wolfinger et al. (1994), it does not require the second derivatives of the likelihood function to be calculated and consequentially takes significantly less time per iteration.

Example

The following dataset is taken from Stroup (1989) and arises from a balanced split-plot design with the whole plots arranged in a randomized complete block-design.
In this example the full design matrix for the random independent variable, Z, is given by:
Z=110000000000000010100000000000001001000000000000000011000000000000001010000000000000100100000000000000001100000000000000101000000000000010010000000000000000110000000000000010100000000000001001110000000000000010100000000000001001000000000000000011000000000000001010000000000000100100000000000000001100000000000000101000000000000010010000000000000000110000000000000010100000000000001001
=A0000A0000A0000AA0000A0000A0000A, (1)
where
A=110010101001.
The block structure evident in (1) is modelled by specifying a four-level subject variable, taking the values 1,1,1,2,2,2,3,3,3,4,4,4,1,1,1,2,2,2,3,3,3,4,4,4. The first column of 1 s is added to A by setting rint=1. The remaining columns of A are specified by a three level factor, taking the values, 1,2,3,1,2,3,1,….

Example program (C#): g02jbe.cs

Example program data: g02jbe.d

Example program results: g02jbe.r

See Also

G02 Class
G02 Members


g02ka Method

[image]

NAG Library for .NET Release 2
G02..::g02ka Method
G02 Class See Also Send Feedback
g02ka calculates a ridge regression, optimizing the ridge parameter according to one of four prediction error criteria.

Syntax

C#
public static void g02ka(
    int n,
    int m,
    double[,] x,
    int[] isx,
    int ip,
    double tau,
    double[] y,
    ref double h,
    int opt,
    ref int niter,
    double tol,
    out double nep,
    int orig,
    double[] b,
    double[] vif,
    double[] res,
    out double rss,
    out int df,
    int optloo,
    double[] perr,
    out int ifail
)
Visual Basic
Public Shared Sub g02ka ( _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    isx As Integer(), _
    ip As Integer, _
    tau As Double, _
    y As Double(), _
    ByRef h As Double, _
    opt As Integer, _
    ByRef niter As Integer, _
    tol As Double, _
    <OutAttribute> ByRef nep As Double, _
    orig As Integer, _
    b As Double(), _
    vif As Double(), _
    res As Double(), _
    <OutAttribute> ByRef rss As Double, _
    <OutAttribute> ByRef df As Integer, _
    optloo As Integer, _
    perr As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02ka(
    int n,
    int m,
    array<double,2>^ x,
    array<int>^ isx,
    int ip,
    double tau,
    array<double>^ y,
    double% h,
    int opt,
    int% niter,
    double tol,
    [OutAttribute] double% nep,
    int orig,
    array<double>^ b,
    array<double>^ vif,
    array<double>^ res,
    [OutAttribute] double% rss,
    [OutAttribute] int% df,
    int optloo,
    array<double>^ perr,
    [OutAttribute] int% ifail
)
F#
static member g02ka :
        n : int *
        m : int *
        x : float[,] *
        isx : int[] *
        ip : int *
        tau : float *
        y : float[] *
        h : float byref *
        opt : int *
        niter : int byref *
        tol : float *
        nep : float byref *
        orig : int *
        b : float[] *
        vif : float[] *
        res : float[] *
        rss : float byref *
        df : int byref *
        optloo : int *
        perr : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n>1.
m
Type: System..::..Int32
On entry: the number of independent variables available in the data matrix X.
Constraint: m≤n.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: the values of independent variables in the data matrix X.
isx
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: indicates which m independent variables are included in the model.
isx[j-1]=1
The jth variable in x will be included in the model.
isx[j-1]=0
Variable j is excluded.
Constraint: isx[j-1]=0​ or ​1, for j=1,2,…,m.
ip
Type: System..::..Int32
On entry: m, the number of independent variables in the model.
Constraints:
  • 1≤ip≤m;
  • Exactly ip elements of isx must be equal to 1.
tau
Type: System..::..Double
On entry: singular values less than tau of the SVD of the data matrix X will be set equal to zero.
Suggested value: tau=0.0
Constraint: tau≥0.0.
y
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the n values of the dependent variable y.
h
Type: System..::..Double %
On entry: an initial value for the ridge regression parameter h; used as a starting point for the optimization.
Constraint: h>0.0.
On exit: h is the optimized value of the ridge regression parameter h.
opt
Type: System..::..Int32
On entry: the measure of prediction error used to optimize the ridge regression parameter h. The value of opt must be set equal to one of:
opt=1
Generalized cross-validation (GCV);
opt=2
Unbiased estimate of variance (UEV)
opt=3
Future prediction error (FPE)
opt=4
Bayesian information criteron (BIC).
Constraint: opt=1, 2, 3 or 4.
niter
Type: System..::..Int32 %
On entry: the maximum number of iterations allowed to optimize the ridge regression parameter h.
Constraint: niter≥1.
On exit: the number of iterations used to optimize the ridge regression parameter h within tol.
tol
Type: System..::..Double
On entry: iterations of the ridge regression parameter h will halt when consecutive values of h lie within tol.
Constraint: tol>0.0.
nep
Type: System..::..Double %
On exit: the number of effective parameters, γ, in the model.
orig
Type: System..::..Int32
On entry: if orig=1, the parameter estimates b are calculated for the original data; otherwise orig=2 and the parameter estimates b~ are calculated for the standardized data.
Constraint: orig=1 or 2.
b
Type: array< System..::..Double >[]()[][]
An array of size [ip+1]
On exit: contains the intercept and parameter estimates for the fitted ridge regression model in the order indicated by isx. The first element of b contains the estimate for the intercept; b[j] contains the parameter estimate for the jth independent variable in the model, for j=1,2,…,ip.
vif
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On exit: the variance inflation factors in the order indicated by isx. For the jth independent variable in the model, vif[j-1] is the value of vj, for j=1,2,…,ip.
res
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: res[i-1] is the value of the ith residual for the fitted ridge regression model, for i=1,2,…,n.
rss
Type: System..::..Double %
On exit: the sum of squares of residual values.
df
Type: System..::..Int32 %
On exit: the degrees of freedom for the residual sum of squares rss.
optloo
Type: System..::..Int32
On entry: if optloo=2, the leave-one-out cross-validation estimate of prediction error is calculated; otherwise no such estimate is calculated and optloo=1.
Constraint: optloo=1 or 2.
perr
Type: array< System..::..Double >[]()[][]
An array of size [5]
On exit: the first four elements contain, in this order, the measures of prediction error: GCV, UEV, FPE and BIC.
If optloo=2, perr[4] is the LOOCV estimate of prediction error; otherwise perr[4] is not referenced.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

A linear model has the form:
y=c+Xβ+ε,
where
  • y is an n by 1 matrix of values of a dependent variable;
  • c is a scalar intercept term;
  • X is an n by m matrix of values of independent variables;
  • β is an m by 1 matrix of unknown values of parameters;
  • ε is an n by 1 matrix of unknown random errors such that variance of ε=σ 2 I.
Let X~ be the mean-centred X and y~ the mean-centred y. Furthermore, X~ is scaled such that the diagonal elements of the cross product matrix X~T X~ are one. The linear model now takes the form:
y~=X~β~+ε.
Ridge regression estimates the parameters β~ in a penalised least squares sense by finding the b~ that minimizes
X~b~-y~2+h b~2, h>0,
where · denotes the ℓ 2-norm and h is a scalar regularization or ridge parameter. For a given value of h, the parameter estimates b~ are found by evaluating
b~=X~T X~+hI-1X~T y~.
Note that if h=0 the ridge regression solution is equivalent to the ordinary least squares solution.
Rather than calculate the inverse of (X~T X~+hI) directly, g02ka uses the singular value decomposition (SVD) of X~. After decomposing X~ into UD VT where U and V are orthogonal matrices and D is a diagonal matrix, the parameter estimates become
b~=V DT D+hI-1 D UT y~.
A consequence of introducing the ridge parameter is that the effective number of parameters, γ, in the model is given by the sum of diagonal elements of
DT D DT D+hI-1,
see Moody (1992) for details.
Any multi-collinearity in the design matrix X may be highlighted by calculating the variance inflation factors for the fitted model. The jth variance inflation factor, vj, is a scaled version of the multiple correlation coefficient between independent variable j and the other independent variables, Rj, and is given by
vj=1 1-Rj, j=1,2,…,m.
The m variance inflation factors are calculated as the diagonal elements of the matrix:
X~T X~+hI-1X~T X~X~T X~+hI-1,
which, using the SVD of X~, is equivalent to the diagonal elements of the matrix:
V DT D+hI-1DT D DT D+hI-1VT.
Although parameter estimates b~ are calculated by using X~, it is usual to report the parameter estimates b associated with X. These are calculated from b~, and the means and scalings of X. Optionally, either b~ or b may be calculated.
The method can adopt one of four criteria to minimize while calculating a suitable value for h:
(a) Generalized cross-validation (GCV):
ns n-γ 2;
(b) Unbiased estimate of variance (UEV):
s n-γ;
(c) Future prediction error (FPE):
1 n s+2 γsn-γ;
(d) Bayesian information criterion (BIC):
1 n s+log n γsn-γ;
where s is the sum of squares of residuals. However, the function returns all four of the above prediction errors regardless of the one selected to minimize the ridge parameter, h. Furthermore, the function will optionally return the leave-one-out cross-validation (LOOCV) prediction error.

References

Hastie T, Tibshirani R and Friedman J (2003) The Elements of Statistical Learning: Data Mining, Inference and Prediction Springer Series in Statistics
Moody J.E. (1992) The effective number of parameters: An analysis of generalisation and regularisation in nonlinear learning systems In: Neural Information Processing Systems (eds J E Moody, S J Hanson, and R P Lippmann) 4 847–854 Morgan Kaufmann San Mateo CA

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=-1
Maximum number of iterations used.
ifail=1
On entry, | n≤1;
or | tau<0.0;
or | opt≠1, 2, 3 or 4;
or | h≤0.0;
or | optloo≠1 or 2;
or | tol≤0.0;
or | niter<1;
or | orig≠1 or 2
ifail=2
On entry, | m>n;
or | ip<1 or ip>m;
or | An element of isx≠0 or 1;
or | ip does not equal the sum of elements in isx.
ifail=3
SVD failed to converge.
ifail=4
Internal error. Check all array sizes and calls to g02ka. Please contact NAG.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

g02ka allocates internally max 5×n-1,2×ip×ip+n+3×ip+n elements of double precision storage.

Example

This example reads in data from an experiment to model body fat, and a ridge regression is calculated that optimizes GCV prediction error.

Example program (C#): g02kae.cs

Example program data: g02kae.d

Example program results: g02kae.r

See Also

G02 Class
G02 Members


g02kb Method

[image]

NAG Library for .NET Release 2
G02..::g02kb Method
G02 Class See Also Send Feedback
g02kb calculates a ridge regression, with ridge parameters supplied by you.

Syntax

C#
public static void g02kb(
    int n,
    int m,
    double[,] x,
    int[] isx,
    int ip,
    double[] y,
    int lh,
    double[] h,
    double[] nep,
    int wantb,
    double[,] b,
    int wantvf,
    double[,] vf,
    int lpec,
    string[] pec,
    double[,] pe,
    out int ifail
)
Visual Basic
Public Shared Sub g02kb ( _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    isx As Integer(), _
    ip As Integer, _
    y As Double(), _
    lh As Integer, _
    h As Double(), _
    nep As Double(), _
    wantb As Integer, _
    b As Double(,), _
    wantvf As Integer, _
    vf As Double(,), _
    lpec As Integer, _
    pec As String(), _
    pe As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02kb(
    int n,
    int m,
    array<double,2>^ x,
    array<int>^ isx,
    int ip,
    array<double>^ y,
    int lh,
    array<double>^ h,
    array<double>^ nep,
    int wantb,
    array<double,2>^ b,
    int wantvf,
    array<double,2>^ vf,
    int lpec,
    array<String^>^ pec,
    array<double,2>^ pe,
    [OutAttribute] int% ifail
)
F#
static member g02kb :
        n : int *
        m : int *
        x : float[,] *
        isx : int[] *
        ip : int *
        y : float[] *
        lh : int *
        h : float[] *
        nep : float[] *
        wantb : int *
        b : float[,] *
        wantvf : int *
        vf : float[,] *
        lpec : int *
        pec : string[] *
        pe : float[,] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n≥1.
m
Type: System..::..Int32
On entry: the number of independent variables available in the data matrix X.
Constraint: m≤n.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: the values of independent variables in the data matrix X.
isx
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: indicates which m independent variables are included in the model.
isx[j-1]=1
The jth variable in x will be included in the model.
isx[j-1]=0
Variable j is excluded.
Constraint: isx[j-1]=0​ or ​1, for j=1,2,…,m.
ip
Type: System..::..Int32
On entry: m, the number of independent variables in the model.
Constraints:
  • 1≤ip≤m;
  • Exactly ip elements of isx must be equal to 1.
y
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the n values of the dependent variable y.
lh
Type: System..::..Int32
On entry: the number of supplied ridge parameters.
Constraint: lh>0.
h
Type: array< System..::..Double >[]()[][]
An array of size [lh]
On entry: h[j-1] is the value of the jth ridge parameter h.
Constraint: h[j-1]≥0.0, for j=1,2,…,lh.
nep
Type: array< System..::..Double >[]()[][]
An array of size [lh]
On exit: nep[j-1] is the number of effective parameters, γ, in the jth model, for j=1,2,…,lh.
wantb
Type: System..::..Int32
On entry: defines the options for parameter estimates.
wantb=0
Parameter estimates are not calculated and b is not referenced.
wantb=1
Parameter estimates b are calculated for the original data.
wantb=2
Parameter estimates b~ are calculated for the standardized data.
Constraint: wantb=0, 1 or 2.
b
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, _tdb]
Note: dim1 must satisfy the constraint:
  • if wantb≠0, dim1≥ip+1;
  • otherwise dim1≥1.
Note: the second dimension of the array b must be at least lh if wantb≠0, and at least 1 otherwise.
On exit: if wantb≠0, b contains the intercept and parameter estimates for the fitted ridge regression model in the order indicated by isx. b[0,j-1], for j=1,2,…,lh, contains the estimate for the intercept; b[i,j-1] contains the parameter estimate for the ith independent variable in the model fitted with ridge parameter h[j-1], for i=1,2,…,ip.
wantvf
Type: System..::..Int32
On entry: defines the options for variance inflation factors.
wantvf=0
Variance inflation factors are not calculated and the array vf is not referenced.
wantvf=1
Variance inflation factors are calculated.
Constraints:
  • wantvf=0 or 1;
  • if wantb=0, wantvf=1.
vf
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, _tdv]
Note: dim1 must satisfy the constraint:
  • if wantvf≠0, dim1≥ip;
  • otherwise dim1≥1.
Note: the second dimension of the array vf must be at least lh if wantvf≠0, and at least 1 otherwise.
On exit: if wantvf=1, the variance inflation factors. For the ith independent variable in a model fitted with ridge parameter h[j-1], vf[i-1,j-1] is the value of vi, for i=1,2,…,ip.
lpec
Type: System..::..Int32
On entry: the number of prediction error statistics to return; set lpec≤0 for no prediction error estimates.
pec
Type: array< System..::..String >[]()[][]
An array of size [lpec]
On entry: if lpec>0, pec[j-1] defines the jth prediction error, for j=1,2,…,lpec; otherwise pec is not referenced.
pec[j-1]="B"
Bayesian information criterion (BIC).
pec[j-1]="F"
Future prediction error (FPE).
pec[j-1]="G"
Generalized cross-validation (GCV).
pec[j-1]="L"
Leave-one-out cross-validation (LOOCV).
pec[j-1]="U"
Unbiased estimate of variance (UEV).
Constraint: if lpec>0, pec[j-1]="B", "F", "G", "L" or "U", for j=1,2,…,lpec.
pe
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, _tdpe]
Note: dim1 must satisfy the constraint:
  • if lpec>0, dim1≥lpec;
  • otherwise dim1≥1.
Note: the second dimension of the array pe must be at least lh if lpec>0, and at least 1 otherwise.
On exit: if lpec≤0, pe is not referenced; otherwise pe[i-1,j-1] contains the prediction error of criterion pec[i-1] for the model fitted with ridge parameter h[j-1], for i=1,2,…,lpec and j=1,2,…,lh.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

A linear model has the form:
y=c+Xβ+ε,
where
  • y is an n by 1 matrix of values of a dependent variable;
  • c is a scalar intercept term;
  • X is an n by m matrix of values of independent variables;
  • β is a m by 1 matrix of unknown values of parameters;
  • ε is an n by 1 matrix of unknown random errors such that variance of ε=σ 2 I.
Let X~ be the mean-centred X and y~ the mean-centred y. Furthermore, X~ is scaled such that the diagonal elements of the cross product matrix X~T X~ are one. The linear model now takes the form:
y~=X~β~+ε.
Ridge regression estimates the parameters β~ in a penalised least squares sense by finding the b~ that minimizes
X~b~-y~2+h b~2, h>0,
where · denotes the ℓ 2-norm and h is a scalar regularization or ridge parameter. For a given value of h, the parameters estimates b~ are found by evaluating
b~=X~T X~+hI-1X~T y~.
Note that if h=0 the ridge regression solution is equivalent to the ordinary least squares solution.
Rather than calculate the inverse of (X~T X~+hI) directly, g02kb uses the singular value decomposition (SVD) of X~. After decomposing X~ into UD VT where U and V are orthogonal matrices and D is a diagonal matrix, the parameter estimates become
b~=V DT D+hI-1 D UT y~.
A consequence of introducing the ridge parameter is that the effective number of parameters, γ, in the model is given by the sum of diagonal elements of
DT D DT D+hI-1,
see Moody (1992) for details.
Any multi-collinearity in the design matrix X may be highlighted by calculating the variance inflation factors for the fitted model. The jth variance inflation factor, vj, is a scaled version of the multiple correlation coefficient between independent variable j and the other independent variables, Rj, and is given by
vj=1 1-Rj, j=1,2,…,m.
The m variance inflation factors are calculated as the diagonal elements of the matrix:
X~T X~+hI-1X~T X~X~T X~+hI-1,
which, using the SVD of X~, is equivalent to the diagonal elements of the matrix:
V DT D+hI-1DT D DT D+hI-1VT.
Given a value of h, any or all of the following prediction criteria are available:
(a) Generalized cross-validation (GCV):
ns n-γ 2;
(b) Unbiased estimate of variance (UEV):
s n-γ;
(c) Future prediction error (FPE):
1 n s+2 γsn-γ;
(d) Bayesian information criterion (BIC):
1 n s+log n γsn-γ;
(e) Leave-one-out cross-validation (LOOCV),
where s is the sum of squares of residuals.
Although parameter estimates b~ are calculated by using X~, it is usual to report the parameter estimates b associated with X. These are calculated from b~, and the means and scalings of X. Optionally, either b~ or b may be calculated.

References

Hastie T, Tibshirani R and Friedman J (2003) The Elements of Statistical Learning: Data Mining, Inference and Prediction Springer Series in Statistics
Moody J.E. (1992) The effective number of parameters: An analysis of generalisation and regularisation in nonlinear learning systems In: Neural Information Processing Systems (eds J E Moody, S J Hanson, and R P Lippmann) 4 847–854 Morgan Kaufmann San Mateo CA

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDB, LDVF, LDPE) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | n<1,
or | h[j-1]<0.0,
or | lh≤0,
or | wantb≠0, 1 or 2,
or | wantvf≠0 or 1,
or | an element of pec is not defined.
ifail=2
On entry, | m>n,
or | ip<1 or ip>m,
or | an element of isx≠0 or 1,
or | ip does not equal the sum of elements in isx,
ifail=3
Both wantb and wantvf are zero.
ifail=4
Internal error. Check all array sizes and calls to g02kb. Please contact NAG.
ifail=-999
Internal memory allocation failed.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The accuracy of g02kb is closely related to that of the singular value decomposition.

Parallelism and Performance

None.

Further Comments

g02kb allocates internally max 5×n-1,2×ip×ip+n+3×ip+n elements of double precision storage.

Example

This example reads in data from an experiment to model body fat, and a selection of ridge regression models are calculated.

Example program (C#): g02kbe.cs

Example program data: g02kbe.d

Example program results: g02kbe.r

See Also

G02 Class
G02 Members


g02la Method

[image]

NAG Library for .NET Release 2
G02..::g02la Method
G02 Class See Also Send Feedback
g02la fits an orthogonal scores partial least squares (PLS) regression by using singular value decomposition.

Syntax

C#
public static void g02la(
    int n,
    int mx,
    double[,] x,
    int[] isx,
    int ip,
    int my,
    double[,] y,
    double[] xbar,
    double[] ybar,
    int iscale,
    double[] xstd,
    double[] ystd,
    int maxfac,
    double[,] xres,
    double[,] yres,
    double[,] w,
    double[,] p,
    double[,] t,
    double[,] c,
    double[,] u,
    double[] xcv,
    double[,] ycv,
    out int ifail
)
Visual Basic
Public Shared Sub g02la ( _
    n As Integer, _
    mx As Integer, _
    x As Double(,), _
    isx As Integer(), _
    ip As Integer, _
    my As Integer, _
    y As Double(,), _
    xbar As Double(), _
    ybar As Double(), _
    iscale As Integer, _
    xstd As Double(), _
    ystd As Double(), _
    maxfac As Integer, _
    xres As Double(,), _
    yres As Double(,), _
    w As Double(,), _
    p As Double(,), _
    t As Double(,), _
    c As Double(,), _
    u As Double(,), _
    xcv As Double(), _
    ycv As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02la(
    int n,
    int mx,
    array<double,2>^ x,
    array<int>^ isx,
    int ip,
    int my,
    array<double,2>^ y,
    array<double>^ xbar,
    array<double>^ ybar,
    int iscale,
    array<double>^ xstd,
    array<double>^ ystd,
    int maxfac,
    array<double,2>^ xres,
    array<double,2>^ yres,
    array<double,2>^ w,
    array<double,2>^ p,
    array<double,2>^ t,
    array<double,2>^ c,
    array<double,2>^ u,
    array<double>^ xcv,
    array<double,2>^ ycv,
    [OutAttribute] int% ifail
)
F#
static member g02la :
        n : int *
        mx : int *
        x : float[,] *
        isx : int[] *
        ip : int *
        my : int *
        y : float[,] *
        xbar : float[] *
        ybar : float[] *
        iscale : int *
        xstd : float[] *
        ystd : float[] *
        maxfac : int *
        xres : float[,] *
        yres : float[,] *
        w : float[,] *
        p : float[,] *
        t : float[,] *
        c : float[,] *
        u : float[,] *
        xcv : float[] *
        ycv : float[,] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n>1.
mx
Type: System..::..Int32
On entry: the number of predictor variables.
Constraint: mx>1.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, mx]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must contain the ith observation on the jth predictor variable, for i=1,2,…,n and j=1,2,…,mx.
isx
Type: array< System..::..Int32 >[]()[][]
An array of size [mx]
On entry: indicates which predictor variables are to be included in the model.
isx[j-1]=1
The jth predictor variable (with variates in the jth column of X) is included in the model.
isx[j-1]=0
Otherwise.
Constraint: the sum of elements in isx must equal ip.
ip
Type: System..::..Int32
On entry: m, the number of predictor variables in the model.
Constraint: 1<ip≤mx.
my
Type: System..::..Int32
On entry: r, the number of response variables.
Constraint: my≥1.
y
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, my]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: y[i-1,j-1] must contain the ith observation for the jth response variable, for i=1,2,…,n and j=1,2,…,my.
xbar
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On exit: mean values of predictor variables in the model.
ybar
Type: array< System..::..Double >[]()[][]
An array of size [my]
On exit: the mean value of each response variable.
iscale
Type: System..::..Int32
On entry: indicates how predictor variables are scaled.
iscale=1
Data are scaled by the standard deviation of variables.
iscale=2
Data are scaled by user-supplied scalings.
iscale=-1
No scaling.
Constraint: iscale=-1, 1 or 2.
xstd
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On entry: if iscale=2, xstd[j-1] must contain the user-supplied scaling for the jth predictor variable in the model, for j=1,2,…,ip. Otherwise xstd need not be set.
On exit: if iscale=1, standard deviations of predictor variables in the model. Otherwise xstd is not changed.
ystd
Type: array< System..::..Double >[]()[][]
An array of size [my]
On entry: if iscale=2, ystd[j-1] must contain the user-supplied scaling for the jth response variable in the model, for j=1,2,…,my. Otherwise ystd need not be set.
On exit: if iscale=1, the standard deviation of each response variable. Otherwise ystd is not changed.
maxfac
Type: System..::..Int32
On entry: k, the number of latent variables to calculate.
Constraint: 1≤maxfac≤ip.
xres
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, ip]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: the predictor variables' residual matrix Xk.
yres
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, my]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: the residuals for each response variable, Yk.
w
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, maxfac]
Note: dim1 must satisfy the constraint: dim1≥ip
On exit: the jth column of W contains the x-weights wj, for j=1,2,…,maxfac.
p
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, maxfac]
Note: dim1 must satisfy the constraint: dim1≥ip
On exit: the jth column of P contains the x-loadings pj, for j=1,2,…,maxfac.
t
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, maxfac]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: the jth column of T contains the x-scores tj, for j=1,2,…,maxfac.
c
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, maxfac]
Note: dim1 must satisfy the constraint: dim1≥my
On exit: the jth column of C contains the y-loadings cj, for j=1,2,…,maxfac.
u
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, maxfac]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: the jth column of U contains the y-scores uj, for j=1,2,…,maxfac.
xcv
Type: array< System..::..Double >[]()[][]
An array of size [maxfac]
On exit: xcv[j-1] contains the cumulative percentage of variance in the predictor variables explained by the first j factors, for j=1,2,…,maxfac.
ycv
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, my]
Note: dim1 must satisfy the constraint: dim1≥maxfac
On exit: ycv[i-1,j-1] is the cumulative percentage of variance of the jth response variable explained by the first i factors, for i=1,2,…,maxfac and j=1,2,…,my.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Let X 1 be the mean-centred n by m data matrix X of n observations on m predictor variables. Let Y 1 be the mean-centred n by r data matrix Y of n observations on r response variables.
The first of the k factors PLS methods extract from the data predicts both X 1 and Y 1 by regressing on t 1 a column vector of n scores:
X^1=t 1 p 1 TY^1=t 1 c 1 T,with ​t 1 T t 1=1,
where the column vectors of m x-loadings p 1 and r y-loadings c 1 are calculated in the least squares sense:
p 1 T=t 1 T X 1c 1 T=t 1 T Y 1.
The x-score vector t 1=X 1w 1 is the linear combination of predictor data X 1 that has maximum covariance with the y-scores u 1=Y 1c 1, where the x-weights vector w 1 is the normalised first left singular vector of X 1 T Y 1.
The method extracts subsequent PLS factors by repeating the above process with the residual matrices:
Xi=X i-1-X^i-1Yi=Y i-1-Y^i-1, i=2,3,…,k,
and with orthogonal scores:
tiT tj=0, j=1,2,…,i-1.
Optionally, in addition to being mean-centred, the data matrices X 1 and Y 1 may be scaled by standard deviations of the variables. If data are supplied mean-centred, the calculations are not affected within numerical accuracy.

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDY, LDXRES, LDYRES, LDW, LDP, LDT, LDC, LDU, LDYCV) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | n<2,
or | mx<2,
or | an element of isx≠0 or 1,
or | my<1,
or | iscale≠-1, 1 or 2.
ifail=2
On entry, | ip<2 or ip>mx,
or | maxfac<1 or maxfac>ip,
ifail=3
ip does not equal the sum of elements in isx.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The computed singular value decomposition is nearly the exact singular value decomposition for a nearby matrix A+E, where
E 2=O ε A 2,
and ε is the machine precision.

Parallelism and Performance

None.

Further Comments

g02la allocates internally 2 mr+A+max 3 A+B,5 A+r elements of real storage, where A=min m,r and B=max m,r.

Example

This example reads in data from an experiment to measure the biological activity in a chemical compound, and a PLS model is estimated.

Example program (C#): g02lae.cs

Example program data: g02lae.d

Example program results: g02lae.r

See Also

G02 Class
G02 Members


g02lb Method

[image]

NAG Library for .NET Release 2
G02..::g02lb Method
G02 Class See Also Send Feedback
g02lb fits an orthogonal scores partial least squares (PLS) regression by using Wold's iterative method.

Syntax

C#
public static void g02lb(
    int n,
    int mx,
    double[,] x,
    int[] isx,
    int ip,
    int my,
    double[,] y,
    double[] xbar,
    double[] ybar,
    int iscale,
    double[] xstd,
    double[] ystd,
    int maxfac,
    int maxit,
    double tau,
    double[,] xres,
    double[,] yres,
    double[,] w,
    double[,] p,
    double[,] t,
    double[,] c,
    double[,] u,
    double[] xcv,
    double[,] ycv,
    out int ifail
)
Visual Basic
Public Shared Sub g02lb ( _
    n As Integer, _
    mx As Integer, _
    x As Double(,), _
    isx As Integer(), _
    ip As Integer, _
    my As Integer, _
    y As Double(,), _
    xbar As Double(), _
    ybar As Double(), _
    iscale As Integer, _
    xstd As Double(), _
    ystd As Double(), _
    maxfac As Integer, _
    maxit As Integer, _
    tau As Double, _
    xres As Double(,), _
    yres As Double(,), _
    w As Double(,), _
    p As Double(,), _
    t As Double(,), _
    c As Double(,), _
    u As Double(,), _
    xcv As Double(), _
    ycv As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02lb(
    int n,
    int mx,
    array<double,2>^ x,
    array<int>^ isx,
    int ip,
    int my,
    array<double,2>^ y,
    array<double>^ xbar,
    array<double>^ ybar,
    int iscale,
    array<double>^ xstd,
    array<double>^ ystd,
    int maxfac,
    int maxit,
    double tau,
    array<double,2>^ xres,
    array<double,2>^ yres,
    array<double,2>^ w,
    array<double,2>^ p,
    array<double,2>^ t,
    array<double,2>^ c,
    array<double,2>^ u,
    array<double>^ xcv,
    array<double,2>^ ycv,
    [OutAttribute] int% ifail
)
F#
static member g02lb :
        n : int *
        mx : int *
        x : float[,] *
        isx : int[] *
        ip : int *
        my : int *
        y : float[,] *
        xbar : float[] *
        ybar : float[] *
        iscale : int *
        xstd : float[] *
        ystd : float[] *
        maxfac : int *
        maxit : int *
        tau : float *
        xres : float[,] *
        yres : float[,] *
        w : float[,] *
        p : float[,] *
        t : float[,] *
        c : float[,] *
        u : float[,] *
        xcv : float[] *
        ycv : float[,] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n>1.
mx
Type: System..::..Int32
On entry: the number of predictor variables.
Constraint: mx>1.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, mx]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must contain the ith observation on the jth predictor variable, for i=1,2,…,n and j=1,2,…,mx.
isx
Type: array< System..::..Int32 >[]()[][]
An array of size [mx]
On entry: indicates which predictor variables are to be included in the model.
isx[j-1]=1
The jth predictor variable (with variates in the jth column of X) is included in the model.
isx[j-1]=0
Otherwise.
Constraint: the sum of elements in isx must equal ip.
ip
Type: System..::..Int32
On entry: m, the number of predictor variables in the model.
Constraint: 1<ip≤mx.
my
Type: System..::..Int32
On entry: r, the number of response variables.
Constraint: my≥1.
y
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, my]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: y[i-1,j-1] must contain the ith observation for the jth response variable, for i=1,2,…,n and j=1,2,…,my.
xbar
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On exit: mean values of predictor variables in the model.
ybar
Type: array< System..::..Double >[]()[][]
An array of size [my]
On exit: the mean value of each response variable.
iscale
Type: System..::..Int32
On entry: indicates how predictor variables are scaled.
iscale=1
Data are scaled by the standard deviation of variables.
iscale=2
Data are scaled by user-supplied scalings.
iscale=-1
No scaling.
Constraint: iscale=-1, 1 or 2.
xstd
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On entry: if iscale=2, xstd[j-1] must contain the user-supplied scaling for the jth predictor variable in the model, for j=1,2,…,ip. Otherwise xstd need not be set.
On exit: if iscale=1, standard deviations of predictor variables in the model. Otherwise xstd is not changed.
ystd
Type: array< System..::..Double >[]()[][]
An array of size [my]
On entry: if iscale=2, ystd[j-1] must contain the user-supplied scaling for the jth response variable in the model, for j=1,2,…,my. Otherwise ystd need not be set.
On exit: if iscale=1, the standard deviation of each response variable. Otherwise ystd is not changed.
maxfac
Type: System..::..Int32
On entry: k, the number of latent variables to calculate.
Constraint: 1≤maxfac≤ip.
maxit
Type: System..::..Int32
On entry: if my=1, maxit is not referenced; otherwise the maximum number of iterations used to calculate the x-weights.
Suggested value: maxit=200.
Constraint: if my>1, maxit>1.
tau
Type: System..::..Double
On entry: if my=1, tau is not referenced; otherwise the iterative procedure used to calculate the x-weights will halt if the Euclidean distance between two subsequent estimates is less than or equal to tau.
Suggested value: tau=1.0E−4.
Constraint: if my>1, tau>0.0.
xres
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, ip]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: the predictor variables' residual matrix Xk.
yres
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, my]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: the residuals for each response variable, Yk.
w
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, maxfac]
Note: dim1 must satisfy the constraint: dim1≥ip
On exit: the jth column of W contains the x-weights wj, for j=1,2,…,maxfac.
p
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, maxfac]
Note: dim1 must satisfy the constraint: dim1≥ip
On exit: the jth column of P contains the x-loadings pj, for j=1,2,…,maxfac.
t
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, maxfac]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: the jth column of T contains the x-scores tj, for j=1,2,…,maxfac.
c
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, maxfac]
Note: dim1 must satisfy the constraint: dim1≥my
On exit: the jth column of C contains the y-loadings cj, for j=1,2,…,maxfac.
u
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, maxfac]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: the jth column of U contains the y-scores uj, for j=1,2,…,maxfac.
xcv
Type: array< System..::..Double >[]()[][]
An array of size [maxfac]
On exit: xcv[j-1] contains the cumulative percentage of variance in the predictor variables explained by the first j factors, for j=1,2,…,maxfac.
ycv
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, my]
Note: dim1 must satisfy the constraint: dim1≥maxfac
On exit: ycv[i-1,j-1] is the cumulative percentage of variance of the jth response variable explained by the first i factors, for i=1,2,…,maxfac and j=1,2,…,my.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Let X 1 be the mean-centred n by m data matrix X of n observations on m predictor variables. Let Y 1 be the mean-centred n by r data matrix Y of n observations on r response variables.
The first of the k factors PLS methods extract from the data predicts both X 1 and Y 1 by regressing on a t 1 column vector of n scores:
X^1=t 1 p 1 TY^1=t 1 c 1 T,with ​t 1 T t 1=1,
where the column vectors of m x-loadings p 1 and r y-loadings c 1 are calculated in the least squares sense:
p 1 T=t 1 T X 1c 1 T=t 1 T Y 1.
The x-score vector t 1=X 1w 1 is the linear combination of predictor data X 1 that has maximum covariance with the y-scores u 1=Y 1c 1, where the x-weights vector w 1 is the normalised first left singular vector of X 1 T Y 1.
The method extracts subsequent PLS factors by repeating the above process with the residual matrices:
Xi=X i-1-X^i-1Yi=Y i-1-Y^i-1, i=2,3,…,k,
and with orthogonal scores:
tiT tj=0, j=1,2,…,i-1.
Optionally, in addition to being mean-centred, the data matrices X 1 and Y 1 may be scaled by standard deviations of the variables. If data are supplied mean-centred, the calculations are not affected within numerical accuracy.

References

Wold H (1966) Estimation of principal components and related models by iterative least squares In: Multivariate Analysis (ed P R Krishnaiah) 391–420 Academic Press NY

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDY, LDXRES, LDYRES, LDW, LDP, LDT, LDC, LDU, LDYCV) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | n<2,
or | mx<2,
or | an element of isx≠0 or 1,
or | my<1,
or | iscale≠-1, 1 or 2.
ifail=2
On entry, | ip<2 or ip>mx,
or | maxfac<1 or maxfac>ip,
or | my>1 and maxit≤1,
or | my>1 and tau≤0.0,
ifail=3
ip does not equal the sum of elements in isx.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

In general, the iterative method used in the calculations is less accurate (but faster) than the singular value decomposition approach adopted by g02la.

Parallelism and Performance

None.

Further Comments

g02lb allocates internally (n+r) elements of real storage.

Example

This example reads in data from an experiment to measure the biological activity in a chemical compound, and a PLS model is estimated.

Example program (C#): g02lbe.cs

Example program data: g02lbe.d

Example program results: g02lbe.r

See Also

G02 Class
G02 Members


g02lc Method

[image]

NAG Library for .NET Release 2
G02..::g02lc Method
G02 Class See Also Send Feedback
g02lc calculates parameter estimates for a given number of factors given the output from an orthogonal scores PLS regression (g02la or g02lb).

Syntax

C#
public static void g02lc(
    int ip,
    int my,
    int maxfac,
    int nfact,
    double[,] p,
    double[,] c,
    double[,] w,
    double rcond,
    double[,] b,
    int orig,
    double[] xbar,
    double[] ybar,
    int iscale,
    double[] xstd,
    double[] ystd,
    double[,] ob,
    int vipopt,
    double[,] ycv,
    double[,] vip,
    out int ifail
)
Visual Basic
Public Shared Sub g02lc ( _
    ip As Integer, _
    my As Integer, _
    maxfac As Integer, _
    nfact As Integer, _
    p As Double(,), _
    c As Double(,), _
    w As Double(,), _
    rcond As Double, _
    b As Double(,), _
    orig As Integer, _
    xbar As Double(), _
    ybar As Double(), _
    iscale As Integer, _
    xstd As Double(), _
    ystd As Double(), _
    ob As Double(,), _
    vipopt As Integer, _
    ycv As Double(,), _
    vip As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02lc(
    int ip,
    int my,
    int maxfac,
    int nfact,
    array<double,2>^ p,
    array<double,2>^ c,
    array<double,2>^ w,
    double rcond,
    array<double,2>^ b,
    int orig,
    array<double>^ xbar,
    array<double>^ ybar,
    int iscale,
    array<double>^ xstd,
    array<double>^ ystd,
    array<double,2>^ ob,
    int vipopt,
    array<double,2>^ ycv,
    array<double,2>^ vip,
    [OutAttribute] int% ifail
)
F#
static member g02lc :
        ip : int *
        my : int *
        maxfac : int *
        nfact : int *
        p : float[,] *
        c : float[,] *
        w : float[,] *
        rcond : float *
        b : float[,] *
        orig : int *
        xbar : float[] *
        ybar : float[] *
        iscale : int *
        xstd : float[] *
        ystd : float[] *
        ob : float[,] *
        vipopt : int *
        ycv : float[,] *
        vip : float[,] *
        ifail : int byref -> unit

Parameters

ip
Type: System..::..Int32
On entry: m, the number of predictor variables in the fitted model.
Constraint: ip>1.
my
Type: System..::..Int32
On entry: r, the number of response variables.
Constraint: my≥1.
maxfac
Type: System..::..Int32
On entry: k, the number of factors available in the PLS model.
Constraint: 1≤maxfac≤ip.
nfact
Type: System..::..Int32
On entry: l, the number of factors to include in the calculation of parameter estimates.
Constraint: 1≤nfact≤maxfac.
p
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, maxfac]
Note: dim1 must satisfy the constraint: dim1≥ip
On entry: x-loadings as returned from g02la and g02lb.
c
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, maxfac]
Note: dim1 must satisfy the constraint: dim1≥my
On entry: y-loadings as returned from g02la and g02lb.
w
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, maxfac]
Note: dim1 must satisfy the constraint: dim1≥ip
On entry: x-weights as returned from g02la and g02lb.
rcond
Type: System..::..Double
On entry: singular values of PT W less than rcond times the maximum singular value are treated as zero when calculating parameter estimates. If rcond is negative, a value of 0.005 is used.
b
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, my]
Note: dim1 must satisfy the constraint: dim1≥ip
On exit: b[i-1,j-1] contains the parameter estimate for the ith predictor variable in the model for the jth response variable, for i=1,2,…,ip and j=1,2,…,my.
orig
Type: System..::..Int32
On entry: indicates how parameter estimates are calculated.
orig=-1
Parameter estimates for the centered, and possibly, scaled data.
orig=1
Parameter estimates for the original data.
Constraint: orig=-1 or 1.
xbar
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On entry: if orig=1, mean values of predictor variables in the model; otherwise xbar is not referenced.
ybar
Type: array< System..::..Double >[]()[][]
An array of size [my]
On entry: if orig=1, mean value of each response variable in the model; otherwise ybar is not referenced.
iscale
Type: System..::..Int32
On entry: if orig=1, iscale must take the value supplied to either g02la or g02lb; otherwise iscale is not referenced.
Constraint: if orig=1, iscale=-1, 1 or 2.
xstd
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On entry: if orig=1 and iscale≠-1, the scalings of predictor variables in the model as returned from either g02la or g02lb; otherwise xstd is not referenced.
ystd
Type: array< System..::..Double >[]()[][]
An array of size [my]
On entry: if orig=1 and iscale≠-1, the scalings of response variables as returned from either g02la or g02lb; otherwise ystd is not referenced.
ob
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, my]
Note: dim1 must satisfy the constraint:
  • if orig=1, dim1≥ip+1;
  • otherwise dim1≥1.
On exit: if orig=1, ob[0,j-1] contains the intercept value for the jth response variable, and ob[i,j-1] contains the parameter estimate on the original scale for the ith predictor variable in the model, for i=1,2,…,ip and j=1,2,…,my. Otherwise ob is not referenced.
vipopt
Type: System..::..Int32
On entry: a flag that determines variable influence on projections (VIP) options.
vipopt=0
VIP are not calculated.
vipopt=1
VIP are calculated for predictor variables using the mean explained variance in responses.
vipopt=my
VIP are calculated for predictor variables for each response variable in the model.
Note that setting vipopt=my when my=1 gives the same result as setting vipopt=1 directly.
Constraint: vipopt=0, 1 or my.
ycv
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, my]
Note: dim1 must satisfy the constraint: if vipopt≠0, dim1≥nfact
On entry: if vipopt≠0, ycv[i-1,j-1] is the cumulative percentage of variance of the jth response variable explained by the first i factors, for i=1,2,…,nfact and j=1,2,…,my; otherwise ycv is not referenced.
vip
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, vipopt]
Note: dim1 must satisfy the constraint: if vipopt≠0, dim1≥ip
On exit: if vipopt=1, vip[i-1,0] contains the VIP statistic for the ith predictor variable in the model for all response variables, for i=1,2,…,ip.
If vipopt=my, vip[i-1,j-1] contains the VIP statistic for the ith predictor variable in the model for the jth response variable, for i=1,2,…,ip and j=1,2,…,my.
Otherwise vip is not referenced.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The parameter estimates B for a l-factor orthogonal scores PLS model with m predictor variables and r response variables are given by,
B=W PT W-1CT, B∈ℝ m×r,
where W is the m by k (≥l) matrix of x-weights; P is the m by k matrix of x-loadings; and C is the r by k matrix of y-loadings for a fitted PLS model.
The parameter estimates B are for centred, and possibly scaled, predictor data X 1 and response data Y 1. Parameter estimates may also be given for the predictor data X and response data Y.
Optionally, g02lc will calculate variable influence on projection (VIP) statistics, see Wold (1994).

References

Wold S (1994) PLS for multivariate linear modelling QSAR: chemometric methods in molecular design Methods and Principles in Medicinal Chemistry (ed van de Waterbeemd H) Verlag-Chemie

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDP, LDC, LDW, LDB, LDOB, LDYCV, LDVIP) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | ip<2,
or | my<1,
or | orig≠-1 or 1,
or | orig=1 and iscale≠-1, 1 or 2,
or | vipopt≠0, 1 or my.
ifail=2
On entry, | maxfac<1 or maxfac>ip,
or | nfact<1 or nfact>maxfac,
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The calculations are based on the singular value decomposition of PT W.

Parallelism and Performance

None.

Further Comments

g02lc allocates internally l l+r+4+max 2 l,r elements of real storage.

Example

This example reads in details of a PLS model, and a set of parameter estimates are calculated along with their VIP statistics.

Example program (C#): g02lce.cs

Example program data: g02lce.d

Example program results: g02lce.r

See Also

G02 Class
G02 Members


g02ld Method

[image]

NAG Library for .NET Release 2
G02..::g02ld Method
G02 Class See Also Send Feedback
g02ld calculates predictions given the output from an orthogonal scores PLS regression (g02la or g02lb) and g02lc.

Syntax

C#
public static void g02ld(
    int ip,
    int my,
    int orig,
    double[] xbar,
    double[] ybar,
    int iscale,
    double[] xstd,
    double[] ystd,
    double[,] b,
    int n,
    int mz,
    int[] isz,
    double[,] z,
    double[,] yhat,
    out int ifail
)
Visual Basic
Public Shared Sub g02ld ( _
    ip As Integer, _
    my As Integer, _
    orig As Integer, _
    xbar As Double(), _
    ybar As Double(), _
    iscale As Integer, _
    xstd As Double(), _
    ystd As Double(), _
    b As Double(,), _
    n As Integer, _
    mz As Integer, _
    isz As Integer(), _
    z As Double(,), _
    yhat As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02ld(
    int ip,
    int my,
    int orig,
    array<double>^ xbar,
    array<double>^ ybar,
    int iscale,
    array<double>^ xstd,
    array<double>^ ystd,
    array<double,2>^ b,
    int n,
    int mz,
    array<int>^ isz,
    array<double,2>^ z,
    array<double,2>^ yhat,
    [OutAttribute] int% ifail
)
F#
static member g02ld :
        ip : int *
        my : int *
        orig : int *
        xbar : float[] *
        ybar : float[] *
        iscale : int *
        xstd : float[] *
        ystd : float[] *
        b : float[,] *
        n : int *
        mz : int *
        isz : int[] *
        z : float[,] *
        yhat : float[,] *
        ifail : int byref -> unit

Parameters

ip
Type: System..::..Int32
On entry: the number of predictor variables in the fitted model. ip must take the same value as that supplied to g02la or g02lb to fit the model.
Constraint: ip>1.
my
Type: System..::..Int32
On entry: the number of response variables in the fitted model. my must take the same value as that supplied to g02la or g02lb to fit the model.
Constraint: my≥1.
orig
Type: System..::..Int32
On entry: indicates how parameter estimates are supplied.
orig=1
Parameter estimates are for the original data.
orig=-1
Parameter estimates are for the centred, and possibly scaled, data.
Constraint: orig=-1 or 1.
xbar
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On entry: if orig=-1, xbar must contain mean values of predictor variables in the model; otherwise xbar is not referenced.
ybar
Type: array< System..::..Double >[]()[][]
An array of size [my]
On entry: if orig=-1, ybar must contain the mean value of each response variable in the model; otherwise ybar is not referenced.
iscale
Type: System..::..Int32
On entry: if orig=-1, iscale must take the value supplied to either g02la or g02lb; otherwise iscale is not referenced.
Constraint: if orig=-1, iscale=-1, 1 or 2.
xstd
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On entry: if orig=-1 and iscale≠-1, xstd must contain the scalings of predictor variables in the model as returned from either g02la or g02lb; otherwise xstd is not referenced.
ystd
Type: array< System..::..Double >[]()[][]
An array of size [my]
On entry: if orig=-1 and iscale≠-1, ystd must contain the scalings of response variables as returned from either g02la or g02lb; otherwise ystd is not referenced.
b
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, my]
Note: dim1 must satisfy the constraint:
  • if orig=-1, dim1≥ip;
  • if orig=1, dim1≥1+ip.
On entry: if orig=-1, b must contain the parameter estimate for the centred, and possibly scaled, data as returned by g02lc; otherwise b must contain the parameter estimates for the original data as returned by g02lc.
n
Type: System..::..Int32
On entry: n, the number of observations in the test data Z.
Constraint: n≥1.
mz
Type: System..::..Int32
On entry: the number of available predictor variables in the test data.
Constraint: mz≥ip.
isz
Type: array< System..::..Int32 >[]()[][]
An array of size [mz]
On entry: indicates which predictor variables are to be included in the model. Predictor variables included from z must be in the same order as those included in the fitted model.
If isz[j-1]=1, the jth predictor variable is included in the model, for j=1,2,…,mz, otherwise isz[j-1]=0.
Constraints:
  • isz[j-1]=0​ or ​1, for j=1,2,…,mz;
  • ∑j isz[j-1]=ip.
z
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, mz]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: z[i-1,j-1] contains the ith observation on the jth available predictor variable, for i=1,2,…,n and j=1,2,…,mz.
yhat
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, my]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: yhat[i-1,j-1] contains the ith predicted value of the jth y-variable in the model.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g02ld calculates the predictions Y^ of a PLS model given a set Z of test data and a set B of parameter estimates as returned by g02lc.
If g02lc returns parameter estimates for the original data scale, no further information is required.
If g02lc returns parameter estimates for the centred, and possibly scaled, data, further information is required. The means of variables in the fitted model must be supplied. In the case of a PLS model fitted by using scaled data, the means and standard deviations of variables in the fitted model must also be supplied. These means and standard deviations are those returned by either g02la and g02lb.

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDB, LDZ, LDYHAT) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | ip≤1,
or | my<1,
or | orig≠-1 or 1,
or | orig=-1 and iscale≠-1, 1 or 2,
or | n<1,
or | an element of isz≠0 or 1.
ifail=2
On entry, mz<ip,
ifail=3
The sum of elements in isz does not equal ip.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

g02ld allocates internally 3×ip+my elements of real storage.

Example

This example reads in parameter estimates for a fitted PLS model and prediction data, and the PLS model predictions are calculated.

Example program (C#): g02lde.cs

Example program data: g02lde.d

Example program results: g02lde.r

See Also

G02 Class
G02 Members


g02qf Method

[image]

NAG Library for .NET Release 2
G02..::g02qf Method
G02 Class See Also Send Feedback
g02qf performs a multiple linear quantile regression, returning the parameter estimates and associated confidence limits based on an assumption of Normal, independent, identically distributed errors. g02qf is a simplified version of g02qg.

Syntax

C#
public static void g02qf(
    int n,
    int m,
    double[,] x,
    double[] y,
    int ntau,
    double[] tau,
    out double df,
    double[,] b,
    double[,] bl,
    double[,] bu,
    int[] info,
    out int ifail
)
Visual Basic
Public Shared Sub g02qf ( _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    y As Double(), _
    ntau As Integer, _
    tau As Double(), _
    <OutAttribute> ByRef df As Double, _
    b As Double(,), _
    bl As Double(,), _
    bu As Double(,), _
    info As Integer(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02qf(
    int n,
    int m,
    array<double,2>^ x,
    array<double>^ y,
    int ntau,
    array<double>^ tau,
    [OutAttribute] double% df,
    array<double,2>^ b,
    array<double,2>^ bl,
    array<double,2>^ bu,
    array<int>^ info,
    [OutAttribute] int% ifail
)
F#
static member g02qf :
        n : int *
        m : int *
        x : float[,] *
        y : float[] *
        ntau : int *
        tau : float[] *
        df : float byref *
        b : float[,] *
        bl : float[,] *
        bu : float[,] *
        info : int[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations in the dataset.
Constraint: n≥2.
m
Type: System..::..Int32
On entry: p, the number of variates in the model.
Constraint: 1≤m<n.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [n, m]
On entry: X, the design matrix, with the ith value for the jth variate supplied in x[i-1,j-1], for i=1,2,…,n and j=1,2,…,m.
y
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: y, observations on the dependent variable.
ntau
Type: System..::..Int32
On entry: the number of quantiles of interest.
Constraint: ntau≥1.
tau
Type: array< System..::..Double >[]()[][]
An array of size [ntau]
On entry: the vector of quantiles of interest. A separate model is fitted to each quantile.
Constraint: ε<tau[l-1]<1-ε where ε is the machine precision returned by x02aj, for l=1,2,…,ntau.
df
Type: System..::..Double %
On exit: the degrees of freedom given by n-k, where n is the number of observations and k is the rank of the cross-product matrix XT X.
b
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [m, ntau]
On exit: β^, the estimates of the parameters of the regression model, with b[j-1,l-1] containing the coefficient for the variable in column j of x, estimated for τ=tau[l-1].
bl
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [m, ntau]
On exit: β^L, the lower limit of a 95% confidence interval for β^, with bl[j-1,l-1] holding the lower limit associated with b[j-1,l-1].
bu
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [m, ntau]
On exit: β^U, the upper limit of a 95% confidence interval for β^, with bu[j-1,l-1] holding the upper limit associated with b[j-1,l-1].
info
Type: array< System..::..Int32 >[]()[][]
An array of size [ntau]
On exit: info[l] holds additional information concerning the model fitting and confidence limit calculations when τ=tau[l].
Code | Warning
0 | Model fitted and confidence limits calculated successfully.
1 | The method did not converge whilst calculating the parameter estimates. The returned values are based on the estimate at the last iteration.
2 | A singular matrix was encountered during the optimization. The model was not fitted for this value of τ.
8 | The method did not converge whilst calculating the confidence limits. The returned limits are based on the estimate at the last iteration.
16 | Confidence limits for this value of τ could not be calculated. The returned upper and lower limits are set to a large positive and large negative value respectively.
It is possible for multiple warnings to be applicable to a single model. In these cases the value returned in info is the sum of the corresponding individual nonzero warning codes.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Given a vector of n observed values, y=yi:i=1,2,…,n, an n×p design matrix X, a column vector, x, of length p holding the ith row of X and a quantile τ∈0,1, g02qf estimates the p-element vector β as the solution to
minimize β∈ℝp∑ i=1 n ρτ yi-xiT β (1)
where ρτ is the piecewise linear loss function ρτ z=z⁢τ-I z<0, and I z<0 is an indicator function taking the value 1 if z<0 and 0 otherwise.
g02qf assumes Normal, independent, identically distributed (IID) errors and calculates the asymptotic covariance matrix from
Σ=τ 1-τ n s τ 2XT X-1
where s is the sparsity function, which is estimated from the residuals, ri=yi-xiT⁢β^ (see Koenker (2005)).
Given an estimate of the covariance matrix, Σ^, lower, β^L, and upper, β^U, limits for a 95% confidence interval are calculated for each of the p parameters, via
β^Li=β^i-t n-p,0.975 Σ^ii,β^Ui=β^i+t n-p,0.975 Σ^ii
where t n-p,0.975 is the 97.5 percentile of the Student's t distribution with n-k degrees of freedom, where k is the rank of the cross-product matrix XT X.
Further details of the algorithms used by g02qf can be found in the documentation for g02qg.

References

Koenker R (2005) Quantile Regression Econometric Society Monographs, Cambridge University Press, New York

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=11
On entry, n<2.
ifail=21
On entry, | m<1,
or | m≥n.
ifail=51
On entry, ntau<1.
ifail=61
On entry, tau is invalid.
ifail=111
On exit, problems were encountered whilst fitting at least one model. Additional information has been returned in info.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

Calling g02qf is equivalent to calling g02qg with
  • rcord=2,
  • rcord=1, ic1="N",
  • _weight="U",
  • lddat=n,
  • setting each element of isx to 1,
  • ip=m,
  • Interval Method=IID, and
  • Significance Level=0.95.

Example

A quantile regression model is fitted to Engels 1857 study of household expenditure on food. The model regresses the dependent variable, household food expenditure, against household income. An intercept is included in the model by augmenting the dataset with a column of ones.

Example program (C#): g02qfe.cs

Example program data: g02qfe.d

Example program results: g02qfe.r

See Also

G02 Class
G02 Members


g02qg Method

[image]

NAG Library for .NET Release 2
G02..::g02qg Method
G02 Class See Also Send Feedback
g02qg performs a multiple linear quantile regression. Parameter estimates and, if required, confidence limits, covariance matrices and residuals are calculated. g02qg may be used to perform a weighted quantile regression. A simplified interface for g02qg is provided by g02qf.

Syntax

C#
public static void g02qg(
    int sorder,
    int ic1,
    int n,
    int m,
    double[,] dat,
    int[] isx,
    int ip,
    double[] y,
    double[] wt,
    int ntau,
    double[] tau,
    out double df,
    double[,] b,
    double[,] bl,
    double[,] bu,
    double[,,] ch,
    double[,] res,
    G02..::..g02qgOptions options,
    G05..::..G05State g05state,
    int[] info,
    out int ifail
)
Visual Basic
Public Shared Sub g02qg ( _
    sorder As Integer, _
    ic1 As Integer, _
    n As Integer, _
    m As Integer, _
    dat As Double(,), _
    isx As Integer(), _
    ip As Integer, _
    y As Double(), _
    wt As Double(), _
    ntau As Integer, _
    tau As Double(), _
    <OutAttribute> ByRef df As Double, _
    b As Double(,), _
    bl As Double(,), _
    bu As Double(,), _
    ch As Double(,,), _
    res As Double(,), _
    options As G02..::..g02qgOptions, _
    g05state As G05..::..G05State, _
    info As Integer(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g02qg(
    int sorder,
    int ic1,
    int n,
    int m,
    array<double,2>^ dat,
    array<int>^ isx,
    int ip,
    array<double>^ y,
    array<double>^ wt,
    int ntau,
    array<double>^ tau,
    [OutAttribute] double% df,
    array<double,2>^ b,
    array<double,2>^ bl,
    array<double,2>^ bu,
    array<double,3>^ ch,
    array<double,2>^ res,
    G02..::..g02qgOptions^ options,
    G05..::..G05State^ g05state,
    array<int>^ info,
    [OutAttribute] int% ifail
)
F#
static member g02qg :
        sorder : int *
        ic1 : int *
        n : int *
        m : int *
        dat : float[,] *
        isx : int[] *
        ip : int *
        y : float[] *
        wt : float[] *
        ntau : int *
        tau : float[] *
        df : float byref *
        b : float[,] *
        bl : float[,] *
        bu : float[,] *
        ch : float[,,] *
        res : float[,] *
        options : G02..::..g02qgOptions *
        g05state : G05..::..G05State *
        info : int[] *
        ifail : int byref -> unit

Parameters

sorder
Type: System..::..Int32
On entry: determines the storage order of variates supplied in dat.
Constraint: sorder=1 or 2.
ic1
Type: System..::..Int32
On entry: indicates whether an intercept will be included in the model. The intercept is included by adding a column of ones as the first column in the design matrix, X.
ic1=1
An intercept will be included in the model.
ic1=0
An intercept will not be included in the model.
Constraint: ic1=0 or 1.
n
Type: System..::..Int32
On entry: the total number of observations in the dataset. If no weights are supplied, or no zero weights are supplied or observations with zero weights are included in the model then n=n. Otherwise n=n+ the number of observations with zero weights.
Constraint: n≥2.
m
Type: System..::..Int32
On entry: m, the total number of variates in the dataset.
Constraint: m≥0.
dat
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, _sddat]
Note: dim1 must satisfy the constraint:
  • if sorder=1, dim1≥n;
  • otherwise dim1≥m.
On entry: the ith value for the jth variate, for i=1,2,…,n and j=1,2,…,m, must be supplied in
  • dat[i-1,j-1] if sorder=1, and
  • dat[j-1,i-1] if sorder=2.
The design matrix X is constructed from dat, isx and ic1.
isx
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: indicates which independent variables are to be included in the model.
isx[j-1]=0
The jth variate, supplied in dat, is not included in the regression model.
isx[j-1]=1
The jth variate, supplied in dat, is included in the regression model.
Constraints:
  • isx[j-1]=0 or 1, for j=1,2,…,m;
  • if ic1=1, exactly ip-1 values of isx must be set to 1;
  • if ic1=0, exactly ip values of isx must be set to 1.
ip
Type: System..::..Int32
On entry: p, the number of independent variables in the model, including the intercept, see ic1, if present.
Constraints:
  • 1≤ip<n;
  • if ic1=1, 1≤ip≤m+1;
  • if ic1=0, 1≤ip≤m.
y
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: y, observations on the dependent variable.
wt
Type: array< System..::..Double >[]()[][]
An array of size [_lwt]
On entry: if _weight="W", wt must contain the diagonal elements of the weight matrix W. Otherwise wt is not referenced.
When
Drop Zero Weights=YES
If wt[i-1]=0.0, the ith observation is not included in the model, in which case the effective number of observations, n, is the number of observations with nonzero weights. If Return Residuals=YES, the values of res will be set to zero for observations with zero weights.
Drop Zero Weights=NO
All observations are included in the model and the effective number of observations is n, i.e., n=n.
Constraints:
  • If _weight="W", wt[i-1]≥0.0, for i=1,2,…,n;
  • The effective number of observations ≥2.
ntau
Type: System..::..Int32
On entry: the number of quantiles of interest.
Constraint: ntau≥1.
tau
Type: array< System..::..Double >[]()[][]
An array of size [ntau]
On entry: the vector of quantiles of interest. A separate model is fitted to each quantile.
Constraint: ε<tau[j-1]<1-ε where ε is the machine precision returned by x02aj, for j=1,2,…,ntau.
df
Type: System..::..Double %
On exit: the degrees of freedom given by n-k, where n is the effective number of observations and k is the rank of the cross-product matrix XT X.
b
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [ip, ntau]
On entry: if Calculate Initial Values=NO, b[i-1,l-1] must hold an initial estimates for β^i, for i=1,2,…,ip and l=1,2,…,ntau. If Calculate Initial Values=YES, b need not be set.
On exit: b[i-1,l-1], for i=1,2,…,ip, contains the estimates of the parameters of the regression model, β^, estimated for τ=tau[l-1].
If ic1=1, b[0,l-1] will contain the estimate corresponding to the intercept and b[i,l-1] will contain the coefficient of the jth variate contained in dat, where isx[j-1] is the ith nonzero value in the array isx.
If ic1=0, b[i-1,l-1] will contain the coefficient of the jth variate contained in dat, where isx[j-1] is the ith nonzero value in the array isx.
bl
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, ntau]
Note: dim1 must satisfy the constraint:
Note: the second dimension of the array bl must be at least ntau if Interval Method≠NONE.
On exit: if Interval Method≠NONE, bl[i-1,l-1] contains the lower limit of an 100×α% confidence interval for b[i-1,l-1], for i=1,2,…,ip and l=1,2,…,ntau.
If Interval Method=NONE, bl is not referenced.
The method used for calculating the interval is controlled by the optional parameters Interval Method and Bootstrap Interval Method. The size of the interval, α, is controlled by the optional parameter Significance Level.
bu
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, ntau]
Note: dim1 must satisfy the constraint:
Note: the second dimension of the array bu must be at least ntau if Interval Method≠NONE.
On exit: if Interval Method≠NONE, bu[i-1,l-1] contains the upper limit of an 100×α% confidence interval for b[i-1,l-1], for i=1,2,…,ip and l=1,2,…,ntau.
If Interval Method=NONE, bu is not referenced.
The method used for calculating the interval is controlled by the optional parameters Interval Method and Bootstrap Interval Method. The size of the interval, α is controlled by the optional parameter Significance Level.
ch
Type: array< System..::..Double ,3>[,](,)[,][,]
An array of size [dim1, dim2, dim3]
Note: dim1 must satisfy the constraint:
Note: dim2 must satisfy the constraint:
Note: dim3 must satisfy the constraint:
Note: the last dimension of the array ch must be at least ntau if Interval Method≠NONE and Matrix Returned=COVARIANCE and at least ntau+1 if Interval Method≠NONE, IID or BOOTSTRAP XY and Matrix Returned=H INVERSE.
On exit: depending on the supplied optional parameters, ch will either not be referenced, hold an estimate of the upper triangular part of the covariance matrix, Σ, or an estimate of the upper triangular parts of n⁢Jn and n-1⁢Hn-1.
If Interval Method=NONE or Matrix Returned=NONE, ch is not referenced.
If Interval Method=BOOTSTRAP XY or IID and Matrix Returned=H INVERSE, ch is not referenced.
Otherwise, for i,j=1,2,…,ip,j≥i and l=1,2,…,ntau:
  • If Matrix Returned=COVARIANCE, ch[i-1,j-1,l-1] holds an estimate of the covariance between b[i-1,l-1] and b[j-1,l-1].
  • If Matrix Returned=H INVERSE, ch[i-1,j-1,0] holds an estimate of the i,jth element of n⁢Jn and ch[i-1,j-1,l+1-1] holds an estimate of the i,jth element of n-1⁢Hn-1, for τ=tau[l-1].
The method used for calculating Σ and Hn-1 is controlled by the optional parameter Interval Method.
res
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [n, dim2]
Note: dim2 must satisfy the constraint:
On exit: if Return Residuals=YES, res[i-1,l-1] holds the (weighted) residuals, ri, for τ=tau[l-1], for i=1,2,…,n and l=1,2,…,ntau.
If wt is not NULL and Drop Zero Weights=YES, the value of res will be set to zero for observations with zero weights.
If Return Residuals=NO, res is not referenced.
options
Type: NagLibrary..::..G02..::..g02qgOptions
An Object of type G02.g02qgOptions. Used to configure optional parameters to this method.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
info
Type: array< System..::..Int32 >[]()[][]
An array of size [ntau]
On exit: info[i] holds additional information concerning the model fitting and confidence limit calculations when τ=tau[i].
Code | Warning
0 | Model fitted and confidence limits (if requested) calculated successfully
1 | The method did not converge. The returned values are based on the estimate at the last iteration. Try increasing Iteration Limit whilst calculating the parameter estimates or relaxing the definition of convergence by increasing Tolerance.
2 | A singular matrix was encountered during the optimization. The model was not fitted for this value of τ.
4 | Some truncation occurred whilst calculating the confidence limits for this value of τ. See [Algorithmic Details] for details. The returned upper and lower limits may be narrower than specified.
8 | The method did not converge whilst calculating the confidence limits. The returned limits are based on the estimate at the last iteration. Try increasing Iteration Limit.
16 | Confidence limits for this value of τ could not be calculated. The returned upper and lower limits are set to a large positive and large negative value respectively as defined by the optional parameter Big.
It is possible for multiple warnings to be applicable to a single model. In these cases the value returned in info is the sum of the corresponding individual nonzero warning codes.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Given a vector of n observed values, y=yi:i=1,2,…,n, an n×p design matrix X, a column vector, x, of length p holding the ith row of X and a quantile τ∈0,1, g02qg estimates the p-element vector β as the solution to
minimize β∈ℝp∑ i=1 n ρτ yi-xiT β (1)
where ρτ is the piecewise linear loss function ρτ z=z⁢τ-I z<0, and I z<0 is an indicator function taking the value 1 if z<0 and 0 otherwise. Weights can be incorporated by replacing X and y with W⁢X and W⁢y respectively, where W is an n×n diagonal matrix. Observations with zero weights can either be included or excluded from the analysis; this is in contrast to least squares regression where such observations do not contribute to the objective function and are therefore always dropped.
g02qg uses the interior point algorithm of Portnoy and Koenker (1997), described briefly in [Algorithmic Details], to obtain the parameter estimates β^, for a given value of τ.
Under the assumption of Normally distributed errors, Koenker (2005) shows that the limiting covariance matrix of β^-β has the form
Σ=τ 1-τ n Hn-1 Jn Hn-1
where Jn=n-1⁢∑ i=1 n xi xiT and Hn is a function of τ, as described below. Given an estimate of the covariance matrix, Σ^, lower (β^L) and upper (β^U) limits for an 100×α% confidence interval can be calculated for each of the p parameters, via
β^Li=β^i-t n-p,1+α/2 Σ^ii,β^Ui=β^i+t n-p,1+α/2 Σ^ii
where t n-p,0.975 is the 97.5 percentile of the Student's t distribution with n-k degrees of freedom, where k is the rank of the cross-product matrix XT X.
Four methods for estimating the covariance matrix, Σ, are available:
(i) Independent, identically distributed (IID) errors
Under an assumption of IID errors the asymptotic relationship for Σ simplifies to
Σ=τ 1-τ n s τ 2XT X-1
where s is the sparsity function. g02qg estimates s τ from the residuals, ri=yi-xiT⁢β^ and a bandwidth hn.
(ii) Powell Sandwich
Powell (1991) suggested estimating the matrix Hn by a kernel estimator of the form
H^n=n cn-1∑ i=1 n K ri cn⁢xi xiT
where K is a kernel function and cn satisfies lim n→∞cn→0 and lim n→∞n cn→∞. When the Powell method is chosen, g02qg uses a Gaussian kernel (i.e., K=ϕ) and sets
cn=min σr,q r 3-q r 1/1.34×Φ-1 τ+hn-Φ-1 τ-hn
where hn is a bandwidth, σr,q r 1 and q r 3 are, respectively, the standard deviation and the 25% and 75% quantiles for the residuals, ri.
(iii) Hendricks–Koenker Sandwich
Koenker (2005) suggested estimating the matrix Hn using
H^n=n-1∑ i=1 n 2⁢hnxiT β^τ+hn-β^τ-hn⁢xi xiT
where hn is a bandwidth and β^τ+hn denotes the parameter estimates obtained from a quantile regression using the τ+hnth quantile. Similarly with β^τ-hn.
(iv) Bootstrap
The last method uses bootstrapping to either estimate a covariance matrix or obtain confidence intervals for the parameter estimates directly. This method therefore does not assume Normally distributed errors. Samples of size n are taken from the paired data yi,xi (i.e., the independent and dependent variables are sampled together). A quantile regression is then fitted to each sample resulting in a series of bootstrap estimates for the model parameters, β. A covariance matrix can then be calculated directly from this series of values. Alternatively, confidence limits, β^L and β^U, can be obtained directly from the 1-α/2 and 1+α/2 sample quantiles of the bootstrap estimates.
Further details of the algorithms used to calculate the covariance matrices can be found in [Algorithmic Details].
All three asymptotic estimates of the covariance matrix require a bandwidth, hn. Two alternative methods for determining this are provided:
(i) Sheather–Hall
hn=1.5⁢Φ-1 αbϕ Φ-1 τ 2n⁢2⁢Φ-1 τ+1 13
for a user-supplied value αb,
(ii) Bofinger
hn=4.5⁢ϕ Φ-1 τ 4n⁢2⁢Φ-1 τ+1 2 15
g02qg allows optional arguments to be supplied via the iopts and opts arrays (see [Optional Parameters] for details of the available options). Prior to calling g02qg the optional parameter arrays, iopts and opts must be initialized by calling (G02ZKF not in this release) with optstr set to Initialize=g02qg (see [Optional Parameters] for details on the available options). If bootstrap confidence limits are required (Interval Method=BOOTSTRAP XY) then one of the random number initialization methods (G05KFF not in this release) (for a repeatable analysis) or (G05KGF not in this release) (for an unrepeatable analysis) must also have been previously called.

References

Koenker R (2005) Quantile Regression Econometric Society Monographs, Cambridge University Press, New York
Mehrotra S (1992) On the implementation of a primal-dual interior point method SIAM J. Optim. 2 575–601
Nocedal J and Wright S J (1999) Numerical Optimization Springer Series in Operations Research, Springer, New York
Portnoy S and Koenker R (1997) The Gaussian hare and the Laplacian tortoise: computability of squared-error versus absolute error estimators Statistical Science 4 279–300
Powell J L (1991) Estimation of monotonic regression models under quantile restrictions Nonparametric and Semiparametric Methods in Econometrics Cambridge University Press, Cambridge

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDDAT, RIP, TDCH, SDRES, LIOPTS, LOPTS, LSTATE) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=11
On entry, sorder≠1 or 2.
ifail=21
On entry, ic1≠1 or 0.
ifail=31
On entry, _weight≠"U" or "W".
ifail=41
On entry, n<2.
ifail=51
On entry, m<0.
ifail=71
On entry, sorder=1, lddat<n.
ifail=72
On entry, sorder=2, lddat<m.
ifail=81
On entry, isx[j-1]≠0 or 1.
ifail=91
On entry, ip<1 or ip≥n.
ifail=92
On entry, ip is not consistent with isx and ic1.
ifail=111
On entry, _weight="W" and wt[i-1]<0.0 for at least one i.
ifail=112
On entry, the effective number of observations is less than two.
ifail=121
On entry, ntau<1.
ifail=131
On entry, tau is invalid.
ifail=201
On entry, one or more of the optional parameter arrays iopts and opts have not been initialized or have been corrupted.
ifail=221
On entry, Interval Method=BOOTSTRAP XY and state was not initialized or has been corrupted.
ifail=231
On exit, problems were encountered whilst fitting at least one model. Additional information has been returned in info.
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

g02qg allocates internally approximately the following elements of real storage: 13⁢n+n⁢p+3⁢p 2+6⁢p+3⁢p+1×ntau. If Interval Method=BOOTSTRAP XY then a further n⁢p elements are required, and this increases by p×ntau×Bootstrap Iterations if Bootstrap Interval Method=QUANTILE. Where possible, any user-supplied output arrays are used as workspace and so the amount actually allocated may be less. If sorder=2, wt is NULL, ic1=0 and ip=m an internal copy of the input data is avoided and the amount of locally allocated memory is reduced by n⁢p.

Example

A quantile regression model is fitted to Engels 1857 study of household expenditure on food. The model regresses the dependent variable, household food expenditure, against two explanatory variables, a column of ones and household income. The model is fit for five different values of τ and the covariance matrix is estimated assuming Normal IID errors. Both the covariance matrix and the residuals are returned.

Example program (C#): g02qge.cs

Example program data: g02qge.d

Example program results: g02qge.r

Algorithmic Details

By the addition of slack variables the minimization (1) can be reformulated into the linear programming problem
minimize u,v,β∈ℝ+n×ℝ+n×ℝp τ eT u+1-τ eT v​   subject to  y=Xβ+u-v (2)
and its associated dual
maximized yT d​   subject to  XT d=0,d∈τ-1,τ n (3)
where e is a vector of n 1s. Setting a=d+1-τ e gives the equivalent formulation
maximizea yT a​   subject to  XT a=1-τ XT e,a∈0,1 n. (4)
The algorithm introduced by Portnoy and Koenker (1997) and used by g02qg, uses the primal-dual formulation expressed in equations (2) and (4) along with a logarithmic barrier function to obtain estimates for β. The algorithm is based on the predictor-corrector algorithm of Mehrotra (1992) and further details can be obtained from Portnoy and Koenker (1997) and Koenker (2005). A good description of linear programming, interior point algorithms, barrier functions and Mehrotra's predictor-corrector algorithm can be found in Nocedal and Wright (1999).

Interior Point Algorithm

In this section a brief description of the interior point algorithm used to estimate the model parameters is presented. It should be noted that there are some differences in the equations given here – particularly (7) and (9) – compared to those given in Koenker (2005) and Portnoy and Koenker (1997).

Central path

Rather than optimize (4) directly, an additional slack variable s is added and the constraint a∈0,1 n is replaced with a+s=e,ai≥0,si≥0, for i=1,2,…,n.
The positivity constraint on a and s is handled using the logarithmic barrier function
B a,s,μ=yT a+μ⁢∑ i=1 n log ai+log si.
The primal-dual form of the problem is used giving the Lagrangian
L a,s,β,u,μ=B a,s,μ-βT XT a-1-τ XT e-uT a+s-e
whose central path is described by the following first order conditions
XT a=1-τ XT ea+s=eXβ+u-v=ySUe=μeAVe=μe (5)
where A denotes the diagonal matrix with diagonal elements given by a, similarly with S,U and V. By enforcing the inequalities on s and a strictly, i.e., ai>0 and si>0 for all i we ensure that A and S are positive definite diagonal matrices and hence A-1 and S-1 exist.
Rather than applying Newton's method to the system of equations given in (5) to obtain the step directions δβ,δa,δs,δu and δv, Mehrotra substituted the steps directly into (5) giving the augmented system of equations
XT a+δa=1-τ XT ea+δa+s+δs=eX β+δβ+u+δu-v+δv=yS+ΔsU+Δu e=μeA+ΔaV+Δv e=μe (6)
where Δa,Δs,Δu and Δv denote the diagonal matrices with diagonal elements given by δa,δs,δu and δv respectively.

Affine scaling step

The affine scaling step is constructed by setting μ=0 in (5) and applying Newton's method to obtain an intermediate set of step directions
XT WX δβ=XT W y-Xβ+τ-1 XT e+XT aδa=W y-Xβ-X δβδs=-δaδu=S-1 U δa-Ueδv=A-1 V δs-Ve (7)
where W=S-1 U+A-1 V-1.
Initial step sizes for the primal (γ^P) and dual (γ^D) parameters are constructed as
γ^P=σ×min min i,δ ai<0 ai/δ ai,min i,δ si<0 si/δ siγ^D=σ×min min i,δ ui<0 ui/δ ui,min i,δ vi<0 vi/δ vi (8)
where σ is a user-supplied scaling factor. If γ^P×γ^D≥1 then the nonlinearity adjustment, described in [Nonlinearity Adjustment], is not made and the model parameters are updated using the current step size and directions.

Nonlinearity Adjustment

In the nonlinearity adjustment step a new estimate of μ is obtained by letting
g^γ^P,γ^D=s+γ^Pδs T u+γ^Dδu+a+γ^Pδa T v+γ^Dδv
and estimating μ as
μ=g^γ^P,γ^Dg^0,0 3⁢g^0,02⁢n.
This estimate, along with the nonlinear terms (Δu, Δs, Δa and Δv) from (6) are calculated using the values of δa,δs,δu and δv obtained from the affine scaling step.
Given an updated estimate for μ and the nonlinear terms the system of equations
XT WX δβ=XT W y-Xβ+μ S-1-A-1 e+S-1 ΔsΔu e-A-1 ΔaΔv e+τ-1 XT e+XT aδa=W y-Xβ-X δβ+μ S-1-A-1δs=-δaδu=μ S-1 e+S-1 U δa-Ue-S-1 ΔsΔu eδv=μ A-1 e+A-1 V δs-Ve-A-1 ΔaΔv e (9)
are solved and updated values for δβ,δa,δs,δu,δv,γ^P and γ^D calculated.

Update and convergence

At each iteration the model parameters β,a,s,u,v are updated using step directions, δβ,δa,δs,δu,δv and step lengths γ^P,γ^D.
Convergence is assessed using the duality gap, that is, the differences between the objective function in the primal and dual formulations. For any feasible point u,v,s,a the duality gap can be calculated from equations (2) and (3) as
τ eT u+1-τ⁢eT v-dT y=τ eT u+1-τ⁢eT v-a-1-τ e T y=sT u+aT v=eT u-aT y+1-τ eT Xβ
and the optimization terminates if the duality gap is smaller than the tolerance supplied in the optional parameter Tolerance.

Additional information

Initial values are required for the parameters a,s,u,v and β. If not supplied by the user, initial values for β are calculated from a least squares regression of y on X. This regression is carried out by first constructing the cross-product matrix XT X and then using a pivoted Q⁢R decomposition as performed by f08bf. In addition, if the cross-product matrix is not of full rank, a rank reduction is carried out and, rather than using the full design matrix, X, a matrix formed from the first p-rank columns of X⁢P is used instead, where P is the pivot matrix used during the Q⁢R decomposition. Parameter estimates, confidence intervals and the rows and columns of the matrices returned in the parameter ch (if any) are set to zero for variables dropped during the rank-reduction. The rank reduction step is performed irrespective of whether initial values are supplied by the user.
Once initial values have been obtained for β, the initial values for u and v are calculated from the residuals. If ri<εu then a value of ±εu is used instead, where εu is supplied in the optional parameter Epsilon. The initial values for the a and s are always set to 1-τ and τ respectively.
The solution for δβ in both (7) and (9) is obtained using a Bunch–Kaufman decomposition, as implemented in (F07MDF not in this release).

Calculation of Covariance Matrix

g02qg supplies four methods to calculate the covariance matrices associated with the parameter estimates for β. This section gives some additional detail on three of the algorithms, the fourth, (which uses bootstrapping), is described in [Description].
(i) Independent, identically distributed (IID) errors
When assuming IID errors, the covariance matrices depend on the sparsity, s τ, which g02qg estimates as follows:
(a) | Let ri denote the residuals from the original quantile regression, that is ri=yi-xiT⁢β^.
(b) | Drop any residual where ri is less than εu, supplied in the optional parameter Epsilon.
(c) | Sort and relabel the remaining residuals in ascending order, by absolute value, so that εu<r 1<r 2<….
(d) | Select the first l values where l=hn⁢n, for some bandwidth hn.
(e) | Sort and relabel these l residuals again, so that r 1<r 2<…<rl and regress them against a design matrix with two columns (p=2) and rows given by xi=1,i/n-p using quantile regression with τ=0.5.
(f) | Use the resulting estimate of the slope as an estimate of the sparsity.
(ii) Powell Sandwich
When using the Powell Sandwich to estimate the matrix Hn, the quantity
cn=min σr,q r 3-q r 1/1.34×Φ-1 τ+hn-Φ-1 τ-hn
is calculated. Dependent on the value of τ and the method used to calculate the bandwidth (hn), it is possible for the quantities τ±hn to be too large or small, compared to machine precision (ε). More specifically, when τ-hn≤ε, or τ+hn≥1-ε, a warning flag is raised in info, the value is truncated to ε or 1-ε respectively and the covariance matrix calculated as usual.
(iii) Hendricks–Koenker Sandwich
The Hendricks–Koenker Sandwich requires the calculation of the quantity di=xiT β^τ+hn-β^τ-hn. As with the Powell Sandwich, in cases where τ-hn≤ε, or τ+hn≥1-ε, a warning flag is raised in info, the value truncated to ε or 1-ε respectively and the covariance matrix calculated as usual.
In addition, it is required that di>0, in this method. Hence, instead of using 2⁢hn/di in the calculation of Hn, max 2⁢hn/di+εu,0 is used instead, where εu is supplied in the optional parameter Epsilon.

Description of Monitoring Information

See the description of the optional argument Monitoring.

See Also

G02 Class
G02 Members


G03 Class

[image]

NAG Library for .NET Release 2
G03 Class
Members See Also Send Feedback
This chapter is concerned with methods for studying multivariate data. A multivariate dataset consists of several variables recorded on a number of objects or individuals. Multivariate methods can be classified as those that seek to examine the relationships between the variables (e.g., principal components), known as variable-directed methods, and those that seek to examine the relationships between the objects (e.g., cluster analysis), known as individual-directed methods.
Multiple regression is not included in this chapter as it involves the relationship of a single variable, known as the response variable, to the other variables in the dataset, the explanatory variables. Routines for multiple regression are provided in G02 class.

Syntax

C#
public static class G03
Visual Basic
Public NotInheritable Class G03
Visual C++
public ref class G03 abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type G03 =  class end

Background to the Problems

Variable-directed Methods

Let the n by p data matrix consist of p variables, x 1,x 2,…,xp, observed on n objects or individuals. Variable-directed methods seek to examine the linear relationships between the p variables with the aim of reducing the dimensionality of the problem. There are different methods depending on the structure of the problem. Principal component analysis and factor analysis examine the relationships between all the variables. If the individuals are classified into groups, then canonical variate analysis examines the between group structure. If the variables can be considered as coming from two sets, then canonical correlation analysis examines the relationships between the two sets of variables. All four methods are based on an eigenvalue decomposition or a singular value decomposition (SVD) of an appropriate matrix.
The above methods may reduce the dimensionality of the data from the original p variables to a smaller number, k, of derived variables that adequately represent the data. In general, these k derived variables will be unique only up to an orthogonal rotation. Therefore, it may be useful to see if there exists suitable rotations of these variables that lead to a simple interpretation of the new variables in terms of the original variables.

Principal component analysis

Principal component analysis finds new variables which are linear combinations of the p observed variables so that they have maximum variation and are orthogonal (uncorrelated).
Let S be the p by p variance-covariance matrix of the n by p data matrix. A vector a 1 of length p is found such that
a 1 T S a 1​ is maximized subject to ​a 1 T a 1=1.
The variable z 1=∑i=1 p a 1 ixi is known as the first principal component and gives the linear combination of the variables that gives the maximum variation. A second principal component, z 2=∑i=1 p a 2 ixi, is found such that
a 2 T S a 2​ is maximized subject to ​a 2 T a 2=1​ and ​a 2 T a 1=0.
This gives the linear combination of variables, orthogonal to the first principal component, that gives the maximum variation. Further principal components are derived in a similar way.
The vectors ai, for i=1,2,…,p, are the eigenvectors of the matrix S and associated with each eigenvector is the eigenvalue, γi 2. The value of γi 2/∑γi 2 gives the proportion of variation explained by the ith principal component. Alternatively, the ai can be considered as the right singular vectors in a SVD of a scaled mean-centred data matrix. The singular values of the SVD are the γi-values.
Often fewer than p dimensions (principal components) are needed to represent most of the variation in the data. A test on the smaller eigenvalues can be used to investigate the number of dimensions needed.
The values of the principal component variables for the individuals are known as the principal component scores. These can be standardized so that the variance of these scores for each principal component is 1.0 or equal to the corresponding eigenvalue. The principal component scores correspond to the left-hand singular vectors in the SVD.

Factor analysis

Let the p variables have variance-covariance matrix Σ. The aim of factor analysis is to account for the covariances in these p variables in terms of a smaller number, k, of hypothetical variables or factors, f 1,f 2,…,fk. These are assumed to be independent and to have unit variance. The relationship between the observed variables and the factors is given by the model
xi=∑j=1 k λ ijfj+ei,  i=1,2,…,p
where λ ij, for i=1,2,…,p and j=1,2,…,k, are the factor loadings and ei, for i=1,2,…,p, are independent random variables with variances ψi. These represent the unique component of the variation of each observed variable. The proportion of variation for each variable accounted for by the factors is known as the communality.
The model for the variance-covariance matrix, Σ, can then be written as
Σ=Λ ΛT+Ψ,
where Λ is the matrix of the factor loadings, λ ij, and Ψ is a diagonal matrix of the unique variances ψi.
If it is assumed that both the k factors and the ei follow independent Normal distributions then the parameters of the model, Λ and Ψ, can be estimated by maximum likelihood, as described by Lawley and Maxwell (1971). The computation of the maximum likelihood estimates is an iterative procedure which involves computing the eigenvalues and eigenvectors of the matrix
S*=Ψ-1/2 S Ψ-1/2,
where S is the sample variance-covariance matrix. Alternatively, the SVD of the matrix R Ψ-1/2 can be used, where RT R=S. When convergence has been achieved, the estimates Λ^, of Λ, are obtained by scaling the eigenvectors of S*. The use of maximum likelihood estimation means that likelihood ratio tests can be constructed to test for the number of factors required.
Having found the estimates of the parameters of the model, the estimates of the values of the factors for the individuals, the factor scores, can be computed. These involve the calculation of the factor score coefficients. Two common methods of computing factor score coefficients are the regression method and Bartlett's method. Bartlett's method gives unbiased estimates of the factor scores while the estimates from the regression method are biased but have smaller variance; see Lawley and Maxwell (1971).

Canonical variate analysis

If the individuals can be classified into one of g groups, then canonical variate analysis finds the linear combinations of the p variables that maximize the ratio of the between-group variation to the within-group variation. These variables are known as canonical variates. As the canonical variates provide discrimination between the groups, the method is also known as canonical discrimination.
The canonical variates can be calculated from the eigenvectors of the within-group sums of squares and cross-products matrix or from the SVD of the matrix
V=QxT Qg,
where Qg is an orthogonal matrix that defines the groups and Qx is the first p columns of the orthogonal matrix Q from the QR decomposition of the data matrix with the variable means subtracted. If the data matrix is not of full rank, the Qx matrix can be obtained from a SVD. If the SVD of V is
V=Ux Δ UgT,
then the nonzero elements (δi>0) of the diagonal matrix Δ are the canonical correlations. The largest δi is called the first canonical correlation and associated with it is the first canonical variate.
The eigenvalues, γi 2, of the within-group sums of squares matrix are given by
γi 2=δi 21-δi 2.
The value of πi=γi 2/∑γi 2 gives the proportion of variation explained by the ith canonical variate. The values of the πi give an indication as to how many canonical variates are needed to adequately describe the data, i.e., the dimensionality of the problem. The number of dimensions can be investigated by means of a test on the smaller canonical correlations.
The canonical variate loadings and the relationship between the original variables and the canonical variates are calculated from the matrix Ux. This matrix is scaled so that the canonical variates have unit variance.

Canonical correlation analysis

If the p variables can be considered as coming from two sets then canonical correlation analysis finds linear combinations of the variables in each set, known as canonical variates, such that the correlations between corresponding canonical variates for the two sets are maximized. Let the two sets of variables be denoted by x and y, with px and py variables in each set respectively. Let the variance-covariance of the dataset be
S=S xxS xyS yxS yy
and let
Σ=S yy-1 S yx S xx-1 S xy,
then the canonical correlations can be calculated from the eigenvalues of the matrix Σ. Alternatively, the canonical correlations can be calculated by means of a SVD of the matrix
V=QxT Qy,
where Qx is the first px columns of the orthogonal matrix Q from the QR decomposition of the x-variables in the data matrix, and Qy is the first py columns of the Q matrix of the QR decomposition of the y-variables in the data matrix. In both cases, the variable means are subtracted before the QR decomposition is computed. If either set of variables is not of full rank, an SVD can be used instead of the QR decomposition. If the SVD of V is
V=Ux Δ UyT,
then the nonzero elements (δi>0) of the diagonal matrix Δ are the canonical correlations. The largest δi is called the first canonical correlation and associated with it is the first canonical variate. The eigenvalues, γi 2, of the matrix Σ are given by
γi 2=δi 21+δi 2.
The value of πi=γi 2/∑γi 2 gives the proportion of variation explained by the ith canonical variate. The values of the πi give an indication as to how many canonical variates are needed to adequately describe the data, i.e., the dimensionality of the problem; this can also be investigated by means of a test on the smaller values of the γi 2.
The relationship between the canonical variables and the original variables, the canonical variate loadings, can be computed from the Ux and Uy matrices.

Rotations

There are two principal reasons for using rotations: either
(a) | simplifying the structure to aid interpretation of derived variables, or
(b) | comparing two or more datasets or sets of derived variables.
The most common type of rotations used for (a) are orthogonal rotations. If Λ is the p by k loading matrix from a variable-directed multivariate method, then the rotations are selected such that the elements, λ ij*, of the rotated loading matrix, Λ*, are either relatively large or small. The rotations may be found by minimizing the criterion
V=∑j=1 k∑i=1 p λ ij*4-γp∑j=1 k∑i=1 p λ ij*2 2
where the constant, γ, gives a family of rotations, with γ=1 giving varimax rotations and γ=0 giving quartimax rotations.
Given an orthogonal rotation matrix X, a solution may be further simplified by removing the orthogonality restriction with an oblique ProMax rotation. Let Y denote the matrix defined by a power transformation of X, designed to increase high values in X and decrease low values. Then the ProMax solution is based on a least squares fit of X to Y.
For (b) Procrustes rotations are used. Let A and B be two l by m matrices, which can be considered as representing l points in m dimensions. One example is if A is the loading matrix from a variable-directed multivariate method and B is a hypothesised pattern matrix. In order to try to match the points in A and B there are three steps:
(i) | translate so that centroids of both matrices are at the origin,
(ii) | find a rotation that minimizes the sum of squared distances between corresponding points of the matrices,
(iii) | scale the matrices.
For a more detailed description, see Krzanowski (1990).

Individual-directed Methods

While dealing with the same n by p data matrix as variable-directed methods, the emphasis is the n objects or individuals rather than the p variables. The methods are generally based on an n by n distance or dissimilarity matrix such that the (k,j)th element gives a measure of how ‘far apart’ the individuals k and j are. Alternatively, a similarity matrix can be used which measures how ‘close’ individuals are. The form of the measure of distance or similarity will depend upon the form of the p variables. For continuous variables it is usually assumed that some form of Euclidean distance is suitable. That is, for x ki and x ji measured for individuals k and j on variable i respectively, the contribution to distance between individuals k and j from variable i is given by
x ki-x ji 2.
Often there will be a need to scale the variables to produce satisfactory distances. For discrete variables, there are various measures of similarity or distance that can easily be computed. For example, for binary data a measure of similarity could be
  • 1 – if the individuals take the same value,
  • 0 – otherwise.
Given a measure of distance between individuals, there are three basic tasks that can be performed.
(i) | Group the individuals; that is, collect the individuals into groups so that those within a group are closer to each other than they are to members of another group.
(ii) | Classify individuals; that is, if some individuals are known to come from certain groups, allocate individuals whose group membership is unknown, to the nearest group.
(iii) | Map the individuals; that is, produce a multidimensional diagram in which the distances on the diagram represent the distances between the individuals.
In the above, (i) leads to cluster analysis, (ii) leads to discriminant analysis and (iii) leads to scaling methods.

Hierarchical cluster analysis

Approaches for cluster analysis can be classified into two types: hierarchical and non-hierarchical. Hierarchical cluster analysis produces a series of overlapping groups or clusters ranging from separate individuals to one single cluster. For example, five individuals could be hierarchically clustered as follows.
Step 1 | 1 | 2 | 3 | 4 | 5
Step 2 | 1,2 |  | 3 | 4 | 5
Step 3 | 1,2 |  | 3,4 |  | 5
Step 4 | 1,2 |  | 3,4,5
Step 5 | 1,2,3,4,5
The clusters at a level are constructed from the clusters at a previous level. There are two basic approaches to hierarchical cluster analysis: agglomerative methods which build up clusters starting from individuals until there is only one cluster, or divisive methods which start with a single cluster and split clusters until the individual level is reached. This chapter contains the more common agglomerative methods.
The stages in a hierarchical cluster analysis are usually as follows.
(i) | form a distance matrix;
(ii) | use selected criterion to form hierarchy;
(iii) | print cluster information in the form of a dendrogram or use information to form a set of clusters.
These three stages will be considered in turn.
(i) Form a distance matrix
For the n by p data matrix X, a general measure of the distance between object j and object k, d jk, is
d jk=∑i=1 p D x ji/si,x ki/si α,
where x ji and x ki are the j,ith and k,ith elements of X, si is a standardization for the ith variable and D u,v is a suitable function. Three common distances for continuous variables are:
(a) | Euclidean distance: D u,v=u-v 2 and α=12.
(b) | Euclidean squared distance: D u,v=u-v 2 and α=1.
(c) | Absolute distance (city block metric): D u,v=u-v and α=1.
The common standardizations are the standard deviation and the range. For dichotomous variables there are a number of different measures (see Krzanowski (1990) and Everitt (1974)); these are usually easy to compute. If the individuals in a cluster analysis are themselves variables, then a suitable distance measure will be based on the correlation coefficient for continuous variables and contingency table statistics for discrete data.
(ii) Form Hierarchy
Given a distance matrix for the n individuals, an agglomerative clustering method produces a hierarchical tree by starting with n clusters, each with a single individual and then at each of n-1 stages, merging two clusters to form a larger cluster until all individuals are in a single cluster. At each stage, the two clusters that are nearest are merged to form a new cluster and a new distance matrix is computed for the reduced number of clusters.
Methods differ as to how the distances between the new cluster and other clusters are computed. For three clusters i, j and k, let ni, nj and nk be the number of objects in each cluster, and let d ij, d ik and d jk be the distances between the clusters. If clusters j and k, are to be merged to give cluster jk, then the distance from cluster i to cluster jk, d i.jk, can be computed in the following ways.
(a) | Single link or nearest neighbour: d i.jk=min d ij,d ik.
(b) | Complete link or furthest neighbour: d i.jk=max d ij,d ik.
(c) | Group average: d i.jk=nj nj+nk d ij+nk nj+nk d ik.
(d) | Centroid: d i.jk=nj nj+nk d ij+nk nj+nk d ik-njnk nj+nk 2 d jk.
(e) | Median: d i.jk=12 d ij+12 d ik-14 d jk.
(f) | Minimum variance: d i.jk=ni+nj d ij+ni+nk d ik-nid jk/ni+nj+nk.
For further details, see Everitt (1974) or Krzanowski (1990).
(iii) Produce Dendrogram and Clusters
Hierarchical cluster analysis can be represented by a tree that shows at which distance the clusters merge. Such a tree is known as a dendrogram; see Everitt (1974) and Krzanowski (1990).
A simple example is
Figure 1
The end points of the dendrogram represent the individuals that have been clustered.
Alternatively, the information from the tree can be used to produce either a chosen number of clusters or the clusters that exist at a given distance. The latter is equivalent to taking the dendrogram and drawing a line across at a given distance to produce clusters.

Non-hierarchical clustering

Non-hierarchical cluster analysis usually forms a given number of clusters from the data. There is no requirement that if first k-1 and then k clusters were requested then the k-1 clusters would be formed from the k clusters.
Most non-hierarchical methods of cluster analysis seek to partition the set of individuals into a number of clusters so as to optimize a criterion. The number of clusters is usually specified prior to the analysis. One commonly used criterion is the within-cluster sum of squares. Given n individuals with p variables measured on each individual, x ij, for i=1,2,…,n and j=1,2,…,p, the within-cluster sum of squares for K clusters is
SSc=∑k=1 K∑i∈Sk∑j=1 p x ij-x-kj 2,
where Sk is the set of objects in the kth cluster and x-kj is the mean for the variable j over cluster k. Starting with an initial allocation of individuals to clusters, the method then seeks to minimize SSc by a series of re-allocations. This is often known as K-means clustering.
In the K-means case individuals belong to a single cluster and are excluded from all remaining clusters. Alternatively, probabilities of cluster membership can be estimated and each cluster can have its own distributional properties. For example, given an initial set of probabilities, the Normal (Gaussian) mixture model uses the E–M method of Dempster et al. (1977) to maximize the sum of log-likelihoods over K clusters for a given covariance model ranging from pooled variance to individual covariance matrices.

Discriminant analysis

Discriminant analysis is concerned with the allocation of objects to ng groups on the basis of observations on those objects using an allocation rule. This rule is computed from observations coming from a training set in which group membership is known. The allocation rule is based on the distance between the object and an estimate of the location of the groups. If p variables are observed and the vector of means for the jth group in the training set are x-j then the usual measure of the distance of an observation, xk, from the jth group mean is given by Mahalanobis squared distance
D kj 2=xk-x-j T S*-1 xk-x-j,
where S* is either the within-group variance-covariance matrix, Sj, for the nj objects in the jth group, or a pooled variance-covariance matrix, S, computed from all n objects from all groups where
S=∑j=1 ng nj-1 Sj n-ng.
If the within-group variance-covariance matrices can be assumed to be equal then the pooled variance-covariance matrix can be used. This assumption can be tested using the test statistic
G=C n-ng log S-∑j=1 ng nj-1 log Sj,
where
C=1-2 p 2+3 p-16 p+1ng-1∑j=1 ng 1 nj-1-1 n-ng.
For large n, G is approximately distributed as a χ 2 variable with 12 p p+1ng-1 degrees of freedom; see Morrison (1967).
In addition to the distances, a set of prior probabilities of group membership, πj, for j=1,2,…,ng, may be used. The prior probabilities reflect your view as to the likelihood of the objects coming from the different groups.
It is generally assumed that the p variables follow a multivariate Normal distribution with, for the jth group, mean μj and variance-covariance matrix Σj. If p xk∣μj,Σj is the probability of observing the observation xk from group j, then the posterior probability of belonging to group j is
p j∣xk,μj,Σj∝p xk∣μj,Σj πj.
An observation is allocated to the group with the highest posterior probability.
In the estimative approach to discrimination, the parameters μj and Σj in p j∣xk,μj,Σj are replaced by their estimates calculated from the training set. If it is assumed that the within-group variance-covariance matrices are equal then the linear discriminant function is obtained; otherwise if it is assumed that the variance-covariance matrices are unequal then the quadratic discriminant function is obtained.
In the Bayesian predictive approach, a non-informative prior distribution is used for the parameters giving the posterior distribution for the parameters from the training set, Xt, of, p μj,Σj∣Xt. A predictive distribution is then obtained by integrating p j∣xk,μj,Σj p μj,Σj∣X over the parameter space. This predictive distribution, p xk∣Xt, then replaces p xk∣μj,Σj to give
p j∣xk,μj,Σj∝p xk∣Xt πj.
In addition to allocating the objects to groups, an atypicality index for each object and for each group can be computed. This represents the probability of obtaining an observation more typical of the group than that observed. A high value of the atypicality index for all groups indicates that the observation may in fact come from a group not represented in the training set.
Alternative approaches to discrimination are the use of canonical variates and logistic discrimination. Canonical variate analysis is described above and as it seeks to find the directions that best discriminate between groups these directions can also be used to allocate further observations. This can be viewed as an extension of Fisher's linear discriminant function. This approach does not assume that the data is Normally distributed, but Fisher's linear discriminant function may not perform well on non-Normal data. In the case of two groups, logistic regression can be performed with the response variable indicating the group allocation and the variables in the discriminant analysis being the explanatory variables. Allocation can then be made on the basis of the fitted response value. This is known as logistic discrimination and can be shown to be valid for a wide range of distributional assumptions.

Scaling methods

Scaling methods seek to represent the observed dissimilarities or distances between objects as distances between points in Euclidean space. For example if the distances between objects A, B and C were 3, 4 and 5, the distances could be represented exactly by three points in two-dimensional space. Only their relative positions would be important, the whole configuration of points could be rotated or shifted without effecting the distances between the points. If a one-dimensional representation was required, the ‘best’ representation might give distances of 2 13,3 13 and 5 23, which may be an adequate representation. If the distances were 3, 4 and 8 then these distances could not be exactly represented in Euclidean space, even in two dimensions, the best representation being the three points in a straight line giving distances 3, 4 and 7.
In practice, the use of scaling methods has to decide upon the number of dimensions in which the data is to be represented. The smaller the number the easier it will be to assimilate the information. The chosen number of dimensions needs to give an adequate representation of the data but will often not give an exact representation because either the number of chosen dimensions is too small or the data cannot be represented in Euclidean space.
Two basic methods are available depending on the nature of the dissimilarities or distances being analysed. If the distances can be assumed to satisfy the metric inequality
d ij≤d ik+d kj,
then the distances can be represented exactly by points in Euclidean space and the technique known as metric scaling, classical scaling or principal coordinate analysis can be used. This technique involves the computing of the eigenvalues of a matrix derived from the distance matrix. The eigenvectors corresponding to the k largest positive eigenvalues gives the best k dimensions in which to represent the objects. If there are negative eigenvalues then the distance matrix cannot be represented in Euclidean space.
Instead of the above approach of requiring the distances from the points to match the distances from the objects as closely as possible, sometimes only a rank order equivalence is required. That is, the ith largest distance between objects should, as far as possible, be represented by the ith largest distance between points. This would be appropriate when the dissimilarities are based on subjective rankings. For example, if the objects were foods then a number of judges rank the foods for different qualities such as taste and texture, the resulting distances would not necessarily obey the metric inequality, but the rank order would be significant. Alternatively, by relaxing the requirement from matching distances to rank order equivalence only, the number of dimensions required to represent the distance matrix may be decreased. The requirement of rank order equivalence leads to non-metric or ordinal multidimensional scaling. The criterion used to measure the closeness of the fitted distance matrix to the observed distance matrix is known as STRESS, which is given by
∑i=1 n∑j=1i-1 d ij^-d ij~2∑i=1 n∑j=1i-1 d ij 2^,
where d ij 2^ is the Euclidean squared distance between the computed points i and j, and d ij~ is the fitted distance obtained when d ij^ is monotonically regressed on the observed distances d ij; that is, d ij~ is monotonic relative to d ij and is obtained from d ij^ with the smallest number of changes. Thus STRESS is a measure of by how much the set of points preserve the order of the distances in the original distance matrix, and non-metric multidimensional scaling seeks to find the set of points that minimize the STRESS.

Recommendations on Choice and Use of Available Methods

See [] for a list of methods available in this Chapter.
Note also that g02gb will fit a logistic regression model and can be used for logistic discrimination.

References

Chatfield C and Collins A J (1980) Introduction to Multivariate Analysis Chapman and Hall
Dempster A P, Laird N M and Rubin D B (1977) Maximum likelihood from incomplete data via the EM algorithm (with discussion) J. Roy. Statist. Soc. Ser. B 39 1–38
Everitt B S (1974) Cluster Analysis Heinemann
Gnanadesikan R (1977) Methods for Statistical Data Analysis of Multivariate Observations Wiley
Hammarling S (1985) The singular value decomposition in multivariate statistics SIGNUM Newsl. 20(3) 2–25
Kendall M G and Stuart A (1976) The Advanced Theory of Statistics (Volume 3) (3rd Edition) Griffin
Krzanowski W J (1990) Principles of Multivariate Analysis Oxford University Press
Lawley D N and Maxwell A E (1971) Factor Analysis as a Statistical Method (2nd Edition) Butterworths
Morrison D F (1967) Multivariate Statistical Methods McGraw–Hill

Inheritance Hierarchy

System..::..Object
NagLibrary..::..G03

See Also

G03 Members


G03 Members

[image] [image]

NAG Library for .NET Release 2
G03 Members
G03 Class Methods See Also Send Feedback

The G03 type exposes the following members.

Methods

Name | Description
g03aa | g03aa performs a principal component analysis on a data matrix; both the principal component loadings and the principal component scores are returned.

See Also

G03 Class


G03 Methods

[image] [image]

NAG Library for .NET Release 2
G03 Methods
G03 Class See Also Send Feedback

The G03 type exposes the following members.

Methods

Name | Description
g03aa | g03aa performs a principal component analysis on a data matrix; both the principal component loadings and the principal component scores are returned.

See Also

G03 Class


g03aa Method

[image]

NAG Library for .NET Release 2
G03..::g03aa Method
G03 Class See Also Send Feedback
g03aa performs a principal component analysis on a data matrix; both the principal component loadings and the principal component scores are returned.

Syntax

C#
public static void g03aa(
    string matrix,
    string std,
    string weight,
    int n,
    int m,
    double[,] x,
    int[] isx,
    double[] s,
    double[] wt,
    int nvar,
    double[,] e,
    double[,] p,
    double[,] v,
    out int ifail
)
Visual Basic
Public Shared Sub g03aa ( _
    matrix As String, _
    std As String, _
    weight As String, _
    n As Integer, _
    m As Integer, _
    x As Double(,), _
    isx As Integer(), _
    s As Double(), _
    wt As Double(), _
    nvar As Integer, _
    e As Double(,), _
    p As Double(,), _
    v As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g03aa(
    String^ matrix,
    String^ std,
    String^ weight,
    int n,
    int m,
    array<double,2>^ x,
    array<int>^ isx,
    array<double>^ s,
    array<double>^ wt,
    int nvar,
    array<double,2>^ e,
    array<double,2>^ p,
    array<double,2>^ v,
    [OutAttribute] int% ifail
)
F#
static member g03aa :
        matrix : string *
        std : string *
        weight : string *
        n : int *
        m : int *
        x : float[,] *
        isx : int[] *
        s : float[] *
        wt : float[] *
        nvar : int *
        e : float[,] *
        p : float[,] *
        v : float[,] *
        ifail : int byref -> unit

Parameters

matrix
Type: System..::..String
On entry: indicates for which type of matrix the principal component analysis is to be carried out.
matrix="C"
It is for the correlation matrix.
matrix="S"
It is for a standardized matrix, with standardizations given by s.
matrix="U"
It is for the sums of squares and cross-products matrix.
matrix="V"
It is for the variance-covariance matrix.
Constraint: matrix="C", "S", "U" or "V".
std
Type: System..::..String
On entry: indicates if the principal component scores are to be standardized.
std="S"
The principal component scores are standardized so that F′F=I, i.e., F=Xs P Λ-1=V.
std="U"
The principal component scores are unstandardized, i.e., F=Xs P=VΛ.
std="Z"
The principal component scores are standardized so that they have unit variance.
std="E"
The principal component scores are standardized so that they have variance equal to the corresponding eigenvalue.
Constraint: std="E", "S", "U" or "Z".
weight
Type: System..::..String
On entry: indicates if weights are to be used.
weight="U"
No weights are used.
weight="W"
Weights are used and must be supplied in wt.
Constraint: weight="U" or "W".
n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n≥2.
m
Type: System..::..Int32
On entry: m, the number of variables in the data matrix.
Constraint: m≥1.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥n
On entry: x[i-1,j-1] must contain the ith observation for the jth variable, for i=1,2,…,n and j=1,2,…,m.
isx
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On entry: isx[j-1] indicates whether or not the jth variable is to be included in the analysis.
If isx[j-1]>0, the variable contained in the jth column of x is included in the principal component analysis, for j=1,2,…,m.
Constraint: isx[j-1]>0 for nvar values of j.
s
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: the standardizations to be used, if any.
If matrix="S", the first m elements of s must contain the standardization coefficients, the diagonal elements of σ.
Constraint: if isx[j-1]>0, s[j]>0.0, for j=0,1,…,m-1.
On exit: if matrix="S", s is unchanged on exit.
If matrix="C", s contains the variances of the selected variables. s[j-1] contains the variance of the variable in the jth column of x if isx[j-1]>0.
If matrix="U" or "V", s is not referenced.
wt
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array wt must be at least n if weight="W", and at least 1 otherwise.
On entry: if weight="W", the first n elements of wt must contain the weights to be used in the principal component analysis.
If wt[i-1]=0.0, the ith observation is not included in the analysis. The effective number of observations is the sum of the weights.
If weight="U", wt is not referenced and the effective number of observations is n.
Constraints:
  • wt[i-1]≥0.0, for i=1,2,…,n;
  • the sum of weights ≥nvar+1.
nvar
Type: System..::..Int32
On entry: p, the number of variables in the principal component analysis.
Constraint: 1≤nvar≤min n-1,m.
e
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, 6]
Note: dim1 must satisfy the constraint: dim1≥nvar
On exit: the statistics of the principal component analysis.
e[i-1,0]
The eigenvalues associated with the ith principal component, λi 2, for i=1,2,…,p.
e[i-1,1]
The proportion of variation explained by the ith principal component, for i=1,2,…,p.
e[i-1,2]
The cumulative proportion of variation explained by the first ith principal components, for i=1,2,…,p.
e[i-1,3]
The χ 2 statistics, for i=1,2,…,p.
e[i-1,4]
The degrees of freedom for the χ 2 statistics, for i=1,2,…,p.
If matrix≠"C", e[i-1,5] contains significance level for the χ 2 statistic, for i=1,2,…,p.
If matrix="C", e[i-1,5] is returned as zero.
p
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nvar]
Note: dim1 must satisfy the constraint: dim1≥nvar
On exit: the first nvar columns of p contain the principal component loadings, ai. The jth column of p contains the nvar coefficients for the jth principal component.
v
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nvar]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: the first nvar columns of v contain the principal component scores. The jth column of v contains the n scores for the jth principal component.
If weight="W", any rows for which wt[i-1] is zero will be set to zero.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Let X be an n by p data matrix of n observations on p variables x 1,x 2,…,xp and let the p by p variance-covariance matrix of x 1,x 2,…,xp be S. A vector a 1 of length p is found such that:
a 1 T S a 1  is maximized subject to  a 1 T a 1=1.
The variable z 1=∑i=1 p a 1 ixi is known as the first principal component and gives the linear combination of the variables that gives the maximum variation. A second principal component, z 2=∑i=1 p a 2 ixi, is found such that:
a 2 T S a 2  is maximized subject to ​a 2 T a 2=1 and ​a 2 T a 1=0.
This gives the linear combination of variables that is orthogonal to the first principal component that gives the maximum variation. Further principal components are derived in a similar way.
The vectors a 1,a 2,…,ap, are the eigenvectors of the matrix S and associated with each eigenvector is the eigenvalue, λi 2. The value of λi 2/∑λi 2 gives the proportion of variation explained by the ith principal component. Alternatively, the ai's can be considered as the right singular vectors in a singular value decomposition with singular values λi of the data matrix centred about its mean and scaled by 1/n-1, Xs. This latter approach is used in g03aa, with
Xs=VΛ P′
where Λ is a diagonal matrix with elements λi, P is the p by p matrix with columns ai and V is an n by p matrix with V′V=I, which gives the principal component scores.
Principal component analysis is often used to reduce the dimension of a dataset, replacing a large number of correlated variables with a smaller number of orthogonal variables that still contain most of the information in the original dataset.
The choice of the number of dimensions required is usually based on the amount of variation accounted for by the leading principal components. If k principal components are selected, then a test of the equality of the remaining p-k eigenvalues is
n-2 p+5/6-∑i=k+1 p log λi 2+p-k log∑i=k+1 p λi 2/p-k
which has, asymptotically, a χ 2-distribution with 12 p-k-1p-k+2 degrees of freedom.
Equality of the remaining eigenvalues indicates that if any more principal components are to be considered then they all should be considered.
Instead of the variance-covariance matrix the correlation matrix, the sums of squares and cross-products matrix or a standardized sums of squares and cross-products matrix may be used. In the last case S is replaced by σ-12 S σ-12 for a diagonal matrix σ with positive elements. If the correlation matrix is used, the χ 2 approximation for the statistic given above is not valid.
The principal component scores, F, are the values of the principal component variables for the observations. These can be standardized so that the variance of these scores for each principal component is 1.0 or equal to the corresponding eigenvalue.
Weights can be used with the analysis, in which case the matrix X is first centred about the weighted means then each row is scaled by an amount wi, where wi is the weight for the ith observation.

References

Chatfield C and Collins A J (1980) Introduction to Multivariate Analysis Chapman and Hall
Cooley W C and Lohnes P R (1971) Multivariate Data Analysis Wiley
Hammarling S (1985) The singular value decomposition in multivariate statistics SIGNUM Newsl. 20(3) 2–25
Kendall M G and Stuart A (1969) The Advanced Theory of Statistics (Volume 1) (3rd Edition) Griffin
Morrison D F (1967) Multivariate Statistical Methods McGraw–Hill

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDE, LDP, LDV) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | m<1,
or | n<2,
or | nvar<1,
or | nvar>m,
or | nvar≥n,
or | matrix≠"C", "S", "U" or "V",
or | std≠"S", "U", "Z" or "E",
or | weight≠"U" or "W".
ifail=2
On entry, weight="W" and a value of wt<0.0.
ifail=3
On entry, | there are not nvar values of isx>0,
or | weight="W" and the effective number of observations is less than nvar+1.
ifail=4
On entry, s[j-1]≤0.0 for some j=1,2,…,m, when matrix="S" and isx[j-1]>0.
ifail=5
The singular value decomposition has failed to converge. This is an unlikely error exit.
ifail=6
All eigenvalues/singular values are zero. This will be caused by all the variables being constant.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

As g03aa uses a singular value decomposition of the data matrix, it will be less affected by ill-conditioned problems than traditional methods using the eigenvalue decomposition of the variance-covariance matrix.

Parallelism and Performance

None.

Further Comments

None.

Example

A dataset is taken from Cooley and Lohnes (1971), it consists of ten observations on three variables. The unweighted principal components based on the variance-covariance matrix are computed and the principal component scores requested. The principal component scores are standardized so that they have variance equal to the corresponding eigenvalue.

Example program (C#): g03aae.cs

Example program data: g03aae.d

Example program results: g03aae.r

See Also

G03 Class
G03 Members


G05 Class

[image]

NAG Library for .NET Release 2
G05 Class
Members See Also Send Feedback
This chapter is concerned with the generation of sequences of independent pseudorandom and quasi-random numbers from various distributions, and models.

Syntax

C#
public static class G05
Visual Basic
Public NotInheritable Class G05
Visual C++
public ref class G05 abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type G05 =  class end

Background to the Problems

Pseudorandom Numbers

A sequence of pseudorandom numbers is a sequence of numbers generated in some systematic way such that they are independent and statistically indistinguishable from a truly random sequence. A pseudorandom number generator (PRNG) is a mathematical algorithm that, given an initial state, produces a sequence of pseudorandom numbers. A PRNG has several advantages over a true random number generator in that the generated sequence is repeatable, has known mathematical properties and can be implemented without needing any specialist hardware. Many books on statistics and computer science have good introductions to PRNGs, for example Knuth (1981) or Banks (1998).
PRNGs can be split into base generators, and distributional generators. Within the context of this document a base generator is defined as a PRNG that produces a sequence (or stream) of variates (or values) uniformly distributed over the interval 0,1. Depending on the algorithm being considered, this interval may be open, closed or half-closed. A distribution generator is a method that takes variates generated from a base generator and transforms them into variates from a specified distribution, for example a uniform, Gaussian (Normal) or gamma distribution.
The period (or cycle length) of a base generator is defined as the maximum number of values that can be generated before the sequence starts to repeat. The initial state of the base generator is often called the seed.
There are six base generators currently available in the NAG Library, these are; a basic linear congruential generator (LCG) (referred to as the NAG basic generator) (see Knuth (1981)), two sets of Wichmann–Hill generators (see Maclaren (1989) and Wichmann and Hill (2006)), the Mersenne Twister (see Matsumoto and Nishimura (1998)), the ACORN generator (see Wikramaratna (1989)) and L'Ecuyer generator (see L'Ecuyer and Simard (2002)).

NAG Basic Generator

The NAG basic generator is a linear congruential generator (LCG) and, like all linear congruential generators, has the form:
xi=a 1x i-1 mod m 1,ui=xim 1,
where the ui, for i=1,2,…, form the required sequence.
The NAG basic generator uses a 1=1313 and m 1=259, which gives a period of approximately 257.
This generator has been part of the NAG Library since Mark 6 and as such has been widely used. It suffers from no known problems, other than those due to the lattice structure inherent in all linear congruential generators, and, even though the period is relatively short compared to many of the newer generators, it is sufficiently large for many practical problems.
The performance of the NAG basic generator has been analysed by the Spectral Test, see Section 3.3.4 of Knuth (1981), yielding the following results in the notation of Knuth (1981).
n | νn | Upper bound for νn
2 | 3.44×108 | 4.08×108
3 | 4.29×105 | 5.88×105
4 | 1.72×104 | 2.32×104
5 | 1.92×103 | 3.33×103
6 | 593 | 939
7 | 198 | 380
8 | 108 | 197
9 | 67 | 120
The right-hand column gives an upper bound for the values of νn attainable by any multiplicative congruential generator working modulo 259.
An informal interpretation of the quantities νn is that consecutive n-tuples are statistically uncorrelated to an accuracy of 1/νn. This is a theoretical result; in practice the degree of randomness is usually much greater than the above figures might support. More details are given in Knuth (1981), and in the references cited therein.
Note that the achievable accuracy drops rapidly as the number of dimensions increases. This is a property of all multiplicative congruential generators and is the reason why very long periods are needed even for samples of only a few random numbers.

Wichmann–Hill I Generator

This series of Wichmann–Hill base generators (see Maclaren (1989)) use a combination of four linear congruential generators and has the form:
wi=a 1w i-1 mod m 1xi=a 2x i-1 mod m 2yi=a 3y i-1 mod m 3zi=a 4z i-1 mod m 4ui=wim 1+xim 2+yim 3+zim 4 mod 1, (1)
where the ui, for i=1,2,…, form the required sequence. The NAG Library implementation includes 273 sets of parameters, aj,mj, for j=1,2,3,4, to choose from.
The constants ai are in the range 112 to 127 and the constants mj are prime numbers in the range 16718909 to 16776971, which are close to 224=16777216. These constants have been chosen so that each of the resulting 273 generators are essentially independent, all calculations can be carried out in 32-bit integer arithmetic and the generators give good results with the spectral test, see Knuth (1981) and Maclaren (1989). The period of each of these generators would be at least 292 if it were not for common factors between m 1-1, m 2-1, m 3-1 and m 4-1. However, each generator should still have a period of at least 280. Further discussion of the properties of these generators is given in Maclaren (1989).

Wichmann–Hill II Generator

This Wichmann–Hill base generator (see Wichmann and Hill (2006)) is of the same form as that described in [Wichmann–Hill I Generator], i.e., a combination of four linear congruential generators. In this case a 1=11600, m 1=2147483579, a 2=47003, m 2=2147483543, a 3=23000, m 3=2147483423, a 4=33000, m 4=2147483123.
Unlike in the original Wichmann–Hill generator, these values are too large to carry out the calculations detailed in (1) using 32-bit integer arithmetic, however, if
wi=11600 w i-1 mod 2147483579
then setting
Wi=11600 w i-1 mod 185127-10379 w i-1/185127
gives
wi=Wi​ if ​Wi≥02147483579+Wi​ otherwise
and Wi can be calculated in 32-bit integer arithmetic. Similar expressions exist for xi, yi and zi. The period of this generator is approximately 2121.
Further details of implementing this algorithm and its properties are given in Wichmann and Hill (2006). This paper also gives some useful guidelines on testing PRNGs.

Mersenne Twister Generator

The Mersenne Twister (see Matsumoto and Nishimura (1998)) is a twisted generalized feedback shift register generator. The algorithm underlying the Mersenne Twister is as follows:
(i) Set some arbitrary initial values x 1,x 2,…,xr, each consisting of w bits.
(ii) Letting
A=0I w-1awa w-1⋯a 1,
where I w-1 is the w-1×w-1 identity matrix and each of the ai,i=1 to w take a value of either 0 or 1 (i.e., they can be represented as bits). Define
x i+r=x i+s⊕xi ω:l+1|x i+1l:1 A,
where xi ω:l+1|x i+1l:1 indicates the concatenation of the most significant (upper) w-l bits of xi and the least significant (lower) l bits of x i+1.
(iii) Perform the following operations sequentially:
z=x i+r⊕x i+r≫t 1z=z⊕z≪t 2​ AND ​m 1z=z⊕z≪t 3​ AND ​m 2z=z⊕z≫t 4u i+r=z/2 w-1,
where t 1, t 2, t 3 and t 4 are integers and m 1 and m 2 are bit-masks and ‘≫t’ and ‘≪t’ represent a t bit shift right and left respectively, ⊕ is bit-wise exclusively or (xor) operation and ‘AND’ is a bit-wise and operation.
The u i+r, for i=1,2,…, form the required sequence. The supplied implementation of the Mersenne Twister uses the following values for the algorithmic constants:
w=32a=0x9908b0 dfl=31r=624s=397t 1=11t 2=7t 3=15t 4=18m 1=0x9d2c5680m 2=0xefc60000
where the notation 0xDD … indicates the bit pattern of the integer whose hexadecimal representation is DD ….
This algorithm has a period length of approximately 219,937-1 and has been shown to be uniformly distributed in 623 dimensions (see Matsumoto and Nishimura (1998)).

ACORN Generator

The ACORN generator is a special case of a multiple recursive generator (see Wikramaratna (1989) and Wikramaratna (2007)). The algorithm underlying ACORN is as follows:
(i) | Choose an integer value k≥1.
(ii) | Choose an integer value M, and an integer seed Y 0 0, such that 0<Y 0 0<M and Y 0 0 and M are relatively prime.
(iii) | Choose an arbitrary set of k initial integer values, Y 0 1,Y 0 2,…,Y 0 k, such that 0≤Y 0 m<M, for all m=1,2,…,k.
(iv) Perform the following sequentially:
Yi m=Yi m-1+Y i-1 m mod M
for m=1,2,…,k.
(v) | Set ui=Yi k/M.
The ui, for i=1,2,…, then form a pseudorandom sequence, with ui∈0,1, for all i.
Although you can choose any value for k, M, Y 0 0 and the Y 0 m, within the constraints mentioned in (i) to (iii) above, it is recommended that k≥10, M is chosen to be a large power of two with M≥260 and Y 0 0 is chosen to be odd.
The period of the ACORN generator, with the modulus M equal to a power of two, and an odd value for Y 0 0 has been shown to be an integer multiple of M (see Wikramaratna (1992)). Therefore, increasing M will give a series with a longer period.

L'Ecuyer MRG32k3a Combined Recursive Generator

The base generator L'Ecuyer MRG32k3a (see L'Ecuyer and Simard (2002)) combines two multiple recursive generators:
xi=a 11x i-1+a 12x i-2+a 13x i-3 mod m 1yi=a 21y i-1+a 22y i-2+a 23y i-3 mod m 2zi=xi-yi mod m 1ui=zi+1/d
where a 11=0, a 12=1403580, a 13=-810728, m 1=232-209, a 21=527612, a 22=0, a 23=-1370589, m 2=232-22853, and ui,i=1,2,… form the required sequence. If d=m 1 then ui∈0,1 else if d=m 1+1 then ui∈0,1. Combining the two multiple recursive generators (MRG) results in sequences with better statistical properties in high dimensions and longer periods compared with those generated from a single MRG. The combined generator described above has a period length of approximately 2191.

Quasi-random Numbers

Low discrepancy (quasi-random) sequences are used in numerical integration, simulation and optimization. Like pseudorandom numbers they are uniformly distributed but they are not statistically independent, rather they are designed to give more even distribution in multidimensional space (uniformity). Therefore they are often more efficient than pseudorandom numbers in multidimensional Monte–Carlo methods.
The quasi-random number generators implemented in this chapter generate a set of points x 1,x 2,…,xN with high uniformity in the S-dimensional unit cube IS=0,1 S. One measure of the uniformity is the discrepancy which is defined as follows:
  • Given a set of points x 1,x 2,…,xN∈IS and a subset G⊂IS, define the counting function SN G as the number of points xi∈G. For each x=x 1,x 2,…,xS∈IS, let Gx be the rectangular S-dimensional region
    Gx=0,x 1×0,x 2×⋯×0,xS
    with volume x 1,x 2,…,xS. Then the discrepancy of the points x 1,x 2,…,xN is
    DN*x 1,x 2,…,xN=sup x∈IS SN Gx-N∑ k=1 S xk.
    The discrepancy of the first N terms of such a sequence has the form
    DN*x 1,x 2,…,xN≤CS log N S+O log N S-1  for all  N≥2.
    The principal aim in the construction of low-discrepancy sequences is to find sequences of points in IS with a bound of this form where the constant CS is as small as possible.
Three types of low-discrepancy sequences are supplied in this library, these are due to Sobol, Faure and Niederreiter. Two sets of Sobol sequences are supplied, the first is based on work of Joe and Kuo (2008) and the second on the work of Bratley and Fox (1988). More information on quasi-random number generation and the Sobol, Faure and Niederreiter sequences in particular can be found in Bratley and Fox (1988) and Fox (1986).
The efficiency of a simulation exercise may often be increased by the use of variance reduction methods (see Morgan (1984)). It is also worth considering whether a simulation is the best approach to solving the problem. For example, low-dimensional integrals are usually more efficiently calculated by methods in D01 class rather than by Monte–Carlo integration.

Scrambled Quasi-random Numbers

Scrambled quasi-random sequences are an extension of standard quasi-random sequences that attempt to eliminate the bias inherent in a quasi-random sequence whilst retaining the low-discrepancy properties. The use of a scrambled sequence allows error estimation of Monte–Carlo results by performing a number of iterates and computing the variance of the results.
This implementation of scrambled quasi-random sequences is based on TOMS algorithm 823 and details can be found in the accompanying paper, Hong and Hickernell (2003). Three methods of scrambling are supplied; the first a restricted form of Owen's scrambling (Owen (1995)), the second based on the method of Faure and Tezuka (2000) and the last method combines the first two.
Scrambled versions of both Sobol sequences and the Niederreiter sequence can be obtained.

Non-uniform Random Numbers

Random numbers from other distributions may be obtained from the uniform random numbers by the use of transformations and rejection techniques, and for discrete distributions, by table based methods.
(a) | Transformation Methods For a continuous random variable, if the cumulative distribution function (CDF) is F x then for a uniform 0,1 random variate u, y=F-1 u will have CDF F x. This method is only efficient in a few simple cases such as the exponential distribution with mean μ, in which case F-1 u=-μ log u. Other transformations are based on the joint distribution of several random variables. In the bivariate case, if v and w are random variates there may be a function g such that y=g v,w has the required distribution; for example, the Student's t-distribution with n degrees of freedom in which v has a Normal distribution, w has a gamma distribution and g v,w=v⁢n/w.
(b) | Rejection Methods Rejection techniques are based on the ability to easily generate random numbers from a distribution (called the envelope) similar to the distribution required. The value from the envelope distribution is then accepted as a random number from the required distribution with a certain probability; otherwise, it is rejected and a new number is generated from the envelope distribution.
(c) | Table Search Methods For discrete distributions, if the cumulative probabilities, Pi=Prob x≤i, are stored in a table then, given u from a uniform 0,1 distribution, the table is searched for i such that P i-1<u≤Pi. The returned value i will have the required distribution. The table searching can be made faster by means of an index, see Ripley (1987). The effort required to set up the table and its index may be considerable, but the methods are very efficient when many values are needed from the same distribution.

Copulas

A copula is a function that links the univariate marginal distributions with their multivariate distribution. Sklar's theorem (see Sklar (1973)) states that if f is an m-dimensional distribution function with continuous margins f 1,f 2,…,fm, then f has a unique copula representation, c, such that
f x 1,x 2,…,xm=c f 1 x 1,f 2 x 2,…,fm xm
The copula, c, is a multivariate uniform distribution whose dependence structure is defined by the dependence structure of the multivariate distribution f, with
c u 1,u 2,…,um=f f 1-1 u 1,f 2-1 u 2,…,fm-1 um
where ui∈0,1. This relationship can be used to simulate variates from distributions defined by the dependence structure of one distribution and each of the marginal distributions given by another. For additional information see Nelsen (1998) or Boye (Unpublished manuscript) and the references therein.

Brownian Bridge

Brownian Bridge Process

Fix two times t 0<T and let W=Wt 0≤t≤T-t 0 be a standard d-dimensional Wiener process on the interval 0,T-t 0. Recall that the terms Wiener process and Brownian motion are often used interchangeably.
A standard d-dimensional Brownian bridge B=Bt t 0≤t≤T on t 0,T is defined (see Revuz and Yor (1999)) as
Bt=W t-t 0-t-t 0T-t 0 W T-t 0.
The process is continuous, starts at zero at time t 0 and ends at zero at time T. It is Gaussian, has zero mean and has a covariance structure given by
𝔼 Bs BtT=s-t 0T-tT-t 0 Id
for any s≤t in t 0,T where Id is the d-dimensional identity matrix. The Brownian bridge is often called a non-free or ‘pinned’ Wiener process since it is forced to be 0 at time T, but is otherwise very similar to a standard Wiener process.
We can generalize this construction as follows. Fix points x,w∈ℝd, let Σ be a d×d covariance matrix and choose any d×d matrix C such that C CT=Σ. The generalized d-dimensional Brownian bridge X=Xt t 0≤t≤T is defined by setting
Xt=t-t 0 w+T-t xT-t 0+C Bt=t-t 0 w+T-t xT-t 0+C W t-t 0-t-t 0T-t 0 C W T-t 0
for all t∈t 0,T. The process X is continuous, starts at x at time t 0 and ends at w at time T. It has mean t-t 0 w+T-t x/T-t 0 and covariance structure
𝔼 Xs-𝔼 Xs Xt-𝔼 Xt T=𝔼 C Bs BtT CT=s-t 0T-tT-t 0 Σ
for all s≤t in t 0,T. This is a non-free Wiener process since it is forced to be equal to w at time T. However if we set w=x+C W T-t 0, then X simplifies to
Xt=x+C W t-t 0
for all t∈t 0,T which is nothing other than a d-dimensional Wiener process with covariance given by Σ.
Two sample paths for a two-dimensional free Wiener process
Figure 1: Two sample paths for a two-dimensional free Wiener process
Two sample paths for a two-dimensional free Wiener process
Figure 2: Two sample paths for a two-dimensional free Wiener process
Figure 1 shows two sample paths for a two-dimensional free Wiener process X=Xt 1,Xt 20≤t≤2. The correlation coefficient between the one-dimensional processes X 1 and X 2 at any time is ρ=0.80. Note that the red and green paths in each figure are uncorrelated, however it is fairly evident that the two red paths are correlated, and that the two green paths are correlated (when one path increases so does the other, and vice versa).
Two sample paths for a two-dimensional non-free Wiener process. The process starts at 0,0 and ends at 1,-1
Figure 3: Two sample paths for a two-dimensional non-free Wiener process. The process starts at 0,0 and ends at 1,-1
Two sample paths for a two-dimensional non-free Wiener process. The process starts at 0,0 and ends at 1,-1
Figure 4: Two sample paths for a two-dimensional non-free Wiener process. The process starts at 0,0 and ends at 1,-1
Figure 2 shows two sample paths for a two-dimensional non-free Wiener process. The process starts at 0,0 and ends at 1,-1. The correlation coefficient between the one-dimensional processes is again ρ=0.80. The red and green paths in each figure are uncorrelated, while the two red paths tend to increase and decrease together, as do the two green paths. Both Figure 1 and Figure 2 were constructed using (G05XBF not in this release).

Brownian Bridge Algorithm

The ideas above can also be used to construct sample paths of a free or non-free Wiener process (recall that a non-free Wiener process is the Brownian bridge process outlined above). Fix two times t 0<T and let ti 1≤i≤N be any set of time points satisfying t 0<t 1<t 2<⋯<tN<T. Let X ti 1≤i≤N denote a d-dimensional (free or non-free) Wiener sample path at these times. These values can be generated by the so-called Brownian bridge algorithm (see Glasserman (2004)) which works as follows. From any two known points X ti at time t i and X tk at time tk with ti<tk, a new point X tj can be interpolated at any time tj∈ti,tk by setting
X tj=X ti tk-tj+X tk tj-titk-ti+CZ tk-tjtj-titk-ti (2)
where Z is a d-dimensional standard Normal random variable and C is any d×d matrix such that C CT is the desired covariance structure for the (free or non-free) Wiener process X. Clearly this algorithm is iterative in nature. All that is needed to complete the specification is to fix the start point X t 0 and end point XT, and to specify how successive interpolation times tj are chosen. For X to behave like a usual (free) Wiener process we should set X t 0 equal to some value x∈ℝd and then set XT=x+C T-t 0 Z where Z is any d-dimensional standard Normal random variable. However when it comes to deciding how the successive interpolation times tj should be chosen, there is virtually no restriction. Any method of choosing which tj∈ti,tk to interpolate next is equally valid, provided ti is the nearest known point to the left of tj and tk is the nearest known point to the right of tj. In other words, the interpolation interval ti,tk must not contain any other known points, otherwise the covariance structure of the process will be incorrect.
The order in which the successive interpolation times tj are chosen is called the bridge construction order. Since all construction orders will produce a correct process, the question arises whether one construction order should be preferred over another. When the Z values are drawn from a pseudorandom generator, the answer is typically no. However the bridge algorithm is frequently used with quasi-random numbers, and in this case the bridge construction order can be important.

Bridge Construction Order and Quasi-random Sequences

Consider the one-dimensional case of a free Wiener process where d=C=1. The Brownian bridge is frequently combined with low-discrepancy (quasi-random) sequences to perform quasi-Monte–Carlo integration. Quasi-random points Z 1,Z 2,Z 3,… are generated from the standard Normal distribution, where each quasi-random point Zi=Z 1 i,Z 2 i,⋯,ZDi consists of D one-dimensional values. The process X starts at X t 0=x which is known. There remain N+1 time points at which the bridge is to be computed, namely X ti 1≤i≤N and XT (recall we are considering a free Wiener process). In this case D is set equal to N+1, so that N+1 dimensional quasi-random points are generated. A single quasi-random point is used to construct one Wiener sample path.
The question is how to use the dimension values of each N+1 dimensional quasi-random point. Often the ‘lower’ dimension values (Z 1 i,Z 2 i, etc.) display better uniformity properties than the ‘higher’ dimension values (Z N+1 i,ZNi, etc.) so that the ‘lower’ dimension values should be used to construct the most important sections of the sample path. For example, consider a model which is particularly sensitive to the behaviour of the underlying process at time 3. When constructing the sample paths, one would therefore ensure that time 3 was one of the interpolation points of the bridge, and that a ‘lower’ dimension value was used in (2) to construct the corresponding bridge point X 3. Indeed, one would most likely also ensure that time X 3 was one of the first bridge points that was constructed: ‘lower’ dimension values would be used to construct both the left and right bridge points used in (2) to interpolate X 3, so that the distribution of X 3 benefits as much as possible from the uniformity properties of the quasi-random sequence. For further discussions in this regard we refer to Glasserman (2004). These remarks extend readily to the case of a non-free Wiener process.

Brownian Bridge and Stochastic Differential Equations

The Brownian bridge algorithm, especially when combined with quasi-random variates, is frequently used to obtain numerical solutions to stochastic differential equations (SDEs) driven by (free or non-free) Wiener processes. The quasi-random variates produce a family of Wiener sample paths which cover the space of all Wiener sample paths fairly evenly. This is analogous to the way in which a two-dimensional quasi-random sequence covers the unit square 0,1 2 evenly. When solving SDEs one is typically interested in the increments of the driving Wiener process between two time points, rather than the value of the process at a particular time point. [Brownian Bridge] contains details on which methods can be used to obtain such Wiener increments.

Random Fields

A random field is a stochastic process, taking values in a Euclidean space, and defined over a parameter space of dimensionality at least one. They are often used to simulate some physical space-dependent parameter, such as the permeability of rock, which cannot be measured at every point in the space. The simulated values can then be used to model other dependent quantities, for example, underground flow of water, often through the use of partial differential equations (PDEs).
A d-dimensional random field Z x is a function which is random at every point x∈D for some domain D⊂ℝd, so Z x is a random variable for each x. The random field has a mean function μ x=𝔼 Z x and a symmetric positive semidefinite covariance function C x,y=𝔼 Z x-μ xZ y-μ y.
A random field, Z x, is a Gaussian random field if, for any choice of n∈ℕ and x 1,…,xn∈ℝd, the random vector Z x 1,…,Z xn T follows a multivariate Gaussian distribution.
A Gaussian random field Z x is stationary if μ x is constant for all x∈ℝ and C x,y=C x+a,y+a for all x,y,a∈ℝd and hence we can express the covariance function C x,y as a function γ of one variable: C x,y=γ x-y. γ is known as a variogram (or more correctly, a semivariogram) and includes the multiplicative factor σ 2 representing the variance such that γ 0=σ 2. There are a number of commonly used variograms, including:
1.Symmetric stable variogram
γ x=σ 2 exp-x′ν.
2.Cauchy variogram
γ x=σ 21+x′2-ν.
3.Differential variogram with compact support
γ x=σ 2 1+8 x′+25 x′2+32 x′3 1-x′8,x′<1,0,x′≥1.
4.Exponential variogram
γ x=σ 2 exp-x′.
5.Gaussian variogram
γ x=σ 2 exp-x′2.
6.Nugget variogram
γ x=σ 2,x=0,0,x≠0.
7.Spherical variogram
γ x=σ 2 1-1.5 x′+0.5 x′3,x′<1,0,x′≥1.
8.Bessel variogram
γ x=σ 2 2 ν Γ ν+1 Jν x′x′ν,
9.Hole effect variogram
γ x=σ 2 sin x′x′.
10.Whittle–Matérn variogram
γ x=σ 2 2 1-νx′ν Kν x′Γ ν.
11.Continuously parameterised variogram with compact support
γ x=σ 2 2 1-νx′ν Kν x′Γ ν 1+8 x′′+25 x′′2+32 x′′3 1-x′′8,x′′<1,0,x′′≥1.
12.Generalized hyperbolic distribution variogram
γ x=σ 2 δ 2+x′2 λ 2 δλ Kλ κδ Kλ κ δ 2+x′2 12.
13.Cosine variogram
γ x=σ 2 cos x′,
where x′ is a scaled norm of x.

Other Random Structures

In addition to random numbers from various distributions, random compound structures can be generated. These include random time series, random matrices and random samples.

Multiple Streams of Pseudorandom Numbers

It is often advantageous to be able to generate variates from multiple, independent, streams (or sequences) of random variates. For example when running a simulation in parallel on several processors. There are four ways of generating multiple streams using the methods available in this chapter:
(i) | using different initial values (seeds);
(ii) | using different generators;
(iii) | skip ahead (also called block-splitting);
(iv) | leap-frogging.

Multiple Streams via Different Initial Values (Seeds)

A different sequence of variates can be generated from the same base generator by initializing the generator using a different set of seeds. The statistical properties of the base generators are only guaranteed within, not between sequences. For example, two sequences generated from two different starting points may overlap if these initial values are not far enough apart. The potential for overlapping sequences is reduced if the period of the generator being used is large. In general, of the four methods for creating multiple streams described here, this is the least satisfactory.
The one exception to this is the Wichmann–Hill II generator. The Wichmann and Hill (2006) paper describes a method of generating blocks of variates, with lengths up to 290, by fixing the first three seed values of the generator (w 0, x 0 and y 0), and setting z 0 to a different value for each stream required. This is similar to the skip-ahead method described in [Multiple Streams via Skip-ahead], in that the full sequence of the Wichmann–Hill II generator is split into a number of different blocks, in this case with a fixed length of 290. But without the computationally intensive initialization usually required for the skip-ahead method.

Multiple Streams via Different Generators

Independent sequences of variates can be generated using a different base generator for each sequence. For example, sequence 1 can be generated using the NAG basic generator, sequence 2 using Mersenne Twister, sequence 3 the ACORN generator and sequence 4 using L'Ecuyer generator. The Wichmann–Hill I generator implemented in this chapter is, in fact, a series of 273 independent generators. The particular sub-generator to use is selected using the subid variable. Therefore, in total, 278 independent streams can be generated with each using a different generator (273 Wichmann–Hill I generators, and 5 additional base generators).

Multiple Streams via Skip-ahead

Independent sequences of variates can be generated from a single base generator through the use of block-splitting, or skipping-ahead. This method consists of splitting the sequence into k non-overlapping blocks, each of length n, where n is no smaller than the maximum number of variates required from any of the sequences. For example,
x 1,x 2,…,xnblock 1,x n+1,x n+2,…,x 2 n block 2,x 2 n+1,x 2 n+2,…,x 3 n block 3,etc.
where x 1,x 2,… is the sequence produced by the generator of interest. Each of the k blocks provide an independent sequence.
The skip-ahead algorithm therefore requires the sequence to be advanced a large number of places, as to generate values from say, block b, you must skip over the b-1 n values in the first b-1 blocks. Due to their form this can be done efficiently for linear congruential generators and multiple congruential generators. A skip-ahead algorithm is also provided for the Mersenne Twister generator.
Although skip-ahead requires some additional computation at the initialization stage (to ‘fast forward’ the sequence) no additional computation is required at the generation stage.
This method of producing multiple streams can also be used for the Sobol and Niederreiter quasi-random number generator via the parameter iskip in g05yl.

Multiple Streams via Leap-frog

Independent sequences of variates can also be generated from a single base generator through the use of leap-frogging. This method involves splitting the sequence from a single generator into k disjoint subsequences. For example:
Subsequence 1:x 1,x k+1,x 2 k+1,…Subsequence 2:x 2,x k+2,x 2 k+2,…⋮Subsequence ​k:xk,x 2 k,x 3 k,…,
where x 1,x 2,… is the sequence produced by the generator of interest. Each of the k subsequences then provides an independent stream of variates.
The leap-frog algorithm therefore requires the generation of every kth variate from the base generator. Due to their form this can be done efficiently for linear congruential generators and multiple congruential generators. A leap-frog algorithm is provided for the NAG Basic generator, both the Wichmann–Hill I and Wichmann–Hill II generators and L'Ecuyer generator.
It is known that, dependent on the number of streams required, leap-frogging can lead to sequences with poor statistical properties, especially when applied to linear congruential generators. In addition, leap-frogging can increase the time required to generate each variate. Therefore leap-frogging should be avoided unless absolutely necessary.

Skip-ahead and Leap-frog for a Linear Congruential Generator (LCG): An Example

As an illustrative example, a brief description of the algebra behind the implementation of the leap-frog and skip-ahead algorithms for a linear congruential generator is given. A linear congruential generator has the form x i+1=a 1xi mod m 1. The recursive nature of a linear congruential generator means that
x i+v=a 1x i+v-1 mod m 1=a 1 a 1x i+v-2 mod m 1 mod m 1=a 12 x i+v-2 mod m 1=a 1 v xi mod m 1.
The sequence can therefore be quickly advanced v places by multiplying the current state (xi) by a 1 v mod m 1, hence skipping the sequence ahead. Leap-frogging can be implemented by using a 1 k, where k is the number of streams required, in place of a 1 in the standard linear congruential generator recursive formula, in order to advance k places, rather than one, at each iteration.
In a linear congruential generator the multiplier a 1 is constructed so that the generator has good statistical properties in, for example, the spectral test. When using leap-frogging to construct multiple streams this multiplier is replaced with a 1 k, and there is no guarantee that this new multiplier will have suitable properties especially as the value of k depends on the number of streams required and so is likely to change depending on the application. This problem can be emphasized by the lattice structure of linear congruential generators. Similiarly, the value of a 1 is often chosen such that the computation a 1xi mod m 1 can be performed efficiently. When a 1 is replaced by a 1 k, this is often no longer the case.
Note that, due to rounding, when using a distributional generator, a sequence generated using leap-frogging and a sequence constructed by taking every k value from a set of variates generated without leap-frogging may differ slightly. These differences should only affect the least significant digit.

Skip-ahead and Leap-frog for the Mersenne Twister: An Example

Skipping ahead with the Mersenne Twister generator is based on the definition of a k×k (where k=19937) transition matrix, A, over the finite field 𝔽 2 (with elements 0 and 1). Multiplying A by the current state xn, represented as a vector of bits, produces the next state vector x n+1:
x n+1=A⁢xn.
Thus, skipping ahead v places in a sequence is equivalent to multiplying by Av:
x n+v=Av xn.
Since calculating Av by a standard square and multiply algorithm is O k 3 log v and requires over 47MB of memory (see Haramoto et al. (2008)), an indirect calculation is performed which relies on a property of the characteristic polynomial p z of A, namely that p A=0. We then define
g z=zv mod p z=a k-1⁢z k-1+…+a 1⁢z+a 0,
and observe that
g z=zv+q z⁢p z
for a polynomial q z. Since p A=0, we have that g A=Av and
Av⁢xn=a k-1⁢A k-1+…+a 1 A+a 0 I⁢xn.
This polynomial evaluation can be performed using Horner's method:
Av⁢xn=A⁢…A⁢A⁢A⁢a k-1⁢xn+a k-2⁢xn+a k-3⁢xn+⋯+a 1⁢xn+a 0⁢xn,
which reduces the problem to advancing the generator k-1 places from state xn and adding (where addition is as defined over 𝔽 2) the intermediate states for which ai is nonzero.
There are therefore two stages to skipping the Mersenne Twister ahead v places:
(i) | Calculate the coefficients of the polynomial g z=zv mod p z;
(ii) | advance the sequence k-1 places from the starting state and add the intermediate states that correspond to nonzero coefficients in the polynomial calculated in the first step.
The resulting state is that for position v in the sequence.
The cost of calculating the polynomial is O k 2 log v and the cost of applying it to state is constant. Skip ahead functionality is typically used in order to generate n independent pseudorandom number streams (e.g., for separate threads of computation). There are two options for generating the n states:
(i) | On the master thread calculate the polynomial for a skip ahead distance of v and apply this polynomial to state n times, after each iteration j saving the current state for later usage by thread j.
(ii) | Have each thread j independently and in parallel with other threads calculate the polynomial for a distance of j+1⁢v and apply to the original state.
Since lim v→∞log v=log n⁢v, then for large v the cost of generating the polynomial for a skip ahead distance of n⁢v (i.e., the calculation performed by thread n-1 in option (ii) above) is approximately the same as generating that for a distance of v (i.e., the calculation performed by thread 0). However, only one application to state need be made per thread, and if n is sufficiently large the cost of applying the polynomial to state becomes the dominant cost in option (i), in which case it is desirable to use option (ii). Tests have shown that as a guideline it becomes worthwhile to switch from option (i) to option (ii) for approximately n>30.
Leap frog calculations with the Mersenne Twister are performed by computing the sequence fully up to the required size and discarding the redundant numbers for a given stream.

Recommendations on Choice and Use of Available Methods

Pseudorandom Numbers

Prior to generating any pseudorandom variates the base generator being used must be initialized. Once initialized, a distributional generator can be called to obtain the variates required. No interfaces have been supplied for direct access to the base generators. If a sequence of random variates from a uniform distribution on the open interval 0,1, is required, then the uniform distribution method (g05sa) should be called.

Initialization

Prior to generating any variates the base generator must be initialized. Two utility methods are provided for this, (G05KFF not in this release) and (G05KGF not in this release), both of which allow any of the base generators to be chosen.
(G05KFF not in this release) selects and initializes a base generator to a repeatable (when executed serially) state: two calls of (G05KFF not in this release) with the same argument-values will result in the same subsequent sequences of random numbers (when both generated serially).
(G05KGF not in this release) selects and initializes a base generator to a non-repeatable state in such a way that different calls of (G05KGF not in this release), either in the same run or different runs of the program, will almost certainly result in different subsequent sequences of random numbers.
No utilities for saving, retrieving or copying the current state of a generator have been provided. All of the information on the current state of a generator (or stream, if multiple streams are being used) is stored in the integer array state and as such this array can be treated as any other integer array, allowing for easy copying, restoring, etc.

Repeated initialization

As mentioned in [Multiple Streams via Different Initial Values (Seeds)], it is important to note that the statistical properties of pseudorandom numbers are only guaranteed within sequences and not between sequences produced by the same generator. Repeated initialization will thus render the numbers obtained less rather than more independent. In a simple case there should be only one call to (G05KFF not in this release) (G05KGF not in this release) and this call should be before any call to an actual generation method.

Choice of Base Generator

If a single sequence is required then it is recommended that the Mersenne Twister is used as the base generator (genid=3). This generator is fast, has an extremely long period and has been shown to perform well on various test suites, see Matsumoto and Nishimura (1998), L'Ecuyer and Simard (2002) and Wichmann and Hill (2006) for example.
When choosing a base generator, the period of the chosen generator should be borne in mind. A good rule of thumb is never to use more numbers than the square root of the period in any one experiment as the statistical properties are impaired. For closely related reasons, breaking numbers down into their bit patterns and using individual bits may also cause trouble.

Choice of Method for Generating Multiple Streams

If the Wichmann–Hill II base generator is being used, and a period of 290 is sufficient, then the method described in [Multiple Streams via Different Initial Values (Seeds)] can be used. If a different generator is used, or a longer period length is required then generating multiple streams by altering the initial values should be avoided.
Using a different generator works well if less than 277 streams are required.
Of the remaining two methods, both skip-ahead and leap-frogging use the sequence from a single generator, both guarantee that the different sequences will not overlap and both can be scaled to an arbitrary number of streams. Leap-frogging requires no a-priori knowledge about the number of variates being generated, whereas skip-ahead requires you to know (approximately) the maximum number of variates required from each stream. Skip-ahead requires no a-priori information on the number of streams required. In contrast leap-frogging requires you to know the maximum number of streams required, prior to generating the first value. Of these two, if possible, skip-ahead should be used in preference to leap-frogging. Both methods required additional computation compared with generating a single sequence, but for skip-ahead this computation occurs only at initialization. For leap-frogging additional computation is required both at initialization and during the generation of the variates. In addition, as mentioned in [Multiple Streams via Leap-frog], using leap-frogging can, in some instances, change the statistical properties of the sequences being generated.
Leap-frogging is performed by calling g05kh after the initialization method ( (G05KFF not in this release) (G05KGF not in this release)). For skip-ahead, either g05kj or g05kk can be called. Of these, g05kk restricts the amount being skipped to a power of 2, but allows for a large ‘skip’ to be performed.

Copulas

After calling one of the copula methods the inverse cumulative distribution function (CDF) can be applied to convert the uniform marginal distribution into the required form. Scalar and vector routines for evaluating the CDF, for a range of distributions, are supplied in G01 class. It should be noted that these routines are often described as computing the ‘deviates’ of the distribution.
When using the inverse CDF methods from G01 class it should be noted that some are limited in the number of significant figures they return. This may affect the statistical properties of the resulting sequence of variates. Section 7 of the individual method documentation will give a discussion of the accuracy of the particular algorithm being used and any available alternatives.

Quasi-random Numbers

Prior to generating any quasi-random variates the generator being used must be initialized via g05yl or g05yn. Of these, g05yl can be used to initialize a standard Sobol, Faure or Niederreiter sequence and g05yn can be used to initialize a scrambled Sobol or Niederreiter sequence.
Due to the random nature of the scrambling, prior to calling the initialization method g05yn one of the pseudorandom initialization methods, (G05KFF not in this release) (G05KGF not in this release), must be called.
Once a quasi-random generator has been initialized, using either g05yl or g05yn, one of three generation methods can be called to generate uniformly distributed sequences (g05ym), Normally distributed sequences ( (G05YJF not in this release)) or sequences with a log-normal distribution ( (G05YKF not in this release)). For example, for a repeatable sequence of scrambled quasi-random variates from the Normal distribution, (G05KFF not in this release) must be called first (to initialize a pseudorandom generator), followed by g05yn (to initialize a scrambled quasi-random generator) and then (G05YJF not in this release) can be called to generate the sequence from the required distribution.
See the last paragraph of [Copulas] on how sequences from other distributions can be obtained using the inverse CDF.

Brownian Bridge

(G05XBF not in this release) may be used to generate sample paths from a (free or non-free) Wiener process using the Brownian bridge algorithm. Prior to calling (G05XBF not in this release), the generator must be initialized by a call to (G05XAF not in this release). (G05XAF not in this release) requires you to specify a bridge construction order. The method (G05XEF not in this release) can be used to convert a set of input times into one of several common bridge construction orders, which can then be used in the initialization call to (G05XAF not in this release).
(G05XDF not in this release) may be used to generate the scaled increments of the sample paths of a (free or non-free) Wiener process. Prior to calling (G05XDF not in this release), the generator must be initialized by a call to (G05XCF not in this release). Note that (G05XDF not in this release) generates these scaled increments directly; it is not necessary to call (G05XBF not in this release) before calling (G05XDF not in this release). As before, (G05XEF not in this release) can be used to convert a set of input times into a bridge construction order which can be passed to (G05XCF not in this release).

Random Fields

Methods for simulating from either a one-dimensional or a two-dimensional stationary Gaussian random field are provided. These methods use the circulant embedding method of Dietrich and Newsam (1997) to efficiently generate from the required field. In both cases a setup method is called, which defines the domain and variogram to use, followed by the generation method. A number of preset variograms are supplied or a user-defined method can be used.
  • One-dimensional random field:
    • (G05ZNF not in this release) setup method, using a preset variogram.
    • (G05ZMF not in this release) setup method, using a user-defined variogram.
    • (G05ZPF not in this release) generation method.
  • Two-dimension random field:
    • (G05ZQF not in this release) setup method, using a preset variogram.
    • (G05ZRF not in this release) setup method, using a user-defined variogram.
    • (G05ZSF not in this release) generation method.
In addition to generating a random field, it is possible to use the circulant embedding method to generate realizations of fractional Brownian motion, this functionality is provided in (G05ZTF not in this release).
Prior to calling (G05ZPF not in this release), (G05ZRF not in this release) or (G05ZTF not in this release) one of the initialization methods, (G05KFF not in this release) or (G05KGF not in this release) must be called.

References

Banks J (1998) Handbook on Simulation Wiley
Boye E (Unpublished manuscript) Copulas for finance: a reading guide and some applications Financial Econometrics Research Centre, City University Business School, London
Bratley P and Fox B L (1988) Algorithm 659: implementing Sobol's quasirandom sequence generator ACM Trans. Math. Software 14(1) 88–100
Dietrich C R and Newsam G N (1997) Fast and exact simulation of stationary Gaussian processes through circulant embedding of the covariance matrix SIAM J. Sci. Comput. 18 1088–1107
Faure H and Tezuka S (2000) Another random scrambling of digital (t,s)-sequences Monte Carlo and Quasi-Monte Carlo Methods Springer-Verlag, Berlin, Germany (eds K T Fang, F J Hickernell and H Niederreiter)
Fox B L (1986) Algorithm 647: implementation and relative efficiency of quasirandom sequence generators ACM Trans. Math. Software 12(4) 362–376
Glasserman P (2004) Monte Carlo Methods in Financial Engineering Springer
Haramoto H, Matsumoto M, Nishimura T, Panneton F and L'Ecuyer P (2008) Efficient jump ahead for F2-linear random number generators INFORMS J. on Computing 20(3) 385–390
Hong H S and Hickernell F J (2003) Algorithm 823: implementing scrambled digital sequences ACM Trans. Math. Software 29:2 95–109
Joe S and Kuo F Y (2008) Constructing Sobol sequences with better two-dimensional projections SIAM J. Sci. Comput. 30 2635–2654
Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley
L'Ecuyer P and Simard R (2002) TestU01: a software library in ANSI C for empirical testing of random number generators Departement d'Informatique et de Recherche Operationnelle, Universite de Montreal http://www.iro.umontreal.ca/~lecuyer
Maclaren N M (1989) The generation of multiple independent sequences of pseudorandom numbers Appl. Statist. 38 351–359
Matsumoto M and Nishimura T (1998) Mersenne twister: a 623-dimensionally equidistributed uniform pseudorandom number generator ACM Transactions on Modelling and Computer Simulations
Morgan B J T (1984) Elements of Simulation Chapman and Hall
Nelsen R B (1998) An Introduction to Copulas. Lecture Notes in Statistics 139 Springer
Owen A B (1995) Randomly permuted (t,m,s)-nets and (t,s)-sequences Monte Carlo and Quasi-Monte Carlo Methods in Scientific Computing, Lecture Notes in Statistics 106 Springer-Verlag, New York, NY 299–317 (eds H Niederreiter and P J-S Shiue)
Revuz D and Yor M (1999) Continuous Martingales and Brownian Motion Springer
Ripley B D (1987) Stochastic Simulation Wiley
Sklar A (1973) Random variables: joint distribution functions and copulas Kybernetika 9 499–460
Wichmann B A and Hill I D (2006) Generating good pseudo-random numbers Computational Statistics and Data Analysis 51 1614–1622
Wikramaratna R S (1989) ACORN - a new method for generating sequences of uniformly distributed pseudo-random numbers Journal of Computational Physics 83 16–31
Wikramaratna R S (1992) Theoretical background for the ACORN random number generator Report AEA-APS-0244 AEA Technology, Winfrith, Dorest, UK
Wikramaratna R S (2007) The additive congruential random number generator a special case of a multiple recursive generator Journal of Computational and Applied Mathematics

Inheritance Hierarchy

System..::..Object
NagLibrary..::..G05

See Also

G05 Members


G05 Members

[image] [image]

NAG Library for .NET Release 2
G05 Members
G05 Class Methods See Also Send Feedback

The G05 type exposes the following members.

Methods

Name | Description
g05kh | g05kh allows for the generation of multiple, independent, sequences of pseudorandom numbers using the leap-frog method.
g05kj | g05kj allows for the generation of multiple, independent, sequences of pseudorandom numbers using the skip-ahead method. The base pseudorandom number sequence defined by state is advanced n places.
g05kk | g05kk allows for the generation of multiple, independent, sequences of pseudorandom numbers using the skip-ahead method. The base pseudorandom number sequence defined by state is advanced 2 n places.
g05nc | g05nc performs a pseudorandom permutation of a vector of integers.
g05nd | g05nd selects a pseudorandom sample without replacement from an integer vector.
g05pd | g05pd generates a given number of terms of a type I AGARCH p,q process (see Engle and Ng (1993)).
g05pe | g05pe generates a given number of terms of a type II AGARCH p,q process (see Engle and Ng (1993)).
g05pf | g05pf generates a given number of terms of a GJR GARCH p,q process (see Glosten et al. (1993)).
g05pg | g05pg generates a given number of terms of an exponential GARCH p,q process (see Engle and Ng (1993)).
g05ph | g05ph generates a realization of a univariate time series from an autoregressive moving average (ARMA) model. The realization may be continued or a new realization generated at subsequent calls to g05ph.
g05pj | g05pj generates a realization of a multivariate time series from a vector autoregressive moving average (VARMA) model. The realization may be continued or a new realization generated at subsequent calls to g05pj.
g05pm | g05pm simulates from an exponential smoothing model, where the model uses either single exponential, double exponential or a Holt–Winters method.
g05px | g05px generates a random orthogonal matrix.
g05py | g05py generates a random correlation matrix with given eigenvalues.
g05pz | g05pz generates a random two-way table.
g05rc | g05rc sets up a reference vector and generates an array of pseudorandom numbers from a Student's t copula with ν degrees of freedom and covariance matrix ν ν-2 C.
g05rd | g05rd sets up a reference vector and generates an array of pseudorandom numbers from a Normal (Gaussian) copula with covariance matrix C.
g05ry | g05ry sets up a reference vector and generates an array of pseudorandom numbers from a multivariate Student's t distribution with ν degrees of freedom, mean vector a and covariance matrix ν ν-2 C.
g05rz | g05rz sets up a reference vector and generates an array of pseudorandom numbers from a multivariate Normal distribution with mean vector a and covariance matrix C.
g05sa | g05sa generates a vector of pseudorandom numbers taken from a uniform distribution between 0 and 1.
g05sb | g05sb generates a vector of pseudorandom numbers taken from a beta distribution with parameters a and b.
g05sc | g05sc generates a vector of pseudorandom numbers from a Cauchy distribution with median a and semi-interquartile range b.
g05sd | g05sd generates a vector of pseudorandom numbers taken from a χ 2-distribution with ν degrees of freedom.
g05se | g05se generates a vector of pseudorandom numbers taken from a Dirichlet distribution.
g05sf | g05sf generates a vector of pseudorandom numbers from a (negative) exponential distribution with mean a.
g05sg | g05sg generates a vector of pseudorandom numbers from an exponential mix distribution composed of m exponential distributions each having a mean ai and weight wi.
g05sh | g05sh generates a vector of pseudorandom numbers taken from an F (or Fisher's variance ratio) distribution with μ and ν degrees of freedom.
g05sj | g05sj generates a vector of pseudorandom numbers taken from a gamma distribution with parameters a and b.
g05sk | g05sk generates a vector of pseudorandom numbers taken from a Normal (Gaussian) distribution with mean μ and variance σ 2.
g05sl | g05sl generates a vector of pseudorandom numbers from a logistic distribution with mean a and spread b.
g05sm | g05sm generates a vector of pseudorandom numbers from a log-normal distribution with parameters μ and σ 2.
g05sn | g05sn generates a vector of pseudorandom numbers taken from a Student's t-distribution with ν degrees of freedom.
g05sp | g05sp generates a vector of pseudorandom numbers from a triangular distribution with parameters xmin, xmed and xmax.
g05sq | g05sq generates a vector of pseudorandom numbers uniformly distributed over the interval a,b.
g05sr | g05sr generates a vector of pseudorandom numbers from a von Mises distribution with concentration parameter κ.
g05ss | g05ss generates a vector of pseudorandom numbers from a two parameter Weibull distribution with shape parameter a and scale parameter b.
g05ta | g05ta generates a vector of pseudorandom integers from the discrete binomial distribution with parameters m and p.
g05tb | g05tb generates a vector of pseudorandom logical values – true with probability p and false with probability 1-p.
g05tc | g05tc generates a vector of pseudorandom integers from the discrete geometric distribution with probability p of success at a trial.
g05td | g05td generates a vector of pseudorandom integers from a discrete distribution with a given PDF (probability density function) or CDF (cumulative distribution function) p.
g05te | g05te generates a vector of pseudorandom integers from the discrete hypergeometric distribution of the number of specified items in a sample of size l, taken from a population of size k with m specified items in it.
g05tf | g05tf generates a vector of pseudorandom integers from the discrete logarithmic distribution with parameter a.
g05tg | g05tg generates a sequence of n variates, each consisting of k pseudorandom integers, from the discrete multinomial distribution with k outcomes and m trials, where the outcomes have probabilities p 1,p 2,…,pk respectively.
g05th | g05th generates a vector of pseudorandom integers from the discrete negative binomial distribution with parameter m and probability p of success at a trial.
g05tj | g05tj generates a vector of pseudorandom integers from the discrete Poisson distribution with mean λ.
g05tk | g05tk generates a vector of pseudorandom integers, each from a discrete Poisson distribution with differing parameter.
g05tl | g05tl generates a vector of pseudorandom integers uniformly distributed over the interval a,b.
g05yl | g05yl initializes a quasi-random generator prior to calling g05ym (G05YJF not in this release) (G05YKF not in this release).
g05ym | g05ym generates a uniformly distributed low-discrepancy sequence as proposed by Sobol, Faure or Niederreiter. It must be preceded by a call to one of the initialization methods g05yl or g05yn.
g05yn | g05yn initializes a scrambled quasi-random generator prior to calling g05ym (G05YJF not in this release) (G05YKF not in this release). It must be preceded by a call to one of the pseudorandom initialization methods (G05KFF not in this release) (G05KGF not in this release).

See Also

G05 Class


G05 Classes

[image]

NAG Library for .NET Release 2
G05 Classes

G05 Classes

  • G05.G05State Class


G05.G05State Class

[image]

NAG Library for .NET Release 2
G05..::..G05State Class
G05 Class Members See Also Send Feedback
Class for holding the state of the Random number generator.

Syntax

C#
public class G05State
Visual Basic
Public Class G05State
Visual C++
public ref class G05State
F#
type G05State =  class end

Inheritance Hierarchy

System..::..Object
NagLibrary..::..G05..::..G05State

See Also

G05..::..G05State Members


G05.G05State Members

[image] [image]

NAG Library for .NET Release 2
G05..::..G05State Members
G05..::..G05State Class Constructors Properties See Also Send Feedback

This chapter is concerned with the generation of sequences of independent pseudorandom and quasi-random numbers from various distributions, and models.

The G05..::..G05State type exposes the following members.

Constructors

Name | Description
G05..::..G05State | Overloaded.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages.
Warning | Set the method used for logging any warning or error messages.

See Also

G05..::..G05State Class


G05.G05State Constructor

[image] [image]

NAG Library for .NET Release 2
G05..::..G05State Constructor
G05..::..G05State Class See Also Send Feedback

Overload List

Name | Description
G05..::..G05State(Int32, Int32, Int32%) | Constructor for G05State class
G05..::..G05State(Int32, Int32, array<Int32>[]()[][], Int32%) | Constructor for G05State class

See Also

G05..::..G05State Class
G05..::..G05State Members


G05.G05State Constructor (Int32, Int32, Int32)

[image]

NAG Library for .NET Release 2
G05..::..G05State Constructor (Int32, Int32, Int32%)
G05..::..G05State Class See Also Send Feedback
Constructor for G05State class

Syntax

C#
public G05State(
    int genid,
    int subid,
    out int ifail
)
Visual Basic
Public Sub New ( _
    genid As Integer, _
    subid As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
G05State(
    int genid,
    int subid,
    [OutAttribute] int% ifail
)
F#
new :
        genid : int *
        subid : int *
        ifail : int byref -> G05State

Parameters

genid
Type: System..::..Int32
On entry: must contain the type of base generator to use.
genid=1
NAG basic generator.
genid=2
Wichmann Hill I generator.
genid=3
Mersenne Twister.
genid=4
Wichmann Hill II generator.
genid=5
ACORN generator.
genid=6
L'Ecuyer MRG32k3a generator.
See the G05 class for details of each of the base generators.
Constraint: genid=1, 2, 3, 4, 5 or 6.
subid
Type: System..::..Int32
On entry: if genid=2, subid indicates which of the 273 sub-generators to use. In this case, the subid+272 mod 273+1 sub-generator is used.
If genid=5, subid indicates the values of k and p to use, where k is the order of the generator, and p controls the size of the modulus, M, with M=2 p×30. If subid<1, the default values of k=10 and p=2 are used, otherwise values for k and p are calculated from the formula, subid=k+1000 p-1.
If genid=6 and subid mod 2=0 the range of the generator is set to 0,1, otherwise the range is set to 0,1; in this case the sequence is identical to the implementation of MRG32k3a in TestU01 (see L'Ecuyer and Simard (2002)) for identical seeds.
For all other values of genid, subid is not referenced.
ifail
Type: System..::..Int32 %
On exit: ifail=0 or -1 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

See Also

G05..::..G05State Class
G05..::..G05State Members
G05..::..G05State Overload


G05.G05State Constructor (Int32, Int32, Int32[], Int32)

[image]

NAG Library for .NET Release 2
G05..::..G05State Constructor (Int32, Int32, array<Int32>[]()[][], Int32%)
G05..::..G05State Class See Also Send Feedback
Constructor for G05State class

Syntax

C#
public G05State(
    int genid,
    int subid,
    int[] seed,
    out int ifail
)
Visual Basic
Public Sub New ( _
    genid As Integer, _
    subid As Integer, _
    seed As Integer(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
G05State(
    int genid,
    int subid,
    array<int>^ seed,
    [OutAttribute] int% ifail
)
F#
new :
        genid : int *
        subid : int *
        seed : int[] *
        ifail : int byref -> G05State

Parameters

genid
Type: System..::..Int32
On entry: must contain the type of base generator to use.
genid=1
NAG basic generator.
genid=2
Wichmann Hill I generator.
genid=3
Mersenne Twister.
genid=4
Wichmann Hill II generator.
genid=5
ACORN generator.
genid=6
L'Ecuyer MRG32k3a generator.
See the G05 class for details of each of the base generators.
Constraint: genid=1, 2, 3, 4, 5 or 6.
subid
Type: System..::..Int32
On entry: if genid=2, subid indicates which of the 273 sub-generators to use. In this case, the subid+272 mod 273+1 sub-generator is used.
If genid=5, subid indicates the values of k and p to use, where k is the order of the generator, and p controls the size of the modulus, M, with M=2 p×30. If subid<1, the default values of k=10 and p=2 are used, otherwise values for k and p are calculated from the formula, subid=k+1000 p-1.
If genid=6 and subid mod 2=0 the range of the generator is set to 0,1, otherwise the range is set to 0,1; in this case the sequence is identical to the implementation of MRG32k3a in TestU01 (see L'Ecuyer and Simard (2002)) for identical seeds.
For all other values of genid, subid is not referenced.
seed
Type: array< System..::..Int32 >[]()[][]
An array of size [lseed]
On entry: the initial (seed) values for the selected base generator. The number of initial values required varies with each of the base generators.
If genid=1, one seed is required.
If genid=2, four seeds are required.
If genid=3, 624 seeds are required.
If genid=4, four seeds are required.
If genid=5, k+1 p seeds are required, where k and p are defined by subid. For the ACORN generator it is recommended that an odd value is used for seed[0].
If genid=6, six seeds are required.
If insufficient seeds are provided then the first lseed-1 values supplied in seed are used and the remaining values are randomly generated using the NAG basic generator. In such cases the NAG basic generator is initialized using the value supplied in seed[lseed-1].
Constraint: seed[i-1]≥1, for i=1,2,…,lseed.
ifail
Type: System..::..Int32 %
On exit: ifail=0 or -1 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

See Also

G05..::..G05State Class
G05..::..G05State Members
G05..::..G05State Overload


G05.G05State Properties

[image] [image]

NAG Library for .NET Release 2
G05..::..G05State Properties
G05..::..G05State Class See Also Send Feedback

The G05..::..G05State type exposes the following members.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages.
Warning | Set the method used for logging any warning or error messages.

See Also

G05..::..G05State Class


Message Property

[image]

NAG Library for .NET Release 2
G05..::..G05State..::Message Property
G05..::..G05State Class See Also Send Feedback
Set the method used for logging any monitoring messages.

Syntax

C#
public PrintManager..::..MessageLogger Message { get; set; }
Visual Basic
Public Property Message As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Message {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Message : PrintManager..::..MessageLogger with get, set

See Also

G05..::..G05State Class
G05..::..G05State Members


Warning Property

[image]

NAG Library for .NET Release 2
G05..::..G05State..::Warning Property
G05..::..G05State Class See Also Send Feedback
Set the method used for logging any warning or error messages.

Syntax

C#
public PrintManager..::..MessageLogger Warning { get; set; }
Visual Basic
Public Property Warning As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Warning {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Warning : PrintManager..::..MessageLogger with get, set

See Also

G05..::..G05State Class
G05..::..G05State Members


G05 Methods

[image] [image]

NAG Library for .NET Release 2
G05 Methods
G05 Class See Also Send Feedback

The G05 type exposes the following members.

Methods

Name | Description
g05kh | g05kh allows for the generation of multiple, independent, sequences of pseudorandom numbers using the leap-frog method.
g05kj | g05kj allows for the generation of multiple, independent, sequences of pseudorandom numbers using the skip-ahead method. The base pseudorandom number sequence defined by state is advanced n places.
g05kk | g05kk allows for the generation of multiple, independent, sequences of pseudorandom numbers using the skip-ahead method. The base pseudorandom number sequence defined by state is advanced 2 n places.
g05nc | g05nc performs a pseudorandom permutation of a vector of integers.
g05nd | g05nd selects a pseudorandom sample without replacement from an integer vector.
g05pd | g05pd generates a given number of terms of a type I AGARCH p,q process (see Engle and Ng (1993)).
g05pe | g05pe generates a given number of terms of a type II AGARCH p,q process (see Engle and Ng (1993)).
g05pf | g05pf generates a given number of terms of a GJR GARCH p,q process (see Glosten et al. (1993)).
g05pg | g05pg generates a given number of terms of an exponential GARCH p,q process (see Engle and Ng (1993)).
g05ph | g05ph generates a realization of a univariate time series from an autoregressive moving average (ARMA) model. The realization may be continued or a new realization generated at subsequent calls to g05ph.
g05pj | g05pj generates a realization of a multivariate time series from a vector autoregressive moving average (VARMA) model. The realization may be continued or a new realization generated at subsequent calls to g05pj.
g05pm | g05pm simulates from an exponential smoothing model, where the model uses either single exponential, double exponential or a Holt–Winters method.
g05px | g05px generates a random orthogonal matrix.
g05py | g05py generates a random correlation matrix with given eigenvalues.
g05pz | g05pz generates a random two-way table.
g05rc | g05rc sets up a reference vector and generates an array of pseudorandom numbers from a Student's t copula with ν degrees of freedom and covariance matrix ν ν-2 C.
g05rd | g05rd sets up a reference vector and generates an array of pseudorandom numbers from a Normal (Gaussian) copula with covariance matrix C.
g05ry | g05ry sets up a reference vector and generates an array of pseudorandom numbers from a multivariate Student's t distribution with ν degrees of freedom, mean vector a and covariance matrix ν ν-2 C.
g05rz | g05rz sets up a reference vector and generates an array of pseudorandom numbers from a multivariate Normal distribution with mean vector a and covariance matrix C.
g05sa | g05sa generates a vector of pseudorandom numbers taken from a uniform distribution between 0 and 1.
g05sb | g05sb generates a vector of pseudorandom numbers taken from a beta distribution with parameters a and b.
g05sc | g05sc generates a vector of pseudorandom numbers from a Cauchy distribution with median a and semi-interquartile range b.
g05sd | g05sd generates a vector of pseudorandom numbers taken from a χ 2-distribution with ν degrees of freedom.
g05se | g05se generates a vector of pseudorandom numbers taken from a Dirichlet distribution.
g05sf | g05sf generates a vector of pseudorandom numbers from a (negative) exponential distribution with mean a.
g05sg | g05sg generates a vector of pseudorandom numbers from an exponential mix distribution composed of m exponential distributions each having a mean ai and weight wi.
g05sh | g05sh generates a vector of pseudorandom numbers taken from an F (or Fisher's variance ratio) distribution with μ and ν degrees of freedom.
g05sj | g05sj generates a vector of pseudorandom numbers taken from a gamma distribution with parameters a and b.
g05sk | g05sk generates a vector of pseudorandom numbers taken from a Normal (Gaussian) distribution with mean μ and variance σ 2.
g05sl | g05sl generates a vector of pseudorandom numbers from a logistic distribution with mean a and spread b.
g05sm | g05sm generates a vector of pseudorandom numbers from a log-normal distribution with parameters μ and σ 2.
g05sn | g05sn generates a vector of pseudorandom numbers taken from a Student's t-distribution with ν degrees of freedom.
g05sp | g05sp generates a vector of pseudorandom numbers from a triangular distribution with parameters xmin, xmed and xmax.
g05sq | g05sq generates a vector of pseudorandom numbers uniformly distributed over the interval a,b.
g05sr | g05sr generates a vector of pseudorandom numbers from a von Mises distribution with concentration parameter κ.
g05ss | g05ss generates a vector of pseudorandom numbers from a two parameter Weibull distribution with shape parameter a and scale parameter b.
g05ta | g05ta generates a vector of pseudorandom integers from the discrete binomial distribution with parameters m and p.
g05tb | g05tb generates a vector of pseudorandom logical values – true with probability p and false with probability 1-p.
g05tc | g05tc generates a vector of pseudorandom integers from the discrete geometric distribution with probability p of success at a trial.
g05td | g05td generates a vector of pseudorandom integers from a discrete distribution with a given PDF (probability density function) or CDF (cumulative distribution function) p.
g05te | g05te generates a vector of pseudorandom integers from the discrete hypergeometric distribution of the number of specified items in a sample of size l, taken from a population of size k with m specified items in it.
g05tf | g05tf generates a vector of pseudorandom integers from the discrete logarithmic distribution with parameter a.
g05tg | g05tg generates a sequence of n variates, each consisting of k pseudorandom integers, from the discrete multinomial distribution with k outcomes and m trials, where the outcomes have probabilities p 1,p 2,…,pk respectively.
g05th | g05th generates a vector of pseudorandom integers from the discrete negative binomial distribution with parameter m and probability p of success at a trial.
g05tj | g05tj generates a vector of pseudorandom integers from the discrete Poisson distribution with mean λ.
g05tk | g05tk generates a vector of pseudorandom integers, each from a discrete Poisson distribution with differing parameter.
g05tl | g05tl generates a vector of pseudorandom integers uniformly distributed over the interval a,b.
g05yl | g05yl initializes a quasi-random generator prior to calling g05ym (G05YJF not in this release) (G05YKF not in this release).
g05ym | g05ym generates a uniformly distributed low-discrepancy sequence as proposed by Sobol, Faure or Niederreiter. It must be preceded by a call to one of the initialization methods g05yl or g05yn.
g05yn | g05yn initializes a scrambled quasi-random generator prior to calling g05ym (G05YJF not in this release) (G05YKF not in this release). It must be preceded by a call to one of the pseudorandom initialization methods (G05KFF not in this release) (G05KGF not in this release).

See Also

G05 Class


g05kh Method

[image]

NAG Library for .NET Release 2
G05..::g05kh Method
G05 Class See Also Send Feedback
g05kh allows for the generation of multiple, independent, sequences of pseudorandom numbers using the leap-frog method.

Syntax

C#
public static void g05kh(
    int n,
    int k,
    G05..::..G05State g05state,
    out int ifail
)
Visual Basic
Public Shared Sub g05kh ( _
    n As Integer, _
    k As Integer, _
    g05state As G05..::..G05State, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05kh(
    int n,
    int k,
    G05..::..G05State^ g05state,
    [OutAttribute] int% ifail
)
F#
static member g05kh :
        n : int *
        k : int *
        g05state : G05..::..G05State *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the total number of sequences required.
Constraint: n>0.
k
Type: System..::..Int32
On entry: k, the number of the current sequence.
Constraint: 0<k≤n.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g05kh adjusts a base generator to allow multiple, independent, sequences of pseudorandom numbers to be generated via the leap-frog method (see the G05 class for details).
If, prior to calling g05kh the base generator defined by state would produce random numbers x 1,x 2,x 3,…, then after calling g05kh the generator will produce random numbers xk,x k+n,x k+2 n,x k+3 n,….
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05kh.
The leap-frog algorithm can be used in conjunction with the NAG basic generator, both the Wichmann–Hill I and Wichmann–Hill II generators, the Mersenne Twister and L'Ecuyer.

References

Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n≤0.
ifail=2
On entry, k>n.
ifail=3
On entry, state vector was not initialized or has been corrupted.
ifail=4
On entry, cannot use the leap-frog method with the base generator defined by state.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

The leap-frog method tends to be less efficient than other methods of producing multiple, independent sequences. See the G05 class for alternative choices.

Example

Example program (C#): g05khe.cs

Example program data: g05khe.d

Example program results: g05khe.r

See Also

G05 Class
G05 Members


g05kj Method

[image]

NAG Library for .NET Release 2
G05..::g05kj Method
G05 Class See Also Send Feedback
g05kj allows for the generation of multiple, independent, sequences of pseudorandom numbers using the skip-ahead method.
The base pseudorandom number sequence defined by state is advanced n places.

Syntax

C#
public static void g05kj(
    int n,
    G05..::..G05State g05state,
    out int ifail
)
Visual Basic
Public Shared Sub g05kj ( _
    n As Integer, _
    g05state As G05..::..G05State, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05kj(
    int n,
    G05..::..G05State^ g05state,
    [OutAttribute] int% ifail
)
F#
static member g05kj :
        n : int *
        g05state : G05..::..G05State *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of places to skip ahead.
Constraint: n≥0.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g05kj adjusts a base generator to allow multiple, independent, sequences of pseudorandom numbers to be generated via the skip-ahead method (see the G05 class for details).
If, prior to calling g05kj the base generator defined by state would produce random numbers x 1,x 2,x 3,…, then after calling g05kj the generator will produce random numbers x n+1,x n+2,x n+3,….
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05kj.
The skip-ahead algorithm can be used in conjunction with any of the six base generators discussed in G05 class.

References

Haramoto H, Matsumoto M, Nishimura T, Panneton F and L'Ecuyer P (2008) Efficient jump ahead for F2-linear random number generators INFORMS J. on Computing 20(3) 385–390
Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<0.
ifail=2
On entry, state vector was not initialized or has been corrupted.
ifail=3
On entry, cannot use the skip-ahead method with the base generator defined by state.
ifail=4
On entry, the base generator is Mersenne Twister, but the state vector defined on initialization is not large enough to perform a skip-ahead. See the initialization method (G05KFF not in this release) (G05KGF not in this release).
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

Calling g05kj and then generating a series of uniform values using g05sa is more efficient than, but equivalent to, calling g05sa and discarding the first n values. This may not be the case for distributions other than the uniform, as some distributional generators require more than one uniform variate to generate a single draw from the required distribution.
To skip ahead k×m places you can either
(a) | call g05kj once with n=k×m, or
(b) | call g05kj k times with n=m, using the state vector output by the previous call as input to the next call
both approaches would result in the same sequence of values. When working in a multithreaded environment, where you want to generate (at most) m values on each of K threads, this would translate into either
(a) | spawning the K threads and calling g05kj once on each thread with n=k-1×m, where k is a thread ID, taking a value between 1 and K, or
(b) | calling g05kj on a single thread with n=m, spawning the K threads and then calling g05kj a further k-1 times on each of the thread.
Due to the way skip ahead is implemented for the Mersenne Twister, approach (a) will tend to be more efficient if more than 30 threads are being used (i.e., K>30), otherwise approach (b) should probably be used. For all other base generators, approach (a) should be used. See the G05 class for more details.

Example

Example program (C#): g05kje.cs

Example program data: g05kje.d

Example program results: g05kje.r

See Also

G05 Class
G05 Members


g05kk Method

[image]

NAG Library for .NET Release 2
G05..::g05kk Method
G05 Class See Also Send Feedback
g05kk allows for the generation of multiple, independent, sequences of pseudorandom numbers using the skip-ahead method. The base pseudorandom number sequence defined by state is advanced 2 n places.

Syntax

C#
public static void g05kk(
    int n,
    G05..::..G05State g05state,
    out int ifail
)
Visual Basic
Public Shared Sub g05kk ( _
    n As Integer, _
    g05state As G05..::..G05State, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05kk(
    int n,
    G05..::..G05State^ g05state,
    [OutAttribute] int% ifail
)
F#
static member g05kk :
        n : int *
        g05state : G05..::..G05State *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, where the number of places to skip-ahead is defined as 2 n.
Constraint: n≥0.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g05kk adjusts a base generator to allow multiple, independent, sequences of pseudorandom numbers to be generated via the skip-ahead method (see the G05 class for details).
If, prior to calling g05kk the base generator defined by state would produce random numbers x 1,x 2,x 3,…, then after calling g05kk the generator will produce random numbers x 2 n+1,x 2 n+2,x 2 n+3,….
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05kk.
The skip-ahead algorithm can be used in conjunction with any of the six base generators discussed in the G05 class.

References

Haramoto H, Matsumoto M, Nishimura T, Panneton F and L'Ecuyer P (2008) Efficient jump ahead for F2-linear random number generators INFORMS J. on Computing 20(3) 385–390
Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<0.
ifail=2
On entry, state vector was not initialized or has been corrupted.
ifail=3
On entry, cannot use the skip-ahead method with the base generator defined by state.
ifail=4
On entry, the base generator is Mersenne Twister, but the state vector defined on initialization is not large enough to perform a skip-ahead. See the initialization method (G05KFF not in this release) (G05KGF not in this release).
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

Calling g05kk and then generating a series of uniform values using g05sa is equivalent to, but more efficient than, calling g05sa and discarding the first 2 n values. This may not be the case for distributions other than the uniform, as some distributional generators require more than one uniform variate to generate a single draw from the required distribution.

Example

Example program (C#): g05kke.cs

Example program data: g05kke.d

Example program results: g05kke.r

See Also

G05 Class
G05 Members


g05nc Method

[image]

NAG Library for .NET Release 2
G05..::g05nc Method
G05 Class See Also Send Feedback
g05nc performs a pseudorandom permutation of a vector of integers.

Syntax

C#
public static void g05nc(
    int[] indx,
    int n,
    G05..::..G05State g05state,
    out int ifail
)
Visual Basic
Public Shared Sub g05nc ( _
    indx As Integer(), _
    n As Integer, _
    g05state As G05..::..G05State, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05nc(
    array<int>^ indx,
    int n,
    G05..::..G05State^ g05state,
    [OutAttribute] int% ifail
)
F#
static member g05nc :
        indx : int[] *
        n : int *
        g05state : G05..::..G05State *
        ifail : int byref -> unit

Parameters

indx
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On entry: the n integer values to be permuted.
On exit: the n permuted integer values.
n
Type: System..::..Int32
On entry: the number of values to be permuted.
Constraint: n≥1.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g05nc permutes the elements of an integer array without inspecting their values. Each of the n! possible permutations of the n values may be regarded as being equally probable.
Even for modest values of n it is theoretically impossible that all n! permutations may occur, as n! is likely to exceed the cycle length of any of the base generators. For practical purposes this is irrelevant, as the time necessary to generate all possible permutations is many millenia.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05nc.

References

Kendall M G and Stuart A (1969) The Advanced Theory of Statistics (Volume 1) (3rd Edition) Griffin
Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=2
On entry, n<1.
ifail=3
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05nce.cs

Example program data: g05nce.d

Example program results: g05nce.r

See Also

G05 Class
G05 Members


g05nd Method

[image]

NAG Library for .NET Release 2
G05..::g05nd Method
G05 Class See Also Send Feedback
g05nd selects a pseudorandom sample without replacement from an integer vector.

Syntax

C#
public static void g05nd(
    int[] ipop,
    int n,
    int[] isampl,
    int m,
    G05..::..G05State g05state,
    out int ifail
)
Visual Basic
Public Shared Sub g05nd ( _
    ipop As Integer(), _
    n As Integer, _
    isampl As Integer(), _
    m As Integer, _
    g05state As G05..::..G05State, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05nd(
    array<int>^ ipop,
    int n,
    array<int>^ isampl,
    int m,
    G05..::..G05State^ g05state,
    [OutAttribute] int% ifail
)
F#
static member g05nd :
        ipop : int[] *
        n : int *
        isampl : int[] *
        m : int *
        g05state : G05..::..G05State *
        ifail : int byref -> unit

Parameters

ipop
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On entry: the population to be sampled.
n
Type: System..::..Int32
On entry: the number of elements in the population vector to be sampled.
Constraint: n≥1.
isampl
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On exit: the selected sample.
m
Type: System..::..Int32
On entry: the sample size.
Constraint: 1≤m≤n.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g05nd selects m elements from a population vector ipop of length n and places them in a sample vector isampl. Their order in ipop will be preserved in isampl. Each of the nm possible combinations of elements of isampl may be regarded as being equally probable.
For moderate or large values of n it is theoretically impossible that all combinations of size m may occur, unless m is near 1 or near n. This is because nm exceeds the cycle length of any of the base generators. For practical purposes this is irrelevant, as the time taken to generate all possible combinations is many millenia.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05nd.

References

Kendall M G and Stuart A (1969) The Advanced Theory of Statistics (Volume 1) (3rd Edition) Griffin
Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=2
On entry, n<1.
ifail=4
On entry, | m<1,
or | m>n.
ifail=5
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

The time taken by g05nd is of order n.
In order to sample other kinds of vectors, or matrices of higher dimension, the following technique may be used:
(a) | set ipop[i-1]=i, for i=1,2,…,n;
(b) | use g05nd to take a sample from ipop and put it into isampl;
(c) | use the contents of isampl as a set of indices to access the relevant vector or matrix.
In order to divide a population into several groups, g05nc is more efficient.

Example

Example program (C#): g05nde.cs

Example program data: g05nde.d

Example program results: g05nde.r

See Also

G05 Class
G05 Members


g05pd Method

[image]

NAG Library for .NET Release 2
G05..::g05pd Method
G05 Class See Also Send Feedback
g05pd generates a given number of terms of a type I AGARCH p,q process (see Engle and Ng (1993)).

Syntax

C#
public static void g05pd(
    string dist,
    int num,
    int ip,
    int iq,
    double[] theta,
    double gamma,
    int df,
    double[] ht,
    double[] et,
    bool fcall,
    double[] r,
    G05..::..G05State g05state,
    out int ifail
)
Visual Basic
Public Shared Sub g05pd ( _
    dist As String, _
    num As Integer, _
    ip As Integer, _
    iq As Integer, _
    theta As Double(), _
    gamma As Double, _
    df As Integer, _
    ht As Double(), _
    et As Double(), _
    fcall As Boolean, _
    r As Double(), _
    g05state As G05..::..G05State, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05pd(
    String^ dist,
    int num,
    int ip,
    int iq,
    array<double>^ theta,
    double gamma,
    int df,
    array<double>^ ht,
    array<double>^ et,
    bool fcall,
    array<double>^ r,
    G05..::..G05State^ g05state,
    [OutAttribute] int% ifail
)
F#
static member g05pd :
        dist : string *
        num : int *
        ip : int *
        iq : int *
        theta : float[] *
        gamma : float *
        df : int *
        ht : float[] *
        et : float[] *
        fcall : bool *
        r : float[] *
        g05state : G05..::..G05State *
        ifail : int byref -> unit

Parameters

dist
Type: System..::..String
On entry: the type of distribution to use for εt.
dist="N"
A Normal distribution is used.
dist="T"
A Student's t-distribution is used.
Constraint: dist="N" or "T".
num
Type: System..::..Int32
On entry: T, the number of terms in the sequence.
Constraint: num≥0.
ip
Type: System..::..Int32
On entry: the number of coefficients, βi, for i=1,2,…,p.
Constraint: ip≥0.
iq
Type: System..::..Int32
On entry: the number of coefficients, αi, for i=1,2,…,q.
Constraint: iq≥1.
theta
Type: array< System..::..Double >[]()[][]
An array of size [iq+ip+1]
On entry: the first element must contain the coefficient αo, the next iq elements must contain the coefficients αi, for i=1,2,…,q. The remaining ip elements must contain the coefficients βj, for j=1,2,…,p.
Constraints:
  • ∑ i=2 iq+ip+1 theta[i-1]<1.0;
  • theta[i-1]≥0.0, for i=2,3,…,ip+iq+1.
gamma
Type: System..::..Double
On entry: the asymmetry parameter γ for the GARCH p,q sequence.
df
Type: System..::..Int32
On entry: the number of degrees of freedom for the Student's t-distribution.
If dist="N", df is not referenced.
Constraint: if dist="T", df>2.
ht
Type: array< System..::..Double >[]()[][]
An array of size [num]
On exit: the conditional variances ht, for t=1,2,…,T, for the GARCH p,q sequence.
et
Type: array< System..::..Double >[]()[][]
An array of size [num]
On exit: the observations εt, for t=1,2,…,T, for the GARCH p,q sequence.
fcall
Type: System..::..Boolean
On entry: if fcall=true, a new sequence is to be generated, otherwise a given sequence is to be continued using the information in r.
r
Type: array< System..::..Double >[]()[][]
An array of size [lr]
On entry: the array contains information required to continue a sequence if fcall=false.
On exit: contains information that can be used in a subsequent call of g05pd, with fcall=false.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

A type I AGARCH p,q process can be represented by:
ht=α 0+∑i=1 q αi ε t-i+γ 2+∑i=1 p βih t-i,  t=1,2,…,T;
where εt∣ψ t-1=N 0,ht or εt∣ψ t-1=St df,ht. Here St is a standardized Student's t-distribution with df degrees of freedom and variance ht, T is the number of observations in the sequence, εt is the observed value of the GARCH p,q process at time t, ht is the conditional variance at time t, and ψt the set of all information up to time t. Symmetric GARCH sequences are generated when γ is zero, otherwise asymmetric GARCH sequences are generated with γ specifying the amount by which positive (or negative) shocks are to be enhanced.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05pd.

References

Bollerslev T (1986) Generalised autoregressive conditional heteroskedasticity Journal of Econometrics 31 307–327
Engle R (1982) Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation Econometrica 50 987–1008
Engle R and Ng V (1993) Measuring and testing the impact of news on volatility Journal of Finance 48 1749–1777
Hamilton J (1994) Time Series Analysis Princeton University Press

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, dist≠"N" or "T".
ifail=2
On entry, num<0.
ifail=3
On entry, ip<0.
ifail=4
On entry, iq<1.
ifail=5
On entry, at least one theta[i-1]<0.0, for i=2,3,…,ip+iq+1.
ifail=51
On entry, ∑i theta[i-1]≥1.0, for i=2,3,…,ip+iq+1.
ifail=7
On entry, dist="T" and df≤2.
ifail=11
The value of ip or iq is not the same as when r was set up in a previous call.
ifail=12
On entry, lr<2×ip+iq+2.
ifail=13
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05pde.cs

Example program data: g05pde.d

Example program results: g05pde.r

See Also

G05 Class
G05 Members


g05pe Method

[image]

NAG Library for .NET Release 2
G05..::g05pe Method
G05 Class See Also Send Feedback
g05pe generates a given number of terms of a type II AGARCH p,q process (see Engle and Ng (1993)).

Syntax

C#
public static void g05pe(
    string dist,
    int num,
    int ip,
    int iq,
    double[] theta,
    double gamma,
    int df,
    double[] ht,
    double[] et,
    bool fcall,
    double[] r,
    G05..::..G05State g05state,
    out int ifail
)
Visual Basic
Public Shared Sub g05pe ( _
    dist As String, _
    num As Integer, _
    ip As Integer, _
    iq As Integer, _
    theta As Double(), _
    gamma As Double, _
    df As Integer, _
    ht As Double(), _
    et As Double(), _
    fcall As Boolean, _
    r As Double(), _
    g05state As G05..::..G05State, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05pe(
    String^ dist,
    int num,
    int ip,
    int iq,
    array<double>^ theta,
    double gamma,
    int df,
    array<double>^ ht,
    array<double>^ et,
    bool fcall,
    array<double>^ r,
    G05..::..G05State^ g05state,
    [OutAttribute] int% ifail
)
F#
static member g05pe :
        dist : string *
        num : int *
        ip : int *
        iq : int *
        theta : float[] *
        gamma : float *
        df : int *
        ht : float[] *
        et : float[] *
        fcall : bool *
        r : float[] *
        g05state : G05..::..G05State *
        ifail : int byref -> unit

Parameters

dist
Type: System..::..String
On entry: the type of distribution to use for εt.
dist="N"
A Normal distribution is used.
dist="T"
A Student's t-distribution is used.
Constraint: dist="N" or "T".
num
Type: System..::..Int32
On entry: T, the number of terms in the sequence.
Constraint: num≥0.
ip
Type: System..::..Int32
On entry: the number of coefficients, βi, for i=1,2,…,p.
Constraint: ip≥0.
iq
Type: System..::..Int32
On entry: the number of coefficients, αi, for i=1,2,…,q.
Constraint: iq≥1.
theta
Type: array< System..::..Double >[]()[][]
An array of size [iq+ip+1]
On entry: the first element must contain the coefficient αo, the next iq elements must contain the coefficients αi, for i=1,2,…,q. The remaining ip elements must contain the coefficients βj, for j=1,2,…,p.
Constraints:
  • ∑ i=2 iq+ip+1 theta[i-1]<1.0;
  • theta[i-1]≥0.0, for i=2,3,…,ip+iq+1.
gamma
Type: System..::..Double
On entry: the asymmetry parameter γ for the GARCH p,q sequence.
df
Type: System..::..Int32
On entry: the number of degrees of freedom for the Student's t-distribution.
If dist="N", df is not referenced.
Constraint: if dist="T", df>2.
ht
Type: array< System..::..Double >[]()[][]
An array of size [num]
On exit: the conditional variances ht, for t=1,2,…,T, for the GARCH p,q sequence.
et
Type: array< System..::..Double >[]()[][]
An array of size [num]
On exit: the observations εt, for t=1,2,…,T, for the GARCH p,q sequence.
fcall
Type: System..::..Boolean
On entry: if fcall=true, a new sequence is to be generated, otherwise a given sequence is to be continued using the information in r.
r
Type: array< System..::..Double >[]()[][]
An array of size [lr]
On entry: the array contains information required to continue a sequence if fcall=false.
On exit: contains information that can be used in a subsequent call of g05pe, with fcall=false.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

A type II AGARCH p,q process can be represented by:
ht=α 0+∑ i=1 q αi ε t-i+γ ε t-i 2+∑ i=1 p βih t-i,  t=1,2,…,T;
where εt∣ψ t-1=N 0,ht or εt∣ψ t-1=St df,ht. Here St is a standardized Student's t-distribution with df degrees of freedom and variance ht, T is the number of observations in the sequence, εt is the observed value of the GARCH p,q process at time t, ht is the conditional variance at time t, and ψt the set of all information up to time t. Symmetric GARCH sequences are generated when γ is zero, otherwise asymmetric GARCH sequences are generated with γ specifying the amount by which positive (or negative) shocks are to be enhanced.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05pe.

References

Bollerslev T (1986) Generalised autoregressive conditional heteroskedasticity Journal of Econometrics 31 307–327
Engle R (1982) Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation Econometrica 50 987–1008
Engle R and Ng V (1993) Measuring and testing the impact of news on volatility Journal of Finance 48 1749–1777
Hamilton J (1994) Time Series Analysis Princeton University Press

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, dist≠"N" or "T".
ifail=2
On entry, num<0.
ifail=3
On entry, ip<0.
ifail=4
On entry, iq<1.
ifail=7
On entry, dist="T" and df≤2.
ifail=11
The value of ip or iq is not the same as when r was set up in a previous call.
ifail=12
On entry, lr<2×ip+iq+2.
ifail=13
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05pee.cs

Example program data: g05pee.d

Example program results: g05pee.r

See Also

G05 Class
G05 Members


g05pf Method

[image]

NAG Library for .NET Release 2
G05..::g05pf Method
G05 Class See Also Send Feedback
g05pf generates a given number of terms of a GJR GARCH p,q process (see Glosten et al. (1993)).

Syntax

C#
public static void g05pf(
    string dist,
    int num,
    int ip,
    int iq,
    double[] theta,
    double gamma,
    int df,
    double[] ht,
    double[] et,
    bool fcall,
    double[] r,
    G05..::..G05State g05state,
    out int ifail
)
Visual Basic
Public Shared Sub g05pf ( _
    dist As String, _
    num As Integer, _
    ip As Integer, _
    iq As Integer, _
    theta As Double(), _
    gamma As Double, _
    df As Integer, _
    ht As Double(), _
    et As Double(), _
    fcall As Boolean, _
    r As Double(), _
    g05state As G05..::..G05State, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05pf(
    String^ dist,
    int num,
    int ip,
    int iq,
    array<double>^ theta,
    double gamma,
    int df,
    array<double>^ ht,
    array<double>^ et,
    bool fcall,
    array<double>^ r,
    G05..::..G05State^ g05state,
    [OutAttribute] int% ifail
)
F#
static member g05pf :
        dist : string *
        num : int *
        ip : int *
        iq : int *
        theta : float[] *
        gamma : float *
        df : int *
        ht : float[] *
        et : float[] *
        fcall : bool *
        r : float[] *
        g05state : G05..::..G05State *
        ifail : int byref -> unit

Parameters

dist
Type: System..::..String
On entry: the type of distribution to use for εt.
dist="N"
A Normal distribution is used.
dist="T"
A Student's t-distribution is used.
Constraint: dist="N" or "T".
num
Type: System..::..Int32
On entry: T, the number of terms in the sequence.
Constraint: num>0.
ip
Type: System..::..Int32
On entry: the number of coefficients, βi, for i=1,2,…,p.
Constraint: ip≥0.
iq
Type: System..::..Int32
On entry: the number of coefficients, αi, for i=1,2,…,q.
Constraint: iq≥1.
theta
Type: array< System..::..Double >[]()[][]
An array of size [iq+ip+1]
On entry: the first element must contain the coefficient αo, the next iq elements must contain the coefficients αi, for i=1,2,…,q. The remaining ip elements must contain the coefficients βj, for j=1,2,…,p.
Constraints:
  • ∑ i=2 iq+ip+1 theta[i-1]<1.0;
  • theta[i-1]≥0.0, for i=1 and i=iq+2,…,iq+ip+1.
gamma
Type: System..::..Double
On entry: the asymmetry parameter γ for the GARCH p,q sequence.
Constraint: gamma+theta[i-1]≥0.0, for i=2,3,…,iq+1.
df
Type: System..::..Int32
On entry: the number of degrees of freedom for the Student's t-distribution.
If dist="N", df is not referenced.
Constraint: if dist="T", df>2.
ht
Type: array< System..::..Double >[]()[][]
An array of size [num]
On exit: the conditional variances ht, for t=1,2,…,T, for the GARCH p,q sequence.
et
Type: array< System..::..Double >[]()[][]
An array of size [num]
On exit: the observations εt, for t=1,2,…,T, for the GARCH p,q sequence.
fcall
Type: System..::..Boolean
On entry: if fcall=true, a new sequence is to be generated, otherwise a given sequence is to be continued using the information in r.
r
Type: array< System..::..Double >[]()[][]
An array of size [lr]
On entry: the array contains information required to continue a sequence if fcall=false.
On exit: contains information that can be used in a subsequent call of g05pf, with fcall=false.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

A GJR GARCH p,q process is represented by:
ht=α 0+∑i=1 q αi+γ I t-i ε t-i 2+∑i=1 p βih t-i,  t=1,2,…,T;
where It=1 if εt<0, It=0 if εt≥0, and εt∣ψ t-1=N 0,ht or εt∣ψ t-1=St df,ht. Here St is a standardized Student's t-distribution with df degrees of freedom and variance ht, T is the number of observations in the sequence, εt is the observed value of the GARCH p,q process at time t, ht is the conditional variance at time t, and ψt the set of all information up to time t. Symmetric GARCH sequences are generated when γ is zero, otherwise asymmetric GARCH sequences are generated with γ specifying the amount by which negative shocks are to be enhanced.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05pf.

References

Bollerslev T (1986) Generalised autoregressive conditional heteroskedasticity Journal of Econometrics 31 307–327
Engle R (1982) Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation Econometrica 50 987–1008
Engle R and Ng V (1993) Measuring and testing the impact of news on volatility Journal of Finance 48 1749–1777
Glosten L, Jagannathan R and Runkle D (1993) Relationship between the expected value and the volatility of nominal excess return on stocks Journal of Finance 48 1779–1801
Hamilton J (1994) Time Series Analysis Princeton University Press

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, dist≠"N" or "T".
ifail=2
On entry, num<0.
ifail=3
On entry, ip<0.
ifail=4
On entry, iq<1.
ifail=5
On entry, | α 0<0,
or | αi+γ<0 for some αi.
ifail=51
On entry, βi<0 for some βi.
ifail=52
On entry, ∑i=1 q αi+∑i=1 p βi≥1.
ifail=7
On entry, dist="T" and df≤2.
ifail=11
The value of ip or iq is not the same as when r was set up in a previous call.
ifail=12
On entry, lr<2×ip+iq+2.
ifail=13
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05pfe.cs

Example program data: g05pfe.d

Example program results: g05pfe.r

See Also

G05 Class
G05 Members


g05pg Method

[image]

NAG Library for .NET Release 2
G05..::g05pg Method
G05 Class See Also Send Feedback
g05pg generates a given number of terms of an exponential GARCH p,q process (see Engle and Ng (1993)).

Syntax

C#
public static void g05pg(
    string dist,
    int num,
    int ip,
    int iq,
    double[] theta,
    int df,
    double[] ht,
    double[] et,
    bool fcall,
    double[] r,
    G05..::..G05State g05state,
    out int ifail
)
Visual Basic
Public Shared Sub g05pg ( _
    dist As String, _
    num As Integer, _
    ip As Integer, _
    iq As Integer, _
    theta As Double(), _
    df As Integer, _
    ht As Double(), _
    et As Double(), _
    fcall As Boolean, _
    r As Double(), _
    g05state As G05..::..G05State, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05pg(
    String^ dist,
    int num,
    int ip,
    int iq,
    array<double>^ theta,
    int df,
    array<double>^ ht,
    array<double>^ et,
    bool fcall,
    array<double>^ r,
    G05..::..G05State^ g05state,
    [OutAttribute] int% ifail
)
F#
static member g05pg :
        dist : string *
        num : int *
        ip : int *
        iq : int *
        theta : float[] *
        df : int *
        ht : float[] *
        et : float[] *
        fcall : bool *
        r : float[] *
        g05state : G05..::..G05State *
        ifail : int byref -> unit

Parameters

dist
Type: System..::..String
On entry: the type of distribution to use for εt.
dist="N"
A Normal distribution is used.
dist="T"
A Student's t-distribution is used.
Constraint: dist="N" or "T".
num
Type: System..::..Int32
On entry: T, the number of terms in the sequence.
Constraint: num≥0.
ip
Type: System..::..Int32
On entry: the number of coefficients, βi, for i=1,2,…,p.
Constraint: ip≥0.
iq
Type: System..::..Int32
On entry: the number of coefficients, αi, for i=1,2,…,q.
Constraint: iq≥1.
theta
Type: array< System..::..Double >[]()[][]
An array of size [2×iq+ip+1]
On entry: the initial parameter estimates for the vector θ. The first element must contain the coefficient αo and the next iq elements must contain the autoregressive coefficients αi, for i=1,2,…,q. The next iq elements must contain the coefficients ϕi, for i=1,2,…,q. The next ip elements must contain the moving average coefficients βj, for j=1,2,…,p.
Constraints:
  • ∑ i=1 p βi≠1.0;
  • α 0 1-∑ i=1 p βi≤-log x02am.
df
Type: System..::..Int32
On entry: the number of degrees of freedom for the Student's t-distribution.
If dist="N", df is not referenced.
Constraint: if dist="T", df>2.
ht
Type: array< System..::..Double >[]()[][]
An array of size [num]
On exit: the conditional variances ht, for t=1,2,…,T, for the GARCH p,q sequence.
et
Type: array< System..::..Double >[]()[][]
An array of size [num]
On exit: the observations εt, for t=1,2,…,T, for the GARCH p,q sequence.
fcall
Type: System..::..Boolean
On entry: if fcall=true, a new sequence is to be generated, otherwise a given sequence is to be continued using the information in r.
r
Type: array< System..::..Double >[]()[][]
An array of size [lr]
On entry: the array contains information required to continue a sequence if fcall=false.
On exit: contains information that can be used in a subsequent call of g05pg, with fcall=false.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

An exponential GARCH p,q process is represented by:
ln ht=α 0+∑i=1 q αiz t-i+∑i=1 q ϕi z t-i-E z t-i+∑j=1 p βj ln h t-j,  t=1,2,…,T;
where zt=εt ht, E z t-i denotes the expected value of z t-i, and εt∣ψ t-1=N 0,ht or εt∣ψ t-1=St df,ht. Here St is a standardized Student's t-distribution with df degrees of freedom and variance ht, T is the number of observations in the sequence, εt is the observed value of the GARCH p,q process at time t, ht is the conditional variance at time t, and ψt the set of all information up to time t.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05pg.

References

Bollerslev T (1986) Generalised autoregressive conditional heteroskedasticity Journal of Econometrics 31 307–327
Engle R (1982) Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation Econometrica 50 987–1008
Engle R and Ng V (1993) Measuring and testing the impact of news on volatility Journal of Finance 48 1749–1777
Glosten L, Jagannathan R and Runkle D (1993) Relationship between the expected value and the volatility of nominal excess return on stocks Journal of Finance 48 1779–1801
Hamilton J (1994) Time Series Analysis Princeton University Press

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, dist≠"N" or "T".
ifail=2
On entry, num<0.
ifail=3
On entry, ip<0.
ifail=4
On entry, iq<1.
ifail=6
On entry, dist="T" and df≤2.
ifail=10
The value of ip or iq is not the same as when r was set up in a previous call.
ifail=11
On entry, lr<2×ip+iq+2.
ifail=12
On entry, state vector was not initialized or has been corrupted.
ifail=20
Invalid sequence generated, use different parameters.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05pge.cs

Example program data: g05pge.d

Example program results: g05pge.r

See Also

G05 Class
G05 Members


g05ph Method

[image]

NAG Library for .NET Release 2
G05..::g05ph Method
G05 Class See Also Send Feedback
g05ph generates a realization of a univariate time series from an autoregressive moving average (ARMA) model. The realization may be continued or a new realization generated at subsequent calls to g05ph.

Syntax

C#
public static void g05ph(
    int mode,
    int n,
    double xmean,
    int ip,
    double[] phi,
    int iq,
    double[] theta,
    double avar,
    double[] r,
    G05..::..G05State g05state,
    out double var,
    double[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05ph ( _
    mode As Integer, _
    n As Integer, _
    xmean As Double, _
    ip As Integer, _
    phi As Double(), _
    iq As Integer, _
    theta As Double(), _
    avar As Double, _
    r As Double(), _
    g05state As G05..::..G05State, _
    <OutAttribute> ByRef var As Double, _
    x As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05ph(
    int mode,
    int n,
    double xmean,
    int ip,
    array<double>^ phi,
    int iq,
    array<double>^ theta,
    double avar,
    array<double>^ r,
    G05..::..G05State^ g05state,
    [OutAttribute] double% var,
    array<double>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05ph :
        mode : int *
        n : int *
        xmean : float *
        ip : int *
        phi : float[] *
        iq : int *
        theta : float[] *
        avar : float *
        r : float[] *
        g05state : G05..::..G05State *
        var : float byref *
        x : float[] *
        ifail : int byref -> unit

Parameters

mode
Type: System..::..Int32
On entry: a code for selecting the operation to be performed by the method.
mode=0
Set up reference vector only.
mode=1
Generate terms in the time series using reference vector set up in a prior call to g05ph.
mode=2
Set up reference vector and generate terms in the time series.
Constraint: mode=0, 1 or 2.
n
Type: System..::..Int32
On entry: n, the number of observations to be generated.
Constraint: n≥0.
xmean
Type: System..::..Double
On entry: the mean of the time series.
ip
Type: System..::..Int32
On entry: p, the number of autoregressive coefficients supplied.
Constraint: ip≥0.
phi
Type: array< System..::..Double >[]()[][]
An array of size [ip]
On entry: the autoregressive coefficients of the model, ϕ 1,ϕ 2,…,ϕp.
iq
Type: System..::..Int32
On entry: q, the number of moving average coefficients supplied.
Constraint: iq≥0.
theta
Type: array< System..::..Double >[]()[][]
An array of size [iq]
On entry: the moving average coefficients of the model, θ 1,θ 2,…,θq.
avar
Type: System..::..Double
On entry: σ 2, the variance of the Normal perturbations.
Constraint: avar≥0.0.
r
Type: array< System..::..Double >[]()[][]
An array of size [lr]
On entry: if mode=1, the reference vector from the previous call to g05ph.
On exit: the reference vector.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
var
Type: System..::..Double %
On exit: the proportion of the variance of a term in the series that is due to the moving-average (error) terms in the model. The smaller this is, the nearer is the model to non-stationarity.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: contains the next n observations from the time series.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Let the vector xt, denote a time series which is assumed to follow an autoregressive moving average (ARMA) model of the form:
xt-μ=ϕ 1 x t-1-μ+ϕ 2 x t-2-μ+⋯+ϕp x t-p-μ+εt-θ 1ε t-1-θ 2ε t-2-⋯-θqε t-q
where εt, is a residual series of independent random perturbations assumed to be Normally distributed with zero mean and variance σ 2. The parameters ϕi, for i=1,2,…,p, are called the autoregressive (AR) parameters, and θj, for j=1,2,…,q, the moving average (MA) parameters. The parameters in the model are thus the p ϕ values, the q θ values, the mean μ and the residual variance σ 2.
g05ph sets up a reference vector containing initial values corresponding to a stationary position using the method described in Tunnicliffe–Wilson (1979). The method can then return a realization of x 1,x 2,…,xn. On a successful exit, the recent history is updated and saved in the reference vector r so that g05ph may be called again to generate a realization of x n+1,x n+2,…, etc. See the description of the parameter mode in [Parameters] for details.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05ph.

References

Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley
Tunnicliffe–Wilson G (1979) Some efficient computational procedures for high order ARMA models J. Statist. Comput. Simulation 8 301–309

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, mode≠0, 1 or 2.
ifail=2
On entry, n<0.
ifail=4
On entry, ip<0.
ifail=5
phi does not define a stationary autoregressive process.
ifail=6
On entry, iq<0.
ifail=8
On entry, avar<0.0.
ifail=9
Either r has been corrupted or the value of ip or iq is not the same as when r was set up in a previous call to g05ph with mode=0 or 2.
ifail=10
On entry, lr<ip+iq+6+max ip,iq+1.
ifail=11
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Any errors in the reference vector's initial values should be very much smaller than the error term; see Tunnicliffe–Wilson (1979).

Parallelism and Performance

None.

Further Comments

The time taken by g05ph is essentially of order ip 2.
The ARMA model for a time series can also be written as:
xn-E=A 1 x n-1-E+⋯+ANA x n-NA-E+B 1an+⋯+BNBa n-NB+1
where
  • xn is the observed value of the time series at time n,
  • NA is the number of autoregressive parameters, Ai,
  • NB is the number of moving average parameters, Bi,
  • E is the mean of the time series,
and
  • at is a series of independent random Standard Normal perturbations.
This is related to the form given in [Description] by:
  • B 12=σ 2,
  • B i+1=-θi σ=-θiB 1,  i=1,2,…,q,
  • NB=q+1,
  • E=μ,
  • Ai=ϕi,  i=1,2,…,p,
  • NA=p.

Example

Example program (C#): g05phe.cs

Example program data: g05phe.d

Example program results: g05phe.r

See Also

G05 Class
G05 Members


g05pj Method

[image]

NAG Library for .NET Release 2
G05..::g05pj Method
G05 Class See Also Send Feedback
g05pj generates a realization of a multivariate time series from a vector autoregressive moving average (VARMA) model. The realization may be continued or a new realization generated at subsequent calls to g05pj.

Syntax

C#
public static void g05pj(
    int mode,
    int n,
    int k,
    double[] xmean,
    int ip,
    double[] phi,
    int iq,
    double[] theta,
    double[,] var,
    double[] r,
    G05..::..G05State g05state,
    double[,] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05pj ( _
    mode As Integer, _
    n As Integer, _
    k As Integer, _
    xmean As Double(), _
    ip As Integer, _
    phi As Double(), _
    iq As Integer, _
    theta As Double(), _
    var As Double(,), _
    r As Double(), _
    g05state As G05..::..G05State, _
    x As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05pj(
    int mode,
    int n,
    int k,
    array<double>^ xmean,
    int ip,
    array<double>^ phi,
    int iq,
    array<double>^ theta,
    array<double,2>^ var,
    array<double>^ r,
    G05..::..G05State^ g05state,
    array<double,2>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05pj :
        mode : int *
        n : int *
        k : int *
        xmean : float[] *
        ip : int *
        phi : float[] *
        iq : int *
        theta : float[] *
        var : float[,] *
        r : float[] *
        g05state : G05..::..G05State *
        x : float[,] *
        ifail : int byref -> unit

Parameters

mode
Type: System..::..Int32
On entry: a code for selecting the operation to be performed by the method.
mode=0
Set up reference vector and compute a realization of the recent history.
mode=1
Generate terms in the time series using reference vector set up in a prior call to g05pj.
mode=2
Combine the operations of mode=0 and 1.
mode=3
A new realization of the recent history is computed using information stored in the reference vector, and the following sequence of time series values are generated.
If mode=1 or 3, then you must ensure that the reference vector r and the values of k, ip, iq, xmean, phi, theta, var and ldvar have not been changed between calls to g05pj.
Constraint: mode=0, 1, 2 or 3.
n
Type: System..::..Int32
On entry: n, the number of observations to be generated.
Constraint: n≥0.
k
Type: System..::..Int32
On entry: k, the dimension of the multivariate time series.
Constraint: k≥1.
xmean
Type: array< System..::..Double >[]()[][]
An array of size [k]
On entry: μ, the vector of means of the multivariate time series.
ip
Type: System..::..Int32
On entry: p, the number of autoregressive parameter matrices.
Constraint: ip≥0.
phi
Type: array< System..::..Double >[]()[][]
An array of size [k×k×ip]
On entry: must contain the elements of the ip×k×k autoregressive parameter matrices of the model, ϕ 1,ϕ 2,…,ϕp. If phi is considered as a three-dimensional array, dimensioned as phi[k-1,k-1,ip-1], then the i,jth element of ϕl would be stored in phi[i-1,j-1,l-1]; that is, phi[l-1×k×k+j-1×k+i-1] must be set equal to the i,jth element of ϕl, for l=1,2,…,p, i=1,2,…,k and j=1,2,…,k.
Constraint: the elements of phi must satisfy the stationarity condition.
iq
Type: System..::..Int32
On entry: q, the number of moving average parameter matrices.
Constraint: iq≥0.
theta
Type: array< System..::..Double >[]()[][]
An array of size [k×k×iq]
On entry: must contain the elements of the iq×k×k moving average parameter matrices of the model, θ 1,θ 2,…,θq. If theta is considered as a three-dimensional array, dimensioned as theta(k,k,iq), then the i,jth element of θl would be stored in theta[i-1,j-1,l-1]; that is, theta[l-1×k×k+j-1×k+i-1] must be set equal to the i,jth element of θl, for l=1,2,…,q, i=1,2,…,k and j=1,2,…,k.
Constraint: the elements of theta must be within the invertibility region.
var
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, k]
Note: dim1 must satisfy the constraint: dim1≥k
On entry: var[i-1,j-1] must contain the (i,j)th element of Σ, for i=1,2,…,k and j=1,2,…,k. Only the lower triangle is required.
Constraint: the elements of var must be such that Σ is positive semidefinite.
r
Type: array< System..::..Double >[]()[][]
An array of size [lr]
On entry: if mode=1 or 3, the array r as output from the previous call to g05pj must be input without any change.
If mode=0 or 2, the contents of r need not be set.
On exit: information required for any subsequent calls to the method with mode=1 or 3. See [Further Comments].
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥k
On exit: x[i-1,t-1] will contain a realization of the ith component of Xt, for i=1,2,…,k and t=1,2,…,n.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Let the vector Xt=x 1 t,x 2 t,…,x kt T, denote a k-dimensional time series which is assumed to follow a vector autoregressive moving average (VARMA) model of the form:
Xt-μ=ϕ 1 X t-1-μ+ϕ 2 X t-2-μ+⋯+ϕp X t-p-μ+εt-θ 1ε t-1-θ 2ε t-2-⋯-θqε t-q (1)
where εt=ε 1 t,ε 2 t,…,ε kt T, is a vector of k residual series assumed to be Normally distributed with zero mean and covariance matrix Σ. The components of εt are assumed to be uncorrelated at non-simultaneous lags. The ϕi's and θj's are k by k matrices of parameters. ϕi, for i=1,2,…,p, are called the autoregressive (AR) parameter matrices, and θj, for j=1,2,…,q, the moving average (MA) parameter matrices. The parameters in the model are thus the p k by k ϕ-matrices, the q k by k θ-matrices, the mean vector μ and the residual error covariance matrix Σ. Let
A ϕ=ϕ 1I0...0ϕ 20I0..0......ϕ p-10...0Iϕp0...00 pk×pk  and  B θ=θ 1I0...0θ 20I0..0......θ q-10...0Iθq0...00 qk×qk
where I denotes the k by k identity matrix.
The model (1) must be both stationary and invertible. The model is said to be stationary if the eigenvalues of A ϕ lie inside the unit circle and invertible if the eigenvalues of B θ lie inside the unit circle.
For k≥6 the VARMA model (1) is recast into state space form and a realization of the state vector at time zero computed. For all other cases the method computes a realization of the pre-observed vectors X 0,X-1,…,X 1-p, ε 0,ε-1,…,ε 1-q, from (1), see Shea (1988). This realization is then used to generate a sequence of successive time series observations. Note that special action is taken for pure MA models, that is for p=0.
At your request a new realization of the time series may be generated more efficiently using the information in a reference vector created during a previous call to g05pj. See the description of the parameter mode in [Parameters] for details.
The method returns a realization of X 1,X 2,…,Xn. On a successful exit, the recent history is updated and saved in the array r so that g05pj may be called again to generate a realization of X n+1,X n+2,…, etc. See the description of the parameter mode in [Parameters] for details.
Further computational details are given in Shea (1988). Note, however, that g05pj uses a spectral decomposition rather than a Cholesky factorization to generate the multivariate Normals. Although this method involves more multiplications than the Cholesky factorization method and is thus slightly slower it is more stable when faced with ill-conditioned covariance matrices. A method of assigning the AR and MA coefficient matrices so that the stationarity and invertibility conditions are satisfied is described in Barone (1987).
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05pj.

References

Barone P (1987) A method for generating independent realisations of a multivariate normal stationary and invertible ARMAp,q process J. Time Ser. Anal. 8 125–130
Shea B L (1988) A note on the generation of independent realisations of a vector autoregressive moving average process J. Time Ser. Anal. 9 403–410

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDVAR, LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, mode≠0, 1, 2 or 3.
ifail=2
On entry, n<0.
ifail=3
On entry, k<1.
ifail=5
On entry, ip<0.
ifail=6
The autoregressive parameter matrices, stored in phi, are such that the model is non-stationary.
ifail=7
On entry, iq<0.
ifail=8
On entry, the moving average parameter matrices, stored in theta, are such that the model is non-invertible.
ifail=9
The covariance matrix Σ, stored in var, is not positive semidefinite.
ifail=10
On entry, ldvar<k.
ifail=11
Either r has been corrupted or the value of k is not the same as when r was set up in a previous call to g05pj with mode=0 or 2.
ifail=12
On entry, lr is too small.
ifail=13
On entry, state vector was not initialized or has been corrupted.
ifail=15
On entry, ldx<k.
ifail=20
This is an unlikely exit brought about by an excessive number of iterations being needed by the NAG Library method used to evaluate the eigenvalues of A ϕ or B θ.
ifail=21
g05pj has not been able to calculate all the required elements of the array r. This is likely to be because the AR parameters are very close to the boundary of the stationarity region.
ifail=22
This is an unlikely exit brought about by an excessive number of iterations being needed by the NAG Library method used to evaluate the eigenvalues of the covariance matrix.
ifail=23
g05pj has not been able to calculate all the required elements of the array r. This is an unlikely exit brought about by an excessive number of iterations being needed by the NAG Library method used to evaluate eigenvalues to be stored in the array r. If this error occurs please contact NAG.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The accuracy is limited by the matrix computations performed, and this is dependent on the condition of the parameter and covariance matrices.

Parallelism and Performance

None.

Further Comments

Note that, in reference to ifail=8, g05pj will permit moving average parameters on the boundary of the invertibility region.
The elements of r contain amongst other information details of the spectral decompositions which are used to generate future multivariate Normals. Note that these eigenvectors may not be unique on different machines. For example the eigenvectors corresponding to multiple eigenvalues may be permuted. Although an effort is made to ensure that the eigenvectors have the same sign on all machines, differences in the signs may theoretically still occur.
The following table gives some examples of the required size of the array r, specified by the parameter lr, for k=1,2 or 3, and for various values of p and q.
 |  |  |  | q
 |  | 0 | 1 | 2 | 3
 |  | 13 | 20 | 31 | 46
 | 0 | 36 | 56 | 92 | 144
 |  | 85 | 124 | 199 | 310
 |  | 19 | 30 | 45 | 64
 | 1 | 52 | 88 | 140 | 208
 |  | 115 | 190 | 301 | 448
p
 |  | 35 | 50 | 69 | 92
 | 2 | 136 | 188 | 256 | 340
 |  | 397 | 508 | 655 | 838
 |  | 57 | 76 | 99 | 126
 | 3 | 268 | 336 | 420 | 520
 |  | 877 | 1024 | 1207 | 1426
Note that g13dx may be used to check whether a VARMA model is stationary and invertible.
The time taken depends on the values of p, q and especially n and k.

Example

Example program (C#): g05pje.cs

Example program data: g05pje.d

Example program results: g05pje.r

See Also

G05 Class
G05 Members


g05pm Method

[image]

NAG Library for .NET Release 2
G05..::g05pm Method
G05 Class See Also Send Feedback
g05pm simulates from an exponential smoothing model, where the model uses either single exponential, double exponential or a Holt–Winters method.

Syntax

C#
public static void g05pm(
    int mode,
    int n,
    int itype,
    int p,
    double[] param,
    double[] init,
    double var,
    double[] r,
    G05..::..G05State g05state,
    double[] e,
    int en,
    double[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05pm ( _
    mode As Integer, _
    n As Integer, _
    itype As Integer, _
    p As Integer, _
    param As Double(), _
    init As Double(), _
    var As Double, _
    r As Double(), _
    g05state As G05..::..G05State, _
    e As Double(), _
    en As Integer, _
    x As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05pm(
    int mode,
    int n,
    int itype,
    int p,
    array<double>^ param,
    array<double>^ init,
    double var,
    array<double>^ r,
    G05..::..G05State^ g05state,
    array<double>^ e,
    int en,
    array<double>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05pm :
        mode : int *
        n : int *
        itype : int *
        p : int *
        param : float[] *
        init : float[] *
        var : float *
        r : float[] *
        g05state : G05..::..G05State *
        e : float[] *
        en : int *
        x : float[] *
        ifail : int byref -> unit

Parameters

mode
Type: System..::..Int32
On entry: indicates if g05pm is continuing from a previous call or, if not, how the initial values are computed.
mode=0
Values for m 0, r 0 and s-j, for j=0,1,…,p-1, are supplied in init.
mode=1
g05pm continues from a previous call using values that are supplied in r. r is not updated.
mode=2
g05pm continues from a previous call using values that are supplied in r. r is updated.
Constraint: mode=0, 1 or 2.
n
Type: System..::..Int32
On entry: the number of terms of the time series being generated.
Constraint: n≥0.
itype
Type: System..::..Int32
On entry: the smoothing function.
itype=1
Single exponential.
itype=2
Brown's double exponential.
itype=3
Linear Holt.
itype=4
Additive Holt–Winters.
itype=5
Multiplicative Holt–Winters.
Constraint: itype=1, 2, 3, 4 or 5.
p
Type: System..::..Int32
On entry: if itype=4 or 5, the seasonal order, p, otherwise p is not referenced.
Constraint: if itype=4 or 5, p>1.
param
Type: array< System..::..Double >[]()[][]
An array of size [_lparam]
Note: the dimension of the array param must be at least 1 if itype=1 or 2, 3 if itype=3 and at least 4 if itype=4 or 5.
On entry: the smoothing parameters.
If itype=1 or 2, param[0]=α and any remaining elements of param are not referenced.
If itype=3, param[0]=α, param[1]=γ, param[2]=ϕ and any remaining elements of param are not referenced.
If itype=4 or 5, param[0]=α, param[1]=γ, param[2]=β and param[3]=ϕ and any remaining elements of param are not referenced.
Constraints:
  • if itype=1, 0.0≤α≤1.0;
  • if itype=2, 0.0<α≤1.0;
  • if itype=3, 0.0≤α≤1.0 and 0.0≤γ≤1.0 and ϕ≥0.0;
  • if itype=4 or 5, 0.0≤α≤1.0 and 0.0≤γ≤1.0 and 0.0≤β≤1.0 and ϕ≥0.0.
init
Type: array< System..::..Double >[]()[][]
An array of size [_linit]
Note: the dimension of the array init must be at least 1 if itype=1, 2 if itype=2 or 3 and at least 2+p if itype=4 or 5.
On entry: if mode=0, the initial values for m 0, r 0 and s-j, for j=0,1,…,p-1, used to initialize the smoothing.
If itype=1, init[0]=m 0 and any remaining elements of init are not referenced.
If itype=2 or 3, init[0]=m 0 and init[1]=r 0 and any remaining elements of init are not referenced.
If itype=4 or 5, init[0]=m 0, init[1]=r 0 and init[2] to init[2+p-1] hold the values for s-j, for j=0,1,…,p-1. Any remaining elements of init are not referenced.
var
Type: System..::..Double
On entry: the variance, σ 2 of the Normal distribution used to generate the errors εi. If var≤0.0 then Normally distributed errors are not used.
r
Type: array< System..::..Double >[]()[][]
An array of size [_lr]
Note: the dimension of the array r must be at least 13 if itype=1, 2 or 3 and at least 13+p if itype=4 or 5.
On entry: if mode=1 or 2, r must contain the values as returned by a previous call to g05pm, r need not be set otherwise.
On exit: if mode=1, r is unchanged. Otherwise, r contains the information on the current state of smoothing.
Constraint: if mode=1 or 2, r must have been initialized by at least one call to g05pm or g13am with mode≠1, and r must not have been changed since that call.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
e
Type: array< System..::..Double >[]()[][]
An array of size [en]
On entry: if en>0 and var≤0.0, a vector from which the errors, εt are randomly drawn, with replacement.
If en≤0, e is not referenced.
en
Type: System..::..Int32
On entry: if en>0, then the length of the vector e.
If both var≤0.0 and en≤0 then εt=0.0, for t=1,2,…,n.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the generated time series, xt, for t=1,2,…,n.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g05pm returns xt:t=1,2,…,n, a realization of a time series from an exponential smoothing model defined by one of five smoothing functions:
  • Single Exponential Smoothing
    xt=m t-1+εtmt=α xt+1-α m t-1
  • Brown Double Exponential Smoothing
    xt=m t-1+r t-1 α+εtmt=α xt+1-α m t-1rt=α mt-m t-1+1-α r t-1
  • Linear Holt Exponential Smoothing
    xt=m t-1+ϕ r t-1+εtmt=α xt+1-αm t-1+ϕ r t-1rt=γ mt-m t-1+1-γ ϕ r t-1
  • Additive Holt–Winters Smoothing
    xt=m t-1+ϕ r t-1+s t-1-p+εtmt=α xt-s t-p+1-αm t-1+ϕ r t-1rt=γ mt-m t-1+1-γ ϕ r t-1st=β xt-mt+1-β s t-p
  • Multiplicative Holt–Winters Smoothing
    xt=m t-1+ϕ r t-1×s t-1-p+εtmt=α xt/s t-p+1-αm t-1+ϕ r t-1rt=γ mt-m t-1+1-γ ϕ r t-1st=β xt/mt+1-β s t-p
where mt is the mean, rt is the trend and st is the seasonal component at time t with p being the seasonal order. The errors, εt are either drawn from a normal distribution with mean zero and variance σ 2 or randomly sampled, with replacement, from a user-supplied vector.

References

Chatfield C (1980) The Analysis of Time Series Chapman and Hall

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, mode≠0, 1 or 2.
ifail=2
On entry, itype≠1, 2, 3, 4 or 5.
ifail=3
On entry, itype=4 or 5 and p<2.
ifail=4
On entry, at least one of α, β or γ>0.0 or >1.0.
On entry, itype=2 and α=0.0.
On entry, ϕ<0.0.
ifail=5
On entry, n<0.
ifail=8
On entry, mode=1 or 2 and the array r has not been initialized correctly.
ifail=9
On entry, the array state has not been initialized correctly.
ifail=12
itype=5 and model is unsuitable for multiplicative Holt–Winter.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

g05pm is then called multiple times to obtain simulated forecast confidence intervals.

Example program (C#): g05pme.cs

Example program data: g05pme.d

Example program results: g05pme.r

See Also

G05 Class
G05 Members


g05px Method

[image]

NAG Library for .NET Release 2
G05..::g05px Method
G05 Class See Also Send Feedback
g05px generates a random orthogonal matrix.

Syntax

C#
public static void g05px(
    string side,
    string init,
    int m,
    int n,
    G05..::..G05State g05state,
    double[,] a,
    out int ifail
)
Visual Basic
Public Shared Sub g05px ( _
    side As String, _
    init As String, _
    m As Integer, _
    n As Integer, _
    g05state As G05..::..G05State, _
    a As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05px(
    String^ side,
    String^ init,
    int m,
    int n,
    G05..::..G05State^ g05state,
    array<double,2>^ a,
    [OutAttribute] int% ifail
)
F#
static member g05px :
        side : string *
        init : string *
        m : int *
        n : int *
        g05state : G05..::..G05State *
        a : float[,] *
        ifail : int byref -> unit

Parameters

side
Type: System..::..String
On entry: indicates whether the matrix A is multiplied on the left or right by the random orthogonal matrix U.
side="L"
The matrix A is multiplied on the left, i.e., premultiplied.
side="R"
The matrix A is multiplied on the right, i.e., post-multiplied.
Constraint: side="L" or "R".
init
Type: System..::..String
On entry: indicates whether or not a should be initialized to the identity matrix.
init="I"
a is initialized to the identity matrix.
init="N"
a is not initialized and the matrix A must be supplied in a.
Constraint: init="I" or "N".
m
Type: System..::..Int32
On entry: m, the number of rows of the matrix A.
Constraints:
  • if side="L", m>1;
  • otherwise m≥1.
n
Type: System..::..Int32
On entry: n, the number of columns of the matrix A.
Constraints:
  • if side="R", n>1;
  • otherwise n≥1.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥m
On entry: if init="N", a must contain the matrix A.
On exit: the matrix UA when side="L" or the matrix AU when side="R".
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g05px pre- or post-multiplies an m by n matrix A by a random orthogonal matrix U, overwriting A. The matrix A may optionally be initialized to the identity matrix before multiplying by U, hence U is returned. U is generated using the method of Stewart (1980). The algorithm can be summarised as follows.
Let x 1,x 2,…,x n-1 follow independent multinormal distributions with zero mean and variance I σ 2 and dimensions n,n-1,…,2; let Hj=diag I j-1,Hj*, where I j-1 is the identity matrix and Hj* is the Householder transformation that reduces xj to r jje 1, e 1 being the vector with first element one and the remaining elements zero and r jj being a scalar, and let D=diag sign r 11,sign r 22,…,sign r nn. Then the product U=D H 1H 2…H n-1 is a random orthogonal matrix distributed according to the Haar measure over the set of orthogonal matrices of n. See Theorem 3.3 in Stewart (1980).
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05px.

References

Stewart G W (1980) The efficient generation of random orthogonal matrices with an application to condition estimates SIAM J. Numer. Anal. 17 403–409

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, side≠"L" or "R".
ifail=2
On entry, init≠"I" or "N".
ifail=3
On entry, m<1.
ifail=4
On entry, n<1.
ifail=5
On entry, state vector was not initialized or has been corrupted.
ifail=8
On entry, an orthogonal matrix of dimension 1 has been requested.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The maximum error in UT U should be a modest multiple of machine precision (see X02 class).

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05pxe.cs

Example program data: g05pxe.d

Example program results: g05pxe.r

See Also

G05 Class
G05 Members


g05py Method

[image]

NAG Library for .NET Release 2
G05..::g05py Method
G05 Class See Also Send Feedback
g05py generates a random correlation matrix with given eigenvalues.

Syntax

C#
public static void g05py(
    int n,
    double[] d,
    double eps,
    G05..::..G05State g05state,
    double[,] c,
    out int ifail
)
Visual Basic
Public Shared Sub g05py ( _
    n As Integer, _
    d As Double(), _
    eps As Double, _
    g05state As G05..::..G05State, _
    c As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05py(
    int n,
    array<double>^ d,
    double eps,
    G05..::..G05State^ g05state,
    array<double,2>^ c,
    [OutAttribute] int% ifail
)
F#
static member g05py :
        n : int *
        d : float[] *
        eps : float *
        g05state : G05..::..G05State *
        c : float[,] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the dimension of the correlation matrix to be generated.
Constraint: n≥1.
d
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the n eigenvalues, λi, for i=1,2,…,n.
Constraints:
  • d[i-1]≥0.0, for i=1,2,…,n;
  • ∑i=1 nd[i-1]=n to within eps.
eps
Type: System..::..Double
On entry: the maximum acceptable error in the diagonal elements.
Suggested value: eps=0.00001.
Constraint: eps≥n×machine precision (see X02 class).
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
c
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: a random correlation matrix, C, of dimension n.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Given n eigenvalues, λ 1,λ 2,…,λn, such that
∑i=1 n λi=n
and
λi≥0,  i=1,2,…,n,
g05py will generate a random correlation matrix, C, of dimension n, with eigenvalues λ 1,λ 2,…,λn.
The method used is based on that described by Lin and Bendel (1985). Let D be the diagonal matrix with values λ 1,λ 2,…,λn and let A be a random orthogonal matrix generated by g05px then the matrix C 0=AD AT is a random covariance matrix with eigenvalues λ 1,λ 2,…,λn. The matrix C 0 is transformed into a correlation matrix by means of n-1 elementary rotation matrices Pi such that C=P n-1P n-2…P 1C 0 P 1 T…P n-2 TP n-1 T. The restriction on the sum of eigenvalues implies that for any diagonal element of C 0>1, there is another diagonal element <1. The Pi are constructed from such pairs, chosen at random, to produce a unit diagonal element corresponding to the first element. This is repeated until all diagonal elements are 1 to within a given tolerance ε.
The randomness of C should be interpreted only to the extent that A is a random orthogonal matrix and C is computed from A using the Pi which are chosen as arbitrarily as possible.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05py.

References

Lin S P and Bendel R B (1985) Algorithm AS 213: Generation of population correlation on matrices with specified eigenvalues Appl. Statist. 34 193–198

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDC) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, n<1.
ifail=2
On entry, | d[i-1]<0.0 for some i,
or | ∑i=1 n d[i-1]≠n.
ifail=3
On entry, eps<n×machine precision.
ifail=4
On entry, state vector was not initialized or has been corrupted.
ifail=5
The error in a diagonal element is greater than eps. The value of eps should be increased. Otherwise the program could be rerun with a different value used for the seed of the random number generator, see (G05KFF not in this release) (G05KGF not in this release).
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The maximum error in a diagonal element is given by eps.

Parallelism and Performance

None.

Further Comments

The time taken by g05py is approximately proportional to n 2.

Example

Example program (C#): g05pye.cs

Example program data: g05pye.d

Example program results: g05pye.r

See Also

G05 Class
G05 Members


g05pz Method

[image]

NAG Library for .NET Release 2
G05..::g05pz Method
G05 Class See Also Send Feedback
g05pz generates a random two-way table.

Syntax

C#
public static void g05pz(
    int mode,
    int nrow,
    int ncol,
    int[] totr,
    int[] totc,
    double[] r,
    G05..::..G05State g05state,
    int[,] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05pz ( _
    mode As Integer, _
    nrow As Integer, _
    ncol As Integer, _
    totr As Integer(), _
    totc As Integer(), _
    r As Double(), _
    g05state As G05..::..G05State, _
    x As Integer(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05pz(
    int mode,
    int nrow,
    int ncol,
    array<int>^ totr,
    array<int>^ totc,
    array<double>^ r,
    G05..::..G05State^ g05state,
    array<int,2>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05pz :
        mode : int *
        nrow : int *
        ncol : int *
        totr : int[] *
        totc : int[] *
        r : float[] *
        g05state : G05..::..G05State *
        x : int[,] *
        ifail : int byref -> unit

Parameters

mode
Type: System..::..Int32
On entry: a code for selecting the operation to be performed by the method.
mode=0
Set up reference vector only.
mode=1
Generate two-way table using reference vector set up in a prior call to g05pz.
mode=2
Set up reference vector and generate two-way table.
Constraint: mode=0, 1 or 2.
nrow
Type: System..::..Int32
On entry: m, the number of rows in the table.
Constraint: nrow≥2.
ncol
Type: System..::..Int32
On entry: n, the number of columns in the table.
Constraint: ncol≥2.
totr
Type: array< System..::..Int32 >[]()[][]
An array of size [nrow]
On entry: the m row totals, Ri, for i=1,2,…,m.
Constraints:
  • totr[i-1]≥0, for i=1,2,…,m;
  • ∑i=1 m totr[i-1]=∑j=1 n totc[j-1];
  • ∑i totr[i-1]>0, for i=1,2,…,m.
totc
Type: array< System..::..Int32 >[]()[][]
An array of size [ncol]
On entry: the n column totals, Cj, for j=1,2,…,n.
Constraints:
  • totc[j-1]≥0, for j=1,2,…,n;
  • ∑j=1 n totc[j-1]=∑i=1 m totr[i-1].
r
Type: array< System..::..Double >[]()[][]
An array of size [lr]
On entry: if mode=1, the reference vector from the previous call to g05pz.
On exit: the reference vector.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Int32 ,2>[,](,)[,][,]
An array of size [dim1, ncol]
Note: dim1 must satisfy the constraint: dim1≥nrow
On exit: if mode=1 or 2, a pseudorandom two-way m by n table, X, with element x[i-1,j-1] containing the i,jth entry in the table such that ∑ i=1 m x[i-1,j-1]=totc[j-1] and ∑ j=1 n x[i-1,j-1]=totr[i-1]
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Given m row totals Ri and n column totals Cj (with ∑i=1 m Ri=∑j=1 n Cj=T, say), g05pz will generate a pseudorandom two-way table of integers such that the row and column totals are satisfied.
The method used is based on that described by Patefield (1981) which is most efficient when T is large relative to the number of table entries m×n (i.e., T>2 mn). Entries are generated one row at a time and one entry at a time within a row. Each entry is generated using the conditional probability distribution for that entry given the entries in the previous rows and the previous entries in the same row.
A reference vector is used to store computed values that can be reused in the generation of new tables with the same row and column totals. g05pz can be called to simply set up the reference vector, or to generate a two-way table using a reference vector set up in a previous call, or it can combine both functions in a single call.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05pz.

References

Patefield W M (1981) An efficient method of generating R×C tables with given row and column totals Appl. Stats. 30 91–97

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, mode≠0, 1 or 2.
ifail=2
On entry, nrow<2.
ifail=3
On entry, ncol<2.
ifail=4
At least one element of totr is negative.
ifail=5
At least one element of totc is negative.
ifail=6
The value of nrow or ncol is not the same as when r was set up in a previous call to g05pz with mode=0 or 2.
ifail=7
On entry, lr is too small when mode=0 or 2 (see [Parameters]).
ifail=8
On entry, state vector was not initialized or has been corrupted.
ifail=15
The arrays totr and totc do not sum to the same total.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

None.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05pze.cs

Example program data: g05pze.d

Example program results: g05pze.r

See Also

G05 Class
G05 Members


g05rc Method

[image]

NAG Library for .NET Release 2
G05..::g05rc Method
G05 Class See Also Send Feedback
g05rc sets up a reference vector and generates an array of pseudorandom numbers from a Student's t copula with ν degrees of freedom and covariance matrix ν ν-2 C.

Syntax

C#
public static void g05rc(
    int mode,
    int n,
    int df,
    int m,
    double[,] c,
    double[] r,
    G05..::..G05State g05state,
    double[,] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05rc ( _
    mode As Integer, _
    n As Integer, _
    df As Integer, _
    m As Integer, _
    c As Double(,), _
    r As Double(), _
    g05state As G05..::..G05State, _
    x As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05rc(
    int mode,
    int n,
    int df,
    int m,
    array<double,2>^ c,
    array<double>^ r,
    G05..::..G05State^ g05state,
    array<double,2>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05rc :
        mode : int *
        n : int *
        df : int *
        m : int *
        c : float[,] *
        r : float[] *
        g05state : G05..::..G05State *
        x : float[,] *
        ifail : int byref -> unit

Parameters

mode
Type: System..::..Int32
On entry: a code for selecting the operation to be performed by the method.
mode=0
Set up reference vector only.
mode=1
Generate variates using reference vector set up in a prior call to g05rc.
mode=2
Set up reference vector and generate variates.
Constraint: mode=0, 1 or 2.
n
Type: System..::..Int32
On entry: n, the number of random variates required.
Constraint: n≥0.
df
Type: System..::..Int32
On entry: ν, the number of degrees of freedom of the distribution.
Constraint: df≥3.
m
Type: System..::..Int32
On entry: m, the number of dimensions of the distribution.
Constraint: m>0.
c
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On entry: matrix which, along with df, defines the covariance of the distribution. Only the upper triangle need be set.
Constraint: C must be positive semidefinite to machine precision.
r
Type: array< System..::..Double >[]()[][]
An array of size [lr]
On entry: if mode=1, the reference vector as set up by g05rc in a previous call with mode=0 or 2.
On exit: if mode=0 or 2, the reference vector that can be used in subsequent calls to g05rc with mode=1.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, _tdx]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: the array of values from a multivariate Student's t copula, with x[i-1,j-1] holding the jth dimension for the ith variate.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The Student's t copula, G, is defined by
G u 1,u 2,…,um;C=T ν,C m t ν,C 11-1 u 1,t ν,C 22-1 u 2,…,t ν,Cmm-1 um
where m is the number of dimensions, T ν,C m is the multivariate Student's t density function with ν degrees of freedom, mean zero and covariance matrix ν ν-2 C and t ν,Cii-1 is the inverse of the univariate Student's t density function with ν degrees of freedom, zero mean and variance ν ν-2 Cii.
g05ry is used to generate a vector from a multivariate Student's t distribution and g01eb is used to convert each element of that vector into a uniformly distributed value between zero and one.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05rc.

References

Nelsen R B (1998) An Introduction to Copulas. Lecture Notes in Statistics 139 Springer
Sklar A (1973) Random variables: joint distribution functions and copulas Kybernetika 9 499–460

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDC, LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, mode≠0, 1 or 2.
ifail=2
On entry, n<0.
ifail=3
On entry, df≤2.
ifail=4
On entry, m<1.
ifail=5
The covariance matrix C is not positive semidefinite to machine precision.
ifail=6
On entry, ldc<m.
ifail=7
The reference vector r has been corrupted or m has changed since r was set up in a previous call to g05rc with mode=0 or 2.
ifail=8
On entry, lr≤m×m+1+1.
ifail=9
On entry, state vector was not initialized or has been corrupted.
ifail=11
On entry, ldx<n.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

See [Accuracy] in g05ry for an indication of the accuracy of the underlying multivariate Student's t-distribution.

Parallelism and Performance

None.

Further Comments

The time taken by g05rc is of order n⁢m 3.
It is recommended that the diagonal elements of C should not differ too widely in order of magnitude. This may be achieved by scaling the variables if necessary. The actual matrix decomposed is C+E=L LT, where E is a diagonal matrix with small positive diagonal elements. This ensures that, even when C is singular, or nearly singular, the Cholesky factor L corresponds to a positive definite covariance matrix that agrees with C within machine precision.

Example

Example program (C#): g05rce.cs

Example program data: g05rce.d

Example program results: g05rce.r

See Also

G05 Class
G05 Members


g05rd Method

[image]

NAG Library for .NET Release 2
G05..::g05rd Method
G05 Class See Also Send Feedback
g05rd sets up a reference vector and generates an array of pseudorandom numbers from a Normal (Gaussian) copula with covariance matrix C.

Syntax

C#
public static void g05rd(
    int mode,
    int n,
    int m,
    double[,] c,
    double[] r,
    G05..::..G05State g05state,
    double[,] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05rd ( _
    mode As Integer, _
    n As Integer, _
    m As Integer, _
    c As Double(,), _
    r As Double(), _
    g05state As G05..::..G05State, _
    x As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05rd(
    int mode,
    int n,
    int m,
    array<double,2>^ c,
    array<double>^ r,
    G05..::..G05State^ g05state,
    array<double,2>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05rd :
        mode : int *
        n : int *
        m : int *
        c : float[,] *
        r : float[] *
        g05state : G05..::..G05State *
        x : float[,] *
        ifail : int byref -> unit

Parameters

mode
Type: System..::..Int32
On entry: a code for selecting the operation to be performed by the method.
mode=0
Set up reference vector only.
mode=1
Generate variates using reference vector set up in a prior call to g05rd.
mode=2
Set up reference vector and generate variates.
Constraint: mode=0, 1 or 2.
n
Type: System..::..Int32
On entry: n, the number of random variates required.
Constraint: n≥0.
m
Type: System..::..Int32
On entry: m, the number of dimensions of the distribution.
Constraint: m>0.
c
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On entry: the covariance matrix of the distribution. Only the upper triangle need be set.
Constraint: C must be positive semidefinite to machine precision.
r
Type: array< System..::..Double >[]()[][]
An array of size [lr]
On entry: if mode=1, the reference vector as set up by g05rd in a previous call with mode=0 or 2.
On exit: if mode=0 or 2, the reference vector that can be used in subsequent calls to g05rd with mode=1.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, _tdx]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: the array of values from a multivariate Gaussian copula, with x[i-1,j-1] holding the jth dimension for the ith variate.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The Gaussian copula, G, is defined by
G u 1,u 2,…,um;C=ΦC ϕ C 11-1 u 1,ϕ C 22-1 u 2,…,ϕ Cmm-1 um
where m is the number of dimensions, ΦC is the multivariate Normal density function with mean zero and covariance matrix C and ϕ Cii-1 is the inverse of the univariate Normal density function with mean zero and variance Cii.
g05rz is used to generate a vector from a multivariate Normal distribution and g01ea is used to convert each element of that vector into a uniformly distributed value between zero and one.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05rd.

References

Nelsen R B (1998) An Introduction to Copulas. Lecture Notes in Statistics 139 Springer
Sklar A (1973) Random variables: joint distribution functions and copulas Kybernetika 9 499–460

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDC, LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, mode≠0, 1 or 2.
ifail=2
On entry, n<0.
ifail=3
On entry, m<1.
ifail=4
The covariance matrix C is not positive semidefinite to machine precision.
ifail=5
On entry, ldc<m.
ifail=6
The reference vector r has been corrupted or m has changed since r was set up in a previous call to g05rd with mode=0 or 2.
ifail=7
On entry, lr≤m×m+1.
ifail=8
On entry, state vector was not initialized or has been corrupted.
ifail=10
On entry, ldx<n.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

See [Accuracy] in g05rz for an indication of the accuracy of the underlying multivariate Normal distribution.

Parallelism and Performance

None.

Further Comments

The time taken by g05rd is of order n⁢m 3.
It is recommended that the diagonal elements of C should not differ too widely in order of magnitude. This may be achieved by scaling the variables if necessary. The actual matrix decomposed is C+E=L LT, where E is a diagonal matrix with small positive diagonal elements. This ensures that, even when C is singular, or nearly singular, the Cholesky factor L corresponds to a positive definite covariance matrix that agrees with C within machine precision.

Example

Example program (C#): g05rde.cs

Example program data: g05rde.d

Example program results: g05rde.r

See Also

G05 Class
G05 Members


g05ry Method

[image]

NAG Library for .NET Release 2
G05..::g05ry Method
G05 Class See Also Send Feedback
g05ry sets up a reference vector and generates an array of pseudorandom numbers from a multivariate Student's t distribution with ν degrees of freedom, mean vector a and covariance matrix ν ν-2 C.

Syntax

C#
public static void g05ry(
    int mode,
    int n,
    int df,
    int m,
    double[] xmu,
    double[,] c,
    double[] r,
    G05..::..G05State g05state,
    double[,] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05ry ( _
    mode As Integer, _
    n As Integer, _
    df As Integer, _
    m As Integer, _
    xmu As Double(), _
    c As Double(,), _
    r As Double(), _
    g05state As G05..::..G05State, _
    x As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05ry(
    int mode,
    int n,
    int df,
    int m,
    array<double>^ xmu,
    array<double,2>^ c,
    array<double>^ r,
    G05..::..G05State^ g05state,
    array<double,2>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05ry :
        mode : int *
        n : int *
        df : int *
        m : int *
        xmu : float[] *
        c : float[,] *
        r : float[] *
        g05state : G05..::..G05State *
        x : float[,] *
        ifail : int byref -> unit

Parameters

mode
Type: System..::..Int32
On entry: a code for selecting the operation to be performed by the method.
mode=0
Set up reference vector only.
mode=1
Generate variates using reference vector set up in a prior call to g05ry.
mode=2
Set up reference vector and generate variates.
Constraint: mode=0, 1 or 2.
n
Type: System..::..Int32
On entry: n, the number of random variates required.
Constraint: n≥0.
df
Type: System..::..Int32
On entry: ν, the number of degrees of freedom of the distribution.
Constraint: df≥3.
m
Type: System..::..Int32
On entry: m, the number of dimensions of the distribution.
Constraint: m>0.
xmu
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: a, the vector of means of the distribution.
c
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On entry: matrix which, along with df, defines the covariance of the distribution. Only the upper triangle need be set.
Constraint: c must be positive semidefinite to machine precision.
r
Type: array< System..::..Double >[]()[][]
An array of size [lr]
On entry: if mode=1, the reference vector as set up by g05ry in a previous call with mode=0 or 2.
On exit: if mode=0 or 2, the reference vector that can be used in subsequent calls to g05ry with mode=1.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, _tdx]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: the array of pseudorandom multivariate Student's t vectors generated by the method, with x[i-1,j-1] holding the jth dimension for the ith variate.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

When the covariance matrix is nonsingular (i.e., strictly positive definite), the distribution has probability density function
f x=Γ ν+m 2πv m/2 Γ ν/2 C 12 1+x-a TC-1 x-a ν-ν+m 2
where m is the number of dimensions, ν is the degrees of freedom, a is the vector of means, x is the vector of positions and ν ν-2 C is the covariance matrix.
The method returns the value
x=a+νs z
where z is generated by g05sk from a Normal distribution with mean zero and covariance matrix C and s is generated by g05sd from a χ 2-distribution with ν degrees of freedom.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05ry.

References

Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley
Wilkinson J H (1965) The Algebraic Eigenvalue Problem Oxford University Press, Oxford

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDC, LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, mode≠0, 1 or 2.
ifail=2
On entry, n<0.
ifail=3
On entry, df≤2.
ifail=4
On entry, m<1.
ifail=6
The covariance matrix c is not positive semidefinite to machine precision.
ifail=7
On entry, ldc<m.
ifail=8
The reference vector r has been corrupted or m has changed since r was set up in a previous call to g05ry with mode=0 or 2.
ifail=9
On entry, lr≤m×m+1+1.
ifail=10
On entry, state vector was not initialized or has been corrupted.
ifail=12
On entry, ldx<n.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

The time taken by g05ry is of order n⁢m 3.
It is recommended that the diagonal elements of C should not differ too widely in order of magnitude. This may be achieved by scaling the variables if necessary. The actual matrix decomposed is C+E=L LT, where E is a diagonal matrix with small positive diagonal elements. This ensures that, even when C is singular, or nearly singular, the Cholesky factor L corresponds to a positive definite covariance matrix that agrees with C within machine precision.

Example

Example program (C#): g05rye.cs

Example program data: g05rye.d

Example program results: g05rye.r

See Also

G05 Class
G05 Members


g05rz Method

[image]

NAG Library for .NET Release 2
G05..::g05rz Method
G05 Class See Also Send Feedback
g05rz sets up a reference vector and generates an array of pseudorandom numbers from a multivariate Normal distribution with mean vector a and covariance matrix C.

Syntax

C#
public static void g05rz(
    int mode,
    int n,
    int m,
    double[] xmu,
    double[,] c,
    double[] r,
    G05..::..G05State g05state,
    double[,] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05rz ( _
    mode As Integer, _
    n As Integer, _
    m As Integer, _
    xmu As Double(), _
    c As Double(,), _
    r As Double(), _
    g05state As G05..::..G05State, _
    x As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05rz(
    int mode,
    int n,
    int m,
    array<double>^ xmu,
    array<double,2>^ c,
    array<double>^ r,
    G05..::..G05State^ g05state,
    array<double,2>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05rz :
        mode : int *
        n : int *
        m : int *
        xmu : float[] *
        c : float[,] *
        r : float[] *
        g05state : G05..::..G05State *
        x : float[,] *
        ifail : int byref -> unit

Parameters

mode
Type: System..::..Int32
On entry: a code for selecting the operation to be performed by the method.
mode=0
Set up reference vector only.
mode=1
Generate variates using reference vector set up in a prior call to g05rz.
mode=2
Set up reference vector and generate variates.
Constraint: mode=0, 1 or 2.
n
Type: System..::..Int32
On entry: n, the number of random variates required.
Constraint: n≥0.
m
Type: System..::..Int32
On entry: m, the number of dimensions of the distribution.
Constraint: m>0.
xmu
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: a, the vector of means of the distribution.
c
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On entry: the covariance matrix of the distribution. Only the upper triangle need be set.
Constraint: C must be positive semidefinite to machine precision.
r
Type: array< System..::..Double >[]()[][]
An array of size [lr]
On entry: if mode=1, the reference vector as set up by g05rz in a previous call with mode=0 or 2.
On exit: if mode=0 or 2, the reference vector that can be used in subsequent calls to g05rz with mode=1.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, _tdx]
Note: dim1 must satisfy the constraint: dim1≥n
  • if mode=1 or 2, dim1≥n;
  • if mode=3 or 4, dim1≥m.
On exit: the array of pseudorandom multivariate Normal vectors generated by the method.
Two possible storage orders are available. If mode=1 or 2 then x[i-1,j-1] holds the jth dimension for the ith variate. If mode=3 or 4 this ordering is reversed and x[j-1,i-1] holds the jth dimension for the ith variate.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

When the covariance matrix is nonsingular (i.e., strictly positive definite), the distribution has probability density function
f x=C-12 π m exp-12 x-a TC-1 x-a
where m is the number of dimensions, C is the covariance matrix, a is the vector of means and x is the vector of positions.
Covariance matrices are symmetric and positive semidefinite. Given such a matrix C, there exists a lower triangular matrix L such that L LT=C. L is not unique, if C is singular.
g05rz decomposes C to find such an L. It then stores m, a and L in the reference vector r which is used to generate a vector x of independent standard Normal pseudorandom numbers. It then returns the vector a+Lx, which has the required multivariate Normal distribution.
It should be noted that this method will work with a singular covariance matrix C, provided C is positive semidefinite, despite the fact that the above formula for the probability density function is not valid in that case. Wilkinson (1965) should be consulted if further information is required.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05rz.

References

Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley
Wilkinson J H (1965) The Algebraic Eigenvalue Problem Oxford University Press, Oxford

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDC, LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, mode=value.
Constraint: mode=0, 1 or 2.
ifail=2
On entry, n=value.
Constraint: n≥0.
ifail=3
On entry, m=value.
Constraint: m>0.
ifail=5
On entry, the covariance matrix C is not positive semidefinite to machine precision.
ifail=6
On entry, ldc=value and m=value.
Constraint: ldc≥m.
ifail=7
m is not the same as when r was set up in a previous call.
Previous value of m=value and m=value.
ifail=8
On entry, lr is not large enough, lr=value: minimum length required =value.
ifail=9
On entry, state vector has been corrupted or not initialized.
ifail=11
On entry, ldx=value and m=value.
Constraint: ldx≥m.
On entry, ldx=value and n=value.
Constraint: ldx≥n.
ifail=12
On entry, _tdx=value and m=value.
Constraint: _sorder≠1 or _tdx≥m.
ifail=22
On entry,_tdx=value and n=value.
Constraint: _sorder=1 or _tdx≥n.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

The time taken by g05rz is of order n⁢m 3.
It is recommended that the diagonal elements of C should not differ too widely in order of magnitude. This may be achieved by scaling the variables if necessary. The actual matrix decomposed is C+E=L LT, where E is a diagonal matrix with small positive diagonal elements. This ensures that, even when C is singular, or nearly singular, the Cholesky factor L corresponds to a positive definite covariance matrix that agrees with C within machine precision.

Example

Example program (C#): g05rze.cs

Example program data: g05rze.d

Example program results: g05rze.r

See Also

G05 Class
G05 Members


g05sa Method

[image]

NAG Library for .NET Release 2
G05..::g05sa Method
G05 Class See Also Send Feedback
g05sa generates a vector of pseudorandom numbers taken from a uniform distribution between 0 and 1.

Syntax

C#
public static void g05sa(
    int n,
    G05..::..G05State g05state,
    double[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05sa ( _
    n As Integer, _
    g05state As G05..::..G05State, _
    x As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05sa(
    int n,
    G05..::..G05State^ g05state,
    array<double>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05sa :
        n : int *
        g05state : G05..::..G05State *
        x : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the n pseudorandom numbers from a uniform distribution over the half closed interval 0,1.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g05sa generates n values from a uniform distribution over the half closed interval 0,1.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05sa.

References

Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<0.
ifail=2
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05sae.cs

Example program data: g05sae.d

Example program results: g05sae.r

See Also

G05 Class
G05 Members


g05sb Method

[image]

NAG Library for .NET Release 2
G05..::g05sb Method
G05 Class See Also Send Feedback
g05sb generates a vector of pseudorandom numbers taken from a beta distribution with parameters a and b.

Syntax

C#
public static void g05sb(
    int n,
    double a,
    double b,
    G05..::..G05State g05state,
    double[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05sb ( _
    n As Integer, _
    a As Double, _
    b As Double, _
    g05state As G05..::..G05State, _
    x As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05sb(
    int n,
    double a,
    double b,
    G05..::..G05State^ g05state,
    array<double>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05sb :
        n : int *
        a : float *
        b : float *
        g05state : G05..::..G05State *
        x : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
a
Type: System..::..Double
On entry: a, the parameter of the beta distribution.
Constraint: a>0.0.
b
Type: System..::..Double
On entry: b, the parameter of the beta distribution.
Constraint: b>0.0.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the n pseudorandom numbers from the specified beta distribution.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The beta distribution has PDF (probability density function)
f x=Γ a+bΓ a Γ b x a-11-x b-1if 0≤x≤1; ​a,b>0,f x=0otherwise.
One of four algorithms is used to generate the variates depending on the values of a and b. Let α be the maximum and β be the minimum of a and b. Then the algorithms are as follows:
(i) | if α<0.5, Johnk's algorithm is used, see for example Dagpunar (1988). This generates the beta variate as u 1 1/a/u 1 1/a+u 2 1/b, where u 1 and u 2 are uniformly distributed random variates;
(ii) | if β>1, the algorithm BB given by Cheng (1978) is used. This involves the generation of an observation from a beta distribution of the second kind by the envelope rejection method using a log-logistic target distribution and then transforming it to a beta variate;
(iii) | if α>1 and β<1, the switching algorithm given by Atkinson (1979) is used. The two target distributions used are f 1 x=β xβ and f 2 x=α 1-x β-1, along with the approximation to the switching parameter of t=1-β/α+1-β;
(iv) | in all other cases, Cheng's BC algorithm (see Cheng (1978)) is used with modifications suggested by Dagpunar (1988). This algorithm is similar to BB, used when β>1, but is tuned for small values of a and b.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05sb.

References

Atkinson A C (1979) A family of switching algorithms for the computer generation of beta random variates Biometrika 66 141–5
Cheng R C H (1978) Generating beta variates with nonintegral shape parameters Comm. ACM 21 317–322
Dagpunar J (1988) Principles of Random Variate Generation Oxford University Press
Hastings N A J and Peacock J B (1975) Statistical Distributions Butterworth

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<0.
ifail=2
On entry, a≤0.0.
ifail=3
On entry, b≤0.0.
ifail=4
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

To generate an observation, y, from the beta distribution of the second kind from an observation, x, generated by g05sb the transformation, y=x/1-x, may be used.

Example

Example program (C#): g05sbe.cs

Example program data: g05sbe.d

Example program results: g05sbe.r

See Also

G05 Class
G05 Members


g05sc Method

[image]

NAG Library for .NET Release 2
G05..::g05sc Method
G05 Class See Also Send Feedback
g05sc generates a vector of pseudorandom numbers from a Cauchy distribution with median a and semi-interquartile range b.

Syntax

C#
public static void g05sc(
    int n,
    double xmed,
    double semiqr,
    G05..::..G05State g05state,
    double[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05sc ( _
    n As Integer, _
    xmed As Double, _
    semiqr As Double, _
    g05state As G05..::..G05State, _
    x As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05sc(
    int n,
    double xmed,
    double semiqr,
    G05..::..G05State^ g05state,
    array<double>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05sc :
        n : int *
        xmed : float *
        semiqr : float *
        g05state : G05..::..G05State *
        x : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
xmed
Type: System..::..Double
On entry: a, the median of the distribution.
semiqr
Type: System..::..Double
On entry: b, the semi-interquartile range of the distribution.
Constraint: semiqr≥0.0.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the n pseudorandom numbers from the specified Cauchy distribution.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The distribution has PDF (probability density function)
f x=1 πb 1+x-a b 2.
g05sc returns the value
a+b 2 y 1-1 y 2,
where y 1 and y 2 are a pair of consecutive pseudorandom numbers from a uniform distribution over 0,1, such that
2 y 1-1 2+y 22≤1.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05sc.

References

Kendall M G and Stuart A (1969) The Advanced Theory of Statistics (Volume 1) (3rd Edition) Griffin
Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<0.
ifail=3
On entry, semiqr<0.0.
ifail=4
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05sce.cs

Example program data: g05sce.d

Example program results: g05sce.r

See Also

G05 Class
G05 Members


g05sd Method

[image]

NAG Library for .NET Release 2
G05..::g05sd Method
G05 Class See Also Send Feedback
g05sd generates a vector of pseudorandom numbers taken from a χ 2-distribution with ν degrees of freedom.

Syntax

C#
public static void g05sd(
    int n,
    int df,
    G05..::..G05State g05state,
    double[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05sd ( _
    n As Integer, _
    df As Integer, _
    g05state As G05..::..G05State, _
    x As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05sd(
    int n,
    int df,
    G05..::..G05State^ g05state,
    array<double>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05sd :
        n : int *
        df : int *
        g05state : G05..::..G05State *
        x : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
df
Type: System..::..Int32
On entry: ν, the number of degrees of freedom of the distribution.
Constraint: df≥1.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the n pseudorandom numbers from the specified χ 2-distribution.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The distribution has PDF (probability density function)
f x=x ν/2-1×e-x/22 ν/2×ν/2-1!if ​x>0;f x=0otherwise.
This is the same as a gamma distribution with parameters ν/2 and 2.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05sd.

References

Kendall M G and Stuart A (1969) The Advanced Theory of Statistics (Volume 1) (3rd Edition) Griffin
Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<0.
ifail=2
On entry, df<1.
ifail=3
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

The time taken by g05sd increases with ν.

Example

Example program (C#): g05sde.cs

Example program data: g05sde.d

Example program results: g05sde.r

See Also

G05 Class
G05 Members


g05se Method

[image]

NAG Library for .NET Release 2
G05..::g05se Method
G05 Class See Also Send Feedback
g05se generates a vector of pseudorandom numbers taken from a Dirichlet distribution.

Syntax

C#
public static void g05se(
    int n,
    int m,
    double[] a,
    G05..::..G05State g05state,
    double[,] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05se ( _
    n As Integer, _
    m As Integer, _
    a As Double(), _
    g05state As G05..::..G05State, _
    x As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05se(
    int n,
    int m,
    array<double>^ a,
    G05..::..G05State^ g05state,
    array<double,2>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05se :
        n : int *
        m : int *
        a : float[] *
        g05state : G05..::..G05State *
        x : float[,] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
m
Type: System..::..Int32
On entry: m, the number of dimensions of the distribution.
Constraint: m>0.
a
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: the parameter vector for the distribution.
Constraint: a[i-1]>0.0, for i=1,2,…,m.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, _tdx]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: the n pseudorandom numbers from the specified Dirichlet distribution, with x[i-1,j-1] holding the jth dimension for the ith variate.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The distribution has PDF (probability density function)
f x=1 B α∏ i=1 m xi αi-1 andB α=∏ i=1 m Γ αiΓ∑ i=1 m αi
where x=x 1,x 2,…,xm is a vector of dimension m, such that xi>0 for all i and ∑ i=1 m xi=1.
g05se generates a draw from a Dirichlet distribution by first drawing m independent samples, yi∼gamma αi,1, i.e., independent draws from a gamma distribution with parameters αi>0 and one, and then setting xi=yi/∑ j=1 m yj.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05se.

References

Dagpunar J (1988) Principles of Random Variate Generation Oxford University Press
Hastings N A J and Peacock J B (1975) Statistical Distributions Butterworth

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, n<0.
ifail=2
On entry, m<1.
ifail=3
On entry, at least one a[i-1]≤0.0.
ifail=4
On entry, state vector was not initialized or has been corrupted.
ifail=6
On entry, ldx<n.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05see.cs

Example program data: g05see.d

Example program results: g05see.r

See Also

G05 Class
G05 Members


g05sf Method

[image]

NAG Library for .NET Release 2
G05..::g05sf Method
G05 Class See Also Send Feedback
g05sf generates a vector of pseudorandom numbers from a (negative) exponential distribution with mean a.

Syntax

C#
public static void g05sf(
    int n,
    double a,
    G05..::..G05State g05state,
    double[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05sf ( _
    n As Integer, _
    a As Double, _
    g05state As G05..::..G05State, _
    x As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05sf(
    int n,
    double a,
    G05..::..G05State^ g05state,
    array<double>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05sf :
        n : int *
        a : float *
        g05state : G05..::..G05State *
        x : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
a
Type: System..::..Double
On entry: a, the mean of the distribution.
Constraint: a>0.0.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the n pseudorandom numbers from the specified exponential distribution.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The exponential distribution has PDF (probability density function):
f x=1 a e-x/aif ​x≥0,f x=0otherwise.
g05sf returns the values
xi=-a ln yi
where yi are the next n numbers generated by a uniform 0,1 generator.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05sf.

References

Kendall M G and Stuart A (1969) The Advanced Theory of Statistics (Volume 1) (3rd Edition) Griffin
Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<0.
ifail=2
On entry, a≤0.0.
ifail=3
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05sfe.cs

Example program data: g05sfe.d

Example program results: g05sfe.r

See Also

G05 Class
G05 Members


g05sg Method

[image]

NAG Library for .NET Release 2
G05..::g05sg Method
G05 Class See Also Send Feedback
g05sg generates a vector of pseudorandom numbers from an exponential mix distribution composed of m exponential distributions each having a mean ai and weight wi.

Syntax

C#
public static void g05sg(
    int n,
    int nmix,
    double[] a,
    double[] wgt,
    G05..::..G05State g05state,
    double[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05sg ( _
    n As Integer, _
    nmix As Integer, _
    a As Double(), _
    wgt As Double(), _
    g05state As G05..::..G05State, _
    x As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05sg(
    int n,
    int nmix,
    array<double>^ a,
    array<double>^ wgt,
    G05..::..G05State^ g05state,
    array<double>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05sg :
        n : int *
        nmix : int *
        a : float[] *
        wgt : float[] *
        g05state : G05..::..G05State *
        x : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
nmix
Type: System..::..Int32
On entry: m, the number of exponential distributions in the mix.
Constraint: nmix≥1.
a
Type: array< System..::..Double >[]()[][]
An array of size [nmix]
On entry: the m parameters ai for the m exponential distributions in the mix.
Constraint: a[i-1]>0.0, for i=1,2,…,nmix.
wgt
Type: array< System..::..Double >[]()[][]
An array of size [nmix]
On entry: the m weights wi for the m exponential distributions in the mix.
Constraints:
  • ∑i=1 m wgt[i-1]=1.0;
  • wgt[i-1]≥0.0, for i=1,2,…,m.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the n pseudorandom numbers from the specified exponential mix distribution.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The distribution has PDF (probability density function)
f x=∑i=1 m 1 ai wi e-x/aiif ​x≥0,f x=0otherwise,
where ∑i=1 m wi=1 and ai>0, wi≥0.
g05sg returns the values xi by selecting, with probability wj, random variates from an exponential distribution with parameter aj.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05sg.

References

Kendall M G and Stuart A (1969) The Advanced Theory of Statistics (Volume 1) (3rd Edition) Griffin
Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<0.
ifail=2
On entry, nmix≤0.
ifail=3
On entry, a[i-1]≤0.0 for at least one a[i-1].
ifail=4
On entry, wgt[i-1]<0.0 for at least one wgt[i-1].
On entry, ∑i=1 nmix wgt[i-1]≠1.0.
ifail=5
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05sge.cs

Example program data: g05sge.d

Example program results: g05sge.r

See Also

G05 Class
G05 Members


g05sh Method

[image]

NAG Library for .NET Release 2
G05..::g05sh Method
G05 Class See Also Send Feedback
g05sh generates a vector of pseudorandom numbers taken from an F (or Fisher's variance ratio) distribution with μ and ν degrees of freedom.

Syntax

C#
public static void g05sh(
    int n,
    int df1,
    int df2,
    G05..::..G05State g05state,
    double[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05sh ( _
    n As Integer, _
    df1 As Integer, _
    df2 As Integer, _
    g05state As G05..::..G05State, _
    x As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05sh(
    int n,
    int df1,
    int df2,
    G05..::..G05State^ g05state,
    array<double>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05sh :
        n : int *
        df1 : int *
        df2 : int *
        g05state : G05..::..G05State *
        x : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
df1
Type: System..::..Int32
On entry: μ, the number of degrees of freedom of the distribution.
Constraint: df1≥1.
df2
Type: System..::..Int32
On entry: ν, the number of degrees of freedom of the distribution.
Constraint: df2≥1.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the n pseudorandom numbers from the specified F-distribution.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The distribution has PDF (probability density function)
f x=μ+ν-2 2!x 12 μ-112 μ-1!12 ν-1!1+μν x 12 μ+ν×μν 12 μif ​x>0,f x=0otherwise.
g05sh calculates the values
ν yiμ zi,  i=1,2,…,n,
where yi and zi are generated by g05sj from gamma distributions with parameters 12 μ,2 and 12 ν,2 respectively (i.e., from χ 2-distributions with μ and ν degrees of freedom).
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05sh.

References

Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<0.
ifail=2
On entry, df1<1.
ifail=3
On entry, df2<1.
ifail=4
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

The time taken by g05sh increases with μ and ν.

Example

Example program (C#): g05she.cs

Example program data: g05she.d

Example program results: g05she.r

See Also

G05 Class
G05 Members


g05sj Method

[image]

NAG Library for .NET Release 2
G05..::g05sj Method
G05 Class See Also Send Feedback
g05sj generates a vector of pseudorandom numbers taken from a gamma distribution with parameters a and b.

Syntax

C#
public static void g05sj(
    int n,
    double a,
    double b,
    G05..::..G05State g05state,
    double[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05sj ( _
    n As Integer, _
    a As Double, _
    b As Double, _
    g05state As G05..::..G05State, _
    x As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05sj(
    int n,
    double a,
    double b,
    G05..::..G05State^ g05state,
    array<double>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05sj :
        n : int *
        a : float *
        b : float *
        g05state : G05..::..G05State *
        x : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
a
Type: System..::..Double
On entry: a, the parameter of the gamma distribution.
Constraint: a>0.0.
b
Type: System..::..Double
On entry: b, the parameter of the gamma distribution.
Constraint: b>0.0.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the n pseudorandom numbers from the specified gamma distribution.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The gamma distribution has PDF (probability density function)
f x=1 ba Γ a x a-1e-x/bif ​x≤0;  a,b>0f x=0otherwise.
One of three algorithms is used to generate the variates depending upon the value of a:
(i) | if a<1, a switching algorithm described by Dagpunar (1988) (called G6) is used. The target distributions are f 1 x=ca x a-1/ta and f 2 x=1-c e-x-t, where c=t/t+a e-t, and the switching parameter, t, is taken as 1-a. This is similar to Ahrens and Dieter's GS algorithm (see Ahrens and Dieter (1974)) in which t=1;
(ii) | if a=1, the gamma distribution reduces to the exponential distribution and the method based on the logarithmic transformation of a uniform random variate is used;
(iii) | if a>1, the algorithm given by Best (1978) is used. This is based on using a Student's t-distribution with two degrees of freedom as the target distribution in an envelope rejection method.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05sj.

References

Ahrens J H and Dieter U (1974) Computer methods for sampling from gamma, beta, Poisson and binomial distributions Computing 12 223–46
Best D J (1978) Letter to the Editor Appl. Statist. 27 181
Dagpunar J (1988) Principles of Random Variate Generation Oxford University Press
Hastings N A J and Peacock J B (1975) Statistical Distributions Butterworth

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<0.
ifail=2
On entry, a≤0.0.
ifail=3
On entry, b≤0.0.
ifail=4
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05sje.cs

Example program data: g05sje.d

Example program results: g05sje.r

See Also

G05 Class
G05 Members


g05sk Method

[image]

NAG Library for .NET Release 2
G05..::g05sk Method
G05 Class See Also Send Feedback
g05sk generates a vector of pseudorandom numbers taken from a Normal (Gaussian) distribution with mean μ and variance σ 2.

Syntax

C#
public static void g05sk(
    int n,
    double xmu,
    double var,
    G05..::..G05State g05state,
    double[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05sk ( _
    n As Integer, _
    xmu As Double, _
    var As Double, _
    g05state As G05..::..G05State, _
    x As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05sk(
    int n,
    double xmu,
    double var,
    G05..::..G05State^ g05state,
    array<double>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05sk :
        n : int *
        xmu : float *
        var : float *
        g05state : G05..::..G05State *
        x : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
xmu
Type: System..::..Double
On entry: μ, the mean of the distribution.
var
Type: System..::..Double
On entry: σ 2, the variance of the distribution.
Constraint: var≥0.0.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the n pseudorandom numbers from the specified Normal distribution.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The distribution has PDF (probability distribution function)
f x=1 σ⁢2 π exp-x-μ 2 2 σ 2.
g05sk uses the algorithm of Wichura (1988).
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05sk.

References

Kendall M G and Stuart A (1969) The Advanced Theory of Statistics (Volume 1) (3rd Edition) Griffin
Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley
Wichura (1988) Algorithm AS 241: the percentage points of the Normal distribution Appl. Statist. 37 477–484

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<0.
ifail=3
On entry, var<0.0.
ifail=4
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05ske.cs

Example program data: g05ske.d

Example program results: g05ske.r

See Also

G05 Class
G05 Members


g05sl Method

[image]

NAG Library for .NET Release 2
G05..::g05sl Method
G05 Class See Also Send Feedback
g05sl generates a vector of pseudorandom numbers from a logistic distribution with mean a and spread b.

Syntax

C#
public static void g05sl(
    int n,
    double a,
    double b,
    G05..::..G05State g05state,
    double[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05sl ( _
    n As Integer, _
    a As Double, _
    b As Double, _
    g05state As G05..::..G05State, _
    x As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05sl(
    int n,
    double a,
    double b,
    G05..::..G05State^ g05state,
    array<double>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05sl :
        n : int *
        a : float *
        b : float *
        g05state : G05..::..G05State *
        x : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
a
Type: System..::..Double
On entry: a, the mean of the distribution.
b
Type: System..::..Double
On entry: b, the spread of the distribution, where ‘spread’ is 3 π×standard deviation.
Constraint: b≥0.0.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the n pseudorandom numbers from the specified logistic distribution.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The distribution has PDF (probability density function)
f x=e x-a/b b 1+e x-a/b 2.
g05sl returns the value
a+b ln y 1-y,
where y is a pseudorandom number uniformly distributed over 0,1.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05sl.

References

Kendall M G and Stuart A (1969) The Advanced Theory of Statistics (Volume 1) (3rd Edition) Griffin
Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<0.
ifail=3
On entry, b<0.0.
ifail=4
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05sle.cs

Example program data: g05sle.d

Example program results: g05sle.r

See Also

G05 Class
G05 Members


g05sm Method

[image]

NAG Library for .NET Release 2
G05..::g05sm Method
G05 Class See Also Send Feedback
g05sm generates a vector of pseudorandom numbers from a log-normal distribution with parameters μ and σ 2.

Syntax

C#
public static void g05sm(
    int n,
    double xmu,
    double var,
    G05..::..G05State g05state,
    double[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05sm ( _
    n As Integer, _
    xmu As Double, _
    var As Double, _
    g05state As G05..::..G05State, _
    x As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05sm(
    int n,
    double xmu,
    double var,
    G05..::..G05State^ g05state,
    array<double>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05sm :
        n : int *
        xmu : float *
        var : float *
        g05state : G05..::..G05State *
        x : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
xmu
Type: System..::..Double
On entry: μ, the mean of the distribution of ln x.
var
Type: System..::..Double
On entry: σ 2, the variance of the distribution of ln x.
Constraint: var≥0.0.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the n pseudorandom numbers from the specified log-normal distribution.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The distribution has PDF (probability density function)
f x=1 xσ⁢2 π exp-ln x-μ 2 2 σ 2if ​x>0,f x=0otherwise,
i.e., ln x is normally distributed with mean μ and variance σ 2. g05sm evaluates exp yi, where the yi are generated by g05sk from a Normal distribution with mean μ and variance σ 2, for i=1,2,…,n.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05sm.

References

Kendall M G and Stuart A (1969) The Advanced Theory of Statistics (Volume 1) (3rd Edition) Griffin
Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<0.
ifail=2
On entry, unable to calculate exp xmu as xmu is too large.
ifail=3
On entry, var<0.0.
ifail=4
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05sme.cs

Example program data: g05sme.d

Example program results: g05sme.r

See Also

G05 Class
G05 Members


g05sn Method

[image]

NAG Library for .NET Release 2
G05..::g05sn Method
G05 Class See Also Send Feedback
g05sn generates a vector of pseudorandom numbers taken from a Student's t-distribution with ν degrees of freedom.

Syntax

C#
public static void g05sn(
    int n,
    int df,
    G05..::..G05State g05state,
    double[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05sn ( _
    n As Integer, _
    df As Integer, _
    g05state As G05..::..G05State, _
    x As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05sn(
    int n,
    int df,
    G05..::..G05State^ g05state,
    array<double>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05sn :
        n : int *
        df : int *
        g05state : G05..::..G05State *
        x : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
df
Type: System..::..Int32
On entry: ν, the number of degrees of freedom of the distribution.
Constraint: df≥1.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the n pseudorandom numbers from the specified Student's t-distribution.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The distribution has PDF (probability density function)
f x=ν-1 2!12 ν-1!πν 1+x 2 ν 12 ν+1.
g05sn calculates the values
yi ν zi,  i=1,…,n
where the yi are generated by g05sk from a Normal distribution with mean 0 and variance 1.0, and the zi are generated by g05sj from a gamma distribution with parameters 12 ν and 2 (i.e., from a χ 2-distribution with ν degrees of freedom).
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05sn.

References

Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<0.
ifail=2
On entry, df<1.
ifail=3
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

The time taken by g05sn increases with ν.

Example

Example program (C#): g05sne.cs

Example program data: g05sne.d

Example program results: g05sne.r

See Also

G05 Class
G05 Members


g05sp Method

[image]

NAG Library for .NET Release 2
G05..::g05sp Method
G05 Class See Also Send Feedback
g05sp generates a vector of pseudorandom numbers from a triangular distribution with parameters xmin, xmed and xmax.

Syntax

C#
public static void g05sp(
    int n,
    double xmin,
    double xmed,
    double xmax,
    G05..::..G05State g05state,
    double[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05sp ( _
    n As Integer, _
    xmin As Double, _
    xmed As Double, _
    xmax As Double, _
    g05state As G05..::..G05State, _
    x As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05sp(
    int n,
    double xmin,
    double xmed,
    double xmax,
    G05..::..G05State^ g05state,
    array<double>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05sp :
        n : int *
        xmin : float *
        xmed : float *
        xmax : float *
        g05state : G05..::..G05State *
        x : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
xmin
Type: System..::..Double
On entry: the end point xmin of the triangular distribution.
xmed
Type: System..::..Double
On entry: the median of the distribution xmed (also the location of the vertex of the triangular distribution at which the PDF reaches a maximum).
Constraint: xmed≥xmin.
xmax
Type: System..::..Double
On entry: the end point xmax of the triangular distribution.
Constraint: xmax≥xmed.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the n pseudorandom numbers from the specified triangular distribution.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The triangular distribution has a PDF (probability density function) that is triangular in profile. The base of the triangle ranges from x=xmin to x=xmax and the PDF has a maximum value of 2 xmax-xmin at x=xmed. If xmin=xmed=xmax then x=xmed with probability 1; otherwise the triangular distribution has PDF:
f x=x-xminxmed-xmin×2 xmax-xmin​ if ​xmin≤x≤xmed,f x=xmax-xxmax-xmed×2 xmax-xmin​ if ​xmed<x≤xmax,f x=0​ otherwise.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05sp.

References

Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<0.
ifail=3
On entry, xmed<xmin.
ifail=4
On entry, xmax<xmed.
ifail=5
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05spe.cs

Example program data: g05spe.d

Example program results: g05spe.r

See Also

G05 Class
G05 Members


g05sq Method

[image]

NAG Library for .NET Release 2
G05..::g05sq Method
G05 Class See Also Send Feedback
g05sq generates a vector of pseudorandom numbers uniformly distributed over the interval a,b.

Syntax

C#
public static void g05sq(
    int n,
    double a,
    double b,
    G05..::..G05State g05state,
    double[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05sq ( _
    n As Integer, _
    a As Double, _
    b As Double, _
    g05state As G05..::..G05State, _
    x As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05sq(
    int n,
    double a,
    double b,
    G05..::..G05State^ g05state,
    array<double>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05sq :
        n : int *
        a : float *
        b : float *
        g05state : G05..::..G05State *
        x : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
a
Type: System..::..Double
On entry: the end points a and b of the uniform distribution.
Constraint: a≤b.
b
Type: System..::..Double
On entry: the end points a and b of the uniform distribution.
Constraint: a≤b.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the n pseudorandom numbers from the specified uniform distribution.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

If a=0 and b=1, g05sq returns the next n values yi from a uniform 0,1 generator (see g05sa for details).
For other values of a and b, g05sq applies the transformation
xi=a+b-a yi.
The method ensures that the values xi lie in the closed interval a,b.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05sq.

References

Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<0.
ifail=3
On entry, b<a.
ifail=4
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

Although yi takes a value from the half closed interval 0,1 and xi=a+b-a yi, xi is documented as taking values from the closed interval a,b. This is because for some values of a and b, g05sq may return a value of a due to numerical rounding.

Example

Example program (C#): g05sqe.cs

Example program data: g05sqe.d

Example program results: g05sqe.r

See Also

G05 Class
G05 Members


g05sr Method

[image]

NAG Library for .NET Release 2
G05..::g05sr Method
G05 Class See Also Send Feedback
g05sr generates a vector of pseudorandom numbers from a von Mises distribution with concentration parameter κ.

Syntax

C#
public static void g05sr(
    int n,
    double vk,
    G05..::..G05State g05state,
    double[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05sr ( _
    n As Integer, _
    vk As Double, _
    g05state As G05..::..G05State, _
    x As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05sr(
    int n,
    double vk,
    G05..::..G05State^ g05state,
    array<double>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05sr :
        n : int *
        vk : float *
        g05state : G05..::..G05State *
        x : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
vk
Type: System..::..Double
On entry: κ, the concentration parameter of the required von Mises distribution.
Constraint: 0.0<vk≤x02al/2.0.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the n pseudorandom numbers from the specified von Mises distribution.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The von Mises distribution is a symmetric distribution used in the analysis of circular data. The PDF (probability density function) of this distribution on the circle with mean direction μ 0=0 and concentration parameter κ, can be written as:
f θ=e κ cos θ2 π I 0 κ,
where θ is reduced modulo 2 π so that -π≤θ<π and κ≥0. For very small κ the distribution is almost the uniform distribution, whereas for κ→∞ all the probability is concentrated at one point.
The n variates, θ 1,θ 2,…,θn, are generated using an envelope rejection method with a wrapped Cauchy target distribution as proposed by Best and Fisher (1979) and described by Dagpunar (1988).
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05sr.

References

Best D J and Fisher N I (1979) Efficient simulation of the von Mises distribution Appl. Statist. 28 152–157
Dagpunar J (1988) Principles of Random Variate Generation Oxford University Press
Mardia K V (1972) Statistics of Directional Data Academic Press

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<0.
ifail=2
On entry, | vk≤0.0,
or | vk>x02al/2.0.
ifail=3
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

For a given number of random variates the generation time increases slightly with increasing κ.

Example

Example program (C#): g05sre.cs

Example program data: g05sre.d

Example program results: g05sre.r

See Also

G05 Class
G05 Members


g05ss Method

[image]

NAG Library for .NET Release 2
G05..::g05ss Method
G05 Class See Also Send Feedback
g05ss generates a vector of pseudorandom numbers from a two parameter Weibull distribution with shape parameter a and scale parameter b.

Syntax

C#
public static void g05ss(
    int n,
    double a,
    double b,
    G05..::..G05State g05state,
    double[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05ss ( _
    n As Integer, _
    a As Double, _
    b As Double, _
    g05state As G05..::..G05State, _
    x As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05ss(
    int n,
    double a,
    double b,
    G05..::..G05State^ g05state,
    array<double>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05ss :
        n : int *
        a : float *
        b : float *
        g05state : G05..::..G05State *
        x : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
a
Type: System..::..Double
On entry: a, the shape parameter of the distribution.
Constraint: a>0.0.
b
Type: System..::..Double
On entry: b, the scale parameter of the distribution.
Constraint: b>0.0.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the n pseudorandom numbers from the specified Weibull distribution.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The distribution has PDF (probability density function)
f x=ab x a-1e-xa/bif ​x>0,f x=0otherwise.
g05ss returns the value -b ln y 1/a, where y is a pseudorandom number from a uniform distribution over 0,1.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05ss.

References

Kendall M G and Stuart A (1969) The Advanced Theory of Statistics (Volume 1) (3rd Edition) Griffin
Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<0.
ifail=2
On entry, a≤0.0.
ifail=3
On entry, b≤0.0.
ifail=4
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05sse.cs

Example program data: g05sse.d

Example program results: g05sse.r

See Also

G05 Class
G05 Members


g05ta Method

[image]

NAG Library for .NET Release 2
G05..::g05ta Method
G05 Class See Also Send Feedback
g05ta generates a vector of pseudorandom integers from the discrete binomial distribution with parameters m and p.

Syntax

C#
public static void g05ta(
    int mode,
    int n,
    int m,
    double p,
    double[] r,
    G05..::..G05State g05state,
    int[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05ta ( _
    mode As Integer, _
    n As Integer, _
    m As Integer, _
    p As Double, _
    r As Double(), _
    g05state As G05..::..G05State, _
    x As Integer(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05ta(
    int mode,
    int n,
    int m,
    double p,
    array<double>^ r,
    G05..::..G05State^ g05state,
    array<int>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05ta :
        mode : int *
        n : int *
        m : int *
        p : float *
        r : float[] *
        g05state : G05..::..G05State *
        x : int[] *
        ifail : int byref -> unit

Parameters

mode
Type: System..::..Int32
On entry: a code for selecting the operation to be performed by the method.
mode=0
Set up reference vector only.
mode=1
Generate variates using reference vector set up in a prior call to g05ta.
mode=2
Set up reference vector and generate variates.
mode=3
Generate variates without using the reference vector.
Constraint: mode=0, 1, 2 or 3.
n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
m
Type: System..::..Int32
On entry: m, the number of trials of the distribution.
Constraint: m≥0.
p
Type: System..::..Double
On entry: p, the probability of success of the binomial distribution.
Constraint: 0.0≤p≤1.0.
r
Type: array< System..::..Double >[]()[][]
An array of size [lr]
On entry: if mode=1, the reference vector from the previous call to g05ta.
If mode=3, r is not referenced.
On exit: if mode≠3, the reference vector.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On exit: the n pseudorandom numbers from the specified binomial distribution.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g05ta generates n integers xi from a discrete binomial distribution, where the probability of xi=I is
P xi=I=m!I!m-I!⁢pI×1-p m-I,  I=0,1,…,m,
where m≥0 and 0≤p≤1. This represents the probability of achieving I successes in m trials when the probability of success at a single trial is p.
The variates can be generated with or without using a search table and index. If a search table is used then it is stored with the index in a reference vector and subsequent calls to g05ta with the same parameter values can then use this reference vector to generate further variates.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05ta.

References

Kendall M G and Stuart A (1969) The Advanced Theory of Statistics (Volume 1) (3rd Edition) Griffin
Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, mode≠0, 1, 2 or 3.
ifail=2
On entry, n<0.
ifail=3
On entry, m<0.
ifail=4
On entry, | p<0.0,
or | p>1.0.
ifail=5
On entry, m or p is not the same as when r was set up in a previous call to g05ta with mode=0 or 2.
On entry, the r vector was not initialized correctly or has been corrupted.
ifail=6
On entry, lr is too small when mode=0 or 2.
ifail=7
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05tae.cs

Example program data: g05tae.d

Example program results: g05tae.r

See Also

G05 Class
G05 Members


g05tb Method

[image]

NAG Library for .NET Release 2
G05..::g05tb Method
G05 Class See Also Send Feedback
g05tb generates a vector of pseudorandom logical values – true with probability p and false with probability 1-p.

Syntax

C#
public static void g05tb(
    int n,
    double p,
    G05..::..G05State g05state,
    bool[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05tb ( _
    n As Integer, _
    p As Double, _
    g05state As G05..::..G05State, _
    x As Boolean(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05tb(
    int n,
    double p,
    G05..::..G05State^ g05state,
    array<bool>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05tb :
        n : int *
        p : float *
        g05state : G05..::..G05State *
        x : bool[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of pseudorandom logical values to be generated.
Constraint: n≥0.
p
Type: System..::..Double
On entry: must contain the probability of g05tb returning true.
Constraint: 0.0≤p≤1.0.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Boolean >[]()[][]
An array of size [n]
On exit: the n logical values.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g05tb generates n logical values xi from the relation
yi<p
where yi is a pseudorandom number from a uniform distribution over 0,1, generated by g05sa using the values of state as input to this method.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05tb.

References

Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<0.
ifail=2
On entry, | p<0.0,
or | p>1.0.
ifail=3
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05tbe.cs

Example program data: g05tbe.d

Example program results: g05tbe.r

See Also

G05 Class
G05 Members


g05tc Method

[image]

NAG Library for .NET Release 2
G05..::g05tc Method
G05 Class See Also Send Feedback
g05tc generates a vector of pseudorandom integers from the discrete geometric distribution with probability p of success at a trial.

Syntax

C#
public static void g05tc(
    int mode,
    int n,
    double p,
    double[] r,
    G05..::..G05State g05state,
    int[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05tc ( _
    mode As Integer, _
    n As Integer, _
    p As Double, _
    r As Double(), _
    g05state As G05..::..G05State, _
    x As Integer(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05tc(
    int mode,
    int n,
    double p,
    array<double>^ r,
    G05..::..G05State^ g05state,
    array<int>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05tc :
        mode : int *
        n : int *
        p : float *
        r : float[] *
        g05state : G05..::..G05State *
        x : int[] *
        ifail : int byref -> unit

Parameters

mode
Type: System..::..Int32
On entry: a code for selecting the operation to be performed by the method.
mode=0
Set up reference vector only.
mode=1
Generate variates using reference vector set up in a prior call to g05tc.
mode=2
Set up reference vector and generate variates.
mode=3
Generate variates without using the reference vector.
Constraint: mode=0, 1, 2 or 3.
n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
p
Type: System..::..Double
On entry: the parameter p of the geometric distribution representing the probability of success at a single trial.
Constraint: machine precision≤p≤1.0 (see x02aj).
r
Type: array< System..::..Double >[]()[][]
An array of size [lr]
On entry: if mode=1, the reference vector from the previous call to g05tc.
If mode=3, r is not referenced.
On exit: if mode≠3, the reference vector.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On exit: the n pseudorandom numbers from the specified geometric distribution.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g05tc generates n integers xi from a discrete geometric distribution, where the probability of xi=I (a first success after I+1 trials) is
P xi=I=p×1-p I,  I=0,1,….
The variates can be generated with or without using a search table and index. If a search table is used then it is stored with the index in a reference vector and subsequent calls to g05tc with the same parameter value can then use this reference vector to generate further variates. If the search table is not used (as recommended for small values of p) then a direct transformation of uniform variates is used.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05tc.

References

Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, mode≠0, 1, 2 or 3.
ifail=2
On entry, n<0.
ifail=3
On entry, | p<0.0 or p>1.0,
or | mode=0 or 2 and p is so small that lr would have to be larger than the largest representable integer. Use mode=3 in this case.
ifail=4
On entry, p is not the same as when r was set up in a previous call to g05tc with mode=0 or 2.
On entry, the r vector was not initialized correctly or has been corrupted.
ifail=5
On entry, lr is too small when mode=0 or 2.
ifail=6
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

The time taken to set up the reference vector, if used, increases with the length of array r. However, if the reference vector is used, the time taken to generate numbers decreases as the space allotted to the index part of r increases. Nevertheless, there is a point, depending on the distribution, where this improvement becomes very small and the suggested value for the length of array r is designed to approximate this point.
If p is very small then the storage requirements for the reference vector and the time taken to set up the reference vector becomes prohibitive. In this case it is recommended that the reference vector is not used. This is achieved by selecting mode=3.

Example

Example program (C#): g05tce.cs

Example program data: g05tce.d

Example program results: g05tce.r

See Also

G05 Class
G05 Members


g05td Method

[image]

NAG Library for .NET Release 2
G05..::g05td Method
G05 Class See Also Send Feedback
g05td generates a vector of pseudorandom integers from a discrete distribution with a given PDF (probability density function) or CDF (cumulative distribution function) p.

Syntax

C#
public static void g05td(
    int mode,
    int n,
    double[] p,
    int np,
    int ip1,
    int itype,
    double[] r,
    G05..::..G05State g05state,
    int[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05td ( _
    mode As Integer, _
    n As Integer, _
    p As Double(), _
    np As Integer, _
    ip1 As Integer, _
    itype As Integer, _
    r As Double(), _
    g05state As G05..::..G05State, _
    x As Integer(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05td(
    int mode,
    int n,
    array<double>^ p,
    int np,
    int ip1,
    int itype,
    array<double>^ r,
    G05..::..G05State^ g05state,
    array<int>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05td :
        mode : int *
        n : int *
        p : float[] *
        np : int *
        ip1 : int *
        itype : int *
        r : float[] *
        g05state : G05..::..G05State *
        x : int[] *
        ifail : int byref -> unit

Parameters

mode
Type: System..::..Int32
On entry: a code for selecting the operation to be performed by the method.
mode=0
Set up reference vector only.
mode=1
Generate variates using reference vector set up in a prior call to g05td.
mode=2
Set up reference vector and generate variates.
mode=3
Generate variates without using the reference vector.
Constraint: mode=0, 1, 2 or 3.
n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
p
Type: array< System..::..Double >[]()[][]
An array of size [np]
On entry: the PDF or CDF of the distribution.
Constraints:
  • 0.0≤p[i-1]≤1.0, for i=1,2,…,np;
  • if itype=1, ∑ i=1 np p[i-1]=1.0;
  • if itype=2, p[i-1]<p[j-1], ​i<j​ and ​p[np-1]=1.0.
np
Type: System..::..Int32
On entry: the number of values supplied in p defining the PDF or CDF of the discrete distribution.
Constraint: np>0.
ip1
Type: System..::..Int32
On entry: the value of the variate, a whole number, to which the probability in p[0] corresponds.
itype
Type: System..::..Int32
On entry: indicates the type of information contained in p.
itype=1
p contains a probability distribution function (PDF).
itype=2
p contains a cumulative distribution function (CDF).
Constraint: itype=1 or 2.
r
Type: array< System..::..Double >[]()[][]
An array of size [lr]
On entry: if mode=1, the reference vector from the previous call to g05td.
On exit: the reference vector.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On exit: contains n pseudorandom numbers from the specified discrete distribution.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g05td generates a sequence of n integers xi, from a discrete distribution defined by information supplied in p. This may either be the PDF or CDF of the distribution. A reference vector is first set up to contain the CDF of the distribution in its higher elements, followed by an index.
Setting up the reference vector and subsequent generation of variates can each be performed by separate calls to g05td or may be combined in a single call.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05td.

References

Kendall M G and Stuart A (1969) The Advanced Theory of Statistics (Volume 1) (3rd Edition) Griffin
Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, mode≠0, 1 or 2.
ifail=2
On entry, n<0.
ifail=3
With itype=1, p[j-1]<0 for at least one value of j.
With itype=1, the sum of p[j-1], for j=1,2,…,np, does not equal 1.
With itype=2, the values of p[j-1] are not all in non-descending order.
ifail=4
On entry, np<1.
ifail=6
On entry, itype≠1 or 2.
ifail=7
The value of np, itype or ip1 is not the same as when r was set up in a previous call to g05td with mode=0 or 2.
On entry, the r vector was not initialized correctly, or has been corrupted.
ifail=8
On entry, lr is too small when mode=0 or 2.
ifail=9
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05tde.cs

Example program data: g05tde.d

Example program results: g05tde.r

See Also

G05 Class
G05 Members


g05te Method

[image]

NAG Library for .NET Release 2
G05..::g05te Method
G05 Class See Also Send Feedback
g05te generates a vector of pseudorandom integers from the discrete hypergeometric distribution of the number of specified items in a sample of size l, taken from a population of size k with m specified items in it.

Syntax

C#
public static void g05te(
    int mode,
    int n,
    int ns,
    int np,
    int m,
    double[] r,
    G05..::..G05State g05state,
    int[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05te ( _
    mode As Integer, _
    n As Integer, _
    ns As Integer, _
    np As Integer, _
    m As Integer, _
    r As Double(), _
    g05state As G05..::..G05State, _
    x As Integer(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05te(
    int mode,
    int n,
    int ns,
    int np,
    int m,
    array<double>^ r,
    G05..::..G05State^ g05state,
    array<int>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05te :
        mode : int *
        n : int *
        ns : int *
        np : int *
        m : int *
        r : float[] *
        g05state : G05..::..G05State *
        x : int[] *
        ifail : int byref -> unit

Parameters

mode
Type: System..::..Int32
On entry: a code for selecting the operation to be performed by the method.
mode=0
Set up reference vector only.
mode=1
Generate variates using reference vector set up in a prior call to g05te.
mode=2
Set up reference vector and generate variates.
mode=3
Generate variates without using the reference vector.
Constraint: mode=0, 1, 2 or 3.
n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
ns
Type: System..::..Int32
On entry: l, the sample size of the hypergeometric distribution.
Constraint: 0≤ns≤np.
np
Type: System..::..Int32
On entry: k, the population size of the hypergeometric distribution.
Constraint: np≥0.
m
Type: System..::..Int32
On entry: m, the number of specified items of the hypergeometric distribution.
Constraint: 0≤m≤np.
r
Type: array< System..::..Double >[]()[][]
An array of size [lr]
On entry: if mode=1, the reference vector from the previous call to g05te.
If mode=3, r is not referenced.
On exit: if mode≠3, the reference vector.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On exit: the pseudorandom numbers from the specified hypergeometric distribution.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g05te generates n integers xi from a discrete hypergeometric distribution, where the probability of xi=I is
P i=I=l!m!k-l!k-m!I!l-I!m-I!k-m-l+I!k!  if I=max 0,m+l-k,…,min l,m,P i=I=0  otherwise.
The variates can be generated with or without using a search table and index. If a search table is used then it is stored with the index in a reference vector and subsequent calls to g05te with the same parameter values can then use this reference vector to generate further variates. The reference array is generated by a recurrence relation if lm k-lk-m<50 k 3, otherwise Stirling's approximation is used.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05te.

References

Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, mode≠0, 1, 2 or 3.
ifail=2
On entry, n<0.
ifail=3
On entry, | ns>np,
or | ns<0.
ifail=4
On entry, np<0.
ifail=5
On entry, | m>np,
or | m<0.
ifail=6
On entry, at least one of ns, np or m is not the same as when r was set up in a previous call to g05te with mode=0 or 2.
On entry, the r vector was not initialized correctly or has been corrupted.
ifail=7
On entry, lr is too small when mode=0 or 2.
ifail=8
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05tee.cs

Example program data: g05tee.d

Example program results: g05tee.r

See Also

G05 Class
G05 Members


g05tf Method

[image]

NAG Library for .NET Release 2
G05..::g05tf Method
G05 Class See Also Send Feedback
g05tf generates a vector of pseudorandom integers from the discrete logarithmic distribution with parameter a.

Syntax

C#
public static void g05tf(
    int mode,
    int n,
    double a,
    double[] r,
    G05..::..G05State g05state,
    int[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05tf ( _
    mode As Integer, _
    n As Integer, _
    a As Double, _
    r As Double(), _
    g05state As G05..::..G05State, _
    x As Integer(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05tf(
    int mode,
    int n,
    double a,
    array<double>^ r,
    G05..::..G05State^ g05state,
    array<int>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05tf :
        mode : int *
        n : int *
        a : float *
        r : float[] *
        g05state : G05..::..G05State *
        x : int[] *
        ifail : int byref -> unit

Parameters

mode
Type: System..::..Int32
On entry: a code for selecting the operation to be performed by the method.
mode=0
Set up reference vector only.
mode=1
Generate variates using reference vector set up in a prior call to g05tf.
mode=2
Set up reference vector and generate variates.
mode=3
Generate variates without using the reference vector.
Constraint: mode=0, 1, 2 or 3.
n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
a
Type: System..::..Double
On entry: a, the parameter of the logarithmic distribution.
Constraint: 0.0<a<1.0.
r
Type: array< System..::..Double >[]()[][]
An array of size [lr]
On entry: if mode=1, the reference vector from the previous call to g05tf.
If mode=3, r is not referenced.
On exit: mode≠3, the reference vector.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On exit: the n pseudorandom numbers from the specified logarithmic distribution.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g05tf generates n integers xi from a discrete logarithmic distribution, where the probability of xi=I is
P xi=I=-aI I×log 1-a,  I=1,2,…,
where 0<a<1.
The variates can be generated with or without using a search table and index. If a search table is used then it is stored with the index in a reference vector and subsequent calls to g05tf with the same parameter value can then use this reference vector to generate further variates.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05tf.

References

Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, mode≠0, 1, 2 or 3.
ifail=2
On entry, n<0.
ifail=3
On entry, | a≤0.0,
or | a≥1.0.
ifail=4
On entry, a is not the same as when r was set up in a previous call to g05tf with mode=0 or 2.
On entry, the r vector was not initialized correctly, or has been corrupted.
ifail=5
On entry, lr is too small when mode=0 or 2.
ifail=6
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05tfe.cs

Example program data: g05tfe.d

Example program results: g05tfe.r

See Also

G05 Class
G05 Members


g05tg Method

[image]

NAG Library for .NET Release 2
G05..::g05tg Method
G05 Class See Also Send Feedback
g05tg generates a sequence of n variates, each consisting of k pseudorandom integers, from the discrete multinomial distribution with k outcomes and m trials, where the outcomes have probabilities p 1,p 2,…,pk respectively.

Syntax

C#
public static void g05tg(
    int mode,
    int n,
    int m,
    int k,
    double[] p,
    double[] r,
    G05..::..G05State g05state,
    int[,] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05tg ( _
    mode As Integer, _
    n As Integer, _
    m As Integer, _
    k As Integer, _
    p As Double(), _
    r As Double(), _
    g05state As G05..::..G05State, _
    x As Integer(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05tg(
    int mode,
    int n,
    int m,
    int k,
    array<double>^ p,
    array<double>^ r,
    G05..::..G05State^ g05state,
    array<int,2>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05tg :
        mode : int *
        n : int *
        m : int *
        k : int *
        p : float[] *
        r : float[] *
        g05state : G05..::..G05State *
        x : int[,] *
        ifail : int byref -> unit

Parameters

mode
Type: System..::..Int32
On entry: a code for selecting the operation to be performed by the method.
mode=0
Set up reference vector only.
mode=1
Generate variates using reference vector set up in a prior call to g05tg.
mode=2
Set up reference vector and generate variates.
mode=3
Generate variates without using the reference vector.
Constraint: mode=0, 1, 2 or 3.
n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
m
Type: System..::..Int32
On entry: m, the number of trials of the multinomial distribution.
Constraint: m≥0.
k
Type: System..::..Int32
On entry: k, the number of possible outcomes of the multinomial distribution.
Constraint: k≥2.
p
Type: array< System..::..Double >[]()[][]
An array of size [k]
On entry: contains the probabilities pj, for j=1,2,…,k, of the k possible outcomes of the multinomial distribution.
Constraint: 0.0≤p[j-1]≤1.0 and ∑j=1 k p[j-1]=1.0.
r
Type: array< System..::..Double >[]()[][]
An array of size [lr]
On entry: if mode=1, the reference vector from the previous call to g05tg.
If mode=3, r is not referenced.
On exit: if mode≠3, the reference vector.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Int32 ,2>[,](,)[,][,]
An array of size [dim1, _tdx]
Note: dim1 must satisfy the constraint: dim1≥n
On exit: the first n rows of x[i-1,j-1] each contain k pseudorandom numbers representing a k-dimensional variate from the specified multinomial distribution.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g05tg generates a sequence of n groups of k integers x i,j, for j=1,2,…,k and i=1,2,…,n, from a multinomial distribution with m trials and k outcomes, where the probability of x i,j=Ij for each j=1,2,…,k is
P i 1=I 1,…,ik=Ik=m!∏j=1 k Ij!∏j=1 k pj Ij=m!I 1!I 2!⋯Ik!p 1 I 1p 2 I 2⋯pk Ik,
where
∑j=1 k pj=1  and  ∑j=1 k Ij=m.
A single trial can have several outcomes (k) and the probability of achieving each outcome is known (pj). After m trials each outcome will have occurred a certain number of times. The k numbers representing the numbers of occurrences for each outcome after m trials is then a single sample from the multinomial distribution defined by the parameters k, m and pj, for j=1,2,…,k. This method returns n such samples.
When k=2 this distribution is equivalent to the binomial distribution with parameters m and p=p 1 (see g05ta).
The variates can be generated with or without using a search table and index. If a search table is used then it is stored with the index in a reference vector and subsequent calls to g05tg with the same parameter values can then use this reference vector to generate further variates. The reference array is generated only for the outcome with greatest probability. The number of successes for the outcome with greatest probability is calculated first as for the binomial distribution (see g05ta); the number of successes for other outcomes are calculated in turn for the remaining reduced multinomial distribution; the number of successes for the final outcome is simply calculated to ensure that the total number of successes is m.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05tg.

References

Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, mode≠0, 1, 2 or 3.
ifail=2
On entry, n<0.
ifail=3
On entry, m<0.
ifail=4
On entry, k<2.
ifail=5
On entry, p[j-1]<0.0 or p[j-1]>1.0 for at least one value of j.
The probabilities p[j-1], for j=1,2,…,k, do not add up to 1.
ifail=6
The maximum value of p[j-1], for j=1,2,…,k, or m is not the same as when r was set up in a previous call to g05tg with mode=0 or 2.
On entry, the r vector was not initialized correctly, or has been corrupted.
ifail=7
On entry, lr is too small when mode=0 or 2.
ifail=8
On entry, state vector was not initialized or has been corrupted.
ifail=10
On entry, ldx<n.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

The reference vector for only one outcome can be set up because the conditional distributions cannot be known in advance of the generation of variates. The outcome with greatest probability of success is chosen for the reference vector because it will have the greatest spread of likely values.

Example

Example program (C#): g05tge.cs

Example program data: g05tge.d

Example program results: g05tge.r

See Also

G05 Class
G05 Members


g05th Method

[image]

NAG Library for .NET Release 2
G05..::g05th Method
G05 Class See Also Send Feedback
g05th generates a vector of pseudorandom integers from the discrete negative binomial distribution with parameter m and probability p of success at a trial.

Syntax

C#
public static void g05th(
    int mode,
    int n,
    int m,
    double p,
    double[] r,
    G05..::..G05State g05state,
    int[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05th ( _
    mode As Integer, _
    n As Integer, _
    m As Integer, _
    p As Double, _
    r As Double(), _
    g05state As G05..::..G05State, _
    x As Integer(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05th(
    int mode,
    int n,
    int m,
    double p,
    array<double>^ r,
    G05..::..G05State^ g05state,
    array<int>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05th :
        mode : int *
        n : int *
        m : int *
        p : float *
        r : float[] *
        g05state : G05..::..G05State *
        x : int[] *
        ifail : int byref -> unit

Parameters

mode
Type: System..::..Int32
On entry: a code for selecting the operation to be performed by the method.
mode=0
Set up reference vector only.
mode=1
Generate variates using reference vector set up in a prior call to g05th.
mode=2
Set up reference vector and generate variates.
mode=3
Generate variates without using the reference vector.
Constraint: mode=0, 1, 2 or 3.
n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
m
Type: System..::..Int32
On entry: m, the number of failures of the distribution.
Constraint: m≥0.
p
Type: System..::..Double
On entry: p, the parameter of the negative binomial distribution representing the probability of success at a single trial.
Constraint: 0.0≤p<1.0.
r
Type: array< System..::..Double >[]()[][]
An array of size [lr]
On entry: if mode=1, the reference vector from the previous call to g05th.
If mode=3, r is not referenced.
On exit: if mode≠3, the reference vector.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On exit: the n pseudorandom numbers from the specified negative binomial distribution.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g05th generates n integers xi from a discrete negative binomial distribution, where the probability of xi=I (I successes before m failures) is
P xi=I=m+I-1!I!m-1!×pI×1-p m,  I=0,1,….
The variates can be generated with or without using a search table and index. If a search table is used then it is stored with the index in a reference vector and subsequent calls to g05th with the same parameter value can then use this reference vector to generate further variates.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05th.

References

Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, mode≠0, 1, 2 or 3.
ifail=2
On entry, n<0.
ifail=3
On entry, m<0.
ifail=4
On entry, | p<0.0,
or | p≥1.0.
ifail=5
On entry, p or m is not the same as when r was set up in a previous call to g05th with mode=0 or 2.
On entry, the r vector was not initialized correctly, or has been corrupted.
ifail=6
On entry, lr is too small when mode=0 or 2.
ifail=7
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05the.cs

Example program data: g05the.d

Example program results: g05the.r

See Also

G05 Class
G05 Members


g05tj Method

[image]

NAG Library for .NET Release 2
G05..::g05tj Method
G05 Class See Also Send Feedback
g05tj generates a vector of pseudorandom integers from the discrete Poisson distribution with mean λ.

Syntax

C#
public static void g05tj(
    int mode,
    int n,
    double lambda,
    double[] r,
    G05..::..G05State g05state,
    int[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05tj ( _
    mode As Integer, _
    n As Integer, _
    lambda As Double, _
    r As Double(), _
    g05state As G05..::..G05State, _
    x As Integer(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05tj(
    int mode,
    int n,
    double lambda,
    array<double>^ r,
    G05..::..G05State^ g05state,
    array<int>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05tj :
        mode : int *
        n : int *
        lambda : float *
        r : float[] *
        g05state : G05..::..G05State *
        x : int[] *
        ifail : int byref -> unit

Parameters

mode
Type: System..::..Int32
On entry: a code for selecting the operation to be performed by the method.
mode=0
Set up reference vector only.
mode=1
Generate variates using reference vector set up in a prior call to g05tj.
mode=2
Set up reference vector and generate variates.
mode=3
Generate variates without using the reference vector.
Constraint: mode=0, 1, 2 or 3.
n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
lambda
Type: System..::..Double
On entry: λ, the mean of the Poisson distribution.
Constraint: lambda≥0.0.
r
Type: array< System..::..Double >[]()[][]
An array of size [lr]
On entry: if mode=1, the reference vector from the previous call to g05tj.
If mode=3, r is not referenced.
On exit: if mode≠3, the reference vector.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On exit: the n pseudorandom numbers from the specified Poisson distribution.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g05tj generates n integers xi from a discrete Poisson distribution with mean λ, where the probability of xi=I is
P xi=I=λI×e-λI!,  I=0,1,…,
where λ≥0.
The variates can be generated with or without using a search table and index. If a search table is used then it is stored with the index in a reference vector and subsequent calls to g05tj with the same parameter values can then use this reference vector to generate further variates. The reference array is found using a recurrence relation if λ is less than 50 and by Stirling's formula otherwise.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05tj.

References

Kendall M G and Stuart A (1969) The Advanced Theory of Statistics (Volume 1) (3rd Edition) Griffin
Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, mode≠0, 1, 2 or 3.
ifail=2
On entry, n<0.
ifail=3
On entry, lambda<0.0.
mode=0 or 2 and lambda is such that lr would have to be larger than the largest representable integer. Use mode=3 in this case.
ifail=4
On entry, lambda is not the same as when r was set up in a previous call to g05tj with mode=0 or 2.
On entry, the r vector was not initialized correctly, or has been corrupted.
ifail=5
On entry, lr is too small when mode=0 or 2.
ifail=6
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05tje.cs

Example program data: g05tje.d

Example program results: g05tje.r

See Also

G05 Class
G05 Members


g05tk Method

[image]

NAG Library for .NET Release 2
G05..::g05tk Method
G05 Class See Also Send Feedback
g05tk generates a vector of pseudorandom integers, each from a discrete Poisson distribution with differing parameter.

Syntax

C#
public static void g05tk(
    int m,
    double[] vlamda,
    G05..::..G05State g05state,
    int[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05tk ( _
    m As Integer, _
    vlamda As Double(), _
    g05state As G05..::..G05State, _
    x As Integer(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05tk(
    int m,
    array<double>^ vlamda,
    G05..::..G05State^ g05state,
    array<int>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05tk :
        m : int *
        vlamda : float[] *
        g05state : G05..::..G05State *
        x : int[] *
        ifail : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: m, the number of Poisson distributions for which pseudorandom variates are required.
Constraint: m≥1.
vlamda
Type: array< System..::..Double >[]()[][]
An array of size [m]
On entry: the means, λj, for j=1,2,…,m, of the Poisson distributions.
Constraint: 0.0≤vlamda[j-1]≤x02bb/2.0, for j=1,2,…,m.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Int32 >[]()[][]
An array of size [m]
On exit: the m pseudorandom numbers from the specified Poisson distributions.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g05tk generates m integers xj, each from a discrete Poisson distribution with mean λj, where the probability of xj=I is
P xj=I=λjI×e-λjI!,  I=0,1,…,
where
λj≥0,  j=1,2,…,m.
The methods used by this method have low set up times and are designed for efficient use when the value of the parameter λ changes during the simulation. For large samples from a distribution with fixed λ using g05tj to set up and use a reference vector may be more efficient.
When λ<7.5 the product of uniforms method is used, see for example Dagpunar (1988). For larger values of λ an envelope rejection method is used with a target distribution:
f x=13if ​x≤1,f x=13 x-3otherwise.
This distribution is generated using a ratio of uniforms method. A similar approach has also been suggested by Ahrens and Dieter (1989). The basic method is combined with quick acceptance and rejection tests given by Maclaren (1990). For values of λ≥87 Stirling's approximation is used in the computation of the Poisson distribution function, otherwise tables of factorials are used as suggested by Maclaren (1990).
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05tk.

References

Ahrens J H and Dieter U (1989) A convenient sampling method with bounded computation times for Poisson distributions Amer. J. Math. Management Sci. 1–13
Dagpunar J (1988) Principles of Random Variate Generation Oxford University Press
Maclaren N M (1990) A Poisson random number generator Personal Communication

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, m<1.
ifail=2
On entry, vlamda[j-1]<0.0 for at least one value of j.
On entry, 2×vlamda[j-1]>x02bb for at least one value of j.
ifail=3
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05tke.cs

Example program data: g05tke.d

Example program results: g05tke.r

See Also

G05 Class
G05 Members


g05tl Method

[image]

NAG Library for .NET Release 2
G05..::g05tl Method
G05 Class See Also Send Feedback
g05tl generates a vector of pseudorandom integers uniformly distributed over the interval a,b.

Syntax

C#
public static void g05tl(
    int n,
    int a,
    int b,
    G05..::..G05State g05state,
    int[] x,
    out int ifail
)
Visual Basic
Public Shared Sub g05tl ( _
    n As Integer, _
    a As Integer, _
    b As Integer, _
    g05state As G05..::..G05State, _
    x As Integer(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05tl(
    int n,
    int a,
    int b,
    G05..::..G05State^ g05state,
    array<int>^ x,
    [OutAttribute] int% ifail
)
F#
static member g05tl :
        n : int *
        a : int *
        b : int *
        g05state : G05..::..G05State *
        x : int[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of pseudorandom numbers to be generated.
Constraint: n≥0.
a
Type: System..::..Int32
On entry: the end points a and b of the uniform distribution.
Constraint: a≤b.
b
Type: System..::..Int32
On entry: the end points a and b of the uniform distribution.
Constraint: a≤b.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
x
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On exit: the n pseudorandom numbers from the specified uniform distribution.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g05tl generates the next n values yi from a uniform 0,1 generator (see g05sa for details) and applies the transformation
xi=a+b-a+1 yi,
where z is the integer part of the real value z. The method ensures that the values xi lie in the closed interval a,b.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05tl.

References

Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<0.
ifail=3
On entry, b<a.
ifail=4
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05tle.cs

Example program data: g05tle.d

Example program results: g05tle.r

See Also

G05 Class
G05 Members


g05yl Method

[image]

NAG Library for .NET Release 2
G05..::g05yl Method
G05 Class See Also Send Feedback
g05yl initializes a quasi-random generator prior to calling g05ym (G05YJF not in this release) (G05YKF not in this release).

Syntax

C#
public static void g05yl(
    int genid,
    int idim,
    int[] iref,
    int iskip,
    out int ifail
)
Visual Basic
Public Shared Sub g05yl ( _
    genid As Integer, _
    idim As Integer, _
    iref As Integer(), _
    iskip As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05yl(
    int genid,
    int idim,
    array<int>^ iref,
    int iskip,
    [OutAttribute] int% ifail
)
F#
static member g05yl :
        genid : int *
        idim : int *
        iref : int[] *
        iskip : int *
        ifail : int byref -> unit

Parameters

genid
Type: System..::..Int32
On entry: must identify the quasi-random generator to use.
genid=1
Sobol generator.
genid=2
Sobol (A659) generator.
genid=3
Niederreiter generator.
genid=4
Faure generator.
Constraint: genid=1, 2, 3 or 4.
idim
Type: System..::..Int32
On entry: the number of dimensions required.
Constraints:
  • if genid=1, 1≤idim≤10000;
  • if genid=2, 1≤idim≤1111;
  • if genid=3, 1≤idim≤318;
  • if genid=4, 1≤idim≤40.
iref
Type: array< System..::..Int32 >[]()[][]
An array of size [liref]
On exit: contains initialization information for use by the generator methods (G05YJF not in this release) (G05YKF not in this release) g05ym. iref must not be altered in any way between initialization and calls of the generator methods.
iskip
Type: System..::..Int32
On entry: the number of terms of the sequence to skip on initialization for the Sobol and Niederreiter generators. If genid=4, iskip is ignored.
Constraint: if genid=1, 2 or 3, 0≤iskip≤230.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g05yl selects a quasi-random number generator through the input value of genid and initializes the iref communication array for use by the methods g05ym (G05YJF not in this release) (G05YKF not in this release).
One of three types of quasi-random generator may be chosen, allowing the low-discrepancy sequences proposed by Sobol, Faure or Niederreiter to be generated.
Two sets of Sobol sequences are supplied, the first, is based on the work of Joe and Kuo (2008). The second, referred to in the documentation as "Sobol (A659)", is based on Algorithm 659 of Bratley and Fox (1988) with the extension to 1111 dimensions proposed by Joe and Kuo (2003). Both sets of Sobol sequences should satisfy the so-called Property A, up to 1111 dimensions, but the first set should have better two-dimensional projections than those produced using Algorithm 659.

References

Bratley P and Fox B L (1988) Algorithm 659: implementing Sobol's quasirandom sequence generator ACM Trans. Math. Software 14(1) 88–100
Fox B L (1986) Algorithm 647: implementation and relative efficiency of quasirandom sequence generators ACM Trans. Math. Software 12(4) 362–376
Joe S and Kuo F Y (2003) Remark on Algorithm 659: implementing Sobol's quasirandom sequence generator ACM Trans. Math. Software (TOMS) 29 49–57
Joe S and Kuo F Y (2008) Constructing Sobol sequences with better two-dimensional projections SIAM J. Sci. Comput. 30 2635–2654

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | genid<1,
or | genid>4.
ifail=2
On entry, | idim<1,
or | idim is too large.
ifail=4
On entry, liref is too small.
ifail=5
The value of iskip<0 or iskip is too large.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

The primitive polynomials and direction numbers used for the Sobol generator (genid=1) were calculated by Joe and Kuo (2008) using the search critera D 6.

Example

See [Example] in g05ym.

See Also

G05 Class
G05 Members


g05ym Method

[image]

NAG Library for .NET Release 2
G05..::g05ym Method
G05 Class See Also Send Feedback
g05ym generates a uniformly distributed low-discrepancy sequence as proposed by Sobol, Faure or Niederreiter. It must be preceded by a call to one of the initialization methods g05yl or g05yn.

Syntax

C#
public static void g05ym(
    int n,
    int rcord,
    double[,] quas,
    int[] iref,
    out int ifail
)
Visual Basic
Public Shared Sub g05ym ( _
    n As Integer, _
    rcord As Integer, _
    quas As Double(,), _
    iref As Integer(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05ym(
    int n,
    int rcord,
    array<double,2>^ quas,
    array<int>^ iref,
    [OutAttribute] int% ifail
)
F#
static member g05ym :
        n : int *
        rcord : int *
        quas : float[,] *
        iref : int[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: the number of quasi-random numbers required.
Constraint: n≥0 and n+previous number of generated values≤231-1.
rcord
Type: System..::..Int32
On entry: the order in which the generated values are returned.
Constraint: rcord=1 or 2.
quas
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, tdquas]
Note: dim1 must satisfy the constraint:
  • if rcord=1, dim1≥idim;
  • if rcord=2, dim1≥n.
On exit: contains the n quasi-random numbers of dimension idim.
If rcord=1, quas[i-1,j-1] holds the jth value for the ith dimension.
If rcord=2, quas[i-1,j-1] holds the ith value for the jth dimension.
iref
Type: array< System..::..Int32 >[]()[][]
An array of size [liref]
On entry: contains information on the current state of the sequence.
On exit: contains updated information on the state of the sequence.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Low discrepancy (quasi-random) sequences are used in numerical integration, simulation and optimization. Like pseudorandom numbers they are uniformly distributed but they are not statistically independent, rather they are designed to give more even distribution in multidimensional space (uniformity). Therefore they are often more efficient than pseudorandom numbers in multidimensional Monte–Carlo methods.
g05ym generates a set of points x 1,x 2,…,xN with high uniformity in the S-dimensional unit cube IS=0,1 S.
Let G be a subset of IS and define the counting function SN G as the number of points xi∈G. For each x=x 1,x 2,…,xS∈IS, let Gx be the rectangular S-dimensional region
Gx=0,x 1×0,x 2×⋯×0,xS
with volume x 1,x 2,…,xS. Then one measure of the uniformity of the points x 1,x 2,…,xN is the discrepancy:
DN*x 1,x 2,…,xN=sup x∈IS SN Gx-N x 1,x 2,…,xS.
which has the form
DN*x 1,x 2,…,xN≤CS log N S+O log N S-1  for all  N≥2.
The principal aim in the construction of low-discrepancy sequences is to find sequences of points in IS with a bound of this form where the constant CS is as small as possible.
The type of low-discrepancy sequence generated by g05ym depends on the initialization method called and can include those proposed by Sobol, Faure or Niederreiter. If the initialization method g05yn was used then the sequence will be scrambled (see [Description] in g05yn for details).

References

Bratley P and Fox B L (1988) Algorithm 659: implementing Sobol's quasirandom sequence generator ACM Trans. Math. Software 14(1) 88–100
Fox B L (1986) Algorithm 647: implementation and relative efficiency of quasirandom sequence generators ACM Trans. Math. Software 12(4) 362–376

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDQUAS) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, either n<0 or there have been too many calls to the generator.
ifail=2
On entry, rcord≠1 or 2.
ifail=4
On entry, rcord=1 and ldquas<idim.
On entry, rcord=2 and ldquas<n.
ifail=5
Incorrect initialization. g05yl must be called prior to g05ym and iref must remain unaltered after this call.
ifail=-9000
An error occured, see message report.
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

In this example the number of dimensions S is set to 8.

Example program (C#): g05yme.cs

Example program data: g05yme.d

Example program results: g05yme.r

See Also

G05 Class
G05 Members


g05yn Method

[image]

NAG Library for .NET Release 2
G05..::g05yn Method
G05 Class See Also Send Feedback
g05yn initializes a scrambled quasi-random generator prior to calling g05ym (G05YJF not in this release) (G05YKF not in this release). It must be preceded by a call to one of the pseudorandom initialization methods (G05KFF not in this release) (G05KGF not in this release).

Syntax

C#
public static void g05yn(
    int genid,
    int stype,
    int idim,
    int[] iref,
    int iskip,
    int nsdigi,
    G05..::..G05State g05state,
    out int ifail
)
Visual Basic
Public Shared Sub g05yn ( _
    genid As Integer, _
    stype As Integer, _
    idim As Integer, _
    iref As Integer(), _
    iskip As Integer, _
    nsdigi As Integer, _
    g05state As G05..::..G05State, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05yn(
    int genid,
    int stype,
    int idim,
    array<int>^ iref,
    int iskip,
    int nsdigi,
    G05..::..G05State^ g05state,
    [OutAttribute] int% ifail
)
F#
static member g05yn :
        genid : int *
        stype : int *
        idim : int *
        iref : int[] *
        iskip : int *
        nsdigi : int *
        g05state : G05..::..G05State *
        ifail : int byref -> unit

Parameters

genid
Type: System..::..Int32
On entry: must identify the quasi-random generator to use.
genid=1
Sobol generator.
genid=2
Sobol (A659) generator.
genid=3
Niederreiter generator.
Constraint: genid=1, 2 or 3.
stype
Type: System..::..Int32
On entry: must identify the scrambling method to use.
stype=0
No scrambling. This is equivalent to calling g05yl.
stype=1
Owen like scrambling.
stype=2
Faure–Tezuka scrambling.
stype=3
Owen and Faure–Tezuka scrambling.
Constraint: stype=0, 1, 2 or 3.
idim
Type: System..::..Int32
On entry: the number of dimensions required.
Constraints:
  • if genid=1, 1≤idim≤50000;
  • if genid=2, 1≤idim≤50000;
  • if genid=3, 1≤idim≤318.
iref
Type: array< System..::..Int32 >[]()[][]
An array of size [liref]
On exit: contains initialization information for use by the generator methods (G05YJF not in this release) (G05YKF not in this release) g05ym. iref must not be altered in any way between initialization and calls of the generator methods.
iskip
Type: System..::..Int32
On entry: the number of terms of the sequence to skip on initialization for the Sobol and Niederreiter generators.
Constraint: 0≤iskip≤230.
nsdigi
Type: System..::..Int32
On entry: controls the number of digits (bits) to scramble when genid=1 or 2, otherwise nsdigi is ignored. If nsdigi<1 or nsdigi>30 then all the digits are scrambled.
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g05yn selects a quasi-random number generator through the input value of genid, a method of scrambling through the input value of stype and initializes the iref communication array for use in the methods g05ym (G05YJF not in this release) (G05YKF not in this release).
Scrambled quasi-random sequences are an extension of standard quasi-random sequences that attempt to eliminate the bias inherent in a quasi-random sequence whilst retaining the low-discrepancy properties. The use of a scrambled sequence allows error estimation of Monte–Carlo results by performing a number of iterates and computing the variance of the results.
This implementation of scrambled quasi-random sequences is based on TOMS Algorithm 823 and details can be found in the accompanying paper, Hong and Hickernell (2003). Three methods of scrambling are supplied; the first a restricted form of Owen's scrambling (Owen (1995)), the second based on the method of Faure and Tezuka (2000) and the last method combines the first two.
Scrambled versions of the Niederreiter sequence and two sets of Sobol sequences are provided. The first Sobol sequence is obtained using genid=1. The first 10000 direction numbers for this sequence are based on the work of Joe and Kuo (2008). For dimensions greater than 10000 the direction numbers are randomly generated using the pseudorandom generator specified in state (see Jäckel (2002) for details). The second Sobol sequence is obtained using genid=2 and referred to in the documentation as ‘Sobol (A659)’. The first 1111 direction numbers for this sequence are based on Algorithm 659 of Bratley and Fox (1988) with the extension proposed by Joe and Kuo (2003). For dimensions greater than 1111 the direction numbers are once again randomly generated. The Niederreiter sequence is obtained by setting genid=3.

References

Bratley P and Fox B L (1988) Algorithm 659: implementing Sobol's quasirandom sequence generator ACM Trans. Math. Software 14(1) 88–100
Faure H and Tezuka S (2000) Another random scrambling of digital (t,s)-sequences Monte Carlo and Quasi-Monte Carlo Methods Springer-Verlag, Berlin, Germany (eds K T Fang, F J Hickernell and H Niederreiter)
Hong H S and Hickernell F J (2003) Algorithm 823: implementing scrambled digital sequences ACM Trans. Math. Software 29:2 95–109
Jäckel P (2002) Monte Carlo Methods in Finance Wiley Finance Series, John Wiley and Sons, England
Joe S and Kuo F Y (2003) Remark on Algorithm 659: implementing Sobol's quasirandom sequence generator ACM Trans. Math. Software (TOMS) 29 49–57
Joe S and Kuo F Y (2008) Constructing Sobol sequences with better two-dimensional projections SIAM J. Sci. Comput. 30 2635–2654
Niederreiter H (1988) Low-discrepancy and low dispersion sequences Journal of Number Theory 30 51–70
Owen A B (1995) Randomly permuted (t,m,s)-nets and (t,s)-sequences Monte Carlo and Quasi-Monte Carlo Methods in Scientific Computing, Lecture Notes in Statistics 106 Springer-Verlag, New York, NY 299–317 (eds H Niederreiter and P J-S Shiue)

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, genid≠1, 2 or 3.
ifail=2
stype≠0, 1, 2 or 3.
ifail=3
On entry, | idim<1,
or | idim is too large.
ifail=5
On entry, liref is too small.
ifail=6
The value of iskip<0 or iskip is too large.
ifail=8
On entry, state vector was not initialized or has been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

The additional computational cost in using a scrambled quasi-random sequence over a non-scrambled one comes entirely during the initialization. Once g05yn has been called the computational cost of generating a scrambled sequence and a non-scrambled one is identical.

Example

Example program (C#): g05yne.cs

Example program data: g05yne.d

Example program results: g05yne.r

See Also

G05 Class
G05 Members


G07 Class

[image]

NAG Library for .NET Release 2
G07 Class
Members See Also Send Feedback
This chapter deals with the estimation of unknown parameters of a univariate distribution. It includes both point and interval estimation using maximum likelihood and robust methods.

Syntax

C#
public static class G07
Visual Basic
Public NotInheritable Class G07
Visual C++
public ref class G07 abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type G07 =  class end

Background to the Problems

Statistical inference is concerned with the making of inferences about a population using the observed part of the population called a sample. The population can usually be described using a probability model which will be written in terms of some unknown parameters. For example, the hours of relief given by a drug may be assumed to follow a Normal distribution with mean μ and variance σ 2; it is then required to make inferences about the parameters, μ and σ 2, on the basis of an observed sample of relief times.
There are two main aspects of statistical inference: the estimation of the parameters and the testing of hypotheses about the parameters. In the example above, the values of the parameter σ 2 may be estimated and the hypothesis that μ≥3 tested. This chapter is mainly concerned with estimation but the test of a hypothesis about a parameter is often closely linked to its estimation. Tests of hypotheses which are not linked closely to estimation are given in the chapter on nonparametric statistics ( (G08 not in this release)).
There are two types of estimation to be considered in this chapter: point estimation and interval estimation. Point estimation is when a single value is obtained as the best estimate of the parameter. However, as this estimate will be based on only one of a large number of possible samples, it can be seen that if a different sample were taken, a different estimate would be obtained. The distribution of the estimate across all the possible samples is known as the sampling distribution. The sampling distribution contains information on the performance of the estimator, and enables estimators to be compared. For example, a good estimator would have a sampling distribution with mean equal to the true value of the parameter; that is, it should be an unbiased estimator; also the variance of the sampling distribution should be as small as possible. When considering a parameter estimate it is important to consider its variability as measured by its variance, or more often the square root of the variance, the standard error.
The sampling distribution can be used to find interval estimates or confidence intervals for the parameter. A confidence interval is an interval calculated from the sample so that its distribution, as given by the sampling distribution, is such that it contains the true value of the parameter with a certain probability.
Estimates will be functions of the observed sample and these functions are known as estimators. It is usually more convenient for the estimator to be based on statistics from the sample rather than all the individuals observations. If these statistics contain all the relevant information then they are known as sufficient statistics. There are several ways of obtaining the estimators; these include least squares, the method of moments, and maximum likelihood. Least squares estimation requires no knowledge of the distributional form of the error apart from its mean and variance matrix, whereas the method of maximum likelihood is mainly applicable to situations in which the true distribution is known apart from the values of a finite number of unknown parameters. Note that under the assumption of Normality, the least squares estimation is equivalent to the maximum likelihood estimation. Least squares is often used in regression analysis as described in G02 class, and maximum likelihood is described below.
Estimators derived from least squares or maximum likelihood will often be greatly affected by the presence of extreme or unusual observations. Estimators that are designed to be less affected are known as robust estimators.

Maximum Likelihood Estimation

Let Xi be a univariate random variable with probability density function
f Xi xi;θ,
where θ is a vector of length p consisting of the unknown parameters. For example, a Normal distribution with mean θ 1 and standard deviation θ 2 has probability density function
1 2 π θ 2 exp-12 xi-θ 1 θ 2 2.
The likelihood for a sample of n independent observations is
Like=∏i=1 n f Xi xi;θ,
where xi is the observed value of Xi. If each Xi has an identical distribution, this reduces to
Like=∏i=1 n fX xi;θ, (1)
and the log-likelihood is
log Like=L=∑i=1 n log fX xi;θ. (2)
The maximum likelihood estimates (θ^) of θ are the values of θ that maximize (1) and (2). If the range of X is independent of the parameters, then θ^ can usually be found as the solution to
∑i=1 n∂∂θ^j log fX xi;θ^=∂L∂θ^j=0,  j=1,2,…,p. (3)
Note that ∂L∂θj is known as the efficient score.
Maximum likelihood estimators possess several important properties.
(a) | Maximum likelihood estimators are functions of the sufficient statistics.
(b) | Maximum likelihood estimators are (under certain conditions) consistent. That is, the estimator converges in probability to the true value as the sample size increases. Note that for small samples the maximum likelihood estimator may be biased.
(c) For maximum likelihood estimators found as a solution to (3), subject to certain conditions, it follows that
E∂L∂θ=0, (4)
and
I θ=-E∂2 L∂θ 2=E∂L∂θ 2, (5)
and then that θ^ is asymptotically Normal with mean vector θ 0 and variance-covariance matrix I θ 0-1 where θ 0 denotes the true value of θ. The matrix Iθ is known as the information matrix and I θ 0-1 is known as the Cramer–Rao lower bound for the variance of an estimator of θ.
For example, if we consider a sample, x 1,x 2,…,xn, of size n drawn from a Normal distribution with unknown mean μ and unknown variance σ 2 then we have
L=log Like μ,σ 2;x=-n 2 log 2 π-n 2 log σ 2-∑i=1 n xi-μ 2/2 σ 2
and thus
∂L∂μ=∑i=1 n xi-μ/σ 2
and
∂L∂σ 2=-n 2 σ 2+∑i=1 n xi-μ 2/2 σ 4.
Then equating these two equations to zero and solving gives the maximum likelihood estimates
μ^=x-
and
σ^2=∑i=1 n xi-x-2/n.
These maximum likelihood estimates are asymptotically Normal with mean vector a, where
aT=μ,σ 2,
and covariance matrix C. To obtain C we find the second derivatives of L with respect to μ and σ 2 as follows:
∂2 L∂μ 2=-n σ 2∂2 L∂σ 2 2=n 2 σ 4-∑i=1 n xi-μ 2/σ 6∂2 L∂μ∂σ 2=∂2 L∂σ 2∂μ=-n x--μ σ 4.
Then
C-1=-E∂2 L∂μ 2∂2 L∂σ 2∂μ∂2 L∂μ∂σ 2∂2 L∂σ 2 2=n/σ 200n/2 σ 4
so that
C=σ 2/n002 σ 4/n.
To obtain an estimate of C the matrix may be evaluated at the maximum likelihood estimates.
It may not always be possible to find maximum likelihood estimates in a convenient closed form, and in these cases iterative numerical methods, such as the Newton–Raphson procedure or the EM algorithm (expectation maximization), will be necessary to compute the maximum likelihood estimates. Their asymptotic variances and covariances may then be found by substituting the estimates into the second derivatives. Note that it may be difficult to find the expected value of the second derivatives required for the variance-covariance matrix and in these cases the observed value of the second derivatives is often used.
The use of maximum likelihood estimation allows the construction of generalized likelihood ratio tests. If λ=2 l 1-l 2, where l 1 is the maximized log-likelihood function for a model 1 and l 2 is the maximized log-likelihood function for a model 2, then under the hypothesis that model 2 is correct, 2 λ is asymptotically distributed as a χ 2 variable with p-q degrees of freedom. Consider two models in which model 1 has p parameters and model 2 is a sub-model (nested model) of model 1 with q<p parameters, that is model 1 has an extra p-q parameters. This result provides a useful method for performing hypothesis tests on the parameters. Alternatively, tests exist based on the asymptotic Normality of the estimator and the efficient score; see page 315 of Cox and Hinkley (1974).

Confidence Intervals

Suppose we can find a function, t x,θ, whose distribution depends upon the sample x but not on the unknown parameter θ, and which is a monotonic (say decreasing) function in θ for each x, then we can find t 1 such that P t 1≤t x,θ=1-α no matter what θ happens to be. The function t x,θ is known as a pivotal quantity. Since the function is monotonic the statement that t 1≤t x,θ may be rewritten as θ≥θ 1 x see Figure 1. The statistic θ 1 x will vary from sample to sample and if we assert that θ≥θ 1 x for any sample values which arise, we will be right in a proportion 1-α of the cases, in the long run or on average. We call θ 1 x a 1-α upper confidence limit for θ.
Figure 1
We have considered only an upper confidence limit. The above idea may be generalized to a two-sided confidence interval where two quantities, t 0 and t 1, are found such that for all θ, P t 1≤t x,θ≤t 0=1-α. This interval may be rewritten as θ 0 x≤θ≤θ 1 x. Thus if we assert that θ lies in the interval [θ 0 x,θ 1 x] we will be right on average in 1-α proportion of the times under repeated sampling.
Hypothesis (significance) tests on the parameters may be used to find these confidence limits. For example, if we observe a value, k, from a binomial distribution, with known parameter n and unknown parameter p, then to find the lower confidence limit we find pl such that the probability that the null hypothesis H 0: p=pl (against the one sided alternative that p>pl) will be rejected, is less than or equal to α/2. Thus for a binomial random variable, B, with parameters n and pl we require that P B≥k≤α/2. The upper confidence limit, pu, can be constructed in a similar way.
For large samples the asymptotic Normality of the maximum likelihood estimates discussed above is used to construct confidence intervals for the unknown parameters.

Robust Estimation

For particular cases the probability density function can be written as
f Xi xi;θ=1 θ 2 g xi-θ 1 θ 2
for a suitable function g; then θ 1 is known as a location parameter and θ 2, usually written as σ, is known as a scale parameter. This is true of the Normal distribution.
If θ 1 is a location parameter, as described above, then equation (3) becomes
∑i=1 n ψ xi-θ^1 σ^=0, (6)
where ψ z=-d dz log g z.
For the scale parameter σ (or σ 2) the equation is
∑i=1 n χ xi-θ^1 σ^=n/2, (7)
where χ z=zψ z/2.
For the Normal distribution ψ z=z and χ z=z 2/2. Thus, the maximum likelihood estimates for θ 1 and σ 2 are the sample mean and variance with the n divisor respectively. As the latter is biased, (7) can be replaced by
∑i=1 n χ xi-θ^1 σ^=n-1 β, (8)
where β is a suitable constant, which for the Normal χ function is 12.
The influence of an observation on the estimates depends on the form of the ψ and χ functions. For a discussion of influence, see Hampel et al. (1986) and Huber (1981). The influence of extreme values can be reduced by bounding the values of the ψ- and χ-functions. One suggestion due to Huber (1981) is
ψ z=-C,||z<-Cz,z≤CC,||z>C.
Figure 2
Redescending ψ-functions are often considered; these give zero values to ψ z for large positive or negative values of z. Hampel et al. (1986) suggested
ψ z=-ψ-zz,0≤z≤h 1.h 1,h 1≤z≤h 2.h 1 h 3-z/h 3-h 2,h 2≤z≤h 3.0,z>h 3.
Figure 3
Usually a χ-function based on Huber's ψ-function is used: χ=ψ 2/2. Estimators based on such bounded ψ-functions are known as M-estimators, and provide one type of robust estimator.
Other robust estimators for the location parameter are
(i) | the sample median,
(ii) | the trimmed mean, i.e., the mean calculated after the extreme values have been removed from the sample,
(iii) | the winsorized mean, i.e., the mean calculated after the extreme values of the sample have been replaced by other more moderate values from the sample.
For the scale parameter, alternative estimators are
(i) | the median absolute deviation scaled to produce an estimator which is unbiased in the case of data coming from a Normal distribution,
(ii) | the winsorized variance, i.e., the variance calculated after the extreme values of the sample have been replaced by other more moderate values from the sample.
For a general discussion of robust estimation, see Hampel et al. (1986) and Huber (1981).

Robust Confidence Intervals

In [Confidence Intervals] it was shown how tests of hypotheses can be used to find confidence intervals. That approach uses a parametric test that requires the assumption that the data used in the computation of the confidence has a known distribution. As an alternative, a more robust confidence interval can be found by replacing the parametric test by a nonparametric test. In the case of the confidence interval for the location parameter, a Wilcoxon test statistic can be used, and for the difference in location, computed from two samples, a Mann–Whitney test statistic can be used.

Recommendations on Choice and Use of Available Methods

Maximum Likelihood Estimation and Confidence Intervals
(G07AAF not in this release) | provides a confidence interval for the parameter p of the binomial distribution.
(G07ABF not in this release) | provides a confidence interval for the mean parameter of the Poisson distribution.
(G07BBF not in this release) | provides maximum likelihood estimates and their standard errors for the parameters of the Normal distribution from grouped and/or censored data.
(G07BEF not in this release) | provides maximum likelihood estimates and their standard errors for the parameters of the Weibull distribution from data which may be right-censored.
(G07BFF not in this release) | provides maximum likelihood estimates and their standard errors for the parameters of the generalized Pareto distribution.
(G07CAF not in this release) | provides a t-test statistic to test for a difference in means between two Normal populations, together with a confidence interval for the difference between the means.
Robust Estimation
(G07DBF not in this release) | provides M-estimates for location and, optionally, scale using four common forms of the ψ-function.
(G07DCF not in this release) | produces the M-estimates for location and, optionally, scale but for user-supplied ψ- and χ-functions.
(G07DAF not in this release) | provides the sample median, median absolute deviation, and the scaled value of the median absolute deviation.
(G07DDF not in this release) | provides the trimmed mean and winsorized mean together with estimates of their variance based on a winsorized variance.
Robust Internal Estimation
(G07EAF not in this release) | produces a rank based confidence interval for locations.
(G07EBF not in this release) | produces a rank based confidence interval for the difference in location between two populations.
Outlier Detection
This chapter provides two methods for identifying potential outlying values, g07ga and g07gb. Many of the model fitting methods, for examples those in G02 class G13 class also return vectors of residuals which can also be used to aid in the identification of outlying values.

References

Cox D R and Hinkley D V (1974) Theoretical Statistics Chapman and Hall
Hampel F R, Ronchetti E M, Rousseeuw P J and Stahel W A (1986) Robust Statistics. The Approach Based on Influence Functions Wiley
Huber P J (1981) Robust Statistics Wiley
Kendall M G and Stuart A (1973) The Advanced Theory of Statistics (Volume 2) (3rd Edition) Griffin
Silvey S D (1975) Statistical Inference Chapman and Hall

Inheritance Hierarchy

System..::..Object
NagLibrary..::..G07

See Also

G07 Members


G07 Members

[image] [image]

NAG Library for .NET Release 2
G07 Members
G07 Class Methods See Also Send Feedback

The G07 type exposes the following members.

Methods

Name | Description
g07ga | g07ga identifies outlying values using Peirce's criterion.
g07gb | g07gb returns a flag indicating whether a single data point is an outlier as defined by Peirce's criterion.

See Also

G07 Class


G07 Methods

[image] [image]

NAG Library for .NET Release 2
G07 Methods
G07 Class See Also Send Feedback

The G07 type exposes the following members.

Methods

Name | Description
g07ga | g07ga identifies outlying values using Peirce's criterion.
g07gb | g07gb returns a flag indicating whether a single data point is an outlier as defined by Peirce's criterion.

See Also

G07 Class


g07ga Method

[image]

NAG Library for .NET Release 2
G07..::g07ga Method
G07 Class See Also Send Feedback
g07ga identifies outlying values using Peirce's criterion.

Syntax

C#
public static void g07ga(
    int n,
    int p,
    double[] y,
    double mean,
    double var,
    int[] iout,
    out int niout,
    int ldiff,
    double[] diff,
    double[] llamb,
    out int ifail
)
Visual Basic
Public Shared Sub g07ga ( _
    n As Integer, _
    p As Integer, _
    y As Double(), _
    mean As Double, _
    var As Double, _
    iout As Integer(), _
    <OutAttribute> ByRef niout As Integer, _
    ldiff As Integer, _
    diff As Double(), _
    llamb As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g07ga(
    int n,
    int p,
    array<double>^ y,
    double mean,
    double var,
    array<int>^ iout,
    [OutAttribute] int% niout,
    int ldiff,
    array<double>^ diff,
    array<double>^ llamb,
    [OutAttribute] int% ifail
)
F#
static member g07ga :
        n : int *
        p : int *
        y : float[] *
        mean : float *
        var : float *
        iout : int[] *
        niout : int byref *
        ldiff : int *
        diff : float[] *
        llamb : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n≥3.
p
Type: System..::..Int32
On entry: p, the number of parameters in the model used in obtaining the y. If y is an observed set of values, as opposed to the residuals from fitting a model with p parameters, then p should be set to 1, i.e., as if a model just containing the mean had been used.
Constraint: 1≤p≤n-2.
y
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: y, the data being tested.
mean
Type: System..::..Double
On entry: if var>0.0, mean must contain μ, the mean of y, otherwise mean is not referenced and the mean is calculated from the data supplied in y.
var
Type: System..::..Double
On entry: if var>0.0, var must contain σ 2, the variance of y, otherwise the variance is calculated from the data supplied in y.
iout
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On exit: the indices of the values in y sorted in descending order of the absolute difference from the mean, therefore y[iout[i-2]-1]-μ≥y[iout[i-1]-1]-μ, for i=2,3,…,n.
niout
Type: System..::..Int32 %
On exit: the number of potential outliers. The indices for these potential outliers are held in the first niout elements of iout. By construction there can be at most n-p-1 values flagged as outliers.
ldiff
Type: System..::..Int32
On entry: the maximum number of values to be returned in arrays diff and llamb.
If ldiff≤0, arrays diff and llamb are not referenced.
diff
Type: array< System..::..Double >[]()[][]
An array of size [ldiff]
On exit: diff[i-1] holds y-μ-σ 2 z for observation y[iout[i-1]-1], for i=1,2,…,min ldiff,niout+1,n-p-1.
llamb
Type: array< System..::..Double >[]()[][]
An array of size [ldiff]
On exit: llamb[i-1] holds log λ 2 for observation y[iout[i-1]-1], for i=1,2,…,min ldiff,niout+1,n-p-1.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g07ga flags outlying values in data using Peirce's criterion. Let
  • y denote a vector of n observations (for example the residuals) obtained from a model with p parameters,
  • m denote the number of potential outlying values,
  • μ and σ 2 denote the mean and variance of y respectively,
  • y~ denote a vector of length n-m constructed by dropping the m values from y with the largest value of yi-μ,
  • σ~2 denote the (unknown) variance of y~,
  • λ denote the ratio of σ~ and σ with λ=σ~σ.
Peirce's method flags yi as a potential outlier if yi-μ≥x, where x=σ 2 z and z is obtained from the solution of
Rm=λ m-n mmn-m n-m nn (1)
where
R=2 exp z 2-1 21-Φ z (2)
and Φ is the cumulative distribution function for the standard Normal distribution.
As σ~2 is unknown an assumption is made that the relationship between σ~2 and σ 2, hence λ, depends only on the sum of squares of the rejected observations and the ratio estimated as
λ 2=n-p-m z 2n-p-m
which gives
z 2=1+n-p-m m 1-λ 2 (3)
A value for the cutoff x is calculated iteratively. An initial value of R=0.2 is used and a value of λ is estimated using equation (1). Equation (3) is then used to obtain an estimate of z and then equation (2) is used to get a new estimate for R. This process is then repeated until the relative change in z between consecutive iterations is ≤ε, where ε is machine precision.
By construction, the cutoff for testing for m+1 potential outliers is less than the cutoff for testing for m potential outliers. Therefore Peirce's criterion is used in sequence with the existence of a single potential outlier being investigated first. If one is found, the existence of two potential outliers is investigated etc.
If one of a duplicate series of observations is flagged as an outlier, then all of them are flagged as outliers.

References

Gould B A (1855) On Peirce's criterion for the rejection of doubtful observations, with tables for facilitating its application The Astronomical Journal 45
Peirce B (1852) Criterion for the rejection of doubtful observations The Astronomical Journal 45

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<3.
ifail=2
On entry, p≤0 or p>n-2.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

One problem with Peirce's algorithm as implemented in g07ga is the assumed relationship between σ 2, the variance using the full dataset, and σ~2, the variance with the potential outliers removed. In some cases, for example if the data y were the residuals from a linear regression, this assumption may not hold as the regression line may change significantly when outlying values have been dropped resulting in a radically different set of residuals. In such cases g07gb should be used instead.

Example

This example reads in a series of data and flags any potential outliers.
The dataset used is from Peirce's original paper and consists of fifteen observations on the vertical semidiameter of Venus.

Example program (C#): g07gae.cs

Example program data: g07gae.d

Example program results: g07gae.r

See Also

G07 Class
G07 Members


g07gb Method

[image]

NAG Library for .NET Release 2
G07..::g07gb Method
G07 Class See Also Send Feedback
g07gb returns a flag indicating whether a single data point is an outlier as defined by Peirce's criterion.

Syntax

C#
public static bool g07gb(
    int n,
    double e,
    double var1,
    double var2,
    out double x,
    out double lx,
    out double ux,
    out int ifail
)
Visual Basic
Public Shared Function g07gb ( _
    n As Integer, _
    e As Double, _
    var1 As Double, _
    var2 As Double, _
    <OutAttribute> ByRef x As Double, _
    <OutAttribute> ByRef lx As Double, _
    <OutAttribute> ByRef ux As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Boolean
Visual C++
public:
static bool g07gb(
    int n,
    double e,
    double var1,
    double var2,
    [OutAttribute] double% x,
    [OutAttribute] double% lx,
    [OutAttribute] double% ux,
    [OutAttribute] int% ifail
)
F#
static member g07gb :
        n : int *
        e : float *
        var1 : float *
        var2 : float *
        x : float byref *
        lx : float byref *
        ux : float byref *
        ifail : int byref -> bool

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations.
Constraint: n≥3.
e
Type: System..::..Double
On entry: e~, the value being tested.
var1
Type: System..::..Double
On entry: σ 2, the residual variance on fitting model M to y.
Constraint: var1>0.0.
var2
Type: System..::..Double
On entry: σ~2, the residual variance on fitting model M to y~.
Constraints:
  • var2>0.0;
  • var2<var1.
x
Type: System..::..Double %
On exit: an estimated value of x, the cutoff that indicates an outlier.
lx
Type: System..::..Double %
On exit: l, the lower limit for x.
ux
Type: System..::..Double %
On exit: u, the upper limit for x.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

g07gb returns a flag indicating whether a single data point is an outlier as defined by Peirce's criterion.

Description

g07gb tests a potential outlying value using Peirce's criterion. Let
  • e denote a vector of n residuals with mean zero and variance σ 2 obtained from fitting some model M to a series of data y,
  • e~ denote the largest absolute residual in e, i.e., e~≥ei for all i, and let y~ denote the data series y with the observation corresponding to e~ having been omitted,
  • σ~2 denote the residual variance on fitting model M to y~,
  • λ denote the ratio of σ~ and σ with λ=σ~σ.
Peirce's method flags e~ as a potential outlier if e~≥x, where x=σ 2 z and z is obtained from the solution of
R=λ 1-n n-1 n-1 nn (1)
where
R=2 exp z 2-1 21-Φ z (2)
and Φ is the cumulative distribution function for the standard Normal distribution.
Unlike g07ga, both σ 2 and σ~2 must be supplied and therefore no assumptions are made about the nature of the relationship between these two quantities. Only a single potential outlier is tested for at a time.
This method uses an algorithm described in e04ab to refine a lower, l, and upper, u, limit for x. This refinement stops when e~<l or e~>u.

References

Gould B A (1855) On Peirce's criterion for the rejection of doubtful observations, with tables for facilitating its application The Astronomical Journal 45
Peirce B (1852) Criterion for the rejection of doubtful observations The Astronomical Journal 45

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, n<3.
ifail=3
On entry, var1≤0.0.
ifail=4
On entry, var2≤0.0 or var2≥var1.
ifail=-9000
An error occured, see message report.

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads in a series of values and variances and checks whether each is a potential outlier.
The dataset used is from Peirce's original paper and consists of fifteen observations on the vertical semidiameter of Venus. Each subsequent line in the dataset, after the first, is the result of dropping the observation with the highest absolute value from the previous data and recalculating the variance.

Example program (C#): g07gbe.cs

Example program data: g07gbe.d

Example program results: g07gbe.r

See Also

G07 Class
G07 Members


G13 Class

[image]

NAG Library for .NET Release 2
G13 Class
Members See Also Send Feedback
This chapter provides facilities for investigating and modelling the statistical structure of series of observations collected at points in time. The models may then be used to forecast the series.
The chapter covers the following models and approaches.
1. | Univariate time series analysis, including autocorrelation functions and autoregressive moving average (ARMA) models.
2. | Univariate spectral analysis.
3. | Transfer function (multi-input) modelling, in which one time series is dependent on other time series.
4. | Bivariate spectral methods including coherency, gain and input response functions.
5. | Vector ARMA models for multivariate time series.
6. | Kalman filter models.
7. | GARCH models for volatility.
8. | Inhomogeneous Time Series.

Syntax

C#
public static class G13
Visual Basic
Public NotInheritable Class G13
Visual C++
public ref class G13 abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type G13 =  class end

Background to the Problems

Univariate Analysis

Let the given time series be x 1,x 2,…,xn, where n is its length. The structure which is intended to be investigated, and which may be most evident to the eye in a graph of the series, can be broadly described as:
(a) | trends, linear or possibly higher-order polynomial;
(b) | seasonal patterns, associated with fixed integer seasonal periods. The presence of such seasonality and the period will normally be known a priori. The pattern may be fixed, or slowly varying from one season to another;
(c) | cycles or waves of stable amplitude and period p (from peak to peak). The period is not necessarily integer, the corresponding absolute frequency (cycles/time unit) being f=1/p and angular frequency ω=2 πf. The cycle may be of pure sinusoidal form like sin ωt, or the presence of higher harmonic terms may be indicated, e.g., by asymmetry in the wave form;
(d) | quasi-cycles, i.e., waves of fluctuating period and amplitude; and
(e) | irregular statistical fluctuations and swings about the overall mean or trend.
Trends, seasonal patterns, and cycles might be regarded as deterministic components following fixed mathematical equations, and the quasi-cycles and other statistical fluctuations as stochastic and describable by short-term correlation structure. For a finite dataset it is not always easy to discriminate between these two types, and a common description using the class of autoregressive integrated moving-average (ARIMA) models is now widely used. The form of these models is that of difference equations (or recurrence relations) relating present and past values of the series. You are referred to Box and Jenkins (1976) for a thorough account of these models and how to use them. We follow their notation and outline the recommended steps in ARIMA model building for which methods are available.

Transformations

If the variance of the observations in the series is not constant across the range of observations it may be useful to apply a variance-stabilizing transformation to the series. A common situation is for the variance to increase with the magnitude of the observations and in this case typical transformations used are the log or square root transformation. A range-mean plot or standard deviation-mean plot provides a quick and easy way of detecting non-constant variance and of choosing, if required, a suitable transformation. These are plots of either the range or standard deviation of successive groups of observations against their means.

Differencing operations

These may be used to simplify the structure of a time series.
First-order differencing, i.e., forming the new series
∇xt=xt-x t-1
will remove a linear trend. First-order seasonal differencing
∇sxt=xt-x t-s
eliminates a fixed seasonal pattern.
These operations reflect the fact that it is often appropriate to model a time series in terms of changes from one value to another. Differencing is also therefore appropriate when the series has something of the nature of a random walk, which is by definition the accumulation of independent changes.
Differencing may be applied repeatedly to a series, giving
wt=∇d∇sD xt
where d and D are the orders of differencing. The derived series wt will be shorter, of length N=n-d-s×D, and extend for t=1+d+s×D,…,n.

Sample autocorrelations

Given that a series has (possibly as a result of simplifying by differencing operations) a homogeneous appearance throughout its length, fluctuating with approximately constant variance about an overall mean level, it is appropriate to assume that its statistical properties are stationary. For most purposes the correlations ρk between terms xt,x t+k or wt,w t+k separated by lag k give an adequate description of the statistical structure and are estimated by the sample autocorrelation function (ACF) rk, for k=1,2,….
As described by Box and Jenkins (1976), these may be used to indicate which particular ARIMA model may be appropriate.

Partial autocorrelations

The information in the autocorrelations, ρk, may be presented in a different light by deriving from them the coefficients of the partial autocorrelation function (PACF) ϕ k,k, for k=1,2,…. ϕ k,k which measures the correlation between xt and x t+k conditional upon the intermediate values x t+1,x t+2,…,x t+k-1. The corresponding sample values ϕ^k,k give further assistance in the selection of ARIMA models.
Both autocorrelation function (ACF) and PACF may be rapidly computed, particularly in comparison with the time taken to estimate ARIMA models.

Finite lag predictor coefficients and error variances

The partial autocorrelation coefficient ϕ k,k is determined as the final parameter in the minimum variance predictor of xt in terms of x t-1,x t-2,…,x t-k,
xt=ϕ k,1x t-1+ϕ k,2x t-2+⋯+ϕ k,kx t-k+e k,t
where e k,t is the prediction error, and the first subscript k of ϕ k,i and e k,t emphasizes the fact that the parameters will alter as k increases. Moderately good estimates ϕ^k,i of ϕ k,i are obtained from the sample autocorrelation function (ACF), and after calculating the partial autocorrelation function (PACF) up to lag L, the successive values v 1,v 2,…,vL of the prediction error variance estimates, vk=var e k,t, are available, together with the final values of the coefficients ϕ^k,1,ϕ^k,2,…,ϕ^k,L. If xt has nonzero mean, x-, it is adequate to use xt-x- in place of xt in the prediction equation.
Although Box and Jenkins (1976) do not place great emphasis on these prediction coefficients, their use is advocated for example by Akaike (1971), who recommends selecting an optimal order of the predictor as the lag for which the final prediction error (FPE) criterion 1+k/n 1-k/n-1 vk is a minimum.

ARIMA models

The correlation structure in stationary time series may often be represented by a model with a small number of parameters belonging to the autoregressive moving-average (ARMA) class. If the stationary series wt has been derived by differencing from the original series xt, then xt is said to follow an ARIMA model. Taking wt=∇d xt, the (non-seasonal) ARIMA p,d,q model with p autoregressive parameters ϕ 1,ϕ 2,…,ϕp and q moving-average parameters θ 1,θ 2,…,θq, represents the structure of wt by the equation
wt=ϕ 1w t-1+⋯+ϕpw t-p+at-θ 1a t-1-⋯-θqa t-q, (1)
where at is an uncorrelated series (white noise) with mean 0 and constant variance σa 2. If wt has a nonzero mean c, then this is allowed for by replacing wt,w t-1,… by wt-c,w t-1-c,… in the model. Although c is often estimated by the sample mean of wt this is not always optimal.
A series generated by this model will only be stationary provided restrictions are placed on ϕ 1,ϕ 2,…,ϕp to avoid unstable growth of wt. These are called stationarity constraints. The series at may also be usefully interpreted as the linear innovations in xt (and in wt), i.e., the error if xt were to be predicted using the information in all past values x t-1,x t-2,…, provided also that θ 1,θ 2,…,θq satisfy invertibility constraints. This allows the series at to be regenerated by rewriting the model equation as
at=wt-ϕ 1w t-1-⋯-ϕpw t-p+θ 1a t-1+⋯+θqa t-q. (2)
For a series with short-term correlation only, i.e., rk is not significant beyond some low lag q (see Box and Jenkins (1976) for the statistical test), then the pure moving-average model MA q is appropriate, with no autoregressive parameters, i.e., p=0.
Autoregressive parameters are appropriate when the autocorrelation function (ACF) pattern decays geometrically, or with a damped sinusoidal pattern which is associated with quasi-periodic behaviour in the series. If the sample partial autocorrelation function (PACF) ϕ^k,k is significant only up to some low lag p, then a pure autoregressive model AR p is appropriate, with q=0. Otherwise moving-average terms will need to be introduced, as well as autoregressive terms.
The seasonal ARIMA p,d,q,P,D,Q,s model allows for correlation at lags which are multiples of the seasonal period s. Taking wt=∇d∇sD xt, the series is represented in a two-stage manner via an intermediate series et:
wt=Φ 1w t-s+⋯+ΦPw t-s×P+et-Θ 1e t-s-⋯-ΘQe t-s×Q (3)
et=ϕ 1e t-1+⋯+ϕpe t-p+at-θ 1a t-1-⋯-θqa t-q (4)
where Φi, Θi are the seasonal parameters and P and Q are the corresponding orders. Again, wt may be replaced by wt-c.

ARIMA model estimation

In theory, the parameters of an ARIMA model are determined by a sufficient number of autocorrelations ρ 1,ρ 2,…. Using the sample values r 1,r 2,… in their place it is usually (but not always) possible to solve for the corresponding ARIMA parameters.
These are rapidly computed but are not fully efficient estimates, particularly if moving-average parameters are present. They do provide useful preliminary values for an efficient but relatively slow iterative method of estimation. This is based on the least squares principle by which parameters are chosen to minimize the sum of squares of the innovations at, which are regenerated from the data using (2), or the reverse of (3) and (4) in the case of seasonal models.
Lack of knowledge of terms on the right-hand side of (2), when t=1,2,…,max p,q, is overcome by introducing q unknown series values w 0,w 1,…,w q-1 which are estimated as nuisance parameters, and using correction for transient errors due to the autoregressive terms. If the data w 1,w 2,…,wN=w is viewed as a single sample from a multivariate Normal density whose covariance matrix V is a function of the ARIMA model parameters, then the exact likelihood of the parameters is
-12 log V-12 wTV-1 w.
The least squares criterion as outlined above is equivalent to using the quadratic form
QF=wTV-1 w
as an objective function to be minimized. Neglecting the term -12log V yields estimates which differ very little from the exact likelihood except in small samples, or in seasonal models with a small number of whole seasons contained in the data. In these cases bias in moving-average parameters may cause them to stick at the boundary of their constraint region, resulting in failure of the estimation method.
Approximate standard errors of the parameter estimates and the correlations between them are available after estimation.
The model residuals, a^t, are the innovations resulting from the estimation and are usually examined for the presence of autocorrelation as a check on the adequacy of the model.

ARIMA model forecasting

An ARIMA model is particularly suited to extrapolation of a time series. The model equations are simply used for t=n+1,n+2,… replacing the unknown future values of at by zero. This produces future values of wt, and if differencing has been used this process is reversed (the so-called integration part of ARIMA models) to construct future values of xt.
Forecast error limits are easily deduced.
This process requires knowledge only of the model orders and parameters together with a limited set of the terms a t-i,e t-i,w t-i,x t-i which appear on the right-hand side of the models (3) and (4) (and the differencing equations) when t=n. It does not require knowledge of the whole series.
We call this the state set. It is conveniently constituted after model estimation. Moreover, if new observations x n+1,x n+2,… come to hand, then the model equations can easily be used to update the state set before constructing forecasts from the end of the new observations. This is particularly useful when forecasts are constructed on a regular basis. The new innovations a n+1,a n+2,… may be compared with the residual standard deviation, σa, of the model used for forecasting, as a check that the model is continuing to forecast adequately.

Exponential Smoothing

Exponential smoothing is a relatively simple method of short term forecasting for a time series. A variety of different smoothing methods are possible, including; single exponential, Brown's double exponential, linear Holt (also called double exponential smoothing in some references), additive Holt–Winters and multiplicative Holt–Winters. The choice of smoothing method used depends on the characteristics of the time series. If the mean of the series is only slowly changing then single exponential smoothing may be suitable. If there is a trend in the time series, which itself may be slowly changing, then linear Holt smoothing may be suitable. If there is a seasonal component to the time series, e.g., daily or monthly data, then one of the two Holt–Winters methods may be suitable.
For a time series yt, for t=1,2,…,n, the five smoothing functions are defined by the following:
  • Single Exponential Smoothing
    mt=α yt+1-α m t-1y^t+f=mtvar y^t+f=var εt 1+f-1 α 2
  • Brown Double Exponential Smoothing
    mt=α yt+1-α m t-1rt=α mt-m t-1+1-α r t-1y^t+f=mt+f-1+1/α rtvar y^t+f=var εt 1+∑ i=0 f-1 2 α+i-1 α 2 2
  • Linear Holt Smoothing
    mt=α yt+1-αm t-1+ϕ r t-1rt=γ mt-m t-1+1-γ ϕ r t-1y^t+f=mt+∑ i=1 f ϕi rtvar y^t+f=var εt 1+∑ i=1 f-1 α+αγϕ ϕi-1 ϕ-1 2
  • Additive Holt–Winters Smoothing
    mt=α yt-s t-p+1-αm t-1+ϕ r t-1rt=γ mt-m t-1+1-γ ϕ r t-1st=β yt-mt+1-β s t-py^t+f=mt+∑ i=1 f ϕi rt+s t-pvar y^t+f=var εt 1+∑ i=1 f-1 ψi 2ψi=0if ​i≥fα+αγϕ ϕi-1ϕ-1if ​i mod p≠0α+αγϕ ϕi-1 ϕ-1+β 1-αotherwise
  • Multiplicative Holt–Winters Smoothing
    mt=α yt/s t-p+1-αm t-1+ϕ r t-1rt=γ mt-m t-1+1-γ ϕ r t-1st=β yt/mt+1-β s t-py^t+f=mt+∑ i=1 f ϕi rt×s t-pvar y^t+f=var εt∑ i=0 ∞ ∑ j=0 p-1 ψ j+ip s t+fs t+f-j 2
    and ψ is defined as in the additive Holt–Winters smoothing,
where mt is the mean, rt is the trend and st is the seasonal component at time t with p being the seasonal order. The f-step ahead forecasts are given by y^t+f and their variances by var y^t+f. The term var εt is estimated as the mean deviation.
The parameters, α, β and γ control the amount of smoothing. The nearer these parameters are to one, the greater the emphasis on the current data point. Generally these parameters take values in the range 0.1 to 0.3. The linear Holt and two Holt–Winters smoothers include an additional parameter, ϕ, which acts as a trend dampener. For 0.0<ϕ<1.0 the trend is dampened and for ϕ>1.0 the forecast function has an exponential trend, ϕ=0.0 removes the trend term from the forecast function and ϕ=1.0 does not dampen the trend.
For all methods, values for α, β, γ and ψ can be chosen by trying different values and then visually comparing the results by plotting the fitted values along side the original data. Alternatively, for single exponential smoothing a suitable value for α can be obtained by fitting an ARIMA 0,1,1 model. For Brown's double exponential smoothing and linear Holt smoothing with no dampening, (i.e., ϕ=1.0), suitable values for α and, in the case of linear Holt smoothing, γ can be obtained by fitting an ARIMA 0,2,2 model. Similarly, the linear Holt method, with ϕ≠1.0, can be expressed as an ARIMA 1,2,2 model and the additive Holt–Winters, with no dampening, (ϕ=1.0), can be expressed as a seasonal ARIMA model with order p of the form ARIMA 0,1,p+10,1,0. There is no similar procedure for obtaining parameter values for the multiplicative Holt–Winters method, or the additive Holt–Winters method with ϕ≠1.0. In these cases parameters could be selected by minimizing a measure of fit using nonlinear optimization.

Univariate Spectral Analysis

In describing a time series using spectral analysis the fundamental components are taken to be sinusoidal waves of the form R cos ωt+ϕ, which for a given angular frequency ω, 0≤ω≤π, is specified by its amplitude R>0 and phase ϕ, 0≤ϕ<2 π. Thus in a time series of n observations it is not possible to distinguish more than n/2 independent sinusoidal components. The frequency range 0≤ω≤π is limited to the shortest wavelength of two sampling units because any wave of higher frequency is indistinguishable upon sampling (or is aliased with) a wave within this range. Spectral analysis follows the idea that for a series made up of a finite number of sine waves the amplitude of any component at frequency ω is given to order 1/n by
R 2=1 n 2∑t=1 n xt e iωt 2.

The sample spectrum

For a series x 1,x 2,…,xn this is defined as
f*ω=1 2 nπ∑t=1 n xt e iωt 2,
the scaling factor now being chosen in order that
2∫0 π f*ω dω=σx 2,
i.e., the spectrum indicates how the sample variance (σx 2) of the series is distributed over components in the frequency range 0≤ω≤π.
It may be demonstrated that f*ω is equivalently defined in terms of the sample ACF rk of the series as
f*ω=1 2 πc 0+2∑k=1n-1 ck cos k ω,
where ck=σx 2 rk are the sample autocovariance coefficients.
If the series xt does contain a deterministic sinusoidal component of amplitude R, this will be revealed in the sample spectrum as a sharp peak of approximate width π/n and height n/2 π R 2. This is called the discrete part of the spectrum, the variance R 2 associated with this component being in effect concentrated at a single frequency.
If the series xt has no deterministic components, i.e., is purely stochastic being stationary with autocorrelation function (ACF) rk, then with increasing sample size the expected value of f*ω converges to the theoretical spectrum – the continuous part
f ω=1 2 πγ 0+2∑k=1∞γk cos ωk,
where γk are the theoretical autocovariances.
The sample spectrum does not however converge to this value but at each frequency point fluctuates about the theoretical spectrum with an exponential distribution, being independent at frequencies separated by an interval of 2 π/n or more. Various devices are therefore employed to smooth the sample spectrum and reduce its variability. Much of the strength of spectral analysis derives from the fact that the error limits are multiplicative so that features may still show up as significant in a part of the spectrum which has a generally low level, whereas they are completely masked by other components in the original series. The spectrum can help to distinguish deterministic cyclical components from the stochastic quasi-cycle components which produce a broader peak in the spectrum. (The deterministic components can be removed by regression and the remaining part represented by an ARIMA model.)
A large discrete component in a spectrum can distort the continuous part over a large frequency range surrounding the corresponding peak. This may be alleviated at the cost of slightly broadening the peak by tapering a portion of the data at each end of the series with weights which decay smoothly to zero. It is usual to correct for the mean of the series and for any linear trend by simple regression, since they would similarly distort the spectrum.

Spectral smoothing by lag window

The estimate is calculated directly from the sample autocovariances ck as
f ω=1 2 πc 0+2∑k=1M-1 wkck cos k ω,
the smoothing being induced by the lag window weights wk which extend up to a truncation lag M which is generally much less than n. The smaller the value of M, the greater the degree of smoothing, the spectrum estimates being independent only at a wider frequency separation indicated by the bandwidth b which is proportional to 1/M. It is wise, however, to calculate the spectrum at intervals appreciably less than this. Although greater smoothing narrows the error limits, it can also distort the spectrum, particularly by flattening peaks and filling in troughs.

Direct spectral smoothing

The unsmoothed sample spectrum is calculated for a fine division of frequencies, then averaged over intervals centred on each frequency point for which the smoothed spectrum is required. This is usually at a coarser frequency division. The bandwidth corresponds to the width of the averaging interval.

Linear Lagged Relationships Between Time Series

We now consider the context in which one time series, called the dependent or output series, y 1,y 2,…,yn, is believed to depend on one or more explanatory or input series, e.g., x 1,x 2,…,xn. This dependency may follow a simple linear regression, e.g.,
yt=v xt+nt
or more generally may involve lagged values of the input
yt=v 0xt+v 1x t-1+v 2x t-2+⋯+nt.
The sequence v 0,v 1,v 2,… is called the impulse response function (IRF) of the relationship. The term nt represents that part of yt which cannot be explained by the input, and it is assumed to follow a univariate ARIMA model. We call nt the (output) noise component of yt, and it includes any constant term in the relationship. It is assumed that the input series, xt, and the noise component, nt, are independent.
The part of yt which is explained by the input is called the input component zt:
zt=v 0xt+v 1x t-1+v 2x t-2+⋯
so yt=zt+nt.
The eventual aim is to model both these components of yt on the basis of observations of y 1,y 2,…,yn and x 1,x 2,…,xn. In applications to forecasting or control both components are important. In general there may be more than one input series, e.g., x 1,t and x 2,t, which are assumed to be independent and corresponding components z 1,t and z 2,t, so
yt=z 1,t+z 2,t+nt.

Transfer function models

In a similar manner to that in which the structure of a univariate series may be represented by a finite-parameter ARIMA model, the structure of an input component may be represented by a transfer function (TF) model with delay time b, p autoregressive-like parameters δ 1,δ 2,…,δp and q+1 moving-average-like parameters ω 0,ω 1,…,ωq:
zt=δ 1z t-1+δ 2z t-2+⋯+δpz t-p+ω 0x t-b-ω 1x t-b-1-⋯-ωqx t-b-q. (5)
If p>0 this represents an impulse response function (IRF) which is infinite in extent and decays with geometric and/or sinusoidal behaviour. The parameters δ 1,δ 2,…,δp are constrained to satisfy a stability condition identical to the stationarity condition of autoregressive models. There is no constraint on ω 0,ω 1,…,ωq.

Cross-correlations

An important tool for investigating how an input series xt affects an output series yt is the sample cross-correlation function (CCF) r xy k, for k=0,1,… between the series. If xt and yt are (jointly) stationary time series this is an estimator of the theoretical quantity
ρ xy k=corr xt,y t+k.
The sequence r yx k, for k=0,1,…, is distinct from r xy k, though it is possible to interpret
r yx k=r xy-k.
When the series yt and xt are believed to be related by a transfer function (TF) model, the CCF is determined by the impulse response function (IRF) v 0,v 1,v 2,… and the autocorrelation function (ACF) of the input xt.
In the particular case when xt is an uncorrelated series or white noise (and is uncorrelated with any other inputs):
ρ xy k∝vk
and the sample CCF can provide an estimate of vk:
v~k=sy/sx r xy k
where sy and sx are the sample standard deviations of yt and xt, respectively.
In theory the IRF coefficients vb,…,v b+p+q determine the parameters in the TF model, and using v~k to estimate v~k it is possible to solve for preliminary estimates of δ 1,δ 2,…,δp, ω 0,ω 1,…,ωq.

Prewhitening or filtering by an ARIMA model

In general an input series xt is not white noise, but may be represented by an ARIMA model with innovations or residuals at which are white noise. If precisely the same operations by which at is generated from xt are applied to the output yt to produce a series bt, then the transfer function relationship between yt and xt is preserved between bt and at. It is then possible to estimate
v~k=sb/sa r ab k.
The procedure of generating at from xt (and bt from yt) is called prewhitening or filtering by an ARIMA model. Although at is necessarily white noise, this is not generally true of bt.

Multi-input model estimation

The term multi-input model is used for the situation when one output series yt is related to one or more input series x j,t, as described in [Linear Lagged Relationships Between Time Series]. If for a given input the relationship is a simple linear regression, it is called a simple input; otherwise it is a transfer function input. The error or noise term follows an ARIMA model.
Given that the orders of all the transfer function models and the ARIMA model of a multi-input model have been specified, the various parameters in those models may be (simultaneously) estimated.
The procedure used is closely related to the least squares principle applied to the innovations in the ARIMA noise model.
The innovations are derived for any proposed set of parameter values by calculating the response of each input to the transfer functions and then evaluating the noise nt as the difference between this response (combined for all the inputs) and the output. The innovations are derived from the noise using the ARIMA model in the same manner as for a univariate series, and as described in [ARIMA models].
In estimating the parameters, consideration has to be given to the lagged terms in the various model equations which are associated with times prior to the observation period, and are therefore unknown. The method descriptions provide the necessary detail as to how this problem is treated.
Also, as described in [ARIMA model estimation] the sum of squares criterion
S=∑at 2
is related to the quadratic form in the exact log-likelihood of the parameters:
-12 log V-12 wTV-1 w.
Here w is the vector of appropriately differenced noise terms, and
wTV-1 w=S/σa 2,
where σa 2 is the innovation variance parameter.
The least squares criterion is therefore identical to minimization of the quadratic form, but is not identical to exact likelihood. Because V may be expressed as M σa 2, where M is a function of the ARIMA model parameters, substitution of σa 2 by its maximum likelihood (ML) estimator yields a concentrated (or profile) likelihood which is a function of
M 1/N S.
N is the length of the differenced noise series w, and M=det M.
Use of the above quantity, called the deviance, D, as an objective function is preferable to the use of S alone, on the grounds that it is equivalent to exact likelihood, and yields estimates with better properties. However, there is an appreciable computational penalty in calculating D, and in large samples it differs very little from S, except in the important case of seasonal ARIMA models where the number of whole seasons within the data length must also be large.
You are given the option of taking the objective function to be either S or D, or a third possibility, the marginal likelihood. This is similar to exact likelihood but can counteract bias in the ARIMA model due to the fitting of a large number of simple inputs.
Approximate standard errors of the parameter estimates and the correlations between them are available after estimation.
The model residuals a^t are the innovations resulting from the estimation, and they are usually examined for the presence of either autocorrelation or cross-correlation with the inputs. Absence of such correlation provides some confirmation of the adequacy of the model.

Multi-input model forecasting

A multi-input model may be used to forecast the output series provided future values (possibly forecasts) of the input series are supplied.
Construction of the forecasts requires knowledge only of the model orders and parameters, together with a limited set of the most recent variables which appear in the model equations. This is called the state set. It is conveniently constituted after model estimation. Moreover, if new observations y n+1,y n+2,… of the output series and x n+1,x n+2,… of (all) the independent input series become available, then the model equations can easily be used to update the state set before constructing forecasts from the end of the new observations. The new innovations a n+1,a n+2,… generated in this updating may be used to monitor the continuing adequacy of the model.

Transfer function model filtering

In many time series applications it is desired to calculate the response (or output) of a transfer function (TF) model for a given input series.
Smoothing, detrending, and seasonal adjustment are typical applications. You must specify the orders and parameters of a TF model for the purpose being considered. This may then be applied to the input series.
Again, problems may arise due to ignorance of the input series values prior to the observation period. The transient errors which can arise from this may be substantially reduced by using ‘backforecasts’ of these unknown observations.

Multivariate Time Series

Multi-input modelling represents one output time series in terms of one or more input series. Although there are circumstances in which it may be more appropriate to analyse a set of time series by modelling each one in turn as the output series with the remainder as inputs, there is a more symmetric approach in such a context. These models are known as vector autoregressive moving-average (VARMA) models.

Differencing and transforming a multivariate time series

As in the case of a univariate time series, it may be useful to simplify the series by differencing operations which may be used to remove linear or seasonal trends, thus ensuring that the resulting series to be used in the model estimation is stationary. It may also be necessary to apply transformations to the individual components of the multivariate series in order to stabilize the variance. Commonly used transformations are the log and square root transformations.

Model identification for a multivariate time series

Multivariate analogues of the autocorrelation and partial autocorrelation functions are available for analysing a set of k time series, x i,1,x i,2,…,x i,n, for i=1,2,…,k, thereby making it possible to obtain some understanding of a suitable VARMA model for the observed series.
It is assumed that the time series have been differenced if necessary, and that they are jointly stationary. The lagged correlations between all possible pairs of series, i.e.,
ρ ijl=corr x i,t,x j,t+l
are then taken to provide an adequate description of the statistical relationships between the series. These quantities are estimated by sample auto- and cross-correlations r ijl. For each l these may be viewed as elements of a (lagged) autocorrelation matrix.
Thus consider the vector process xt (with elements x it) and lagged autocovariance matrices Γl with elements of σiσjρ ijl where σi 2=var x i,t. Correspondingly, Γl is estimated by the matrix Cl with elements sisjr ijl where si 2 is the sample variance of x it.
For a series with short-term cross-correlation only, i.e., r ijl is not significant beyond some low lag q, then the pure vector MA q model, with no autoregressive parameters, i.e., p=0, is appropriate.
The correlation matrices provide a description of the joint statistical properties of the series. It is also possible to calculate matrix quantities which are closely analogous to the partial autocorrelations of univariate series (see [Partial autocorrelations]). Wei (1990) discusses both the partial autoregression matrices proposed by Tiao and Box (1981) and partial lag correlation matrices.
In the univariate case the partial autocorrelation function (PACF) between xt and x t+l is the correlation coefficient between the two after removing the linear dependence on each of the intervening variables x t+1,x t+2,…,x t+l-1. This partial autocorrelation may also be obtained as the last regression coefficient associated with xt when regressing x t+l on its l lagged variables x t+l-1,x t+l-2,…,xt. Tiao and Box (1981) extended this method to the multivariate case to define the partial autoregression matrix. Heyse and Wei (1985) also extended the univariate definition of the PACF to derive the correlation matrix between the vectors xt and x t+l after removing the linear dependence on each of the intervening vectors x t+1,x t+2,…,x t+l-1, the partial lag correlation matrix.
Note that the partial lag correlation matrix is a correlation coefficient matrix since each of its elements is a properly normalized correlation coefficient. This is not true of the partial autoregression matrices (except in the univariate case for which the two types of matrix are the same). The partial lag correlation matrix at lag 1 also reduces to the regular correlation matrix at lag 1; this is not true of the partial autoregression matrices (again except in the univariate case).
Both the above share the same cut-off property for autoregressive processes; that is for an autoregressive process of order p, the terms of the matrix at lags p+1 and greater are zero. Thus if the sample partial cross-correlations are significant only up to some low lag p then a pure vector AR p model is appropriate with q=0. Otherwise moving-average terms will need to be introduced as well as autoregressive terms.
Under the hypothesis that xt is an autoregressive process of order l-1, n times the sum of the squared elements of the partial lag correlation matrix at lag l is asymptotically distributed as a χ 2 variable with k 2 degrees of freedom where k is the dimension of the multivariate time series. This provides a diagnostic aid for determining the order of an autoregressive model.
The partial autoregression matrices may be found by solving a multivariate version of the Yule–Walker equations to find the autoregression matrices, using the final regression matrix coefficient as the partial autoregression matrix at that particular lag.
The basis of these calculations is a multivariate autoregressive model:
xt=ϕ l,1x t-1+⋯+ϕ l,lx t-l+e l,t
where ϕ l,1,ϕ l,2,…,ϕ l,l are matrix coefficients, and e l,t is the vector of errors in the prediction. These coefficients may be rapidly computed using a recursive technique which requires, and simultaneously furnishes, a backward prediction equation:
x t-l-1=ψ l,1x t-l+ψ l,2x t-l+1+⋯+ψ l,lx t-1+f l,t
(in the univariate case ψ l,i=ϕ l,i).
The forward prediction equation coefficients, ϕ l,i, are of direct interest, together with the covariance matrix Dl of the prediction errors e l,t. The calculation of these quantities for a particular maximum equation lag l=L involves calculation of the same quantities for increasing values of l=1,2,…,L.
The quantities vl=det Dl/det Γ 0 may be viewed as generalized variance ratios, and provide a measure of the efficiency of prediction (the smaller the better). The reduction from v l-1 to vl which occurs on extending the order of the predictor to l may be represented as
vl=v l-1 1-ρl 2
where ρl 2 is a multiple squared partial autocorrelation coefficient associated with k 2 degrees of freedom.
Sample estimates of all the above quantities may be derived by using the series covariance matrices Cl, for l=1,2,…,L, in place of Γl. The best lag for prediction purposes may be chosen as that which yields the minimum final prediction error (FPE) criterion:
FPE l=vl×1+l k 2/n1-l k 2/n.
An alternative method of estimating the sample partial autoregression matrices is by using multivariate least squares to fit a series of multivariate autoregressive models of increasing order.

VARMA model estimation

The cross-correlation structure of a stationary multivariate time series may often be represented by a model with a small number of parameters belonging to the VARMA class. If the stationary series wt has been derived by transforming and/or differencing the original series xt, then wt is said to follow the VARMA model:
wt=ϕ 1w t-1+⋯+ϕpw t-p+εt-θ 1ε t-1-⋯-θqε t-q,
where εt is a vector of uncorrelated residual series (white noise) with zero mean and constant covariance matrix Σ, ϕ 1,ϕ 2,…,ϕp are the p autoregressive (AR) parameter matrices and θ 1,θ 2,…,θq are the q moving-average (MA) parameter matrices. If wt has a nonzero mean μ, then this can be allowed for by replacing wt,w t-1,… by wt-μ,w t-1-μ,… in the model.
A series generated by this model will only be stationary provided restrictions are placed on ϕ 1,ϕ 2,…,ϕp to avoid unstable growth of wt. These are stationarity constraints. The series εt may also be usefully interpreted as the linear innovations in wt, i.e., the error if wt were to be predicted using the information in all past values w t-1,w t-2,…, provided also that θ 1,θ 2,…,θq satisfy what are known as invertibility constraints. This allows the series εt to be generated by rewriting the model equation as
εt=wt-ϕ 1w t-1-⋯-ϕpw t-p+θ 1ε t-1+⋯+θqε t-q.
The method of maximum likelihood (ML) may be used to estimate the parameters of a specified VARMA model from the observed multivariate time series together with their standard errors and correlations.
The residuals from the model may be examined for the presence of autocorrelations as a check on the adequacy of the fitted model.

VARMA model forecasting

Forecasts of the series may be constructed using a multivariate version of the univariate method. Efficient methods are available for updating the forecasts each time new observations become available.

Cross-spectral Analysis

The relationship between two time series may be investigated in terms of their sinusoidal components at different frequencies. At frequency ω a component of yt of the form
Ry ω cos ωt-ϕy ω
has its amplitude Ry ω and phase lag ϕy ω estimated by
Ry ω e i ϕy ω=1 n∑t=1 n yt e iωt
and similarly for xt. In the univariate analysis only the amplitude was important – in the cross analysis the phase is important.

The sample cross-spectrum

This is defined by
f xy*ω=1 2 πn∑t=1 n yt e iωt∑t=1 n xt e-iωt.
It may be demonstrated that this is equivalently defined in terms of the sample cross-correlation function (CCF), r xy k, of the series as
f xy*ω=1 2 π∑-n-1 n-1 c xy k e iωk
where c xy k=sxsyr xy k is the cross-covariance function.

The amplitude and phase spectrum

The cross-spectrum is specified by its real part or cospectrum c f*ω and imaginary part or quadrature spectrum q f*ω, but for the purpose of interpretation the cross-amplitude spectrum and phase spectrum are useful:
A*ω=f xy*ω,  ϕ*ω=arg f xy*ω.
If the series xt and yt contain deterministic sinusoidal components of amplitudes Ry,Rx and phases ϕy,ϕx at frequency ω, then A*ω will have a peak of approximate width π/n and height n/2 π RyRx at that frequency, with corresponding phase ϕ*ω=ϕy-ϕx. This supplies no information that cannot be obtained from the two series separately. The statistical relationship between the series is better revealed when the series are purely stochastic and jointly stationary, in which case the expected value of f xy*ω converges with increasing sample size to the theoretical cross-spectrum
f xy ω=1 2 π∑-∞∞γ xy k e iωk
where γ xy k=cov xt,y t+k. The sample spectrum, as in the univariate case, does not converge to the theoretical spectrum without some form of smoothing which either implicitly (using a lag window) or explicitly (using a frequency window) averages the sample spectrum f xy ω* over wider bands of frequency to obtain a smoothed estimate f^xy ω.

The coherency spectrum

If there is no statistical relationship between the series at a given frequency, then f xy ω=0, and the smoothed estimate f^xy ω, will be close to 0. This is assessed by the squared coherency between the series:
W^ω=f^xy ω 2 f^xx ω f^yy ω
where f^xx ω is the corresponding smoothed univariate spectrum estimate for xt, and similarly for yt. The coherency can be treated as a squared multiple correlation. It is similarly invariant in theory not only to simple scaling of xt and yt, but also to filtering of the two series, and provides a useful test statistic for the relationship between autocorrelated series. Note that without smoothing,
f xy*ω 2=f xx*ω f yy*ω,
so the coherency is 1 at all frequencies, just as a correlation is 1 for a sample of size 1. Thus smoothing is essential for cross-spectrum analysis.

The gain and noise spectrum

If yt is believed to be related to xt by a linear lagged relationship as in [Linear Lagged Relationships Between Time Series], i.e.,
yt=v 0xt+v 1x t-1+v 2x t-2+⋯+nt,
then the theoretical cross-spectrum is
f xy ω=V ω f xx ω
where
V ω=G ω e iϕ ω=∑k=0∞vk e ikω
is called the frequency response of the relationship.
Thus if xt were a sinusoidal wave at frequency ω (and nt were absent), yt would be similar but multiplied in amplitude by G ω and shifted in phase by ϕ ω. Furthermore, the theoretical univariate spectrum
f yy ω=G ω 2 f xx ω+fn ω
where nt, with spectrum fn ω, is assumed independent of the input xt.
Cross-spectral analysis thus furnishes estimates of the gain
G^ω=f^xy ω/f^xx ω
and the phase
ϕ^ω=arg f^xy ω.
From these representations of the estimated frequency response V^ω, parametric transfer function (TF) models may be recognized and selected. The noise spectrum may also be estimated as
f^y∣x ω=f^yy ω1-W^ω
a formula which reflects the fact that in essence a regression is being performed of the sinusoidal components of yt on those of xt over each frequency band.
Interpretation of the frequency response may be aided by extracting from V^ω estimates of the impulse response function (IRF) v^k. It is assumed that there is no anticipatory response between yt and xt, i.e., no coefficients vk with k=-1 or -2 are needed (their presence might indicate feedback between the series).

Cross-spectrum smoothing by lag window

The estimate of the cross-spectrum is calculated from the sample cross-variances as
f^xy ω=1 2 π∑-M+SM+S w k-Sc xy k e iωk.
The lag window wk extends up to a truncation lag M as in the univariate case, but its centre is shifted by an alignment lag S usually chosen to coincide with the peak cross-correlation. This is equivalent to an alignment of the series for peak cross-correlation at lag 0, and reduces bias in the phase estimation.
The selection of the truncation lag M, which fixes the bandwidth of the estimate, is based on the same criteria as for univariate series, and the same choice of M and window shape should be used as in univariate spectrum estimation to obtain valid estimates of the coherency, gain, etc., and test statistics.

Direct smoothing of the cross-spectrum

The computations are exactly as for smoothing of the univariate spectrum except that allowance is made for an implicit alignment shift S between the series.

Kalman Filters

Kalman filtering provides a method for the analysis of multidimensional time series. The underlying model is:
X t+1=AtXt+BtWt (6)
Yt=CtXt+Vt (7)
where Xt is the unobserved state vector, Yt is the observed measurement vector, Wt is the state noise, Vt is the measurement noise, At is the state transition matrix, Bt is the noise coefficient matrix and Ct is the measurement coefficient matrix at time t. The state noise and the measurement noise are assumed to be uncorrelated with zero mean and covariance matrices:
E Wt WtT=Qt  and  E Vt VtT=Rt.
If the system matrices At, Bt, Ct and the covariance matrices Qt,Rt are known then Kalman filtering can be used to compute the minimum variance estimate of the stochastic variable Xt.
The estimate of Xt given observations Y 1 to Y t-1 is denoted by X^t∣t-1 with state covariance matrix E X^t∣t-1 X^t∣t-1 T=P t∣t-1 while the estimate of Xt given observations Y 1 to Yt is denoted by X^t∣t with covariance matrix E X^t∣t X^t∣t T=P t∣t.
The update of the estimate, X^t+1∣t, from time t to time t+1, is computed in two stages.
First, the update equations are
X^t∣t=X^t∣t-1+Ktrt,  P t∣t=I-KtCt P t∣t-1
where the residual rt=Yt-CtX t∣t-1 has an associated covariance matrix Ht=CtP t∣t-1 CtT+Rt, and Kt is the Kalman gain matrix with
Kt=P t∣t-1 CtTHt-1.
The second stage is the one-step-ahead prediction equations given by
X^t+1∣t=AtX^t∣t,  P t+1∣t=AtP t∣t AtT+BtQt BtT.
These two stages can be combined to give the one-step-ahead update-prediction equations
X^t+1∣t=AtX^t∣t-1+AtKtrt.
The above equations thus provide a method for recursively calculating the estimates of the state vectors X^t∣t and X^t+1∣t and their covariance matrices P t∣t and P t+1∣t from their previous values. This recursive procedure can be viewed in a Bayesian framework as being the updating of the prior by the data Yt.
The initial values X^1∣0 and P 1∣0 are required to start the recursion. For stationary systems, P 1∣0 can be computed from the following equation:
P 1∣0=A 1P 1∣0 A 1 T+B 1Q 1 B 1 T,
which can be solved by iterating on the equation. For X^1∣0 the value E X can be used if it is available.

Computational methods

To improve the stability of the computations the square root algorithm is used. One recursion of the square root covariance filter algorithm which can be summarised as follows:
Rt 1/2CtSt00AtStBt Qt 1/2 U=Ht 1/200GtS t+10
where U is an orthogonal transformation triangularizing the left-hand pre-array to produce the right-hand post-array, St is the lower triangular Cholesky factor of the state covariance matrix P t+1∣t, Qt 1/2 and Rt 1/2 are the lower triangular Cholesky factor of the covariance matrices Q and R and H 1/2 is the lower triangular Cholesky factor of the covariance matrix of the residuals. The relationship between the Kalman gain matrix, Kt, and Gt is given by
AtKt=Gt Ht 1/2-1.
To improve the efficiency of the computations when the matrices At,Bt and Ct do not vary with time the system can be transformed to give a simpler structure. The transformed state vector is U*X where U* is the transformation that reduces the matrix pair A,C to lower observer Hessenberg form. That is, the matrix U* is computed such that the compound matrix
C U*TU*A U*T
is a lower trapezoidal matrix. The transformations need only be computed once at the start of a series, and the covariance matrices Qt and Rt can still be time-varying.

Model fitting and forecasting

If the state space model contains unknown parameters, θ, these can be estimated using maximum likelihood (ML). Assuming that Wt and Vt are normal variates the log-likelihood for observations Yt, for t=1,2,…,n, is given by
constant-12∑t=1 n ln det Ht-12∑t=1 t rtTHt-1 rt.
Optimal estimates for the unknown model parameters θ can then be obtained by using a suitable optimizer method to maximize the likelihood function.
Once the model has been fitted forecasting can be performed by using the one-step-ahead prediction equations. The one-step-ahead prediction equations can also be used to ‘jump over’ any missing values in the series.

Kalman filter and time series models

Many commonly used time series models can be written as state space models. A univariate ARMA p,q model can be cast into the following state space form:
xt=A x t-1+B εtwt=C xt
A=ϕ 11ϕ 21....ϕ r-11ϕr00..0,  B=-1-θ 1-θ 2..-θ r-1  and  CT=100..0,
where r=max p,q+1.
The representation for a k-variate ARMA p,q series (VARMA) is very similar to that given above, except now the state vector is of length kr and the ϕ and θ are now k×k matrices and the 1s in A, B and C are now the identity matrix of order k. If p<r or q+1<r then the appropriate ϕ or θ matrices are set to zero, respectively.
Since the compound matrix
CA
is already in lower observer Hessenberg form (i.e., it is lower trapezoidal with zeros in the top right-hand triangle) the invariant Kalman filter algorithm can be used directly without the need to generate a transformation matrix U*.

GARCH Models

ARCH models and their generalizations

Rather than modelling the mean (for example using regression models) or the autocorrelation (by using ARMA models) there are circumstances in which the variance of a time series needs to be modelled. This is common in financial data modelling where the variance (or standard deviation) is known as volatility. The ability to forecast volatility is a vital part in deciding the risk attached to financial decisions like portfolio selection. The basic model for relating the variance at time t to the variance at previous times is the autoregressive conditional heteroskedastic (ARCH) model. The standard ARCH model is defined as
yt∣ψ t-1∼N 0,ht,ht=α 0+∑i=1 q αi ε t-i 2,
where ψt is the information up to time t and ht is the conditional variance.
In a similar way to that in which autoregressive (AR) models were generalized to ARMA models the ARCH models have been generalized to a GARCH model; see Engle (1982), Bollerslev (1986) and Hamilton (1994)
ht=α 0+∑i=1 q αi ε t-i 2+∑i=1 p β h t-i.
This can be combined with a regression model:
yt=b 0+∑i=1 k bix it+εt,
where εt∣ψ t-1∼N 0,ht and where x it, for i=1,2,…,k, are the exogenous variables.
The above models assume that the change in variance, ht, is symmetric with respect to the shocks, that is, that a large negative value of ε t-1 has the same effect as a large positive value of ε t-1. A frequently observed effect is that a large negative value ε t-1 often leads to a greater variance than a large positive value. The following three asymmetric models represent this effect in different ways using the parameter γ as a measure of the asymmetry.
Type I AGARCH(p,q)
ht=α 0+∑i=1 q αi ε t-i+γ 2+∑i=1 p βih t-i.
Type II AGARCH(p,q)
ht=α 0+∑i=1 q αi ε t-i+γ ε t-i 2+∑i=1 p βih t-i.
GJR-GARCH(p,q), or Glosten, Jagannathan and Runkle GARCH (see Glosten et al. (1993))
ht=α 0+∑i=1 q αi+γ I t-1 ε t-1 2+∑i=1 p βih t-i,
where It=1 if εt<0 and It=0 if εt≥0.
The first assumes that the effects of the shocks are symmetric about γ rather than zero, so that for γ<0 the effect of negative shocks is increased and the effect of positive shocks is decreased. Both the Type II AGARCH and the GJR GARCH (see Glosten et al. (1993)) models introduce asymmetry by increasing the value of the coefficient of ε t-1 2 for negative values of ε t-1. In the case of the Type II AGARCH the effect is multiplicative while for the GJR GARCH the effect is additive.
Coefficient | ε t-1<0 | ε t-1>0
Type II AGARCH | αi 1-γ 2 | αi 1+γ 2
GJR GARCH | αi+γ | αi
(Note that in the case of GJR GARCH, γ needs to be positive to inflate variance after negative shocks while for Type I and Type II AGARCH, γ needs to be negative.)
A third type of GARCH model is the exponential GARCH (EGARCH). In this model the variance relationship is on the log scale and hence asymmetric.
ln ht=α 0+∑i=1 q αiz t-i+∑i=1 q ϕi z t-i-E z t-i+∑i=1 p βi ln h t-i,
where zt=εt ht and E z t-i denotes the expected value of z t-i.
Note that the ϕi terms represent a symmetric contribution to the variance while the αi terms give an asymmetric contribution.
Another common characteristic of financial data is that it is heavier in the tails (leptokurtic) than the Normal distribution. To model this the Normal distribution is replaced by a scaled Student's t-distribution (that is a Student's t-distribution standardized to have variance ht). The Student's t-distribution is such that the smaller the degrees of freedom the higher the kurtosis for degrees of freedom >4.

Fitting GARCH models

The models are fitted by maximizing the conditional log-likelihood. For the Normal distribution the conditional log-likelihood is
12∑i=1 T log hi+εi 2 hi.
For the Student's t-distribution the function is more complex. An approximation to the standard errors of the parameter estimates is computed from the Fisher information matrix.

Inhomogeneous Time Series

If we denote a generic univariate time series as a sequence of pairs of values zi,ti, for i=1,2,… where the z's represent an observed scalar value and the t's the time that the value was observed, then in a standard time series analysis, as discussed in other sections of this introduction, it is assumed that the series being analysed is homogeneous, that is the sampling times are regularly spaced with ti-t i-1=δ for some value δ. In many real world applications this assumption does not hold, that is, the series is inhomogeneous.
Standard time series analysis techniques cannot be used on an inhomogeneous series without first preprocessing the series to construct an artificial homogeneous series, by for example, resampling the series at regular intervals. Zumbach and Müller (2001) introduced a series of operators that can be used to extract robust information directly from the inhomogeneous time series. In this context, robust information means that the results should be essentially independent of minor changes to the sampling mechanism used when collecting the data, for example, changing a number of time stamps or adding or removing a few observations.
The basic operator available for inhomogeneous time series is the exponential moving average (EMA). This operator has a single parameter, τ, and is an average operator with an exponentially decaying kernel given by:
e-t/τ τ.
This gives rise to the following iterative formula:
EMA τ;zti=μ⁢EMA τ;zt i-1+ν-μ⁢z i-1+1-ν⁢zi
where
μ=e-α  and  α=ti-t i-1 τ.
The value of ν depends on the method of interpolation chosen. Three interpolation methods are available:
1. | Previous point: | ν=1.
2. | Linear: | ν=1-μ/α.
3. | Next point: | ν=μ.
Given the EMA, a number of other operators can be defined, including:
(i) m-Iterated Exponential Moving Average, defined as
EMA τ,m;z=EMA τ;EMA τ,m-1;z​ where ​EMA τ,1;z=EMA τ;z.
(ii) Moving Average (MA), defined as
MA τ,m 1,m 2;zti=1 m 2-m 1+1∑j=m 1 m 2 EMA τ~,j;zti​ where ​τ~=2⁢τm 2+m 1
(iii) Moving Norm (MNorm), defined as
MNorm τ,m,p;z=MA τ,1,m;z p1/p
(iv) Moving Variance (MVar), defined as
MVar τ,m,p;z=MA τ,1,m;z-MA τ,1,m;z p
(v) Moving Standard Deviation (MSD), defined as
MSD τ,m,p;z=MA τ,1,m;z-MA τ,1,m;z p1/p
(vi) Differential ( Δ), defined as
Δ τ,α,β,γ;z=γ⁢EMA α⁢τ,1;z+EMA α⁢τ,2;z-2⁢EMA α⁢β⁢τ,4;z
(vii) Volatility, defined as
Volatility τ,τ′,m,p;z=MNorm τ/2,m,p;Δ τ′;z
A discussion of each of these operators, their use and in some cases, alternative definitions, are given in Zumbach and Müller (2001).

References

Akaike H (1971) Autoregressive model fitting for control Ann. Inst. Statist. Math. 23 163–180
Bollerslev T (1986) Generalised autoregressive conditional heteroskedasticity Journal of Econometrics 31 307–327
Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day
Engle R (1982) Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation Econometrica 50 987–1008
Gentleman W S and Sande G (1966) Fast Fourier transforms for fun and profit Proc. Joint Computer Conference, AFIPS 29 563–578
Glosten L, Jagannathan R and Runkle D (1993) Relationship between the expected value and the volatility of nominal excess return on stocks Journal of Finance 48 1779–1801
Hamilton J (1994) Time Series Analysis Princeton University Press
Heyse J F and Wei W W S (1985) The partial lag autocorrelation function Technical Report No. 32 Department of Statistics, Temple University, Philadelphia
Tiao G C and Box G E P (1981) Modelling multiple time series with applications J. Am. Stat. Assoc. 76 802–816
Wei W W S (1990) Time Series Analysis: Univariate and Multivariate Methods Addison–Wesley
Zumbach G O and Müller U A (2001) Operators on inhomogeneous time series International Journal of Theoretical and Applied Finance 4(1) 147–178

Inheritance Hierarchy

System..::..Object
NagLibrary..::..G13

See Also

G13 Members


G13 Members

[image] [image]

NAG Library for .NET Release 2
G13 Members
G13 Class Methods See Also Send Feedback

The G13 type exposes the following members.

Methods

Name | Description
g13aa | g13aa carries out non-seasonal and seasonal differencing on a time series. Information which allows the original series to be reconstituted from the differenced series is also produced. This information is required in time series forecasting.
g13ab | g13ab computes the sample autocorrelation function of a time series. It also computes the sample mean, the sample variance and a statistic which may be used to test the hypothesis that the true autocorrelation function is zero.
g13ac | g13ac calculates partial autocorrelation coefficients given a set of autocorrelation coefficients. It also calculates the predictor error variance ratios for increasing order of finite lag autoregressive predictor, and the autoregressive parameters associated with the predictor of maximum order.
g13ad | g13ad calculates preliminary estimates of the parameters of an autoregressive integrated moving average (ARIMA) model from the autocorrelation function of the appropriately differenced times series.
g13af | g13af is an easy-to-use version of (G13AEF not in this release). It fits a seasonal autoregressive integrated moving average (ARIMA) model to an observed time series, using a nonlinear least squares procedure incorporating backforecasting. Parameter estimates are obtained, together with appropriate standard errors. The residual series is returned, and information for use in forecasting the time series is produced for use in g13ag and g13ah. The estimation procedure is iterative, starting with initial parameter values such as may be obtained using g13ad. It continues until a specified convergence criterion is satisfied or until a specified number of iterations have been carried out. The progress of the iteration can be monitored by means of an optional printing facility.
g13ag | g13ag accepts a series of new observations of a time series, the model of which is already fully specified, and updates the ‘state set’ information for use in constructing further forecasts. The previous specifications of the time series model should have been obtained by using (G13AEF not in this release) g13af to estimate the relevant parameters. The supplied state set will originally have been produced by (G13AEF not in this release) g13af, but may since have been updated by earlier calls to g13ag. A set of residuals corresponding to the new observations is returned. These may be of use in checking that the new observations conform to the previously fitted model.
g13ah | g13ah produces forecasts of a time series, given a time series model which has already been fitted to the time series using (G13AEF not in this release) g13af. The original observations are not required, since g13ah uses as input either the original state set produced by (G13AEF not in this release) g13af or the state set updated by a series of new observations using g13ag. Standard errors of the forecasts are also provided.
g13aj | g13aj applies a fully specified seasonal ARIMA model to an observed time series, generates the state set for forecasting and (optionally) derives a specified number of forecasts together with their standard deviations.
g13am | g13am performs exponential smoothing using either single exponential, double exponential or a Holt–Winters method.
g13as | g13as is a diagnostic checking method suitable for use after fitting a Box–Jenkins ARMA model to a univariate time series using (G13AEF not in this release) g13af. The residual autocorrelation function is returned along with an estimate of its asymptotic standard errors and correlations. Also, g13as calculates the Box–Ljung portmanteau statistic and its significance level for testing model adequacy.
g13au | g13au calculates the range (or standard deviation) and the mean for groups of successive time series values. It is intended for use in the construction of range-mean plots.
g13ba | g13ba filters a time series by an ARIMA model.
g13bb | g13bb filters a time series by a transfer function model.
g13bc | g13bc calculates cross-correlations between two time series.
g13bd | g13bd calculates preliminary estimates of the parameters of a transfer function model.
g13be | g13be fits a multi-input model relating one output series to the input series with a choice of three different estimation criteria: nonlinear least squares, exact likelihood and marginal likelihood. When no input series are present, g13be fits a univariate ARIMA model.
g13bg | g13bg accepts a series of new observations of an output time series and any associated input time series, for which a multi-input model is already fully specified, and updates the ‘state set’ information for use in constructing further forecasts. The previous specification of the multi-input model will normally have been obtained by using g13be to estimate the relevant transfer function and ARIMA parameters. The supplied state set will originally have been produced by g13be (or possibly g13bj), but may since have been updated by g13bg.
g13bj | g13bj produces forecasts of a time series (the output series) which depends on one or more other (input) series via a previously estimated multi-input model for which the state set information is not available. The future values of the input series must be supplied. In contrast with (G13BHF not in this release) the original past values of the input and output series are required. Standard errors of the forecasts are produced. If future values of some of the input series have been obtained as forecasts using ARIMA models for those series, this may be allowed for in the calculation of the standard errors.
g13ca | g13ca calculates the smoothed sample spectrum of a univariate time series using one of four lag windows – rectangular, Bartlett, Tukey or Parzen window.
g13cb | g13cb calculates the smoothed sample spectrum of a univariate time series using spectral smoothing by the trapezium frequency (Daniell) window.
g13cc | g13cc calculates the smoothed sample cross spectrum of a bivariate time series using one of four lag windows: rectangular, Bartlett, Tukey or Parzen.
g13cd | g13cd calculates the smoothed sample cross spectrum of a bivariate time series using spectral smoothing by the trapezium frequency (Daniell) window.
g13ce | For a bivariate time series, g13ce calculates the cross amplitude spectrum and squared coherency, together with lower and upper bounds from the univariate and bivariate (cross) spectra.
g13cf | For a bivariate time series, g13cf calculates the gain and phase together with lower and upper bounds from the univariate and bivariate spectra.
g13cg | For a bivariate time series, g13cg calculates the noise spectrum together with multiplying factors for the bounds and the impulse response function and its standard error, from the univariate and bivariate spectra.
g13dd | g13dd fits a vector autoregressive moving average (VARMA) model to an observed vector of time series using the method of Maximum Likelihood (ML). Standard errors of parameter estimates are computed along with their appropriate correlation matrix. The method also calculates estimates of the residual series.
g13dj | g13dj computes forecasts of a multivariate time series. It is assumed that a vector ARMA model has already been fitted to the appropriately differenced/transformed time series using g13dd. The standard deviations of the forecast errors are also returned. A reference vector is set up so that, should future series values become available, the forecasts and their standard errors may be updated by calling g13dk.
g13dk | g13dk accepts a sequence of new observations in a multivariate time series and updates both the forecasts and the standard deviations of the forecast errors. A call to g13dj must be made prior to calling this method in order to calculate the elements of a reference vector together with a set of forecasts and their standard errors. On a successful exit from g13dk the reference vector is updated so that should future series values become available these forecasts may be updated by recalling g13dk.
g13dl | g13dl differences and/or transforms a multivariate time series. It is intended to be used prior to g13dd to fit a vector autoregressive moving average (VARMA) model to the differenced/transformed series.
g13dx | g13dx calculates the zeros of a vector autoregressive (or moving average) operator. This method is likely to be used in conjunction with g05pj g13as g13dd (G13DSF not in this release).
g13fa | g13fa estimates the parameters of either a standard univariate regression GARCH process, or a univariate regression-type I AGARCH p,q process (see Engle and Ng (1993)).
g13fb | g13fb forecasts the conditional variances ht, for t=T+1,…,T+ξ, from a type I AGARCH p,q sequence, where ξ is the forecast horizon and T is the current time (see Engle and Ng (1993)).
g13fc | g13fc estimates the parameters of a univariate regression-type II AGARCH p,q process.
g13fd | g13fd forecasts the conditional variances, ht,t=T+1,…,T+ξ from a type II AGARCH p,q sequence, where ξ is the forecast horizon and T is the current time (see Engle and Ng (1993)).
g13fe | g13fe estimates the parameters of a univariate regression-GJR GARCH p,q process (see Glosten et al. (1993)).
g13ff | g13ff forecasts the conditional variances, ht, for t=T+1,…,T+ξ from a GJR GARCH p,q sequence, where ξ is the forecast horizon and T is the current time (see Glosten et al. (1993)).
g13fg | g13fg estimates the parameters of a univariate regression-exponential GARCH p,q process (see Engle and Ng (1993)).
g13fh | g13fh forecasts the conditional variances, ht,t=T+1,…,T+ξ from an exponential GARCH p,q sequence, where ξ is the forecast horizon and T is the current time (see Engle and Ng (1993)).

See Also

G13 Class


G13 Methods

[image] [image]

NAG Library for .NET Release 2
G13 Methods
G13 Class See Also Send Feedback

The G13 type exposes the following members.

Methods

Name | Description
g13aa | g13aa carries out non-seasonal and seasonal differencing on a time series. Information which allows the original series to be reconstituted from the differenced series is also produced. This information is required in time series forecasting.
g13ab | g13ab computes the sample autocorrelation function of a time series. It also computes the sample mean, the sample variance and a statistic which may be used to test the hypothesis that the true autocorrelation function is zero.
g13ac | g13ac calculates partial autocorrelation coefficients given a set of autocorrelation coefficients. It also calculates the predictor error variance ratios for increasing order of finite lag autoregressive predictor, and the autoregressive parameters associated with the predictor of maximum order.
g13ad | g13ad calculates preliminary estimates of the parameters of an autoregressive integrated moving average (ARIMA) model from the autocorrelation function of the appropriately differenced times series.
g13af | g13af is an easy-to-use version of (G13AEF not in this release). It fits a seasonal autoregressive integrated moving average (ARIMA) model to an observed time series, using a nonlinear least squares procedure incorporating backforecasting. Parameter estimates are obtained, together with appropriate standard errors. The residual series is returned, and information for use in forecasting the time series is produced for use in g13ag and g13ah. The estimation procedure is iterative, starting with initial parameter values such as may be obtained using g13ad. It continues until a specified convergence criterion is satisfied or until a specified number of iterations have been carried out. The progress of the iteration can be monitored by means of an optional printing facility.
g13ag | g13ag accepts a series of new observations of a time series, the model of which is already fully specified, and updates the ‘state set’ information for use in constructing further forecasts. The previous specifications of the time series model should have been obtained by using (G13AEF not in this release) g13af to estimate the relevant parameters. The supplied state set will originally have been produced by (G13AEF not in this release) g13af, but may since have been updated by earlier calls to g13ag. A set of residuals corresponding to the new observations is returned. These may be of use in checking that the new observations conform to the previously fitted model.
g13ah | g13ah produces forecasts of a time series, given a time series model which has already been fitted to the time series using (G13AEF not in this release) g13af. The original observations are not required, since g13ah uses as input either the original state set produced by (G13AEF not in this release) g13af or the state set updated by a series of new observations using g13ag. Standard errors of the forecasts are also provided.
g13aj | g13aj applies a fully specified seasonal ARIMA model to an observed time series, generates the state set for forecasting and (optionally) derives a specified number of forecasts together with their standard deviations.
g13am | g13am performs exponential smoothing using either single exponential, double exponential or a Holt–Winters method.
g13as | g13as is a diagnostic checking method suitable for use after fitting a Box–Jenkins ARMA model to a univariate time series using (G13AEF not in this release) g13af. The residual autocorrelation function is returned along with an estimate of its asymptotic standard errors and correlations. Also, g13as calculates the Box–Ljung portmanteau statistic and its significance level for testing model adequacy.
g13au | g13au calculates the range (or standard deviation) and the mean for groups of successive time series values. It is intended for use in the construction of range-mean plots.
g13ba | g13ba filters a time series by an ARIMA model.
g13bb | g13bb filters a time series by a transfer function model.
g13bc | g13bc calculates cross-correlations between two time series.
g13bd | g13bd calculates preliminary estimates of the parameters of a transfer function model.
g13be | g13be fits a multi-input model relating one output series to the input series with a choice of three different estimation criteria: nonlinear least squares, exact likelihood and marginal likelihood. When no input series are present, g13be fits a univariate ARIMA model.
g13bg | g13bg accepts a series of new observations of an output time series and any associated input time series, for which a multi-input model is already fully specified, and updates the ‘state set’ information for use in constructing further forecasts. The previous specification of the multi-input model will normally have been obtained by using g13be to estimate the relevant transfer function and ARIMA parameters. The supplied state set will originally have been produced by g13be (or possibly g13bj), but may since have been updated by g13bg.
g13bj | g13bj produces forecasts of a time series (the output series) which depends on one or more other (input) series via a previously estimated multi-input model for which the state set information is not available. The future values of the input series must be supplied. In contrast with (G13BHF not in this release) the original past values of the input and output series are required. Standard errors of the forecasts are produced. If future values of some of the input series have been obtained as forecasts using ARIMA models for those series, this may be allowed for in the calculation of the standard errors.
g13ca | g13ca calculates the smoothed sample spectrum of a univariate time series using one of four lag windows – rectangular, Bartlett, Tukey or Parzen window.
g13cb | g13cb calculates the smoothed sample spectrum of a univariate time series using spectral smoothing by the trapezium frequency (Daniell) window.
g13cc | g13cc calculates the smoothed sample cross spectrum of a bivariate time series using one of four lag windows: rectangular, Bartlett, Tukey or Parzen.
g13cd | g13cd calculates the smoothed sample cross spectrum of a bivariate time series using spectral smoothing by the trapezium frequency (Daniell) window.
g13ce | For a bivariate time series, g13ce calculates the cross amplitude spectrum and squared coherency, together with lower and upper bounds from the univariate and bivariate (cross) spectra.
g13cf | For a bivariate time series, g13cf calculates the gain and phase together with lower and upper bounds from the univariate and bivariate spectra.
g13cg | For a bivariate time series, g13cg calculates the noise spectrum together with multiplying factors for the bounds and the impulse response function and its standard error, from the univariate and bivariate spectra.
g13dd | g13dd fits a vector autoregressive moving average (VARMA) model to an observed vector of time series using the method of Maximum Likelihood (ML). Standard errors of parameter estimates are computed along with their appropriate correlation matrix. The method also calculates estimates of the residual series.
g13dj | g13dj computes forecasts of a multivariate time series. It is assumed that a vector ARMA model has already been fitted to the appropriately differenced/transformed time series using g13dd. The standard deviations of the forecast errors are also returned. A reference vector is set up so that, should future series values become available, the forecasts and their standard errors may be updated by calling g13dk.
g13dk | g13dk accepts a sequence of new observations in a multivariate time series and updates both the forecasts and the standard deviations of the forecast errors. A call to g13dj must be made prior to calling this method in order to calculate the elements of a reference vector together with a set of forecasts and their standard errors. On a successful exit from g13dk the reference vector is updated so that should future series values become available these forecasts may be updated by recalling g13dk.
g13dl | g13dl differences and/or transforms a multivariate time series. It is intended to be used prior to g13dd to fit a vector autoregressive moving average (VARMA) model to the differenced/transformed series.
g13dx | g13dx calculates the zeros of a vector autoregressive (or moving average) operator. This method is likely to be used in conjunction with g05pj g13as g13dd (G13DSF not in this release).
g13fa | g13fa estimates the parameters of either a standard univariate regression GARCH process, or a univariate regression-type I AGARCH p,q process (see Engle and Ng (1993)).
g13fb | g13fb forecasts the conditional variances ht, for t=T+1,…,T+ξ, from a type I AGARCH p,q sequence, where ξ is the forecast horizon and T is the current time (see Engle and Ng (1993)).
g13fc | g13fc estimates the parameters of a univariate regression-type II AGARCH p,q process.
g13fd | g13fd forecasts the conditional variances, ht,t=T+1,…,T+ξ from a type II AGARCH p,q sequence, where ξ is the forecast horizon and T is the current time (see Engle and Ng (1993)).
g13fe | g13fe estimates the parameters of a univariate regression-GJR GARCH p,q process (see Glosten et al. (1993)).
g13ff | g13ff forecasts the conditional variances, ht, for t=T+1,…,T+ξ from a GJR GARCH p,q sequence, where ξ is the forecast horizon and T is the current time (see Glosten et al. (1993)).
g13fg | g13fg estimates the parameters of a univariate regression-exponential GARCH p,q process (see Engle and Ng (1993)).
g13fh | g13fh forecasts the conditional variances, ht,t=T+1,…,T+ξ from an exponential GARCH p,q sequence, where ξ is the forecast horizon and T is the current time (see Engle and Ng (1993)).

See Also

G13 Class


g13aa Method

[image]

NAG Library for .NET Release 2
G13..::g13aa Method
G13 Class See Also Send Feedback
g13aa carries out non-seasonal and seasonal differencing on a time series. Information which allows the original series to be reconstituted from the differenced series is also produced. This information is required in time series forecasting.

Syntax

C#
public static void g13aa(
    double[] x,
    int nx,
    int nd,
    int nds,
    int ns,
    double[] xd,
    out int nxd,
    out int ifail
)
Visual Basic
Public Shared Sub g13aa ( _
    x As Double(), _
    nx As Integer, _
    nd As Integer, _
    nds As Integer, _
    ns As Integer, _
    xd As Double(), _
    <OutAttribute> ByRef nxd As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13aa(
    array<double>^ x,
    int nx,
    int nd,
    int nds,
    int ns,
    array<double>^ xd,
    [OutAttribute] int% nxd,
    [OutAttribute] int% ifail
)
F#
static member g13aa :
        x : float[] *
        nx : int *
        nd : int *
        nds : int *
        ns : int *
        xd : float[] *
        nxd : int byref *
        ifail : int byref -> unit

Parameters

x
Type: array< System..::..Double >[]()[][]
An array of size [nx]
On entry: the undifferenced time series, xi, for i=1,2,…,n.
nx
Type: System..::..Int32
On entry: n, the number of values in the undifferenced time series.
Constraint: nx>nd+nds×ns.
nd
Type: System..::..Int32
On entry: d, the order of non-seasonal differencing.
Constraint: nd≥0.
nds
Type: System..::..Int32
On entry: D, the order of seasonal differencing.
Constraint: nds≥0.
ns
Type: System..::..Int32
On entry: s, the seasonality.
Constraints:
  • if nds>0, ns>0;
  • if nds=0, ns≥0.
xd
Type: array< System..::..Double >[]()[][]
An array of size [nx]
On exit: the differenced values in elements 0 to nxd-1, and reconstitution data in the remainder of the array.
nxd
Type: System..::..Int32 %
On exit: the number of differenced values in the array xd.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Let ∇d∇sD xi be the ith value of a time series xi, for i=1,2,…,n after non-seasonal differencing of order d and seasonal differencing of order D (with period or seasonality s). In general,
∇d∇sD xi | = | ∇d-1∇sD x i+1-∇d-1∇sD xi | d>0
∇d∇sD xi | = | ∇d∇s D-1 x i+s-∇d∇s D-1 xi | D>0
Non-seasonal differencing up to the required order d is obtained using
∇1 xi | = | x i+1-xi | for i=1,2,…,n-1
∇2 xi | = | ∇1 x i+1-∇1 xi | for i=1,2,…,n-2
⋮ |  |  |
∇d xi | = | ∇d-1 x i+1-∇d-1 xi | for i=1,2,…,n-d
Seasonal differencing up to the required order D is then obtained using
∇d∇s 1 xi | = | ∇d x i+s-∇d xi | for i=1,2,…,n-d-s
∇d∇s 2 xi | = | ∇d∇s 1 x i+s-∇d∇s 1 xi | for i=1,2,…,n-d-2 s
⋮ |  |  |
∇d∇sD xi | = | ∇d∇s D-1 x i+s-∇d∇s D-1 xi | for i=1,2,…,n-d-D×s
Mathematically, the sequence in which the differencing operations are performed does not affect the final resulting series of m=n-d-D×s values.

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | nd<0,
or | nds<0,
or | ns<0,
or | ns=0 when nds>0.
ifail=2
On entry, nx≤nd+nds×ns.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The computations are believed to be stable.

Parallelism and Performance

None.

Further Comments

The time taken by g13aa is approximately proportional to nd+nds×nx.

Example

This example reads in a set of data consisting of 20 observations from a time series. Non-seasonal differencing of order 2 and seasonal differencing of order 1 (with seasonality of 4) are applied to the input data, giving an output array holding 14 differenced values and 6 values which can be used to reconstitute the output array.

Example program (C#): g13aae.cs

Example program data: g13aae.d

Example program results: g13aae.r

See Also

G13 Class
G13 Members


g13ab Method

[image]

NAG Library for .NET Release 2
G13..::g13ab Method
G13 Class See Also Send Feedback
g13ab computes the sample autocorrelation function of a time series. It also computes the sample mean, the sample variance and a statistic which may be used to test the hypothesis that the true autocorrelation function is zero.

Syntax

C#
public static void g13ab(
    double[] x,
    int nx,
    int nk,
    out double xm,
    out double xv,
    double[] r,
    out double stat,
    out int ifail
)
Visual Basic
Public Shared Sub g13ab ( _
    x As Double(), _
    nx As Integer, _
    nk As Integer, _
    <OutAttribute> ByRef xm As Double, _
    <OutAttribute> ByRef xv As Double, _
    r As Double(), _
    <OutAttribute> ByRef stat As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13ab(
    array<double>^ x,
    int nx,
    int nk,
    [OutAttribute] double% xm,
    [OutAttribute] double% xv,
    array<double>^ r,
    [OutAttribute] double% stat,
    [OutAttribute] int% ifail
)
F#
static member g13ab :
        x : float[] *
        nx : int *
        nk : int *
        xm : float byref *
        xv : float byref *
        r : float[] *
        stat : float byref *
        ifail : int byref -> unit

Parameters

x
Type: array< System..::..Double >[]()[][]
An array of size [nx]
On entry: the time series, xi, for i=1,2,…,n.
nx
Type: System..::..Int32
On entry: n, the number of values in the time series.
Constraint: nx>1.
nk
Type: System..::..Int32
On entry: K, the number of lags for which the autocorrelations are required. The lags range from 1 to K and do not include zero.
Constraint: 0<nk<nx.
xm
Type: System..::..Double %
On exit: the sample mean of the input time series.
xv
Type: System..::..Double %
On exit: the sample variance of the input time series.
r
Type: array< System..::..Double >[]()[][]
An array of size [nk]
On exit: the sample autocorrelation coefficient relating to lag k, for k=1,2,…,K.
stat
Type: System..::..Double %
On exit: the statistic used to test the hypothesis that the true autocorrelation function of the time series is identically zero.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The data consists of n observations xi, for i=1,2,…,n from a time series.
The quantities calculated are
(a) The sample mean
x-=∑i=1 n xi n.
(b) The sample variance (for n≥2)
s 2=∑i=1 n xi-x-2 n-1.
(c) The sample autocorrelation coefficients of lags k=1,2,…,K, where K is a user-specified maximum lag, and K<n, n>1.
The coefficient of lag k is defined as
rk=∑i=1n-k xi-x-x i+k-x-∑i=1 n xi-x-2.
See page 496 of Box and Jenkins (1976) for further details.
(d) A test statistic defined as
stat=n∑k=1 K rk 2,
which can be used to test the hypothesis that the true autocorrelation function is identically zero.
If n is large and K is much smaller than n, stat has a χK 2 distribution under the hypothesis of a zero autocorrelation function. Values of stat in the upper tail of the distribution provide evidence against the hypothesis; g01ec can be used to compute the tail probability.
Section 8.2.2 of Box and Jenkins (1976) provides further details of the use of stat.

References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | nx≤nk,
or | nx≤1,
or | nk≤0.
ifail=2
On entry, all values of x are practically identical, giving zero variance. In this case r and stat are undefined on exit.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The computations are believed to be stable.

Parallelism and Performance

None.

Further Comments

If n<100, or K<10 log n then the autocorrelations are calculated directly and the time taken by g13ab is approximately proportional to nK, otherwise the autocorrelations are calculated by utilizing fast fourier transforms (FFTs) and the time taken is approximately proportional to n log n. If FFTs are used then g13ab internally allocates approximately 4 n real elements.
If the input series for g13ab was generated by differencing using g13aa, ensure that only the differenced values are input to g13ab, and not the reconstituting information.

Example

In the example below, a set of 50 values of sunspot counts is used as input. The first 10 autocorrelations are computed.

Example program (C#): g13abe.cs

Example program data: g13abe.d

Example program results: g13abe.r

See Also

G13 Class
G13 Members


g13ac Method

[image]

NAG Library for .NET Release 2
G13..::g13ac Method
G13 Class See Also Send Feedback
g13ac calculates partial autocorrelation coefficients given a set of autocorrelation coefficients. It also calculates the predictor error variance ratios for increasing order of finite lag autoregressive predictor, and the autoregressive parameters associated with the predictor of maximum order.

Syntax

C#
public static void g13ac(
    double[] r,
    int nk,
    int nl,
    double[] p,
    double[] v,
    double[] ar,
    out int nvl,
    out int ifail
)
Visual Basic
Public Shared Sub g13ac ( _
    r As Double(), _
    nk As Integer, _
    nl As Integer, _
    p As Double(), _
    v As Double(), _
    ar As Double(), _
    <OutAttribute> ByRef nvl As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13ac(
    array<double>^ r,
    int nk,
    int nl,
    array<double>^ p,
    array<double>^ v,
    array<double>^ ar,
    [OutAttribute] int% nvl,
    [OutAttribute] int% ifail
)
F#
static member g13ac :
        r : float[] *
        nk : int *
        nl : int *
        p : float[] *
        v : float[] *
        ar : float[] *
        nvl : int byref *
        ifail : int byref -> unit

Parameters

r
Type: array< System..::..Double >[]()[][]
An array of size [nk]
On entry: the autocorrelation coefficient relating to lag k, for k=1,2,…,K.
nk
Type: System..::..Int32
On entry: K, the number of lags. The lags range from 1 to K and do not include zero.
Constraint: nk>0.
nl
Type: System..::..Int32
On entry: L, the number of partial autocorrelation coefficients required.
Constraint: 0<nl≤nk.
p
Type: array< System..::..Double >[]()[][]
An array of size [nl]
On exit: p[l-1] contains the partial autocorrelation coefficient at lag l, p l,l, for l=1,2,…,nvl.
v
Type: array< System..::..Double >[]()[][]
An array of size [nl]
On exit: v[l-1] contains the predictor error variance ratio vl, for l=1,2,…,nvl.
ar
Type: array< System..::..Double >[]()[][]
An array of size [nl]
On exit: the autoregressive parameters of maximum order, i.e., p Lj if ifail=0, or p l 0-1,j if ifail=3, for j=1,2,…,nvl.
nvl
Type: System..::..Int32 %
On exit: the number of valid values in each of p, v and ar. Thus in the case of premature termination at iteration l 0 (see [Description]), nvl is returned as l 0-1.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The data consist of values of autocorrelation coefficients r 1,r 2,…,rK, relating to lags 1,2,…,K. These will generally (but not necessarily) be sample values such as may be obtained from a time series xt using g13ab.
The partial autocorrelation coefficient at lag l may be identified with the parameter p l,l in the autoregression
xt=cl+p l,1x t-1+p l,2x t-2+⋯+p l,lx t-l+e l,t
where e l,t is the predictor error.
The first subscript l of p l,l and e l,t emphasizes the fact that the parameters will in general alter as further terms are introduced into the equation (i.e., as l is increased).
The parameters are determined from the autocorrelation coefficients by the Yule–Walker equations
ri=p l,1r i-1+p l,2r i-2+⋯+p l,lr i-l,  i=1,2,…,l
taking rj=r j when j<0, and r 0=1.
The predictor error variance ratio vl=var e l,t/var xt is defined by
vl=1-p l,1r 1-p l,2r 2-⋯-p l,lrl.
The above sets of equations are solved by a recursive method (the Durbin–Levinson algorithm). The recursive cycle applied for l=1,2,…,L-1, where L is the number of partial autocorrelation coefficients required, is initialized by setting p 1,1=r 1 and v 1=1-r 12.
Then
p l+1,l+1=r l+1-p l,1rl-p l,2r l-1-⋯-p l,lr 1/vlp l+1,j=p l,j-p l+1,l+1p l,l+1-j,  j=1,2,…,lv l+1=vl 1-p l+1,l+11+p l+1,l+1.
If the condition p l,l≥1 occurs, say when l=l 0, it indicates that the supplied autocorrelation coefficients do not form a positive definite sequence (see Hannan (1960)), and the recursion is not continued. The autoregressive parameters are overwritten at each recursive step, so that upon completion the only available values are p Lj, for j=1,2,…,L, or p l 0-1,j if the recursion has been prematurely halted.

References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day
Durbin J (1960) The fitting of time series models Rev. Inst. Internat. Stat. 28 233
Hannan E J (1960) Time Series Analysis Methuen

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | nk≤0,
or | nl≤0,
or | nk<nl.
ifail=2
On entry, the autocorrelation coefficient of lag 1 has an absolute value greater than or equal to 1.0; no recursions could be performed.
ifail=3
Recursion has been prematurely terminated; the supplied autocorrelation coefficients do not form a positive definite sequence (see [Description]). Parameter nvl returns the number of valid values computed.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The computations are believed to be stable.

Parallelism and Performance

None.

Further Comments

The time taken by g13ac is proportional to nvl 2.

Example

Example program (C#): g13ace.cs

Example program data: g13ace.d

Example program results: g13ace.r

See Also

G13 Class
G13 Members


g13ad Method

[image]

NAG Library for .NET Release 2
G13..::g13ad Method
G13 Class See Also Send Feedback
g13ad calculates preliminary estimates of the parameters of an autoregressive integrated moving average (ARIMA) model from the autocorrelation function of the appropriately differenced times series.

Syntax

C#
public static void g13ad(
    int[] mr,
    double[] r,
    int nk,
    double xv,
    double[] par,
    out double rv,
    int[] isf,
    out int ifail
)
Visual Basic
Public Shared Sub g13ad ( _
    mr As Integer(), _
    r As Double(), _
    nk As Integer, _
    xv As Double, _
    par As Double(), _
    <OutAttribute> ByRef rv As Double, _
    isf As Integer(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13ad(
    array<int>^ mr,
    array<double>^ r,
    int nk,
    double xv,
    array<double>^ par,
    [OutAttribute] double% rv,
    array<int>^ isf,
    [OutAttribute] int% ifail
)
F#
static member g13ad :
        mr : int[] *
        r : float[] *
        nk : int *
        xv : float *
        par : float[] *
        rv : float byref *
        isf : int[] *
        ifail : int byref -> unit

Parameters

mr
Type: array< System..::..Int32 >[]()[][]
An array of size [7]
On entry: the orders vector p,d,q,P,D,Q,s of the ARIMA model whose parameters are to be estimated. p, q, P and Q refer respectively to the number of autoregressive ϕ, moving average θ, seasonal autoregressive Φ and seasonal moving average Θ parameters. d, D and s refer respectively to the order of non-seasonal differencing, the order of seasonal differencing and the seasonal period.
Constraints:
  • p,d,q,P,D,Q,s≥0;
  • p+q+P+Q>0;
  • s≠1;
  • if s=0, P+D+Q=0;
  • if s>1, P+D+Q>0.
r
Type: array< System..::..Double >[]()[][]
An array of size [nk]
On entry: the autocorrelations (starting at lag 1), which must have been calculated after the time series has been appropriately differenced.
Constraint: -1.0≤r[i]≤1.0, for i=0,1,…,nk-1.
nk
Type: System..::..Int32
On entry: the maximum lag of the autocorrelations in array r.
Constraint: nk≥max p+q,s×P+Q.
xv
Type: System..::..Double
On entry: the series sample variance, calculated after appropriate differencing has been applied to the series.
Constraint: xv>0.0.
par
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: dim1 must satisfy the constraint: _npar=p+q+P+Q
On exit: the first _npar elements of par contain the preliminary estimates of the ARIMA model parameters, in standard order.
rv
Type: System..::..Double %
On exit: an estimate of the residual variance of the preliminarily estimated model.
isf
Type: array< System..::..Int32 >[]()[][]
An array of size [4]
On exit: contains success/failure indicators, one for each of the four types of parameter (autoregressive, moving average, seasonal autoregressive, seasonal moving average).
The indicator has the interpretation:
-0 | No parameter of this type is in the model.
-1 | Parameters of this type appear in the model and satisfactory preliminary estimates of this type were obtained.
-1 | Parameters of this type appear in the model but satisfactory preliminary estimates of this type were not obtainable. The estimates of this type of parameter were set to 0.0 in array par.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Preliminary estimates of the p non-seasonal autoregressive parameters ϕ 1,ϕ 2,…,ϕp and the q non-seasonal moving average parameters θ 1,θ 2,…,θq may be obtained from the sample autocorrelations relating to lags 1 to p+q, i.e., r 1,…,r p+q, of the differenced ∇d∇sD xt, where xt is assumed to follow a (possibly) seasonal ARIMA model (see [Description] in g13ae for the specification of an ARIMA model).
Taking r 0=1 and r-k=rk, the ϕi, for i=1,2,…,p are the solutions to the equations
r q+i-1ϕ 1+r q+i-2ϕ 2+⋯+r q+i-pϕp=r q+i,  i=1,2,…,p.
The θj, for j=1,2,…,q, are obtained from the solutions to the equations
cj=τ 0τj+τ 1τ j+1+⋯+τ q+jτq,  j=0,1,…,q
(Cramer Wold-factorization), by setting
θj=-τjτ 0,
where cj are the ‘covariances’ modified in a two stage process by the autoregressive parameters.
Stage 1:
dj=rj-ϕ 1r j-1-⋯-ϕpr j-p,j=0,1,…,q;dj=0,j=q+1,q+2,…,p+q.
Stage 2:
cj=dj-ϕ 1d j+1-ϕ 2d j+2-⋯-ϕpd j+p,  j=0,1,…,q.
The P seasonal autoregressive parameters Φ 1,Φ 2,…,ΦP and the Q seasonal moving average parameters Θ 1,Θ 2,…,ΘQ are estimated in the same way as the non-seasonal parameters, but each rj is replaced in the calculation by r s×j, where s is the seasonal period.
An estimate of the residual variance is obtained by successively reducing the sample variance, first for non-seasonal, and then for seasonal, parameter estimates. If moving average parameters are estimated, the variance is reduced by a multiplying factor of τ 02, but otherwise by c 0.

References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (NPAR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, the orders vector mr is invalid. One of the constraints in [Parameters] has been violated.
ifail=2
On entry, nk<max p+q,s×P+Q. There are not enough autocorrelations to enable the required model to be estimated.
ifail=3
On entry, at least one element of r lies outside the range -1.0,1.0.
ifail=4
On entry, xv≤0.0.
ifail=6
On entry, the workspace array wa is too small. See [Parameters] for the minimum size formula.
ifail=7
Satisfactory parameter estimates could not be obtained for all parameter types in the model. Inspect array isf for indicators of the parameter type(s) which could not be estimated.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The performance of the algorithm is conditioned by the roots of the autoregressive and moving average operators. If these are not close to unity in modulus, the errors, e, should satisfy e<100 ε where ε is machine precision.

Parallelism and Performance

None.

Further Comments

The time taken by g13ad is approximately proportional to p 3+q 2+P 3+Q 2.

Example

This example reads the sample autocorrelations to lag 40 and the sample variance of the lagged and doubly differenced series of airline passenger totals (Box and Jenkins example series G (see Box and Jenkins (1976))). Preliminary estimates of the parameters of the 0,1,1,0,1,1,12 model are obtained by a call to g13ad.

Example program (C#): g13ade.cs

Example program data: g13ade.d

Example program results: g13ade.r

See Also

G13 Class
G13 Members


g13af Method

[image]

NAG Library for .NET Release 2
G13..::g13af Method
G13 Class See Also Send Feedback
g13af is an easy-to-use version of (G13AEF not in this release). It fits a seasonal autoregressive integrated moving average (ARIMA) model to an observed time series, using a nonlinear least squares procedure incorporating backforecasting. Parameter estimates are obtained, together with appropriate standard errors. The residual series is returned, and information for use in forecasting the time series is produced for use in g13ag and g13ah.
The estimation procedure is iterative, starting with initial parameter values such as may be obtained using g13ad. It continues until a specified convergence criterion is satisfied or until a specified number of iterations have been carried out. The progress of the iteration can be monitored by means of an optional printing facility.

Syntax

C#
public static void g13af(
    int[] mr,
    double[] par,
    ref double c,
    int kfc,
    double[] x,
    int nx,
    out double s,
    out int ndf,
    double[] sd,
    int nppc,
    double[,] cm,
    double[] st,
    out int nst,
    int kpiv,
    int nit,
    out int itc,
    int[] isf,
    double[] res,
    out int nres,
    out int ifail
)
Visual Basic
Public Shared Sub g13af ( _
    mr As Integer(), _
    par As Double(), _
    ByRef c As Double, _
    kfc As Integer, _
    x As Double(), _
    nx As Integer, _
    <OutAttribute> ByRef s As Double, _
    <OutAttribute> ByRef ndf As Integer, _
    sd As Double(), _
    nppc As Integer, _
    cm As Double(,), _
    st As Double(), _
    <OutAttribute> ByRef nst As Integer, _
    kpiv As Integer, _
    nit As Integer, _
    <OutAttribute> ByRef itc As Integer, _
    isf As Integer(), _
    res As Double(), _
    <OutAttribute> ByRef nres As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13af(
    array<int>^ mr,
    array<double>^ par,
    double% c,
    int kfc,
    array<double>^ x,
    int nx,
    [OutAttribute] double% s,
    [OutAttribute] int% ndf,
    array<double>^ sd,
    int nppc,
    array<double,2>^ cm,
    array<double>^ st,
    [OutAttribute] int% nst,
    int kpiv,
    int nit,
    [OutAttribute] int% itc,
    array<int>^ isf,
    array<double>^ res,
    [OutAttribute] int% nres,
    [OutAttribute] int% ifail
)
F#
static member g13af :
        mr : int[] *
        par : float[] *
        c : float byref *
        kfc : int *
        x : float[] *
        nx : int *
        s : float byref *
        ndf : int byref *
        sd : float[] *
        nppc : int *
        cm : float[,] *
        st : float[] *
        nst : int byref *
        kpiv : int *
        nit : int *
        itc : int byref *
        isf : int[] *
        res : float[] *
        nres : int byref *
        ifail : int byref -> unit

Parameters

mr
Type: array< System..::..Int32 >[]()[][]
An array of size [7]
On entry: the orders vector p,d,q,P,D,Q,s of the ARIMA model whose parameters are to be estimated. p, q, P and Q refer respectively to the number of autoregressive ϕ, moving average θ, seasonal autoregressive Φ and seasonal moving average Θ parameters. d, D and s refer respectively to the order of non-seasonal differencing, the order of seasonal differencing and the seasonal period.
Constraints:
  • p, d, q, P, D, Q, s≥0;
  • p+q+P+Q>0;
  • s≠1;
  • if s=0, P+D+Q=0;
  • if s>1, P+D+Q>0;
  • d+s×P+D≤n;
  • p+d-q+s×P+D-Q≤n.
par
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: dim1 must satisfy the constraint: _npar=p+q+P+Q
On entry: the initial estimates of the p values of the ϕ parameters, the q values of the θ parameters, the P values of the Φ parameters and the Q values of the Θ parameters, in that order.
On exit: contains the latest values of the estimates of these parameters.
c
Type: System..::..Double %
On entry: if kfc=0, c must contain the expected value, c, of the differenced series.
If kfc=1, c must contain an initial estimate of c.
Therefore, if c and kfc are both zero on entry, there is no constant correction.
On exit: if kfc=0, c is unchanged.
If kfc=1, c contains the latest estimate of c.
kfc
Type: System..::..Int32
On entry: must be set to 1 if the constant, c, is to be estimated and 0 if it is to be held fixed at its initial value.
Constraint: kfc=0 or 1.
x
Type: array< System..::..Double >[]()[][]
An array of size [nx]
On entry: the n values of the original undifferenced time series.
nx
Type: System..::..Int32
On entry: n, the length of the original undifferenced time series.
s
Type: System..::..Double %
On exit: the residual sum of squares after the latest series of parameter estimates has been incorporated into the model. If the method exits with a faulty input parameter, s contains zero.
ndf
Type: System..::..Int32 %
On exit: the number of degrees of freedom associated with s, ndf=n-d-D×s-p-q-P-Q-kfc.
sd
Type: array< System..::..Double >[]()[][]
An array of size [nppc]
On exit: the standard deviations corresponding to the parameters in the model (p autoregressive, q moving average, P seasonal autoregressive, Q seasonal moving average and c, if estimated, in that order). If the method exits with ifail containing a value other than 0 or 9, or if the required number of iterations is zero, the contents of sd will be indeterminate.
nppc
Type: System..::..Int32
On entry: the number of ϕ, θ, Φ, Θ and c parameters to be estimated. nppc=p+q+P+Q+1 if the constant is being estimated and nppc=p+q+P+Q if not.
Constraint: nppc=_npar+kfc.
cm
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nppc]
Note: dim1 must satisfy the constraint: dim1≥nppc
On exit: the correlation coefficients associated with each pair of the nppc parameters. These are held in the first nppc rows and the first nppc columns of cm. These correlation coefficients are indeterminate if ifail contains on exit a value other than 0 or 9, or if the required number of iterations is zero.
st
Type: array< System..::..Double >[]()[][]
An array of size [nx]
On exit: the value of the state set in its first nst elements. If the method exits with ifail containing a value other than 0 or 9, the contents of st will be indeterminate.
nst
Type: System..::..Int32 %
On exit: the size of the state set. nst=P×s+D×s+d+q+max p,Q×s.
nst should be used subsequently in g13ag and g13ah as the dimension of st.
kpiv
Type: System..::..Int32
On entry: must be nonzero if the progress of the optimization is to be monitored using the built-in printing facility. Otherwise kpiv must contain zero. If selected, monitoring output will be sent to the current advisory message unit defined by (X04ABF not in this release). For each iteration, the heading
 G13AFZ MONITORING OUTPUT - ITERATION n
followed by the parameter values, and residual sum of squares, are printed.
nit
Type: System..::..Int32
On entry: the maximum number of iterations to be performed.
Constraint: nit≥0.
itc
Type: System..::..Int32 %
On exit: the number of iterations performed.
isf
Type: array< System..::..Int32 >[]()[][]
An array of size [4]
On exit: the first four elements of isf contain success/failure indicators, one for each of the four types of parameter in the model (autoregressive, moving average, seasonal autoregressive, seasonal moving average), in that order.
Each indicator has the interpretation:
-2 | On entry parameters of this type have initial estimates which do not satisfy the stationarity or invertibility test conditions.
-1 | The search procedure has failed to converge because the latest set of parameter estimates of this type is invalid.
-0 | No parameter of this type is in the model.
-1 | Valid final estimates for parameters of this type have been obtained.
res
Type: array< System..::..Double >[]()[][]
An array of size [ires]
On exit: the first nres elements of res contain the model residuals derived from the differenced series. If the method exits with ifail holding a value other than 0 or 9, these elements of res will be indeterminate. The rest of the array res is used as workspace.
nres
Type: System..::..Int32 %
On exit: the number of model residuals returned in res.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The time series x 1,x 2,…,xn supplied to the method is assumed to follow a seasonal autoregressive integrated moving average (ARIMA) model defined as follows:
∇d∇sD xt-c=wt,
where ∇d∇sD xt is the result of applying non-seasonal differencing of order d and seasonal differencing of seasonality s and order D to the series xt, as outlined in the description of g13aa. The differenced series is then of length N=n-d′, where d′=d+D×s is the generalized order of differencing. The scalar c is the expected value of the differenced series, and the series w 1,w 2,…,wN follows a zero-mean stationary autoregressive moving average (ARMA) model defined by a pair of recurrence equations. These express wt in terms of an uncorrelated series at, via an intermediate series et. The first equation describes the seasonal structure:
wt=Φ 1w t-s+Φ 2w t-2×s+⋯+ΦPw t-P×s+et-Θ 1e t-s-Θ 2e t-2×s-⋯-ΘQe t-Q×s.
The second equation describes the non-seasonal structure. If the model is purely non-seasonal the first equation is redundant and et above is equated with wt:
et=ϕ 1e t-1+ϕ 2e t-2+⋯+ϕpe t-p+at-θ 1a t-1-θ 2a t-2-⋯-θqa t-q.
Estimates of the model parameters defined by
ϕ 1,ϕ 2,…,ϕp,θ 1,θ 2,…,θq,Φ 1,Φ 2,…,ΦP,Θ 1,Θ 2,…,ΘQ
and (optionally) c are obtained by minimizing a quadratic form in the vector w=w 1,w 2,…,wN′.
The minimization process is iterative, iterations being performed until convergence is achieved (see [Description] in g13ae for full details), or until the user-specified maximum number of iterations are completed.
The final values of the residual sum of squares and the parameter estimates are used to obtain asymptotic approximations to the standard deviations of the parameters, and the correlation matrix for the parameters. The ‘state set’ array of information required by forecasting is also returned.
Note: if the maximum number of iterations are performed without convergence, these quantities may not be reliable. In this case, the sequence of iterates should be checked, using the optional monitoring method, to verify that convergence is adequate for practical purposes.

References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day
Marquardt D W (1963) An algorithm for least squares estimation of nonlinear parameters J. Soc. Indust. Appl. Math. 11 431

Error Indicators and Warnings

Note: g13af may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (NPAR, LDCM) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | the orders vector mr is invalid (check the constraints in [Parameters]),
or | kfc≠0 or 1,
ifail=2
On entry, nx-d-D×s≤_npar+kfc, i.e., the number of terms in the differenced series is not greater than the number of parameters in the model. The model is over-parameterised.
ifail=3
On entry, nit<0.
ifail=4
On entry, the required size of the state set array st is greater than nx. This occurs only for very unusual models with long seasonal periods or large numbers of parameters. First check that the orders vector mr has been set up as intended. If it has, change to (G13AEF not in this release) with st dimensioned at least (nst), where nst is the value returned by g13af, or computed using the formula in [Parameters] of this document.
ifail=5
On entry, the workspace array res is too small. Check the value of ires against the constraints in [Parameters].
ifail=7
The search procedure in the algorithm has failed. This may be due to a badly conditioned sum of squares function, or the default convergence criterion may be too strict. Use (G13AEF not in this release) with a less strict convergence criterion.
Some output parameters may contain meaningful values; see [Parameters] for details.
ifail=8
The inversion of the Hessian matrix in the calculation of the covariance matrix of the parameter estimates has failed.
Some output parameters may contain meaningful values; see [Parameters] for details.
ifail=9
This indicates a failure when solving the equations giving the latest estimates of the backforecasts.
Some output parameters may contain meaningful values; see [Parameters] for details.
ifail=10
Satisfactory parameter estimates could not be obtained for all parameter types in the model. Inspect array isf for further information on the parameter type(s) in error.
ifail=11
An internal error has arisen in partitioning res for use by (G13AEF not in this release). This error should not occur; report it to NAG via your site representative.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The computations are believed to be stable.

Parallelism and Performance

None.

Further Comments

The time taken by g13af is approximately proportional to nx×itc×q+Q×s+nppc 2.

Example

This example reads 30 observations from a time series relating to the rate of the earth's rotation about its polar axis. Differencing of order 1 is applied, and the number of non-seasonal parameters is 3, one autoregressive (ϕ) and two moving average (θ). No seasonal effects are taken into account.
The constant is estimated. Up to 50 iterations are allowed.
The initial estimates of ϕ 1, θ 1, θ 2 and c are zero.
Some intermediate monitoring output from (G13AFZ not in this release) has been omitted.

Example program (C#): g13afe.cs

Example program data: g13afe.d

Example program results: g13afe.r

See Also

G13 Class
G13 Members


g13ag Method

[image]

NAG Library for .NET Release 2
G13..::g13ag Method
G13 Class See Also Send Feedback
g13ag accepts a series of new observations of a time series, the model of which is already fully specified, and updates the ‘state set’ information for use in constructing further forecasts. The previous specifications of the time series model should have been obtained by using (G13AEF not in this release) g13af to estimate the relevant parameters. The supplied state set will originally have been produced by (G13AEF not in this release) g13af, but may since have been updated by earlier calls to g13ag.
A set of residuals corresponding to the new observations is returned. These may be of use in checking that the new observations conform to the previously fitted model.

Syntax

C#
public static void g13ag(
    double[] st,
    int nst,
    int[] mr,
    double[] par,
    double c,
    double[] anx,
    int nuv,
    double[] anexr,
    out int ifail
)
Visual Basic
Public Shared Sub g13ag ( _
    st As Double(), _
    nst As Integer, _
    mr As Integer(), _
    par As Double(), _
    c As Double, _
    anx As Double(), _
    nuv As Integer, _
    anexr As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13ag(
    array<double>^ st,
    int nst,
    array<int>^ mr,
    array<double>^ par,
    double c,
    array<double>^ anx,
    int nuv,
    array<double>^ anexr,
    [OutAttribute] int% ifail
)
F#
static member g13ag :
        st : float[] *
        nst : int *
        mr : int[] *
        par : float[] *
        c : float *
        anx : float[] *
        nuv : int *
        anexr : float[] *
        ifail : int byref -> unit

Parameters

st
Type: array< System..::..Double >[]()[][]
An array of size [nst]
On entry: the state set derived from (G13AEF not in this release) g13af, or as modified using earlier calls of g13ag.
On exit: the updated values of the state set.
nst
Type: System..::..Int32
On entry: the number of values in the state set array st.
Constraint: nst=P×s+D×s+d+q+max p,Q×s. (As returned by (G13AEF not in this release) g13af).
mr
Type: array< System..::..Int32 >[]()[][]
An array of size [7]
On entry: the orders vector p,d,q,P,D,Q,s of the ARIMA model, in the usual notation.
Constraints:
  • p,d,q,P,D,Q,s≥0;
  • p+q+P+Q>0;
  • s≠1;
  • if s=0, P+D+Q=0;
  • if s>1, P+D+Q>0.
par
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: dim1 must satisfy the constraint: _npar=p+q+P+Q
On entry: the estimates of the p values of the ϕ parameters, the q values of the θ parameters, the P values of the Φ parameters and the Q values of the Θ parameters in the model – in that order, using the usual notation.
c
Type: System..::..Double
On entry: the constant to be subtracted from the differenced data.
anx
Type: array< System..::..Double >[]()[][]
An array of size [nuv]
On entry: the new undifferenced observations which are to be used to update st.
nuv
Type: System..::..Int32
On entry: k, the number of new observations in anx.
anexr
Type: array< System..::..Double >[]()[][]
An array of size [nuv]
On exit: the residuals corresponding to the new observations in anx.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The time series model is specified as outlined in Section in g13ae or g13af. This also describes how the state set, which contains the minimum amount of time series information needed to construct forecasts, is made up of
(i) | the differenced series wt (uncorrected for the constant c), for N-P×s<t≤N,
(ii) | the d′ values required to reconstitute the original series xt from the differenced series wt,
(iii) | the intermediate series et, for N-max p,Q×s<t≤N, and
(iv) | the residual series at, for N-q<t≤N.
If the number of original undifferenced observations was n, then d′=d+D×s and N=n-d′.
To update the state set, given a number of new undifferenced observations xt, t=n+1,n+2,…,n+k, the four series above are first reconstituted.
Differencing and residual calculation operations are then applied to the new observations and k new values of wt,et and at are derived.
The first k values in these three series are then discarded and a new state set is obtained.
The residuals in the at series corresponding to the k new observations are preserved in an output array. The parameters of the time series model are not changed in this method.

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (NPAR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, the orders vector mr is invalid (check the constraints in [Parameters]).
ifail=2
On entry, nst≠P×s+D×s+d+q+max Q×s,p.
ifail=3
On entry, nuv≤0.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The computations are believed to be stable.

Parallelism and Performance

None.

Further Comments

The time taken by g13ag is approximately proportional to nuv×_npar.

Example

Twelve new observations are supplied. The method updates the state set and outputs a set of residuals corresponding to the new observations.

Example program (C#): g13age.cs

Example program data: g13age.d

Example program results: g13age.r

See Also

G13 Class
G13 Members


g13ah Method

[image]

NAG Library for .NET Release 2
G13..::g13ah Method
G13 Class See Also Send Feedback
g13ah produces forecasts of a time series, given a time series model which has already been fitted to the time series using (G13AEF not in this release) g13af. The original observations are not required, since g13ah uses as input either the original state set produced by (G13AEF not in this release) g13af or the state set updated by a series of new observations using g13ag. Standard errors of the forecasts are also provided.

Syntax

C#
public static void g13ah(
    double[] st,
    int nst,
    int[] mr,
    double[] par,
    double c,
    double rms,
    int nfv,
    double[] fva,
    double[] fsd,
    out int ifail
)
Visual Basic
Public Shared Sub g13ah ( _
    st As Double(), _
    nst As Integer, _
    mr As Integer(), _
    par As Double(), _
    c As Double, _
    rms As Double, _
    nfv As Integer, _
    fva As Double(), _
    fsd As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13ah(
    array<double>^ st,
    int nst,
    array<int>^ mr,
    array<double>^ par,
    double c,
    double rms,
    int nfv,
    array<double>^ fva,
    array<double>^ fsd,
    [OutAttribute] int% ifail
)
F#
static member g13ah :
        st : float[] *
        nst : int *
        mr : int[] *
        par : float[] *
        c : float *
        rms : float *
        nfv : int *
        fva : float[] *
        fsd : float[] *
        ifail : int byref -> unit

Parameters

st
Type: array< System..::..Double >[]()[][]
An array of size [nst]
On entry: the state set derived from (G13AEF not in this release) g13af originally, or as modified using earlier calls of g13ag.
nst
Type: System..::..Int32
On entry: the number of values in the state set array st.
Constraint: nst=P×s+D×s+d+q+max p,Q×s. (As returned by (G13AEF not in this release) g13af).
mr
Type: array< System..::..Int32 >[]()[][]
An array of size [7]
On entry: the orders vector p,d,q,P,D,Q,s of the ARIMA model, in the usual notation.
Constraints:
  • p,d,q,P,D,Q,s≥0;
  • p+q+P+Q>0;
  • s≠1;
  • if s=0, P+D+Q=0;
  • if s>1, P+D+Q>0.
par
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: dim1 must satisfy the constraint: _npar=p+q+P+Q
On entry: the estimates of the p values of the ϕ parameters, the q values of the θ parameters, the P values of the Φ parameters and the Q values of the Θ parameters which specify the model and which were output originally by (G13AEF not in this release) g13af.
c
Type: System..::..Double
On entry: c, the value of the model constant. This will have been output by (G13AEF not in this release) g13af.
rms
Type: System..::..Double
On entry: V, the residual variance associated with the model.
If g13af was used to estimate the model, rms should be set to s/ndf, where s and ndf were output by g13af.
If (G13AEF not in this release) was used to estimate the model, rms should be set to s/icount[4], where s and icount[4] were output by (G13AEF not in this release).
Constraint: rms≥0.0.
nfv
Type: System..::..Int32
On entry: L, the required number of forecasts.
Constraint: nfv>0.
fva
Type: array< System..::..Double >[]()[][]
An array of size [nfv]
On exit: nfv forecast values relating to the original undifferenced series.
fsd
Type: array< System..::..Double >[]()[][]
An array of size [nfv]
On exit: the standard errors associated with each of the nfv forecast values in fva.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The original time series is xt, for t=1,2,…,n and parameters have been fitted to the model of this time series using (G13AEF not in this release) g13af.
Forecasts of xt, for t=n+1,…,n+L, are calculated in five stages, as follows:
(i) | set at=0 for t=N+1,N+2,…,N+L, where N=n-d-D×s is the number of differenced values in the series;
(ii) | calculate the values of et, for t=N+1,…,N+L, and et=ϕ 1×e t-1+⋯+ϕp×e t-p+at-θ 1×a t-1-⋯-θq×a t-q;
(iii) | calculate the values of wt, for t=N+1,…,N+L, where wt=Φ 1×w t-s+⋯+ΦP×w t-s×P+et-Θ 1×e t-s-⋯-ΘQ×e t-s×Q and wt for t≤N are the first s×P values in the state set, corrected for the constant;
(iv) | add the constant term c to give the differenced series ∇d∇sD xt=wt+c, for t=N+1,…,N+L;
(v) | the differencing operations are reversed to reconstitute xt, for t=n+1,…,n+L.
The standard errors of these forecasts are given by st=V×ψ 02+ψ 12+…+ψ t-n-1 2 1/2, for t=n+1,…,n+L, where ψ 0=1, V is the residual variance of at, and ψj is the coefficient expressing the dependence of xt on a t-j.
To calculate ψj, for j=1,2,…,L-1, the following device is used.
A copy of the state set is initialized to zero throughout and the calculations outlined above for the construction of forecasts are carried out with the settings a N+1=1, and at=0, for t=N+2,…,N+L.
The resulting quantities corresponding to the sequence x N+1,x N+2,…,x N+L are precisely 1, ψ 1,ψ 2,…,ψ L-1.
The supplied time series model is used throughout these calculations, with the exception that the constant term c is taken to be zero.

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (NPAR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, the orders vector mr is invalid (check the constraints given in [Parameters]).
ifail=2
On entry, nst≠P×s+D×s+d+q+max Q×s,p.
ifail=3
On entry, nfv≤0.
ifail=5
On entry, rms<0.0.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The computations are believed to be stable.

Parallelism and Performance

None.

Further Comments

The time taken by g13ah is approximately proportional to nfv×_npar.

Example

These consist of a set of orders indicating that there are two moving average parameters (one non-seasonal, and one seasonal with periodicity 12).
The model constant is zero.
The state set contains 26 values.
In addition the residual mean-square derived when the model was originally fitted is given.
Twelve forecasts and their associated errors are obtained.

Example program (C#): g13ahe.cs

Example program data: g13ahe.d

Example program results: g13ahe.r

See Also

G13 Class
G13 Members


g13aj Method

[image]

NAG Library for .NET Release 2
G13..::g13aj Method
G13 Class See Also Send Feedback
g13aj applies a fully specified seasonal ARIMA model to an observed time series, generates the state set for forecasting and (optionally) derives a specified number of forecasts together with their standard deviations.

Syntax

C#
public static void g13aj(
    int[] mr,
    double[] par,
    double c,
    int kfc,
    double[] x,
    int nx,
    out double rms,
    double[] st,
    out int nst,
    int nfv,
    double[] fva,
    double[] fsd,
    int[] isf,
    out int ifail
)
Visual Basic
Public Shared Sub g13aj ( _
    mr As Integer(), _
    par As Double(), _
    c As Double, _
    kfc As Integer, _
    x As Double(), _
    nx As Integer, _
    <OutAttribute> ByRef rms As Double, _
    st As Double(), _
    <OutAttribute> ByRef nst As Integer, _
    nfv As Integer, _
    fva As Double(), _
    fsd As Double(), _
    isf As Integer(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13aj(
    array<int>^ mr,
    array<double>^ par,
    double c,
    int kfc,
    array<double>^ x,
    int nx,
    [OutAttribute] double% rms,
    array<double>^ st,
    [OutAttribute] int% nst,
    int nfv,
    array<double>^ fva,
    array<double>^ fsd,
    array<int>^ isf,
    [OutAttribute] int% ifail
)
F#
static member g13aj :
        mr : int[] *
        par : float[] *
        c : float *
        kfc : int *
        x : float[] *
        nx : int *
        rms : float byref *
        st : float[] *
        nst : int byref *
        nfv : int *
        fva : float[] *
        fsd : float[] *
        isf : int[] *
        ifail : int byref -> unit

Parameters

mr
Type: array< System..::..Int32 >[]()[][]
An array of size [7]
On entry: the orders vector p,d,q,P,D,Q,s of the ARIMA model, in the usual notation.
Constraints:
  • p,d,q,P,D,Q,s≥0;
  • p+q+P+Q>0;
  • s≠1;
  • if s=0, P+D+Q=0;
  • if s>1, P+D+Q>0;
  • d+s×P+D≤n;
  • p+d-q+s×P+D-Q≤n.
par
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: dim1 must satisfy the constraint: _npar=p+q+P+Q
On entry: the p values of the ϕ parameters, the q values of the θ parameters, the P values of the Φ parameters, and the Q values of the Θ parameters, in that order.
c
Type: System..::..Double
On entry: c, the expected value of the differenced series (i.e., c is the constant correction). Where there is no constant term, c must be set to 0.0.
kfc
Type: System..::..Int32
On entry: must be set to 0 if c was not estimated, and 1 if c was estimated. This is irrespective of whether or not c=0.0. The only effect is that the residual degrees of freedom are one greater when kfc=0. Assuming the supplied time series to be the same as that to which the model was originally fitted, this ensures an unbiased estimate of the residual mean-square.
Constraint: kfc=0 or 1.
x
Type: array< System..::..Double >[]()[][]
An array of size [nx]
On entry: the n values of the original undifferenced time series.
nx
Type: System..::..Int32
On entry: n, the length of the original undifferenced time series.
rms
Type: System..::..Double %
On exit: the residual variance (mean square) associated with the model.
st
Type: array< System..::..Double >[]()[][]
An array of size [ist]
On exit: the nst values of the state set.
nst
Type: System..::..Int32 %
On exit: the number of values in the state set array st.
nfv
Type: System..::..Int32
On entry: the required number of forecasts. If nfv≤0, no forecasts will be computed.
fva
Type: array< System..::..Double >[]()[][]
An array of size [ifv]
On exit: if nfv>0, fva contains the nfv forecast values relating to the original undifferenced time series.
fsd
Type: array< System..::..Double >[]()[][]
An array of size [ifv]
On exit: if nfv>0, fsd contains the estimated standard errors of the nfv forecast values.
isf
Type: array< System..::..Int32 >[]()[][]
An array of size [4]
On exit: contains validity indicators, one for each of the four possible parameter types in the model (autoregressive, moving average, seasonal autoregressive, seasonal moving average), in that order.
Each indicator has the interpretation:
-1 | On entry the set of parameter values of this type does not satisfy the stationarity or invertibility test conditions.
-0 | No parameter of this type is in the model.
-1 | Valid parameter values of this type have been supplied.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The time series x 1,x 2,…,xn supplied to the method is assumed to follow a seasonal autoregressive integrated moving average (ARIMA) model with known parameters.
The model is defined by the following relations.
(a) | ∇d∇sD xt-c=wt where ∇d∇sD xt is the result of applying non-seasonal differencing of order d and seasonal differencing of seasonality s and order D to the series xt, and c is a constant.
(b) | wt=Φ 1w t-s+Φ 2w t-2×s+⋯+ΦPw t-P×s+et-Θ 1e t-s-Θ 2e t-2×s-⋯-ΘQe t-Q×s. This equation describes the seasonal structure with seasonal period s; in the absence of seasonality it reduces to wt=et.
(c) | et=ϕ 1e t-1+ϕ 2e t-2+⋯+ϕpe t-p+at-θ 1a t-1-θ 2a t-2-⋯-θqa t-q. This equation describes the non-seasonal structure.
Given the series, the constant c, and the model parameters Φ, Θ, ϕ, θ, the method computes the following.
(a) The state set required for forecasting. This contains the minimum amount of information required for forecasting and comprises:
(i) | the differenced series wt, for N-s×P≤t≤N;
(ii) | the d+D×s values required to reconstitute the original series xt from the differenced series wt;
(iii) | the intermediate series et, for N-max p,Q×s<t≤N;
(iv) | the residual series at, for N-q<t≤N, where N=n-d+D×s.
(b) A set of L forecasts of xt and their estimated standard errors, st, for t=n+1,…,n+L (L may be zero).
The forecasts and estimated standard errors are generated from the state set, and are identical to those that would be produced from the same state set by g13ah.
Use of g13aj should be confined to situations in which the state set for forecasting is unknown. Forecasting from the series requires recalculation of the state set and this is relatively expensive.

References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (NPAR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | the orders vector mr is invalid (check the constraints in [Parameters]),
or | kfc≠0 or 1.
ifail=2
On entry, nx-d-D×s≤_npar+kfc, i.e., the number of terms in the differenced series is not greater than the number of parameters in the model. The model is over-parameterised.
ifail=3
On entry, the workspace array w is too small.
ifail=4
On entry, the state set array st is too small. It must be at least as large as the exit value of nst.
ifail=5
This indicates a failure in (F04ASF not in this release) which is used to solve the equations giving estimates of the backforecasts.
ifail=6
On entry, valid values were not supplied for all parameter types in the model. Inspect array isf for further information on the parameter type(s) in error.
ifail=7
On entry, ifv<max 1,nfv.
ifail=-9000
An error occured, see message report.
ifail=-1000
The array lengths are not the same for arrays
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The computations are believed to be stable.

Parallelism and Performance

None.

Further Comments

The time taken by g13aj is approximately proportional to n and the square of the number of backforecasts derived.

Example

Example program (C#): g13aje.cs

Example program data: g13aje.d

Example program results: g13aje.r

See Also

G13 Class
G13 Members


g13am Method

[image]

NAG Library for .NET Release 2
G13..::g13am Method
G13 Class See Also Send Feedback
g13am performs exponential smoothing using either single exponential, double exponential or a Holt–Winters method.

Syntax

C#
public static void g13am(
    int mode,
    int itype,
    int p,
    double[] param,
    int n,
    double[] y,
    int k,
    double[] init,
    int nf,
    double[] fv,
    double[] fse,
    double[] yhat,
    double[] res,
    out double dv,
    out double ad,
    double[] r,
    out int ifail
)
Visual Basic
Public Shared Sub g13am ( _
    mode As Integer, _
    itype As Integer, _
    p As Integer, _
    param As Double(), _
    n As Integer, _
    y As Double(), _
    k As Integer, _
    init As Double(), _
    nf As Integer, _
    fv As Double(), _
    fse As Double(), _
    yhat As Double(), _
    res As Double(), _
    <OutAttribute> ByRef dv As Double, _
    <OutAttribute> ByRef ad As Double, _
    r As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13am(
    int mode,
    int itype,
    int p,
    array<double>^ param,
    int n,
    array<double>^ y,
    int k,
    array<double>^ init,
    int nf,
    array<double>^ fv,
    array<double>^ fse,
    array<double>^ yhat,
    array<double>^ res,
    [OutAttribute] double% dv,
    [OutAttribute] double% ad,
    array<double>^ r,
    [OutAttribute] int% ifail
)
F#
static member g13am :
        mode : int *
        itype : int *
        p : int *
        param : float[] *
        n : int *
        y : float[] *
        k : int *
        init : float[] *
        nf : int *
        fv : float[] *
        fse : float[] *
        yhat : float[] *
        res : float[] *
        dv : float byref *
        ad : float byref *
        r : float[] *
        ifail : int byref -> unit

Parameters

mode
Type: System..::..Int32
On entry: indicates if g13am is continuing from a previous call or, if not, how the initial values are computed.
mode=0
Required values for m 0, r 0 and s-j, for j=0,1,…,p-1, are supplied in init.
mode=1
g13am continues from a previous call using values that are supplied in r.
mode=2
Required values for m 0, r 0 and s-j, for j=0,1,…,p-1, are estimated using the first k observations.
Constraint: mode=0, 1 or 2.
itype
Type: System..::..Int32
On entry: the smoothing function.
itype=1
Single exponential.
itype=2
Brown double exponential.
itype=3
Linear Holt.
itype=4
Additive Holt–Winters.
itype=5
Multiplicative Holt–Winters.
Constraint: itype=1, 2, 3, 4 or 5.
p
Type: System..::..Int32
On entry: if itype=4 or 5, the seasonal order, p, otherwise p is not referenced.
Constraint: if itype=4 or 5, p>1.
param
Type: array< System..::..Double >[]()[][]
An array of size [_lparam]
Note: the dimension of the array param must be at least 1 if itype=1 or 2, 3 if itype=3 and at least 4 if itype=4 or 5.
On entry: the smoothing parameters.
If itype=1 or 2, param[0]=α and any remaining elements of param are not referenced.
If itype=3, param[0]=α, param[1]=γ, param[2]=ϕ and any remaining elements of param are not referenced.
If itype=4 or 5, param[0]=α, param[1]=γ, param[2]=β and param[3]=ϕ.
Constraints:
  • if itype=1, 0.0≤α≤1.0;
  • if itype=2, 0.0<α≤1.0;
  • if itype=3, 0.0≤α≤1.0 and 0.0≤γ≤1.0 and ϕ≥0.0;
  • if itype=4 or 5, 0.0≤α≤1.0 and 0.0≤γ≤1.0 and 0.0≤β≤1.0 and ϕ≥0.0.
n
Type: System..::..Int32
On entry: the number of observations in the series.
Constraint: n≥0.
y
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the time series.
k
Type: System..::..Int32
On entry: if mode=2, the number of observations used to initialize the smoothing.
If mode≠2, k is not referenced.
Constraints:
  • if mode=2 and itype=4 or 5, 2×p≤k≤n;
  • if mode=2 and itype=1, 2 or 3, 1≤k≤n.
init
Type: array< System..::..Double >[]()[][]
An array of size [_linit]
Note: the dimension of the array init must be at least 1 if itype=1, 2 if itype=2 or 3 and at least 2+p if itype=4 or 5.
On entry: if mode=0, the initial values for m 0, r 0 and s-j, for j=0,1,…,p-1, used to initialize the smoothing.
If itype=1, init[0]=m 0 and the remaining elements of init are not referenced.
If itype=2 or 3, init[0]=m 0 and init[1]=r 0 and the remaining elements of init are not referenced.
If itype=4 or 5, init[0]=m 0, init[1]=r 0 and init[2] to init[p+1] hold the values for s-j, for j=0,1,…,p-1. The remaining elements of init are not referenced.
On exit: if mode≠1, the values used to initialize the smoothing. These are in the same order as described above.
nf
Type: System..::..Int32
On entry: the number of forecasts required beyond the end of the series. Note, the one step ahead forecast is always produced.
Constraint: nf≥0.
fv
Type: array< System..::..Double >[]()[][]
An array of size [nf]
On exit: y^t+f, for f=1,2,…,nf, the next nf step forecasts. Where t=n, if mode≠1, else t is the total number of smoothed and forecast values already produced.
fse
Type: array< System..::..Double >[]()[][]
An array of size [nf]
On exit: the forecast standard errors for the values given in fv.
yhat
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: y^t+1, for t=1,2,…,n, the one step ahead forecast values, with yhat[i-1] being the one step ahead forecast of y[i-2].
res
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the residuals, y t+1-y^t+1, for t=1,2,…,n.
dv
Type: System..::..Double %
On exit: the square root of the mean deviation.
ad
Type: System..::..Double %
On exit: the mean absolute deviation.
r
Type: array< System..::..Double >[]()[][]
An array of size [_lr]
Note: the dimension of the array r must be at least 13 if itype=1, 2 or 3 and at least 13+p if itype=4 or 5.
On entry: if mode=1, r must contain the values as returned by a previous call to g05pm or g13am, r need not be set otherwise.
If itype=1, 2 or 3, only the first 13 elements of r are referenced, otherwise the first 13+p elements are referenced.
On exit: the information on the current state of the smoothing.
Constraint: if mode=1, r must have been initialized by at least one previous call to g05pm or g13am with mode≠1, and r should not have been changed since the last call to g05pm or g13am.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Exponential smoothing is a relatively simple method of short term forecasting for a time series. g13am provides five types of exponential smoothing; single exponential, Brown's double exponential, linear Holt (also called double exponential smoothing in some references), additive Holt–Winters and multiplicative Holt–Winters. The choice of smoothing method used depends on the characteristics of the time series. If the mean of the series is only slowly changing then single exponential smoothing may be suitable. If there is a trend in the time series, which itself may be slowly changing, then double exponential smoothing may be suitable. If there is a seasonal component to the time series, e.g., daily or monthly data, then one of the two Holt–Winters methods may be suitable.
For a time series yt, for t=1,2,…,n, the five smoothing functions are defined by the following:
  • Single Exponential Smoothing
    mt=α yt+1-α m t-1y^t+f=mtvar y^t+f=var εt 1+f-1 α 2
  • Brown Double Exponential Smoothing
    mt=α yt+1-α m t-1rt=α mt-m t-1+1-α r t-1y^t+f=mt+f-1+1/α rtvar y^t+f=var εt 1+∑ i=0 f-1 2 α+i-1 α 2 2
  • Linear Holt Smoothing
    mt=α yt+1-αm t-1+ϕ r t-1rt=γ mt-m t-1+1-γ ϕ r t-1y^t+f=mt+∑ i=1 f ϕi rtvar y^t+f=var εt 1+∑ i=1 f-1 α+αγϕ ϕi-1 ϕ-1 2
  • Additive Holt–Winters Smoothing
    mt=α yt-s t-p+1-αm t-1+ϕ r t-1rt=γ mt-m t-1+1-γ ϕ r t-1st=β yt-mt+1-β s t-py^t+f=mt+∑ i=1 f ϕi rt+s t-pvar y^t+f=var εt 1+∑ i=1 f-1 ψi 2ψi=0if ​i≥fα+αγϕ ϕi-1ϕ-1if ​i mod p≠0α+αγϕ ϕi-1 ϕ-1+β 1-αotherwise
  • Multiplicative Holt–Winters Smoothing
    mt=α yt/s t-p+1-αm t-1+ϕ r t-1rt=γ mt-m t-1+1-γ ϕ r t-1st=β yt/mt+1-β s t-py^t+f=mt+∑ i=1 f ϕi rt×s t-pvar y^t+f=var εt∑ i=0 ∞ ∑ j=0 p-1 ψ j+ip s t+fs t+f-j 2
    and ψ is defined as in the additive Holt–Winters smoothing,
where mt is the mean, rt is the trend and st is the seasonal component at time t with p being the seasonal order. The f-step ahead forecasts are given by y^t+f and their variances by var y^t+f. The term var εt is estimated as the mean deviation.
The parameters, α, β and γ control the amount of smoothing. The nearer these parameters are to one, the greater the emphasis on the current data point. Generally these parameters take values in the range 0.1 to 0.3. The linear Holt and two Holt–Winters smoothers include an additional parameter, ϕ, which acts as a trend dampener. For 0.0<ϕ<1.0 the trend is dampened and for ϕ>1.0 the forecast function has an exponential trend, ϕ=0.0 removes the trend term from the forecast function and ϕ=1.0 does not dampen the trend.
For all methods, values for α, β, γ and ψ can be chosen by trying different values and then visually comparing the results by plotting the fitted values along side the original data. Alternatively, for single exponential smoothing a suitable value for α can be obtained by fitting an ARIMA 0,1,1 model (see g13be). For Brown's double exponential smoothing and linear Holt smoothing with no dampening, (i.e., ϕ=1.0), suitable values for α and γ can be obtained by fitting an ARIMA 0,2,2 model. Similarly, the linear Holt method, with ϕ≠1.0, can be expressed as an ARIMA 1,2,2 model and the additive Holt–Winters, with no dampening, (ϕ=1.0), can be expressed as a seasonal ARIMA model with order p of the form ARIMA 0,1,p+10,1,0. There is no similar procedure for obtaining parameter values for the multiplicative Holt–Winters method, or the additive Holt–Winters method with ϕ≠1.0. In these cases parameters could be selected by minimizing a measure of fit using one of the nonlinear optimization methods in E04 class.
In addition to values for α, β, γ and ψ, initial values, m 0, r 0 and s-j, for j=0,1,…,p-1, are required to start the smoothing process. You can either supply these or they can be calculated by g13am from the first k observations. For single exponential smoothing the mean of the observations is used to estimate m 0. For Brown double exponential smoothing and linear Holt smoothing, a simple linear regression is carried out with the series as the dependent variable and the sequence 1,2,…,k as the independent variable. The intercept is then used to estimate m 0 and the slope to estimate r 0. In the case of the additive Holt–Winters method, the same regression is carried out, but a separate intercept is used for each of the p seasonal groupings. The slope gives an estimate for r 0 and the mean of the p intercepts is used as the estimate of m 0. The seasonal parameters s-j, for j=0,1,…,p-1, are estimated as the p intercepts – m 0. A similar approach is adopted for the multiplicative Holt–Winter's method.
One step ahead forecasts, y^t+1 are supplied along with the residuals computed as y t+1-y^t+1. In addition, two measures of fit are provided. The mean absolute deviation,
1 n∑ t=1 n yt-y^t
and the square root of the mean deviation
1 n∑ t=1 n yt-y^t 2.

References

Chatfield C (1980) The Analysis of Time Series Chapman and Hall

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | mode<0,
or | mode>2.
ifail=2
On entry, | itype<1,
or | itype>5.
ifail=3
On entry, itype=4 or 5 and p<2.
ifail=4
On entry, at least one of α, β or γ<0.0 or >1.0.
On entry, itype=2 and α=0.0.
On entry, ϕ<0.0.
ifail=5
On entry, n<0.
ifail=6
A multiplicative Holt–Winters model cannot be used with the supplied data.
ifail=7
On entry, mode=2 and k<1 or k>n.
On entry, mode=2, itype=4 or 5 and k<2×p.
ifail=9
On entry, nf<0.
ifail=16
On entry, mode=1 and the array r has not been initialized correctly.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

Single exponential, Brown's double exponential and linear Holt smoothing methods are stable, whereas the two Holt–Winters methods can be affected by poor initial values for the seasonal components.
See also the method document for g05pm.

Example

This example smooths a time series relating to the rate of the earth's rotation about its polar axis.

Example program (C#): g13ame.cs

Example program data: g13ame.d

Example program results: g13ame.r

See Also

G13 Class
G13 Members


g13as Method

[image]

NAG Library for .NET Release 2
G13..::g13as Method
G13 Class See Also Send Feedback
g13as is a diagnostic checking method suitable for use after fitting a Box–Jenkins ARMA model to a univariate time series using (G13AEF not in this release) g13af. The residual autocorrelation function is returned along with an estimate of its asymptotic standard errors and correlations. Also, g13as calculates the Box–Ljung portmanteau statistic and its significance level for testing model adequacy.

Syntax

C#
public static void g13as(
    int n,
    double[] v,
    int[] mr,
    int m,
    double[] par,
    int ishow,
    double[] r,
    double[,] rcm,
    out double chi,
    out int idf,
    out double siglev,
    out int ifail
)
Visual Basic
Public Shared Sub g13as ( _
    n As Integer, _
    v As Double(), _
    mr As Integer(), _
    m As Integer, _
    par As Double(), _
    ishow As Integer, _
    r As Double(), _
    rcm As Double(,), _
    <OutAttribute> ByRef chi As Double, _
    <OutAttribute> ByRef idf As Integer, _
    <OutAttribute> ByRef siglev As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13as(
    int n,
    array<double>^ v,
    array<int>^ mr,
    int m,
    array<double>^ par,
    int ishow,
    array<double>^ r,
    array<double,2>^ rcm,
    [OutAttribute] double% chi,
    [OutAttribute] int% idf,
    [OutAttribute] double% siglev,
    [OutAttribute] int% ifail
)
F#
static member g13as :
        n : int *
        v : float[] *
        mr : int[] *
        m : int *
        par : float[] *
        ishow : int *
        r : float[] *
        rcm : float[,] *
        chi : float byref *
        idf : int byref *
        siglev : float byref *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations in the residual series.
If g13as is used following a call to (G13AEF not in this release), then n must be the value icount[1] returned by (G13AEF not in this release).
If g13as is used following a call to g13af, then n must be the value nres returned by g13af.
Constraint: n≥3.
v
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: v[t-1] must contain an estimate of εt, for t=1,2,…,n.
If g13as is used following a call to (G13AEF not in this release) then the actual argument v must be exr[icount[0]] as returned by (G13AEF not in this release).
If g13as is used following a call to g13af then the actual argument v must be res as returned by g13af.
Constraint: v must contain at least two distinct elements.
mr
Type: array< System..::..Int32 >[]()[][]
An array of size [7]
On entry: the orders vector (p, d, q, P, D, Q, s) as supplied to (G13AEF not in this release) g13af.
Constraints:
  • p,q,P,Q,s≥0;
  • p+q+P+Q>0;
  • if s=0, then P=0 and Q=0.
m
Type: System..::..Int32
On entry: the value of m, the number of residual autocorrelations to be computed. See [Choice of m] for advice on the value of m.
Constraint: _npar<m<n.
par
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: dim1 must satisfy the constraint: _npar=mr[0]+mr[2]+mr[3]+mr[5]
On entry: the parameter estimates in the order ϕ 1,ϕ 2,…,ϕp, θ 1,θ 2,…,θq, Φ 1,Φ 2,…,ΦP, Θ 1,Θ 2,…,ΘQ only.
Constraint: the elements in par must satisfy the stationarity and invertibility conditions.
ishow
Type: System..::..Int32
On entry: must be nonzero if the residual autocorrelations, their standard errors and the portmanteau statistics are to be printed and zero otherwise.
These quantities are available also as output variables in r, rcm, chi, idf and siglev.
r
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: an estimate of the residual autocorrelation coefficient at lag l, for l=1,2,…,m. If ifail=3 on exit then all elements of r are set to zero.
rcm
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥m
On exit: the estimated standard errors and correlations of the elements in the array r. The correlation between r[i-1] and r[j-1] is returned as rcm[i-1,j-1] except that if i=j then rcm[i-1,j-1] contains the standard error of r[i-1]. If on exit, ifail≥5, then all off-diagonal elements of rcm are set to zero and all diagonal elements are set to 1/n.
chi
Type: System..::..Double %
On exit: the value of the portmanteau statistic, Q m. If ifail=3 on exit then chi is returned as zero.
idf
Type: System..::..Int32 %
On exit: the number of degrees of freedom of chi.
siglev
Type: System..::..Double %
On exit: the significance level of chi based on idf degrees of freedom. If ifail=3 on exit, siglev is returned as one.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Consider the univariate multiplicative autoregressive-moving average model
ϕ B Φ BsWt-μ=θ B Θ Bs εt (1)
where Wt, for t=1,2,…,n, denotes a time series and εt, for t=1,2,…,n, is a residual series assumed to be normally distributed with zero mean and variance σ 2 (>0). The εt's are also assumed to be uncorrelated. Here μ is the overall mean term, s is the seasonal period and B is the backward shift operator such that Br Wt=W t-r. The polynomials in (1) are defined as follows:
ϕ B=1-ϕ 1 B-ϕ 2 B 2-⋯-ϕp Bp
is the non-seasonal autoregressive (AR) operator;
θ B=1-θ 1 B-θ 2 B 2-⋯-θq Bq
is the non-seasonal moving average (MA) operator;
Φ Bs=1-Φ 1 Bs-Φ 2 B 2 s-⋯-ΦP B Ps
is the seasonal AR operator; and
Θ Bs=1-Θ 1 Bs-Θ 2 B 2 s-⋯-ΘQ B Qs
is the seasonal MA operator. The model (1) is assumed to be stationary, that is the zeros of ϕ B and Φ Bs are assumed to lie outside the unit circle. The model (1) is also assumed to be invertible, that is the zeros of θ B and Θ Bs are assumed to lie outside the unit circle. When both Φ Bs and Θ Bs are absent from the model, that is when P=Q=0, then the model is said to be non-seasonal.
The estimated residual autocorrelation coefficient at lag l, r^l, is computed as:
r^l=∑t=l+1 n ε^t-l-ε-ε^t-ε-∑t=1 n ε^t-ε-2,  l=1,2,…
where ε^t denotes an estimate of the tth residual, εt, and ε-=∑t=1 n ε^t/n. A portmanteau statistic, Q m, is calculated from the formula (see Box and Ljung (1978)):
Q m=n n+2∑l=1 m r^l 2/n-l
where m denotes the number of residual autocorrelations computed. (Advice on the choice of m is given in [Choice of m].) Under the hypothesis of model adequacy, Q m has an asymptotic χ 2-distribution on m-p-q-P-Q degrees of freedom. Let r^T=r^1,r^2,…,r^m then the variance-covariance matrix of r^ is given by:
Var r^=Im-X XT X-1XT/n.
The construction of the matrix X is discussed in McLeod (1978). (Note that the mean, μ, and the residual variance, σ 2, play no part in calculating Var r^ and therefore are not required as input to g13as.)
Note: for additive models with fixed parameter values (i.e., fitted by g13dd) (G13DSF not in this release) should be used instead of g13as.

References

Box G E P and Ljung G M (1978) On a measure of lack of fit in time series models Biometrika 65 297–303
McLeod A I (1978) On the distribution of the residual autocorrelations in Box–Jenkins models J. Roy. Statist. Soc. Ser. B 40 296–302

Error Indicators and Warnings

Note: g13as may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (NPAR, LDRCM) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | mr[0]<0,
or | mr[2]<0,
or | mr[3]<0,
or | mr[5]<0,
or | mr[6]<0,
or | mr[6]=0 and either mr[3]>0 or mr[5]>0,
or | mr[0]=mr[2]=mr[3]=mr[5]=0,
or | m≥n,
or | n<3,
or | liw is too small,
or | lwork is too small.
ifail=2
On entry, the autoregressive (or moving average) parameters are extremely close to or outside the stationarity (or invertibility) region. To proceed, you must supply different parameter estimates in the array par.
ifail=3
On entry, the residuals are practically identical giving zero (or near zero) variance. In this case chi is set to zero and siglev to one and all the elements of r are set to zero.
ifail=4
This is an unlikely exit brought about by an excessive number of iterations being needed to evaluate the zeros of the AR or MA polynomials. All output parameters are undefined.
ifail=5
On entry, one or more of the AR operators has a factor in common with one or more of the MA operators. To proceed, this common factor must be deleted from the model. In this case, the off-diagonal elements of rcm are returned as zero and the diagonal elements set to 1/n. All other output quantities will be correct.
ifail=6
This is an unlikely exit. At least one of the diagonal elements of rcm was found to be either negative or zero. In this case all off-diagonal elements of rcm are returned as zero and all diagonal elements of rcm set to 1/n.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The computations are believed to be stable.

Parallelism and Performance

None.

Further Comments

Timing

The time taken by g13as depends upon the number of residual autocorrelations to be computed, m.

Choice of m

The number of residual autocorrelations to be computed, m should be chosen to ensure that when the ARMA model (1) is written as either an infinite order autoregressive process:
Wt-μ=∑j=1∞πj W t-j-μ+εt
or as an infinite order moving average process:
Wt-μ=∑j=1∞ψjε t-j+εt
then the two sequences π 1,π 2,… and ψ 1,ψ 2,… are such that πj and ψj are approximately zero for j>m. An overestimate of m is therefore preferable to an under-estimate of m. In many instances the choice m=10 will suffice. In practice, to be on the safe side, you should try setting m=20.

Approximate Standard Errors

When ifail=5 or 6 all the standard errors in rcm are set to 1/n. This is the asymptotic standard error of r^l when all the autoregressive and moving average parameters are assumed to be known rather than estimated.

Alternative Applications

g13as may be used for diagnostic checking of suitable univariate ARMA models, as described in [Description], fitted by g13be or g13dd. Great care must be taken in obtaining the input values for g13as from the output values from g13be or g13dd.

Example

This example fits an ARIMA1,1,2 model to a series of 30 observations. 10 residual autocorrelations are computed.

Example program (C#): g13ase.cs

Example program data: g13ase.d

Example program results: g13ase.r

See Also

G13 Class
G13 Members


g13au Method

[image]

NAG Library for .NET Release 2
G13..::g13au Method
G13 Class See Also Send Feedback
g13au calculates the range (or standard deviation) and the mean for groups of successive time series values. It is intended for use in the construction of range-mean plots.

Syntax

C#
public static void g13au(
    int n,
    double[] z,
    int m,
    int ngrps,
    string rs,
    double[] y,
    double[] mean,
    out int ifail
)
Visual Basic
Public Shared Sub g13au ( _
    n As Integer, _
    z As Double(), _
    m As Integer, _
    ngrps As Integer, _
    rs As String, _
    y As Double(), _
    mean As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13au(
    int n,
    array<double>^ z,
    int m,
    int ngrps,
    String^ rs,
    array<double>^ y,
    array<double>^ mean,
    [OutAttribute] int% ifail
)
F#
static member g13au :
        n : int *
        z : float[] *
        m : int *
        ngrps : int *
        rs : string *
        y : float[] *
        mean : float[] *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of observations in the time series.
Constraint: n≥m.
z
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: z[t-1] must contain the tth observation Zt, for t=1,2,…,n.
m
Type: System..::..Int32
On entry: m, the group size.
Constraint: m≥2.
ngrps
Type: System..::..Int32
On entry: k, the number of groups.
Constraint: ngrps=int n/m.
rs
Type: System..::..String
On entry: indicates whether ranges or standard deviations are to be calculated.
rs="R"
Ranges are calculated.
rs="S"
Standard deviations are calculated.
Constraint: rs="R" or "S".
y
Type: array< System..::..Double >[]()[][]
An array of size [ngrps]
On exit: y[i-1] contains the range or standard deviation, as determined by rs, of the ith group of observations, for i=1,2,…,k.
mean
Type: array< System..::..Double >[]()[][]
An array of size [ngrps]
On exit: mean[i-1] contains the mean of the ith group of observations, for i=1,2,…,k.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Let Z 1,Z 2,…,Zn denote n successive observations in a time series. The series may be divided into groups of m successive values and for each group the range or standard deviation (depending on a user-supplied option) and the mean are calculated. If n is not a multiple of m then groups of equal size m are found starting from the end of the series of observations provided, and any remaining observations at the start of the series are ignored. The number of groups used, k, is the integer part of n/m. If you wish to ensure that no observations are ignored then the number of observations, n, should be chosen so that n is divisible by m.
The mean, Mi, the range, Ri, and the standard deviation, Si, for the ith group are defined as
Mi=1 m∑j=1 m Z l+m i-1+jRi=max 1≤j≤m Z l+m i-1+j-min 1≤j≤m Z l+m i-1+j
and
Si=1 m-1∑j=1 m Z l+m i-1+j-Mi 2
where l=n-km, the number of observations ignored.
For seasonal data it is recommended that m should be equal to the seasonal period. For non-seasonal data the recommended group size is 8.
A plot of range against mean or of standard deviation against mean is useful for finding a transformation of the series which makes the variance constant. If the plot appears random or the range (or standard deviation) seems to be constant irrespective of the mean level then this suggests that no transformation of the time series is called for. On the other hand an approximate linear relationship between range (or standard deviation) and mean would indicate that a log transformation is appropriate. Further details may be found in either Jenkins (1979) or McLeod (1982).
You have the choice of whether to use the range or the standard deviation as a measure of variability. If the group size is small they are both equally good but if the group size is fairly large (e.g., m=12 for monthly data) then the range may not be as good an estimate of variability as the standard deviation.

References

Jenkins G M (1979) Practical Experiences with Modelling and Forecasting Time Series GJP Publications, Lancaster
McLeod G (1982) Box–Jenkins in Practice. 1: Univariate Stochastic and Single Output Transfer Function/Noise Analysis GJP Publications, Lancaster

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | n<m,
or | m<2,
or | ngrps≠ integer part of n/m.
ifail=2
On entry, rs is not equal to "R" or "S".
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The computations are believed to be stable.

Parallelism and Performance

None.

Further Comments

The time taken by g13au is approximately proportional to n.

Example

The following program produces the statistics for a range-mean plot for a series of 100 observations divided into groups of 8.

Example program (C#): g13aue.cs

Example program data: g13aue.d

Example program results: g13aue.r

See Also

G13 Class
G13 Members


g13ba Method

[image]

NAG Library for .NET Release 2
G13..::g13ba Method
G13 Class See Also Send Feedback
g13ba filters a time series by an ARIMA model.

Syntax

C#
public static void g13ba(
    double[] y,
    int ny,
    int[] mr,
    int nmr,
    double[] par,
    double cy,
    double[] b,
    out int ifail
)
Visual Basic
Public Shared Sub g13ba ( _
    y As Double(), _
    ny As Integer, _
    mr As Integer(), _
    nmr As Integer, _
    par As Double(), _
    cy As Double, _
    b As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13ba(
    array<double>^ y,
    int ny,
    array<int>^ mr,
    int nmr,
    array<double>^ par,
    double cy,
    array<double>^ b,
    [OutAttribute] int% ifail
)
F#
static member g13ba :
        y : float[] *
        ny : int *
        mr : int[] *
        nmr : int *
        par : float[] *
        cy : float *
        b : float[] *
        ifail : int byref -> unit

Parameters

y
Type: array< System..::..Double >[]()[][]
An array of size [ny]
On entry: the Qy′ backforecasts, starting with backforecast at time 1-Qy′ to backforecast at time 0, followed by the time series starting at time 1, where Qy′=mr[9]+mr[12]×mr[13]. If there are no backforecasts, either because the ARIMA model for the time series is not known, or because it is known but has no moving average terms, then the time series starts at the beginning of y.
ny
Type: System..::..Int32
On entry: the total number of backforecasts and time series data points in array y.
Constraint: ny≥max 1+Qy′,_npar.
mr
Type: array< System..::..Int32 >[]()[][]
An array of size [nmr]
On entry: the orders vector for the filtering model, followed by the orders vector for the ARIMA model for the time series if the latter is known. The orders appear in the standard sequence p,d,q,P,D,Q,s as given in the G13 class. If the ARIMA model for the time series is supplied, then the method will assume that the first Qy′ values of the array y are backforecasts.
Constraints:
the filtering model is restricted in the following ways:
  • mr[0]+mr[2]+mr[3]+mr[5]>0, i.e., filtering by a model which contains only differencing terms is not permitted;
  • mr[k]≥0, for k=0,1,…,6;
  • if mr[6]=0, mr[3]+mr[4]+mr[5]=0;
  • if mr[6]≠0, mr[3]+mr[4]+mr[5]≠0;
  • mr[6]≠1.
the ARIMA model for the time series is restricted in the following ways:
  • mr[k]≥0, for k=7,8,…,13;
  • if mr[13]=0, mr[10]+mr[11]+mr[12]=0;
  • if mr[13]≠0, mr[10]+mr[11]+mr[12]≠0;
  • mr[13]≠1.
nmr
Type: System..::..Int32
On entry: the number of values specified in the array mr. It takes the value 7 if no ARIMA model for the time series is supplied but otherwise it takes the value 14. Thus nmr acts as an indicator as to whether backforecasting can be carried out.
Constraint: nmr=7 or 14.
par
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: dim1 must satisfy the constraint:
  • if nmr=7, _npar=mr[0]+mr[2]+mr[3]+mr[5];
  • if nmr=14, _npar=mr[0]+mr[2]+mr[3]+mr[5]+mr[7]+mr[9]+mr[10]+mr[12].
Note: the first constraint (i.e., mr[0]+mr[2]+mr[3]+mr[5]>0) on the orders of the filtering model, in parameter mr, ensures that _npar>0.
On entry: the parameters of the filtering model, followed by the parameters of the ARIMA model for the time series, if supplied. Within each model the parameters are in the standard order of non-seasonal AR and MA followed by seasonal AR and MA.
cy
Type: System..::..Double
On entry: if the ARIMA model is known (i.e., nmr=14), cy must specify the constant term of the ARIMA model for the time series. If this model is not known (i.e., nmr=7), then cy is not used.
b
Type: array< System..::..Double >[]()[][]
An array of size [nb]
On exit: the filtered output series. If the ARIMA model for the time series was known, and hence Qy′ backforecasts were supplied in y, then b contains Qy′ ‘filtered’ backforecasts followed by the filtered series. Otherwise, the filtered series begins at the start of b just as the original series began at the start of y. In either case, if the value of the series at time t is held in y[t-1], then the filtered value at time t is held in b[t-1].
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

From a given series y 1,y 2,…,yn, a new series b 1,b 2,…,bn is calculated using a supplied (filtering) ARIMA model. This model will be one which has previously been fitted to a series xt with residuals at. The equations defining bt in terms of yt are very similar to those by which at is obtained from xt. The only dissimilarity is that no constant correction is applied after differencing. This is because the series yt is generally distinct from the series xt with which the model is associated, though yt may be related to xt. Whilst it is appropriate to apply the ARIMA model to yt so as to preserve the same relationship between bt and at as exists between yt and xt, the constant term in the ARIMA model is inappropriate for yt. The consequence is that bt will not necessarily have zero mean.
The equations are precisely:
wt=∇d∇sD yt, (1)
the appropriate differencing of yt; both the seasonal and non-seasonal inverted autoregressive operations are then applied,
ut=wt-Φ 1w t-s-⋯-ΦPw t-s×P (2)
vt=ut-ϕ 1u t-1-⋯-ϕpu t-p (3)
followed by the inverted moving average operations
zt=vt+Θ 1z t-s+⋯+ΘQz t-s×Q (4)
bt=zt+θ 1b t-1+⋯+θqb t-q. (5)
Because the filtered series value bt depends on present and past values yt,y t-1,…, there is a problem arising from ignorance of y 0,y-1,… which particularly affects calculation of the early values b 1,b 2,…, causing ‘transient errors’. The method allows two possibilities.
(i) | The equations (1), (2) and (3) are applied from successively later time points so that all terms on their right-hand sides are known, with vt being defined for t=1+d+s×D+s×P,…,n. Equations (4) and (5) are then applied over the same range, taking any values on the right-hand side associated with previous time points to be zero. This procedure may still however result in unacceptably large transient errors in early values of bt.
(ii) | The unknown values y 0,y-1,… are estimated by backforecasting. This requires that an ARIMA model distinct from that which has been supplied for filtering, should have been previously fitted to yt.
For efficiency, you are asked to supply both this ARIMA model for yt and a limited number of backforecasts which are prefixed to the known values of yt. Within the method further backforecasts of yt, and the series wt, ut, vt in (1), (2) and (3) are then easily calculated, and a set of linear equations solved for backforecasts of zt,bt for use in (4) and (5) in the case that q+Q>0.
Even if the best model for yt is not available, a very approximate guess such as
yt=c+et
or
∇yt=et
can help to reduce the transients substantially.
The backforecasts which need to be prefixed to yt are of length Qy′=qy+sy×Qy, where qy and Qy are the non-seasonal and seasonal moving average orders and sy the seasonal period for the ARIMA model of yt. Thus you need not carry out the backforecasting exercise if Qy′=0. Otherwise, the series y 1,y 2,…,yn should be reversed to obtain yn,y n-1,…,y 1 and g13aj should be used to forecast Qy′ values, y^0,…,y^1-Qy′. The ARIMA model used is that fitted to yt (as a forward series) except that, if dy+Dy is odd, the constant should be changed in sign (to allow, for example, for the fact that a forward upward trend is a reversed downward trend). The ARIMA model for yt supplied to the filtering method must however have the appropriate constant for the forward series.
The series y^1-Qy′,…,y^0,y 1,…,yn is then supplied to the method, and a corresponding set of values returned for bt.

References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (NPAR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, nmr≠7 and nmr≠14.
ifail=2
On entry, the orders vector mr does not satisfy the constraints given in [Parameters].
ifail=4
On entry, ny is too small to successfully carry out the requested filtering, (see [Parameters]).
ifail=5
On entry, the work array wa is too small.
ifail=6
On entry, the array b is too small.
ifail=7
The orders vector for the filtering model is invalid.
ifail=8
The orders vector for the ARIMA model is invalid. (Only occurs if nmr=14.)
ifail=9
The initial values of the filtered series are indeterminate for the given models.
ifail=-999
Internal memory allocation failed.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Accuracy and stability are high except when the MA parameters are close to the invertibility boundary.

Parallelism and Performance

None.

Further Comments

If an ARIMA model is supplied, a local workspace array of fixed length is allocated internally by g13ba. The total size of this array amounts to K integer elements, where K is the expression defined in the description of the parameter wa.
The time taken by g13ba is approximately proportional to
ny×mr[0]+mr[2]+mr[3]+mr[5],
with an appreciable fixed increase if an ARIMA model is supplied for the time series.

Example

This example reads a time series of length 296. It reads the univariate ARIMA 4,0,2,0,0,0,0 model and the ARIMA filtering 3,0,0,0,0,0,0 model for the series. Two initial backforecasts are required and these are calculated by a call to g13aj . The backforecasts are inserted at the start of the series and g13ba is called to perform the calculations.

Example program (C#): g13bae.cs

Example program data: g13bae.d

Example program results: g13bae.r

See Also

G13 Class
G13 Members


g13bb Method

[image]

NAG Library for .NET Release 2
G13..::g13bb Method
G13 Class See Also Send Feedback
g13bb filters a time series by a transfer function model.

Syntax

C#
public static void g13bb(
    double[] y,
    int ny,
    int[] mr,
    int nmr,
    double[] par,
    double cy,
    double[] b,
    out int ifail
)
Visual Basic
Public Shared Sub g13bb ( _
    y As Double(), _
    ny As Integer, _
    mr As Integer(), _
    nmr As Integer, _
    par As Double(), _
    cy As Double, _
    b As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13bb(
    array<double>^ y,
    int ny,
    array<int>^ mr,
    int nmr,
    array<double>^ par,
    double cy,
    array<double>^ b,
    [OutAttribute] int% ifail
)
F#
static member g13bb :
        y : float[] *
        ny : int *
        mr : int[] *
        nmr : int *
        par : float[] *
        cy : float *
        b : float[] *
        ifail : int byref -> unit

Parameters

y
Type: array< System..::..Double >[]()[][]
An array of size [ny]
On entry: the Qy′ backforecasts starting with backforecast at time 1-Qy′ to backforecast at time 0 followed by the time series starting at time 1, where Qy′=mr[5]+mr[8]×mr[9]. If there are no backforecasts either because the ARIMA model for the time series is not known or because it is known but has no moving average terms, then the time series starts at the beginning of y.
ny
Type: System..::..Int32
On entry: the total number of backforecasts and time series data points in array y.
Constraint: ny≥max 1+Qy′,_npar.
mr
Type: array< System..::..Int32 >[]()[][]
An array of size [nmr]
On entry: the orders vector for the filtering transfer function model followed by the orders vector for the ARIMA model for the time series if the latter is known. The transfer function model orders appear in the standard form b,q,p as given in the G13 class. Note that if the ARIMA model for the time series is supplied then the method will assume that the first Qy′ values of the array y are backforecasts.
Constraints:
the filtering model is restricted in the following way:
  • mr[0], ​mr[1], ​mr[2]≥0.
the ARIMA model for the time series is restricted in the following ways:
  • mr[k]≥0, for k=3,4,…,9;
  • if mr[9]=0, mr[6]+mr[7]+mr[8]=0;
  • if mr[9]≠0, mr[6]+mr[7]+mr[8]≠0;
  • mr[9]≠1.
nmr
Type: System..::..Int32
On entry: the number of values supplied in the array mr. It takes the value 3 if no ARIMA model for the time series is supplied but otherwise it takes the value 10. Thus nmr acts as an indicator as to whether backforecasting can be carried out.
Constraint: nmr=3 or 10.
par
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: dim1 must satisfy the constraint:
  • if nmr=3, _npar=_transfv.nag_q+_transfv.nag_p+1;
  • if nmr=10, _npar=_transfv.nag_q+_transfv.nag_p+1+_arimas.p+_arimas.q+_arimas.bigp+_arimas.bigq.
  • if nmr=3, _npar=mr[1]+mr[2]+1;
  • if nmr=10, _npar=mr[1]+mr[2]+1+mr[3]+mr[5]+mr[6]+mr[8].
On entry: the parameters of the filtering transfer function model followed by the parameters of the ARIMA model for the time series. In the transfer function model the parameters are in the standard order of MA-like followed by AR-like operator parameters. In the ARIMA model the parameters are in the standard order of non-seasonal AR and MA followed by seasonal AR and MA.
cy
Type: System..::..Double
On entry: if the ARIMA model is known (i.e., nmr=10), cy must specify the constant term of the ARIMA model for the time series. If this model is not known (i.e., nmr=3) then cy is not used.
b
Type: array< System..::..Double >[]()[][]
An array of size [nb]
On exit: the filtered output series. If the ARIMA model for the time series was known, and hence Qy′ backforecasts were supplied in y, then b contains Qy′ ‘filtered’ backforecasts followed by the filtered series. Otherwise, the filtered series begins at the start of b just as the original series began at the start of y. In either case, if the value of the series at time t is held in y[t-1], then the filtered value at time t is held in b[t-1].
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

From a given series y 1,y 2,…,yn a new series b 1,b 2,…,bn is calculated using a supplied (filtering) transfer function model according to the equation
bt=δ 1b t-1+δ 2b t-2+⋯+δpb t-p+ω 0y t-b-ω 1y t-b-1-⋯-ωqy t-b-q. (1)
As in the use of g13ba, large transient errors may arise in the early values of bt due to ignorance of yt for t<0, and two possibilities are allowed.
(i) | The equation (1) is applied from t=1+b+q,…,n so all terms in yt on the right-hand side of (1) are known, the unknown set of values bt for t=b+q,…,b+q+1-p being taken as zero.
(ii) | The unknown values of yt for t≤0 are estimated by backforecasting exactly as for g13ba.

References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (NPAR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | nmr≠3 and nmr≠10,
or | mr[i-1]<0, for i=1,2,…,nmr,
or | nmr=10 and mr[9]=1,
or | nmr=10 and mr[9]=0 and mr[6]+mr[7]+mr[8]≠0,
or | nmr=10 and mr[9]≠0, and mr[6]+mr[7]+mr[8]=0,
or | wa is too small,
or | b is too small.
ifail=2
A supplied model has parameter values which have failed the validity test.
ifail=3
The supplied time series is too short to carry out the requested filtering successfully.
ifail=4
This only occurs when an ARIMA model for the time series has been supplied. The matrix which is used to solve for the starting values for MA filtering is singular.
ifail=-999
Internal memory allocation failed.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Accuracy and stability are high except when the AR-like parameters are close to the invertibility boundary. All calculations are performed in basic precision except for one inner product type calculation which on machines of low precision is performed in additional precision.

Parallelism and Performance

None.

Further Comments

The time taken by g13bb is roughly proportional to the product of the length of the series and number of parameters in the filtering model with appreciable increase if an ARIMA model is supplied for the time series.

Example

This example reads a time series of length 296. It reads one univariate ARIMA 1,1,0,0,1,1,12 model for the series and the 0,13,12 filtering transfer function model. 12 initial backforecasts are required and these are calculated by a call to g13aj . The backforecasts are inserted at the start of the series and g13bb is called to perform the filtering.

Example program (C#): g13bbe.cs

Example program data: g13bbe.d

Example program results: g13bbe.r

See Also

G13 Class
G13 Members


g13bc Method

[image]

NAG Library for .NET Release 2
G13..::g13bc Method
G13 Class See Also Send Feedback
g13bc calculates cross-correlations between two time series.

Syntax

C#
public static void g13bc(
    double[] x,
    double[] y,
    int nxy,
    int nl,
    out double s,
    out double r0,
    double[] r,
    out double stat,
    out int ifail
)
Visual Basic
Public Shared Sub g13bc ( _
    x As Double(), _
    y As Double(), _
    nxy As Integer, _
    nl As Integer, _
    <OutAttribute> ByRef s As Double, _
    <OutAttribute> ByRef r0 As Double, _
    r As Double(), _
    <OutAttribute> ByRef stat As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13bc(
    array<double>^ x,
    array<double>^ y,
    int nxy,
    int nl,
    [OutAttribute] double% s,
    [OutAttribute] double% r0,
    array<double>^ r,
    [OutAttribute] double% stat,
    [OutAttribute] int% ifail
)
F#
static member g13bc :
        x : float[] *
        y : float[] *
        nxy : int *
        nl : int *
        s : float byref *
        r0 : float byref *
        r : float[] *
        stat : float byref *
        ifail : int byref -> unit

Parameters

x
Type: array< System..::..Double >[]()[][]
An array of size [nxy]
On entry: the n values of the x series.
y
Type: array< System..::..Double >[]()[][]
An array of size [nxy]
On entry: the n values of the y series.
nxy
Type: System..::..Int32
On entry: n, the length of the time series.
Constraint: nxy≥2.
nl
Type: System..::..Int32
On entry: L, the maximum lag for calculating cross-correlations.
Constraint: 1≤nl<nxy.
s
Type: System..::..Double %
On exit: the ratio of the standard deviation of the y series to the standard deviation of the x series, sy/sx.
r0
Type: System..::..Double %
On exit: the cross-correlation between the x and y series at lag zero.
r
Type: array< System..::..Double >[]()[][]
An array of size [nl]
On exit: r[l-1] contains the cross-correlations between the x and y series at lags L, r xy l, for l=1,2,…,L.
stat
Type: System..::..Double %
On exit: the statistic for testing for absence of cross-correlation.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Given two series x 1,x 2,…,xn and y 1,y 2,…,yn the method calculates the cross-correlations between xt and lagged values of yt:
r xy l=∑t=1n-l xt-x-y t+l-y-n sxsy,  l=0,1,…,L
where
x-=∑t=1 n xt n
sx 2=∑t=1 n xt-x-2 n
and similarly for y.
The ratio of standard deviations sy/sx is also returned, and a portmanteau statistic is calculated:
stat=n∑l=1 L r xy l 2.
Provided n is large, L much less than n, and both xt,yt are samples of series whose true autocorrelation functions are zero, then, under the null hypothesis that the true cross-correlations between the series are zero, stat has a χ 2-distribution with L degrees of freedom. Values of stat in the upper tail of this distribution provide evidence against the null hypothesis.

References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | nxy≤1,
or | nl<1,
or | nl≥nxy.
ifail=2
One or both of the x and y series have zero variance and hence cross-correlations cannot be calculated.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

All computations are believed to be stable.

Parallelism and Performance

None.

Further Comments

If n<100, or L<10 log n then the autocorrelations are calculated directly and the time taken by g13bc is approximately proportional to nL, otherwise the autocorrelations are calculated by utilizing fast Fourier transforms (FFTs) and the time taken is approximately proportional to n log n. If FFTs are used then g13bc internally allocates approximately 6 n real elements.

Example

This example reads two time series of length 20. It calculates and prints the cross-correlations up to lag 15 for the first series leading the second series and then for the second series leading the first series.

Example program (C#): g13bce.cs

Example program data: g13bce.d

Example program results: g13bce.r

See Also

G13 Class
G13 Members


g13bd Method

[image]

NAG Library for .NET Release 2
G13..::g13bd Method
G13 Class See Also Send Feedback
g13bd calculates preliminary estimates of the parameters of a transfer function model.

Syntax

C#
public static void g13bd(
    double r0,
    double[] r,
    int nl,
    int[] nna,
    double s,
    int nwds,
    double[] wds,
    int[] isf,
    out int ifail
)
Visual Basic
Public Shared Sub g13bd ( _
    r0 As Double, _
    r As Double(), _
    nl As Integer, _
    nna As Integer(), _
    s As Double, _
    nwds As Integer, _
    wds As Double(), _
    isf As Integer(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13bd(
    double r0,
    array<double>^ r,
    int nl,
    array<int>^ nna,
    double s,
    int nwds,
    array<double>^ wds,
    array<int>^ isf,
    [OutAttribute] int% ifail
)
F#
static member g13bd :
        r0 : float *
        r : float[] *
        nl : int *
        nna : int[] *
        s : float *
        nwds : int *
        wds : float[] *
        isf : int[] *
        ifail : int byref -> unit

Parameters

r0
Type: System..::..Double
On entry: the cross-correlation between the two series at lag 0, r xy 0.
Constraint: -1.0≤r0≤1.0.
r
Type: array< System..::..Double >[]()[][]
An array of size [nl]
On entry: the cross-correlations between the two series at lags 1 to L, r xy l, for l=1,2,…,L.
Constraint: -1.0≤r[i]≤1.0, for i=0,1,…,nl-1.
nl
Type: System..::..Int32
On entry: L, the number of lagged cross-correlations in the array r.
Constraint: nl≥max nna[0]+nna[1]+nna[2],1.
nna
Type: array< System..::..Int32 >[]()[][]
An array of size [3]
On entry: the transfer function model orders in the standard form b,q,p (i.e., delay time, number of moving-average MA-like followed by number of autoregressive AR-like parameters).
Constraint: nna[i-1]≥0, for i=1,2,3.
s
Type: System..::..Double
On entry: the ratio of the standard deviation of the y series to that of the x series, sy/sx.
Constraint: s>0.0.
nwds
Type: System..::..Int32
On entry: the exact number of parameters in the transfer function model.
Constraint: nwds=nna[1]+nna[2]+1.
wds
Type: array< System..::..Double >[]()[][]
An array of size [nwds]
On exit: the preliminary estimates of the parameters of the transfer function model in the order of q+1 MA-like parameters followed by the p AR-like parameters. If the estimation of either type of parameter fails then these parameters are set to 0.0.
isf
Type: array< System..::..Int32 >[]()[][]
An array of size [2]
On exit: indicators of the success of the estimation of MA-like and AR-like parameters respectively. A value 0 indicates that there are no parameters of that type to be estimated. A value of 1 or -1 indicates that there are parameters of that type in the model and the estimation of that type has been successful or unsuccessful respectively. Note that there is always at least one MA-like parameter in the model.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g13bd calculates estimates of parameters δ 1,δ 2,…,δp, ω 0,ω 1,…,ωq in the transfer function model
yt=δ 1y t-1+δ 2y t-2+⋯+δpy t-p+ω 0x t-b-ω 1x t-b-1-⋯-ωqx t-b-q
given cross-correlations between the series xt and lagged values of yt:
r xy l,  l=0,1,…,L
and the ratio of standard deviations sy/sx, as supplied by g13bc.
It is assumed that the series xt used to calculate the cross-correlations is a sample from a time series with true autocorrelations of zero. Otherwise the cross-correlations between the series bt and at, as defined in the description of g13ba, should be used in place of those between yt and xt.
The estimates are obtained by solving for δ 1,δ 2,…,δp the equations
r xy b+q+j=δ 1r xy b+q+j-1+⋯+δpr xy b+q+j-p,  j=1,2,…,p
then calculating
ωi=±sy/sxr xy b+i-δ 1r xy b+i-1-⋯-δpr xy b+i-p,  i=0,1,…,q
where the ‘+’ is used for ω 0 and ‘-’ for ωi, i>0.
Any value of r xy l arising in these equations for l<b is taken as zero. The parameters δ 1,δ 2,…,δp are checked as to whether they satisfy the stability criterion.

References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | nna[i-1]<0, for i=1,2,3,
or | nl<max nna[0]+nna[1]+nna[2],1,
or | r0<-1.0 or r0>1.0,
or | r[i-1]<-1.0 or r[i-1]>1.0, for some i=1,2,…,nl,
or | s≤0.0,
or | nwds≠nna[1]+nna[2]+1,
or | iwa<nna[2]×nna[2]+1.
ifail=-999
Internal memory allocation failed.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Equations used in the computations may become unstable, in which case results are reset to zero with array isf values set accordingly.

Parallelism and Performance

None.

Further Comments

If nna[2]>0,a local workspace array of fixed length is allocated internally by g13bd. The total size of this array amounts to nna[2] integer elements and nna[2]×nna[2]+1 real elements.
The time taken by g13bd is roughly proportional to nwds 3.

Example

This example reads the cross-correlations between two series at lags 0 to 6. It then reads a 3,2,1 transfer function model and calculates and prints the preliminary estimates of the parameters of the model.

Example program (C#): g13bde.cs

Example program data: g13bde.d

Example program results: g13bde.r

See Also

G13 Class
G13 Members


g13be Method

[image]

NAG Library for .NET Release 2
G13..::g13be Method
G13 Class See Also Send Feedback
g13be fits a multi-input model relating one output series to the input series with a choice of three different estimation criteria: nonlinear least squares, exact likelihood and marginal likelihood. When no input series are present, g13be fits a univariate ARIMA model.

Syntax

C#
public static void g13be(
    int[] mr,
    int nser,
    int[,] mt,
    double[] para,
    int npara,
    int kfc,
    int nxxy,
    double[,] xxy,
    int kef,
    int nit,
    int kzsp,
    double[] zsp,
    out int itc,
    double[] sd,
    double[,] cm,
    out double s,
    out double d,
    out int ndf,
    int kzef,
    double[] res,
    double[] sttf,
    out int nsttf,
    int kpriv,
    out int ifail
)
Visual Basic
Public Shared Sub g13be ( _
    mr As Integer(), _
    nser As Integer, _
    mt As Integer(,), _
    para As Double(), _
    npara As Integer, _
    kfc As Integer, _
    nxxy As Integer, _
    xxy As Double(,), _
    kef As Integer, _
    nit As Integer, _
    kzsp As Integer, _
    zsp As Double(), _
    <OutAttribute> ByRef itc As Integer, _
    sd As Double(), _
    cm As Double(,), _
    <OutAttribute> ByRef s As Double, _
    <OutAttribute> ByRef d As Double, _
    <OutAttribute> ByRef ndf As Integer, _
    kzef As Integer, _
    res As Double(), _
    sttf As Double(), _
    <OutAttribute> ByRef nsttf As Integer, _
    kpriv As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13be(
    array<int>^ mr,
    int nser,
    array<int,2>^ mt,
    array<double>^ para,
    int npara,
    int kfc,
    int nxxy,
    array<double,2>^ xxy,
    int kef,
    int nit,
    int kzsp,
    array<double>^ zsp,
    [OutAttribute] int% itc,
    array<double>^ sd,
    array<double,2>^ cm,
    [OutAttribute] double% s,
    [OutAttribute] double% d,
    [OutAttribute] int% ndf,
    int kzef,
    array<double>^ res,
    array<double>^ sttf,
    [OutAttribute] int% nsttf,
    int kpriv,
    [OutAttribute] int% ifail
)
F#
static member g13be :
        mr : int[] *
        nser : int *
        mt : int[,] *
        para : float[] *
        npara : int *
        kfc : int *
        nxxy : int *
        xxy : float[,] *
        kef : int *
        nit : int *
        kzsp : int *
        zsp : float[] *
        itc : int byref *
        sd : float[] *
        cm : float[,] *
        s : float byref *
        d : float byref *
        ndf : int byref *
        kzef : int *
        res : float[] *
        sttf : float[] *
        nsttf : int byref *
        kpriv : int *
        ifail : int byref -> unit

Parameters

mr
Type: array< System..::..Int32 >[]()[][]
An array of size [7]
On entry: the orders vector p,d,q,P,D,Q,s of the ARIMA model for the output noise component.
p, q, P and Q refer respectively to the number of autoregressive ϕ, moving average θ, seasonal autoregressive Φ and seasonal moving average Θ parameters.
d, D and s refer respectively to the order of non-seasonal differencing, the order of seasonal differencing and the seasonal period.
Constraints:
  • p, d, q, P, D, Q, s≥0;
  • p+q+P+Q>0;
  • s≠1;
  • if s=0, P+D+Q=0;
  • if s>1, P+D+Q>0;
  • d+s×P+D≤n;
  • p+d-q+s×P+D-Q≤n.
nser
Type: System..::..Int32
On entry: the total number of input and output series. There may be any number of input series (including none), but always one output series.
Constraints:
  • nser≥1;
  • if there are no parameters in the model (that is, p=q=P=Q=0 and kfc=0), nser>1.
mt
Type: array< System..::..Int32 ,2>[,](,)[,][,]
An array of size [4, nser]
On entry: the transfer function model orders b, p and q of each of the input series. The order parameters for input series i are held in column i. Row 1 holds the value bi, row 2 holds the value qi and row 3 holds the value pi. For a simple input, bi=qi=pi=0.
Row 4 holds the value ri, where ri=1 for a simple input, ri=2 for a transfer function input for which no allowance is to be made for pre-observation period effects, and ri=3 for a transfer function input for which pre-observation period effects will be treated by estimation of appropriate nuisance parameters.
When ri=1, any nonzero contents of rows 1, 2, and 3 of column i are ignored.
Constraint: mt[3,i-1]=1, ​2​ or ​3, for i=1,2,…,nser-1.
para
Type: array< System..::..Double >[]()[][]
An array of size [npara]
On entry: initial values of the multi-input model parameters. These are in order, firstly the ARIMA model parameters: p values of ϕ parameters, q values of θ parameters, P values of Φ parameters and Q values of Θ parameters. These are followed by initial values of the transfer function model parameters ω 0,ω 1,…,ω q 1, δ 1,δ 2,…,δ p 1 for the first of any input series and similarly for each subsequent input series. The final component of para is the initial value of the constant c, whether it is fixed or is to be estimated.
On exit: the latest values of the estimates of these parameters.
npara
Type: System..::..Int32
On entry: the exact number of ϕ,θ,Φ,Θ, ω,δ and c parameters.
Constraint: npara=p+q+P+Q+nser+∑pi+qi, the summation being over all the pi≠qi supplied in mt. c must be included, whether fixed or estimated.
kfc
Type: System..::..Int32
On entry: must be set to 0 if the constant c is to remain fixed at its initial value, and 1 if it is to be estimated.
Constraint: kfc=0 or 1.
nxxy
Type: System..::..Int32
On entry: the (common) length of the original, undifferenced input and output time series.
xxy
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nser]
Note: dim1 must satisfy the constraint: dim1≥nxxy
On entry: the columns of xxy must contain the nxxy original, undifferenced values of each of the input series and the output series xt in that order.
On exit: if kzef=0, xxy remains unchanged on exit.
If kzef≠0, the columns of xxy hold the corresponding values of the input component series zt in place of xt and the output noise component nt in place of yt, in that order.
kef
Type: System..::..Int32
On entry: indicates the likelihood option.
kef=1
Gives least squares.
kef=2
Gives exact likelihood.
kef=3
Gives marginal likelihood.
Constraint: kef=1, 2 or 3.
nit
Type: System..::..Int32
On entry: the maximum required number of iterations.
nit=0
No change is made to any of the model parameters in array para except that the constant c (if kfc=1) and any ω relating to simple input series are estimated. (Apart from these, estimates are always derived for the nuisance parameters relating to any backforecasts and any pre-observation period effects for transfer function inputs.)
Constraint: nit≥0.
kzsp
Type: System..::..Int32
On entry: must be set to 1 if the method is to use the input values of zsp in the minimization procedure, and to any other value if the default values of zsp are to be used.
zsp
Type: array< System..::..Double >[]()[][]
An array of size [4]
On entry: if kzsp=1, then zsp must contain the four values used to control the strategy of the search procedure.
zsp[0]
Contains α, the value used to constrain the magnitude of the search procedure steps.
zsp[1]
Contains β, the multiplier which regulates the value of α.
zsp[2]
Contains δ, the value of the stationarity and invertibility test tolerance factor.
zsp[3]
Contains γ, the value of the convergence criterion.
If kzsp≠1 before entry, default values of zsp are supplied by the method. These are 0.01, 10.0, 1000.0 and max 100×machine precision,0.0000001, respectively.
On exit: contains the values, default or otherwise, used by the method.
Constraint: if kzsp=1, zsp[0]>0.0, zsp[1]>1.0, zsp[2]≥1.0, 0≤zsp[3]<1.0.
itc
Type: System..::..Int32 %
On exit: the number of iterations carried out.
itc=-1
Indicates that the only estimates obtained up to this point have been for the nuisance parameters relating to backforecasts, unless the marginal likelihood option is used, in which case estimates have also been obtained for simple input coefficients ω and for the constant c (if kfc=1). This value of itc usually indicates a failure in a consequent step of estimating transfer function input pre-observation period nuisance parameters.
itc=0
Indicates that estimates have been obtained up to this point for the constant c (if kfc=1), for simple input coefficients ω and for the nuisance parameters relating to the backforecasts and to transfer function input pre-observation period effects.
sd
Type: array< System..::..Double >[]()[][]
An array of size [npara]
On exit: the npara values of the standard deviations corresponding to each of the parameters in para. When the constant is fixed its standard deviation is returned as zero. When the values of para are valid, the values of sd are usually also valid. However, if an exit value of ifail=3, 8 or 10, then the contents of sd will be indeterminate.
cm
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, npara]
Note: dim1 must satisfy the constraint: dim1≥npara
On exit: the first npara rows and columns of cm contain the correlation coefficients relating to each pair of parameters in para. All coefficients relating to the constant will be zero if the constant is fixed. The contents of cm will be indeterminate under the same conditions as sd.
s
Type: System..::..Double %
On exit: the residual sum of squares, S, at the latest set of valid parameter estimates.
d
Type: System..::..Double %
On exit: the objective function, D, at the latest set of valid parameter estimates.
ndf
Type: System..::..Int32 %
On exit: the number of degrees of freedom associated with S.
kzef
Type: System..::..Int32
On entry: must not be set to 0, if the values of the input component series zt and the values of the output noise component nt are to overwrite the contents of xxy on exit, and must be set to 0 if xxy is to remain unchanged.
res
Type: array< System..::..Double >[]()[][]
An array of size [nxxy]
On exit: the values of the residuals relating to the differenced values of the output series. The remainder of the first nxxy terms in the array will be zero.
sttf
Type: array< System..::..Double >[]()[][]
An array of size [isttf]
On exit: the nsttf values of the state set array.
nsttf
Type: System..::..Int32 %
On exit: the number of values in the state set array sttf.
kpriv
Type: System..::..Int32
On entry: must not be set to 0, if it is required to monitor the course of the optimization or to print out the requisite minimum values of iwa or imwa in the event of an error of the type ifail=6 or 7. The course of the optimization is monitored by printing out at each iteration the iteration count (itc), the residual sum of squares (s), the objective function (d) and a description and value for each of the parameters in the para array. The descriptions are PHI for ϕ, THETA for θ, SPHI for Φ, STHETA for Θ, OMEGA/SI for ω in a simple input, OMEGA for ω in a transfer function input, DELTA for δ and CONSTANT for c. In addition SERIES 1, SERIES 2, etc. indicate the input series relevant to the OMEGA and DELTA parameters.
kpriv must be set to 0 if the print-out of the above information is not required.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The Multi-input Model

The output series yt, for t=1,2,…,n, is assumed to be the sum of (unobserved) components z i,t which are due respectively to the inputs x i,t, for i=1,2,…,m.
Thus yt=z 1,t+⋯+z m,t+nt where nt is the error, or output noise component.
A typical component zt may be either
(a) a simple regression component, zt=ω xt (here xt is called a simple input), or
(b) a transfer function model component which allows for the effect of lagged values of the variable, related to xt by
zt=δ 1z t-1+δ 2z t-2+⋯+δpz t-p+ω 0x t-b-ω 1x t-b-1-⋯-ωqx t-b-q.
The noise nt is assumed to follow a (possibly seasonal) ARIMA model, i.e., may be represented in terms of an uncorrelated series, at, by the hierarchy of equations
(i) | ∇d∇sD nt=c+wt
(ii) | wt=Φ 1w t-s+Φ 2w t-2×s+⋯+ΦPw t-P×s+et-Θ 1e t-s-Θ 2e t-2×s-⋯-ΘQe t-Q×s
(iii) | et=ϕ 1e t-1+ϕ 2e t-2+⋯+ϕpe t-p+at-θ 1a t-1-θ 2a t-2-⋯-θqa t-q
as outlined in [Description] in g13ae.
Note: the orders p,q appearing in each of the transfer function models and the ARIMA model are not necessarily the same; ∇d∇sD nt is the result of applying non-seasonal differencing of order d and seasonal differencing of seasonality s and order D to the series nt: the differenced series is then of length N=n-d-s×D; the constant term parameter c may optionally be held fixed at its initial value (usually, but not necessarily zero) rather than being estimated.
For the purpose of defining an estimation criterion it is assumed that the series at is a sequence of independent Normal variates having mean 0 and variance σa 2. An allowance has to be made for the effects of unobserved data prior to the observation period. For the noise component an allowance is always made using a form of backforecasting.
For each transfer function input, you have to decide what values are to be assumed for the pre-period terms z 0,z-1,…,z 1-p and x 0,x-1,…,x 1-b-q which are in theory necessary to re-create the component series z 1,z 2,…,zn, during the estimation procedure.
The first choice is to assume that all these values are zero. In this case, in order to avoid undesirable transient distortion of the early values z 1,z 2,…, you are advised first to correct the input series xt by subtracting from all the terms a suitable constant to make the early values x 1,x 2,…, close to zero. The series mean x- is one possibility, but for a series with strong trend the constant might be simply x 1.
The second choice is to treat the unknown pre-period terms as nuisance parameters and estimate them along with the other parameters. This choice should be used with caution. For example, if p=1 and b=q=0, it is equivalent to fitting to the data a decaying geometric curve of the form A δt, for t=1,2,…, along with the other inputs, this being the form of the transient. If the output yt contains a strong trend of this form, which is not otherwise represented in the model, it will have a tendency to influence the estimate of δ away from the value appropriate to the transfer function model.
In most applications the first choice should be adequate, with the option possibly being used as a refinement at the end of the modelling process. The number of nuisance parameters is then max p,b+q, with a corresponding loss of degrees of freedom in the residuals. If you align the input xt with the output by using in its place the shifted series x t-b, then setting b=0 in the transfer function model, there is some improvement in efficiency. On some occasions when the model contains two or more inputs, each with estimation of pre-period nuisance parameters, these parameters may be co-linear and lead to failure of the method. The option must then be ‘switched off’ for one or more inputs.

The Estimation Criterion

This is a measure of how well a proposed set of parameters in the transfer function and noise ARIMA models matches the data. The estimation method searches for parameter values which minimize this criterion. For a proposed set of parameter values it is derived by calculating
(i) | the components z 1,t,z 2,t,…,z m,t as the responses to the input series x 1,t,x 2,t…,x m,t using the equations (a) or (b) above,
(ii) the discrepancy between the output and the sum of these components, as the noise
nt=yt-z 1,t+z 2,t+⋯+z m,t,
(iii) | the residual series at from nt by reversing the recursive equations (i), (ii) and (iii) above.
This last step again requires treatment of the effect of unknown pre-period values of nt and other terms in the equations regenerating at. This is identical to the treatment given in [Description] in g13ae, and leads to a criterion which is a sum of squares function S, of the residuals at. It may be shown that the finite algorithm presented there is equivalent to taking the infinite set of past values n 0,n-1,n-2,…, as (linear) nuisance parameters. There is no loss of degrees of freedom however, because the sum of squares function S may be expressed as including the corresponding set of past residuals; see page 273 of Box and Jenkins (1976), who prove that
S=∑-∞n at 2.
The function D=S is the first of the three possible criteria, and is quite adequate for moderate to long series with no seasonal parameters. The second is the exact likelihood criterion which considers the past set n 0,n-1,n-2 not as simple nuisance parameters, but as unobserved random variables with known distribution. Calculation of the likelihood of the observed set n 1,n 2,…,nn requires theoretical integration over the range of the past set. Fortunately this yields a criterion of the form D=M×S (whose minimization is equivalent to maximizing the exact likelihood of the data), where S is exactly as before, and the multiplier M is a function calculated from the ARIMA model parameters. The value of M is always ≥1, and M tends to 1 for any fixed parameter set as the sample size n tends to ∞. There is a moderate computational overhead in using this option, but its use avoids appreciable bias in the ARIMA model parameters and yields a better conditioned estimation problem.
The third criterion of marginal likelihood treats the coefficients of the simple inputs in a manner analogous to that given to the past set n 0,n-1,n-2,…. These coefficients, together with the constant term c used to represent the mean of wt, are in effect treated as random variables with highly dispersed distributions. This leads to the criterion D=M×S again, but with a different value of M which now depends on the simple input series values xt. In the presence of a moderate to large number of simple inputs, the marginal likelihood criterion can counteract bias in the ARIMA model parameters which is caused by estimation of the simple inputs. This is particularly important in relatively short series.
g13be can be used with no input series present, to estimate a univariate ARIMA model for the output alone. The marginal likelihood criterion is then distinct from exact likelihood only if a constant term is being estimated in the model, because this is treated as an implicit simple input.

The Estimation Procedure

This is the minimization of the estimation criterion or objective function D (for deviance). The method uses an extension of the algorithm of Marquardt (1963). The step size in the minimization is inversely related to a parameter α, which is increased or decreased by a factor β at successive iterations, depending on the progress of the minimization. Convergence is deemed to have occurred if the fractional reduction of D in successive iterations is less than a value γ, while α<1.
Certain model parameters (in fact all excluding the ωs) are subject to stability constraints which are checked throughout to within a specified tolerance multiple δ of machine accuracy. Using the least squares criterion, the minimization may halt prematurely when some parameters ‘stick’ at a constraint boundary. This can happen particularly with short seasonal series (with a small number of whole seasons). It will not happen using the exact likelihood criterion, although convergence to a point on the boundary may sometimes be rather slow, because the criterion function may be very flat in such a region. There is also a smaller risk of a premature halt at a constraint boundary when marginal likelihood is used.
A positive, or zero number of iterations can be specified. In either case, the value D of the objective function at iteration zero is presented at the initial parameter values, except for estimation of any pre-period terms for the input series, backforecasts for the noise series, and the coefficients of any simple inputs, and the constant term (unless this is held fixed).
At any later iteration, the value of D is computed after re-estimation of the backforecasts to their optimal values, corresponding to the model parameters presented at that iteration. This is not true for any pre-period terms for the input series which, although they are updated from the previous iteration, may not be precisely optimal for the parameter values presented, unless convergence of those parameters has occurred. However, in the case of marginal likelihood being specified, the coefficients of the simple inputs and the constant term are also re-estimated together with the backforecasts at each iteration, to values which are optimal for the other parameter values presented.

Further Results

The residual variance is taken as erv=S df, where df=N-(total number of parameters estimated), is the residual degrees of freedom. The pre-period nuisance parameters for the input series are included in the reduction of df, as is the constant if it is estimated.
The covariance matrix of the vector of model parameter estimates is given by
erv×H-1
where H is the linearized least squares matrix taken from the final iteration of the algorithm of Marquardt. From this expression are derived the vector of standard deviations, and the correlation matrix of parameter estimates. These are approximations which are only valid asymptotically, and must be treated with great caution when the parameter estimates are close to their constraint boundaries.
The residual series at is available upon completion of the iterations over the range t=1+d+s×D,…,n corresponding to the differenced noise series wt.
Because of the algorithm used for backforecasting, these are only true residuals for t≥1+q+s×Q-p-s×P-d-s×D, provided this is positive. Estimation of pre-period terms for the inputs will also tend to reduce the magnitude of the early residuals, sometimes severely.
The model component series z 1,t,…,z m,t and nt may optionally be returned in place of the supplied series values, in order to assess the effects of the various inputs on the output.

Forecasting Information

For the purpose of constructing forecasts of the output series at future time points t=n+1,n+2,… using (G13BHF not in this release), it is not necessary to use the whole set of observations yt and x 1,t,x 2,t,…,x m,t, for t=1,2,…,m. It is sufficient to retain a limited set of quantities constituting the ‘state set’ as follows: for each series which appears with lagged subscripts in equations (a), (b), (i), (ii) and (iii) above, include the values at times n+1-k for k=1 up to the maximum lag associated with that series in the equations. Note that (i) implicitly includes past values of nt and intermediate differences of nt such as ∇d-1∇sD.
If later observations of the series become available, it is possible to update the state set (without re-estimating the model) using g13bg. If time series data is supplied with a previously estimated model, it is possible to construct the state set (and forecasts) using g13bj.

References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day
Marquardt D W (1963) An algorithm for least squares estimation of nonlinear parameters J. Soc. Indust. Appl. Math. 11 431

Error Indicators and Warnings

Note: g13be may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDXXY, LDCM) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | kfc<0,
or | kfc>1,
or | kef<1,
or | kef>3,
or | nit<0,
or | nser<1,
or | nser=1 and there are no parameters in the model (p=q=P=Q=0 and kfc=0).
ifail=2
On entry, there is inconsistency between npara and kfc on the one hand and the orders in arrays mr and mt on the other, or one of the ri, stored in mt[3,i-1]≠1, 2 or 3.
ifail=3
On entry or during execution, one or more sets of δ parameters do not satisfy the stationarity or invertibility test conditions.
ifail=4
On entry, | when kzsp=1, zsp[0]≤0.0,
or | zsp[1]≤1.0,
or | zsp[2]<1.0,
or | zsp[3]<0.0,
or | zsp[3]≥1.0.
ifail=5
On entry, iwa is too small by a considerable margin. No information is supplied about the requisite minimum size.
ifail=6
On entry, iwa is too small, but the requisite minimum size is returned in mwa[0], which is printed if kpriv≠0.
ifail=7
On entry, imwa is too small, but the requisite minimum size is returned in mwa[0], which is printed if kpriv≠0.
ifail=8
This indicates a failure in (F04ASF not in this release) which is used to solve the equations giving the latest estimates of the parameters.
ifail=9
This indicates a failure in the inversion of the second derivative matrix. This is needed in the calculation of the correlation matrix and the standard deviations of the parameter estimates.
ifail=10
On entry or during execution, one or more sets of the ARIMA (ϕ, θ, Φ or Θ) parameters do not satisfy the stationarity or invertibility test conditions.
ifail=11
On entry, isttf is too small. The state set information will not be produced and if kzef≠0 array xxy will remain unchanged. All other parameters will be produced correctly.
ifail=12
The method has failed to converge after nit iterations. If steady decreases in the objective function, D, were monitored up to the point where this exit occurred, then the exit probably occurred because nit was set too small, so the calculations should be restarted from the final point held in para.
ifail=13
On entry, isttf is too small (see ifail=11) and nit iterations were carried out without the convergence conditions being satisfied (see ifail=12).
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The computation used is believed to be stable.

Parallelism and Performance

None.

Further Comments

The time taken by g13be is approximately proportional to nxxy×itc×npara 2.

Example

After the full 11 iterations, the following are computed and printed out: the final values of the para parameters and their standard errors, the correlation matrix, the residuals for the 36 differenced values, the values of zt and nt, the values of the state set and the number of degrees of freedom.

Example program (C#): g13bee.cs

Example program data: g13bee.d

Example program results: g13bee.r

See Also

G13 Class
G13 Members


g13bg Method

[image]

NAG Library for .NET Release 2
G13..::g13bg Method
G13 Class See Also Send Feedback
g13bg accepts a series of new observations of an output time series and any associated input time series, for which a multi-input model is already fully specified, and updates the ‘state set’ information for use in constructing further forecasts.
The previous specification of the multi-input model will normally have been obtained by using g13be to estimate the relevant transfer function and ARIMA parameters. The supplied state set will originally have been produced by g13be (or possibly g13bj), but may since have been updated by g13bg.

Syntax

C#
public static void g13bg(
    double[] sttf,
    int nsttf,
    int[] mr,
    int nser,
    int[,] mt,
    double[] para,
    int npara,
    int nnv,
    double[,] xxyn,
    int kzef,
    double[] res,
    out int ifail
)
Visual Basic
Public Shared Sub g13bg ( _
    sttf As Double(), _
    nsttf As Integer, _
    mr As Integer(), _
    nser As Integer, _
    mt As Integer(,), _
    para As Double(), _
    npara As Integer, _
    nnv As Integer, _
    xxyn As Double(,), _
    kzef As Integer, _
    res As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13bg(
    array<double>^ sttf,
    int nsttf,
    array<int>^ mr,
    int nser,
    array<int,2>^ mt,
    array<double>^ para,
    int npara,
    int nnv,
    array<double,2>^ xxyn,
    int kzef,
    array<double>^ res,
    [OutAttribute] int% ifail
)
F#
static member g13bg :
        sttf : float[] *
        nsttf : int *
        mr : int[] *
        nser : int *
        mt : int[,] *
        para : float[] *
        npara : int *
        nnv : int *
        xxyn : float[,] *
        kzef : int *
        res : float[] *
        ifail : int byref -> unit

Parameters

sttf
Type: array< System..::..Double >[]()[][]
An array of size [nsttf]
On entry: the nsttf values in the state set before updating as returned by g13be or g13bj, or a previous call to g13bg.
On exit: the state set values after updating.
nsttf
Type: System..::..Int32
On entry: the exact number of values in the state set array sttf as returned by g13be or g13bj.
mr
Type: array< System..::..Int32 >[]()[][]
An array of size [7]
On entry: the orders vector p,d,q,P,D,Q,s of the ARIMA model for the output noise component.
p, q, P and Q refer respectively to the number of autoregressive ϕ, moving average θ, seasonal autoregressive Φ and seasonal moving average Θ parameters.
d, D and s refer respectively to the order of non-seasonal differencing, the order of seasonal differencing, and the seasonal period.
Constraints:
  • p, d, q, P, D, Q, s≥0;
  • p+q+P+Q>0;
  • s≠1;
  • if s=0, P+D+Q=0;
  • if s>1, P+D+Q>0.
nser
Type: System..::..Int32
On entry: the total number of input and output series. There may be any number of input series (including none), but only one output series.
mt
Type: array< System..::..Int32 ,2>[,](,)[,][,]
An array of size [4, nser]
On entry: the transfer function model orders b, p and q of each of the input series. The data for input series i are held in column i. Row 1 holds the value bi, row 2 holds the value qi and row 3 holds the value pi. For a simple input, bi=qi=pi=0.
Row 4 holds the value ri, where ri=1 for a simple input and ri=2​ or ​3 for a transfer function input. When ri=1 any nonzero contents of rows 1, 2 and 3 of column i are ignored. The choice of ri=2 or ri=3 is an option for use in model estimation and does not affect the operation of g13bg.
Constraint: mt[3,i-1]=1, 2 or 3, for i=1,2,…,nser-1.
para
Type: array< System..::..Double >[]()[][]
An array of size [npara]
On entry: estimates of the multi-input model parameters as returned by g13be. These are in order, firstly the ARIMA model parameters: p values of ϕ parameters, q values of θ parameters, P values of Φ parameters and Q values of Θ parameters. These are followed by the transfer function model parameter values ω 0,ω 1,…,ω q 1, δ 1,δ 2,…,δ p 1 for the first of any input series and similarly for each subsequent input series. The final component of para is the value of the constant c.
npara
Type: System..::..Int32
On entry: the exact number of ϕ, θ, Φ, Θ, ω, δ and c parameters. (c must be included whether its value was previously estimated or was set fixed.)
nnv
Type: System..::..Int32
On entry: the number of new observation sets being used to update the state set, each observation set consisting of a value of the output series and the associated values of each of the input series at a particular time point.
xxyn
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nser]
Note: dim1 must satisfy the constraint: dim1≥nnv
On entry: the nnv new observation sets being used to update the state set. Column i-1 contains the values of input series i, for i=1,2,…,nser-1. Column nser-1 contains the values of the output series. Consecutive rows correspond to increasing time sequence.
On exit: if kzef=0, xxyn remains unchanged.
If kzef≠0, the columns of xxyn hold the corresponding values of the input component series zt and the output noise component nt in that order.
kzef
Type: System..::..Int32
On entry: must not be set to 0, if the values of the input component series zt and the values of the output noise component nt are to overwrite the contents of xxyn on exit, and must be set to 0 if xxyn is to remain unchanged on exit.
res
Type: array< System..::..Double >[]()[][]
An array of size [nnv]
On exit: the values of the residual series at corresponding to the new observations of the output series.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The multi-input model is specified in [Description] in g13be. The form of these equations required to update the state set is as follows:
zt=δ 1z t-1+δ 2z t-2+⋯+δpz t-p+ω 0x t-b-ω 1x t-b-1-⋯-ωqx t-b-q
the transfer models which generate input component values z i,t from one or more inputs x i,t,
nt=yt-z 1,t-z 2,t-⋯-z m,t
which generates the output noise component from the output yt and the input components, and
wt=∇d∇sD nt-cet=wt-Φ 1w t-s-Φ 2w t-2×s-⋯-ΦPw t-P×s+Θ 1e t-s+Θ 2e t-2×s+⋯+ΘQe t-Q×sat=et-ϕ 1e t-1-ϕ 2e t-2-⋯-ϕpe t-p+θ 1a t-1+θ 2a t-2+⋯+θqa t-q
the ARIMA model for the output noise which generates the residuals at.
The state set (as also given in [Description] in g13be) is the collection of terms
z n+1-k,x n+1-k,n n+1-k,w n+1-k,e n+1-k  and  a n+1-k
for k=1 up to the maximum lag associated with each of these series respectively, in the above model equations. n is the latest time point of the series from which the state set has been generated.
The method accepts further values of the series yt, x 1,t,x 2,t,…,x m,t, for t=n+1,…,n+l, and applies the above model equations over this time range, to generate new values of the various model components, noise series and residuals. The state set is reconstructed, corresponding to the latest time point n+l, the earlier values being discarded.
The set of residuals corresponding to the new observations may be of use in checking that the new observations conform to the previously fitted model. The components of the new observations of the output series which are due to the various inputs, and the noise component, are also optionally returned.
The parameters of the model are not changed in this method.

References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDXXYN) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, nsttf is not consistent with the orders in arrays mr and mt.
ifail=2
On entry, npara is not consistent with the orders in arrays mr and mt.
ifail=4
On entry, iwa is too small.
ifail=5
On entry, one of the ri, stored in mt[3,i-1], for i=1,2,…,nser-1 does not equal 1, 2 or 3.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The computations are believed to be stable.

Parallelism and Performance

None.

Further Comments

The time taken by g13bg is approximately proportional to nnv×npara.

Example

The following are computed and printed out: the updated state set, the residuals at and the values of the components zt and the output noise component nt corresponding to the new observations.

Example program (C#): g13bge.cs

Example program data: g13bge.d

Example program results: g13bge.r

See Also

G13 Class
G13 Members


g13bj Method

[image]

NAG Library for .NET Release 2
G13..::g13bj Method
G13 Class See Also Send Feedback
g13bj produces forecasts of a time series (the output series) which depends on one or more other (input) series via a previously estimated multi-input model for which the state set information is not available. The future values of the input series must be supplied. In contrast with (G13BHF not in this release) the original past values of the input and output series are required. Standard errors of the forecasts are produced. If future values of some of the input series have been obtained as forecasts using ARIMA models for those series, this may be allowed for in the calculation of the standard errors.

Syntax

C#
public static void g13bj(
    int[] mr,
    int nser,
    int[,] mt,
    double[] para,
    int npara,
    int kfc,
    int nev,
    int nfv,
    double[,] xxy,
    int kzef,
    double[] rmsxy,
    int[,] mrx,
    double[,] parx,
    double[] fva,
    double[] fsd,
    double[] sttf,
    out int nsttf,
    out int ifail
)
Visual Basic
Public Shared Sub g13bj ( _
    mr As Integer(), _
    nser As Integer, _
    mt As Integer(,), _
    para As Double(), _
    npara As Integer, _
    kfc As Integer, _
    nev As Integer, _
    nfv As Integer, _
    xxy As Double(,), _
    kzef As Integer, _
    rmsxy As Double(), _
    mrx As Integer(,), _
    parx As Double(,), _
    fva As Double(), _
    fsd As Double(), _
    sttf As Double(), _
    <OutAttribute> ByRef nsttf As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13bj(
    array<int>^ mr,
    int nser,
    array<int,2>^ mt,
    array<double>^ para,
    int npara,
    int kfc,
    int nev,
    int nfv,
    array<double,2>^ xxy,
    int kzef,
    array<double>^ rmsxy,
    array<int,2>^ mrx,
    array<double,2>^ parx,
    array<double>^ fva,
    array<double>^ fsd,
    array<double>^ sttf,
    [OutAttribute] int% nsttf,
    [OutAttribute] int% ifail
)
F#
static member g13bj :
        mr : int[] *
        nser : int *
        mt : int[,] *
        para : float[] *
        npara : int *
        kfc : int *
        nev : int *
        nfv : int *
        xxy : float[,] *
        kzef : int *
        rmsxy : float[] *
        mrx : int[,] *
        parx : float[,] *
        fva : float[] *
        fsd : float[] *
        sttf : float[] *
        nsttf : int byref *
        ifail : int byref -> unit

Parameters

mr
Type: array< System..::..Int32 >[]()[][]
An array of size [7]
On entry: the orders vector p,d,q,P,D,Q,s of the ARIMA model for the output noise component.
p, q, P and Q refer respectively to the number of autoregressive ϕ, moving average θ, seasonal autoregressive Φ and seasonal moving average Θ parameters.
d, D and s refer respectively to the order of non-seasonal differencing, the order of seasonal differencing and the seasonal period.
Constraints:
  • p, d, q, P, D, Q, s≥0;
  • p+q+P+Q>0;
  • s≠1;
  • if s=0, P+D+Q=0;
  • if s>1, P+D+Q>0;
  • d+s×P+D≤n;
  • p+d-q+s×P+D-Q≤n.
nser
Type: System..::..Int32
On entry: the number of input and output series. There may be any number of input series (including none), but only one output series.
mt
Type: array< System..::..Int32 ,2>[,](,)[,][,]
An array of size [4, nser]
On entry: the transfer function model orders b, p and q of each of the input series. The data for input series i is held in column i. Row 1 holds the value bi, row 2 holds the value qi and row 3 holds the value pi.
For a simple input, bi=qi=pi=0.
Row 4 holds the value ri, where ri=1 for a simple input, and ri=2​ or ​3 for a transfer function input.
The choice ri=3 leads to estimation of the pre-period input effects as nuisance parameters, and ri=2 suppresses this estimation. This choice may affect the returned forecasts and the state set.
When ri=1, any nonzero contents of rows 1, 2 and 3 of column i are ignored.
Constraint: mt[3,i-1]=1, 2 or 3, for i=1,2,…,nser-1.
para
Type: array< System..::..Double >[]()[][]
An array of size [npara]
On entry: estimates of the multi-input model parameters. These are in order, firstly the ARIMA model parameters: p values of ϕ parameters, q values of θ parameters, P values of Φ parameters, Q values of Θ parameters.
These are followed by the transfer function model parameter values ω 0,ω 1,…,ω q 1, δ 1,…,δ p 1 for the first of any input series and similarly for each subsequent input series. The final component of para is the value of the constant c.
On exit: the parameter values may be updated using an additional iteration in the estimation process.
npara
Type: System..::..Int32
On entry: the exact number of ϕ, θ, Φ, Θ, ω, δ, c parameters, so that npara=p+q+P+Q+nser+∑p+q, the summation being over all the input series. (c must be included whether its value was previously estimated or was set fixed.)
kfc
Type: System..::..Int32
On entry: must be set to 1 if the constant was estimated when the model was fitted, and 0 if it was held at a fixed value. This only affects the degrees of freedom used in calculating the estimated residual variance.
Constraint: kfc=0 or 1.
nev
Type: System..::..Int32
On entry: the number of original (undifferenced) values in each of the input and output time series.
nfv
Type: System..::..Int32
On entry: the number of forecast values of the output series required.
Constraint: nfv>0.
xxy
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nser]
Note: dim1 must satisfy the constraint: dim1≥nev+nfv
On entry: the columns of xxy must contain in the first nev places, the past values of each of the input and output series, in that order. In the next nfv places, the columns relating to the input series (i.e., columns 1 to nser-1) contain the future values of the input series which are necessary for construction of the forecasts of the output series y.
On exit: if kzef=0 then xxy is unchanged except that the relevant nfv values in the column relating to the output series (column nser) contain the forecast values (fva), but if kzef≠0 then the columns of xxy contain the corresponding values of the input component series zt and the values of the output noise component nt, in that order.
kzef
Type: System..::..Int32
On entry: must be set to 0 if the relevant nfv values of the forecasts (fva) are to be held in the output series column (nser) of xxy (which is otherwise unchanged) on exit, and must not be set to 0 if the values of the input component series zt and the values of the output noise component nt are to overwrite the contents of xxy on exit.
rmsxy
Type: array< System..::..Double >[]()[][]
An array of size [nser]
On entry: the first nser-1 elements of rmsxy must contain the estimated residual variance of the input series ARIMA models. In the case of those inputs for which no ARIMA model is available or its effects are to be excluded in the calculation of forecast standard errors, the corresponding entry of rmsxy should be set to 0.
On exit: rmsxy[nser-1] contains the estimated residual variance of the output noise ARIMA model which is calculated from the supplied series. Otherwise rmsxy is unchanged.
mrx
Type: array< System..::..Int32 ,2>[,](,)[,][,]
An array of size [7, nser]
On entry: the orders array for each of the input series ARIMA models. Thus, column i contains values of p, d, q, P, D, Q, s for input series i. In the case of those inputs for which no ARIMA model is available, the corresponding orders should be set to 0.
On exit: unchanged, except for column nser which is used as workspace.
parx
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, nser]
Note: dim1 must satisfy the constraint: dim1≥nce, where nce is the maximum number of parameters in any of the input series ARIMA models. If there are no input series, then dim1≥1
On entry: values of the parameters (ϕ, θ, Φ, and Θ) for each of the input series ARIMA models.
Thus column i contains mrx[0,i-1] values of ϕ, mrx[2,i-1] values of θ, mrx[3,i-1] values of Φ and mrx[5,i-1] values of Θ, in that order.
Values in the columns relating to those input series for which no ARIMA model is available are ignored.
fva
Type: array< System..::..Double >[]()[][]
An array of size [nfv]
On exit: the required forecast values for the output series. (Note that these are also output in column nser of xxy if kzef=0.)
fsd
Type: array< System..::..Double >[]()[][]
An array of size [nfv]
On exit: the standard errors for each of the forecast values.
sttf
Type: array< System..::..Double >[]()[][]
An array of size [isttf]
On exit: the nsttf values of the state set based on the first nev sets of (past) values of the input and output series.
nsttf
Type: System..::..Int32 %
On exit: the number of values in the state set array sttf.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

g13bj has two stages. The first stage is essentially the same as a call to the model estimation method g13be, with zero iterations. In particular, all the parameters remain unchanged in the supplied input series transfer function models and output noise series ARIMA model. The internal nuisance parameters associated with the pre-observation period effects of the input series are estimated where requested, and so are any backforecasts of the output noise series. The output components zt and nt, and residuals at are calculated exactly as in [Description] in g13be, and the state set for forecasting is constituted.
The second stage is essentially the same as a call to the forecasting method (G13BHF not in this release). The same information is required, and the same information is returned.
Use of g13bj should be confined to situations in which the state set for forecasting is unknown. Forecasting from the original data is relatively expensive because it requires recalculation of the state set. g13bj returns the state set for use in producing further forecasts using (G13BHF not in this release), or for updating the state set using g13bg.

References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDXXY, LDPARX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | kfc<0,
or | kfc>1,
or | nfv≤0.
ifail=2
On entry, ldparx is too small or npara is inconsistent with the orders specified in arrays mr and mt; or one of the ri, stored in mt[3,i-1], does not equal 1, 2 or 3.
ifail=3
On entry or during execution, one or more sets of δ parameters do not satisfy the stationarity or invertibility test conditions.
ifail=4
On entry, iwa is too small for the final forecasting calculations. This is a highly unlikely error, and would probably indicate that nfv was abnormally large.
ifail=5
On entry, iwa is too small by a very considerable margin. No information is supplied about the requisite minimum size.
ifail=6
On entry, iwa is too small, but the requisite minimum size is returned in mwa[0].
ifail=7
On entry, imwa is too small, but the requisite minimum size is returned in mwa[0].
ifail=8
This indicates a failure in (F04ASF not in this release) which is used to solve the equations giving the latest estimates of the parameters.
ifail=9
This indicates a failure in the inversion of the second derivative matrix associated with parameter estimation.
ifail=10
On entry or during execution, one or more sets of the ARIMA (ϕ, θ, Φ or Θ) parameters do not satisfy the stationarity or invertibility test conditions.
ifail=11
On entry, isttf is too small.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The computations are believed to be stable.

Parallelism and Performance

None.

Further Comments

The time taken by g13bj is approximately proportional to the product of the length of each series and the square of the number of parameters in the multi-input model.

Example

A further 8 values of the input series are supplied, and it is assumed that the values for the fifth series have themselves been forecast from an ARIMA model with orders 2020114, in which ϕ 1=1.6743, ϕ 2=-0.9505, θ 1=1.4605, θ 2=-0.4862 and Θ 1=0.8993, and for which the residual mean square is 0.1720.
The following are computed and printed out: the state set after initial processing of the original 40 sets of values, the estimated residual variance for the output noise series, the 8 forecast values and their standard errors, and the values of the components zt and the output noise component nt.

Example program (C#): g13bje.cs

Example program data: g13bje.d

Example program results: g13bje.r

See Also

G13 Class
G13 Members


g13ca Method

[image]

NAG Library for .NET Release 2
G13..::g13ca Method
G13 Class See Also Send Feedback
g13ca calculates the smoothed sample spectrum of a univariate time series using one of four lag windows – rectangular, Bartlett, Tukey or Parzen window.

Syntax

C#
public static void g13ca(
    int nx,
    int mtx,
    double px,
    int iw,
    int mw,
    int ic,
    int nc,
    double[] c,
    int kc,
    int l,
    int lg,
    double[] xg,
    out int ng,
    double[] stats,
    out int ifail
)
Visual Basic
Public Shared Sub g13ca ( _
    nx As Integer, _
    mtx As Integer, _
    px As Double, _
    iw As Integer, _
    mw As Integer, _
    ic As Integer, _
    nc As Integer, _
    c As Double(), _
    kc As Integer, _
    l As Integer, _
    lg As Integer, _
    xg As Double(), _
    <OutAttribute> ByRef ng As Integer, _
    stats As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13ca(
    int nx,
    int mtx,
    double px,
    int iw,
    int mw,
    int ic,
    int nc,
    array<double>^ c,
    int kc,
    int l,
    int lg,
    array<double>^ xg,
    [OutAttribute] int% ng,
    array<double>^ stats,
    [OutAttribute] int% ifail
)
F#
static member g13ca :
        nx : int *
        mtx : int *
        px : float *
        iw : int *
        mw : int *
        ic : int *
        nc : int *
        c : float[] *
        kc : int *
        l : int *
        lg : int *
        xg : float[] *
        ng : int byref *
        stats : float[] *
        ifail : int byref -> unit

Parameters

nx
Type: System..::..Int32
On entry: n, the length of the time series.
Constraint: nx≥1.
mtx
Type: System..::..Int32
On entry: if covariances are to be calculated by the method (ic=0), mtx must specify whether the data are to be initially mean or trend corrected.
mtx=0
For no correction.
mtx=1
For mean correction.
mtx=2
For trend correction.
Constraint: if ic=0, 0≤mtx≤2
If covariances are supplied (ic≠0), mtx is not used.
px
Type: System..::..Double
On entry: if covariances are to be calculated by the method (ic=0), px must specify the proportion of the data (totalled over both ends) to be initially tapered by the split cosine bell taper.
If covariances are supplied ic≠0, px must specify the proportion of data tapered before the supplied covariances were calculated and after any mean or trend correction. px is required for the calculation of output statistics. A value of 0.0 implies no tapering.
Constraint: 0.0≤px≤1.0.
iw
Type: System..::..Int32
On entry: the choice of lag window.
iw=1
Rectangular.
iw=2
Bartlett.
iw=3
Tukey.
iw=4
Parzen.
Constraint: 1≤iw≤4.
mw
Type: System..::..Int32
On entry: M, the ‘cut-off’ point of the lag window. Windowed covariances at lag M or greater are zero.
Constraint: 1≤mw≤nx.
ic
Type: System..::..Int32
On entry: indicates whether covariances are to be calculated in the method or supplied in the call to the method.
ic=0
Covariances are to be calculated.
ic≠0
Covariances are to be supplied.
nc
Type: System..::..Int32
On entry: the number of covariances to be calculated in the method or supplied in the call to the method.
Constraint: mw≤nc≤nx.
c
Type: array< System..::..Double >[]()[][]
An array of size [nc]
On entry: if ic≠0, c must contain the nc covariances for lags from 0 to nc-1, otherwise c need not be set.
On exit: if ic=0, c will contain the nc calculated covariances.
If ic≠0, the contents of c will be unchanged.
kc
Type: System..::..Int32
On entry: if ic=0, kc must specify the order of the fast Fourier transform (FFT) used to calculate the covariances. kc should be a product of small primes such as 2 m where m is the smallest integer such that 2 m≥nx+nc, provided m≤20.
If ic≠0, that is covariances are supplied, kc is not used.
Constraint: kc≥nx+nc. The largest prime factor of kc must not exceed 19, and the total number of prime factors of kc, counting repetitions, must not exceed 20. These two restrictions are imposed by the internal FFT algorithm used.
l
Type: System..::..Int32
On entry: L, the frequency division of the spectral estimates as 2 π L. Therefore it is also the order of the FFT used to construct the sample spectrum from the covariances. l should be a product of small primes such as 2 m where m is the smallest integer such that 2 m≥2 M-1, provided m≤20.
Constraint: l≥2×mw-1. The largest prime factor of l must not exceed 19, and the total number of prime factors of l, counting repetitions, must not exceed 20. These two restrictions are imposed by the internal FFT algorithm used.
lg
Type: System..::..Int32
On entry: indicates whether unlogged or logged spectral estimates and confidence limits are required.
lg=0
Unlogged.
lg≠0
Logged.
xg
Type: array< System..::..Double >[]()[][]
An array of size [nxg]
On entry: if the covariances are to be calculated, then xg must contain the nx data points. If covariances are supplied, xg may contain any values.
On exit: contains the ng spectral estimates, f^ωi, for i=0,1,…,L/2 in xg[0] to xg[ng-1] respectively (logged if lg=1). The elements xg[i-1], for i=ng+1,…,nxg contain 0.0.
ng
Type: System..::..Int32 %
On exit: the number of spectral estimates, L/2+1, in xg.
stats
Type: array< System..::..Double >[]()[][]
An array of size [4]
On exit: four associated statistics. These are the degrees of freedom in stats[0], the lower and upper 95% confidence limit factors in stats[1] and stats[2] respectively (logged if lg=1), and the bandwidth in stats[3].
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The smoothed sample spectrum is defined as
f^ω=1 2 π C 0+2∑k=1M-1 wkCk cos ωk,
where M is the window width, and is calculated for frequency values
ωi=2 πi L,  i=0,1,…,L/2,
where denotes the integer part.
The autocovariances Ck may be supplied by you, or constructed from a time series x 1,x 2,…,xn, as
Ck=1 n∑t=1n-k xtx t+k,
the fast Fourier transform (FFT) being used to carry out the convolution in this formula.
The time series may be mean or trend corrected (by classical least squares), and tapered before calculation of the covariances, the tapering factors being those of the split cosine bell:
12 1-cos π t-12/T,1≤t≤T12 1-cos π n-t+12/T,n+1-T≤t≤n1,otherwise,
where T=np 2 and p is the tapering proportion.
The smoothing window is defined by
wk=W kM,  k≤M-1,
which for the various windows is defined over 0≤α<1 by
rectangular:
W α=1
Bartlett:
W α=1-α
Tukey:
W α=12 1+cos πα
Parzen:
W α=1-6 α 2+6 α 3,0≤α≤12W α=2 1-α 3,12<α<1.
The sampling distribution of f^ω is approximately that of a scaled χd 2 variate, whose degrees of freedom d is provided by the method, together with multiplying limits mu, ml from which approximate 95% confidence intervals for the true spectrum f ω may be constructed as ml×f^ω,mu×f^ω. Alternatively, log f^ω may be returned, with additive limits.
The bandwidth b of the corresponding smoothing window in the frequency domain is also provided. Spectrum estimates separated by (angular) frequencies much greater than b may be assumed to be independent.

References

Bloomfield P (1976) Fourier Analysis of Time Series: An Introduction Wiley
Jenkins G M and Watts D G (1968) Spectral Analysis and its Applications Holden–Day

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | nx<1,
or | mtx<0 and ic=0,
or | mtx>2 and ic=0,
or | px<0.0,
or | px>1.0,
or | iw<1,
or | iw>4,
or | mw<1,
or | mw>nx,
or | nc<mw,
or | nc>nx,
or | nxg<max kc,l and ic=0,
or | nxg<l and ic≠0.
ifail=2
On entry, | kc<nx+nc,
or | kc has a prime factor exceeding 19,
or | kc has more than 20 prime factors, counting repetitions.
This error only occurs when ic=0.
ifail=3
On entry, | l<2×mw-1,
or | l has a prime factor exceeding 19,
or | l has more than 20 prime factors, counting repetitions.
ifail=4
One or more spectral estimates are negative. Unlogged spectral estimates are returned in xg, and the degrees of freedom, unlogged confidence limit factors and bandwidth in stats.
ifail=5
The calculation of confidence limit factors has failed. This error will not normally occur. Spectral estimates (logged if requested) are returned in xg, and degrees of freedom and bandwidth in stats.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The FFT is a numerically stable process, and any errors introduced during the computation will normally be insignificant compared with uncertainty in the data.

Parallelism and Performance

None.

Further Comments

g13ca carries out two FFTs of length kc to calculate the covariances and one FFT of length l to calculate the sample spectrum. The time taken by the method for an FFT of length n is approximately proportional to n log n (but see [Further Comments] in c06pa for further details).

Example

This example reads a time series of length 256. It selects the mean correction option, a tapering proportion of 0.1, the Parzen smoothing window and a cut-off point for the window at lag 100. It chooses to have 100 auto-covariances calculated and unlogged spectral estimates at a frequency division of 2 π/200. It then calls g13ca to calculate the univariate spectrum and statistics and prints the autocovariances and the spectrum together with its 95% confidence multiplying limits.

Example program (C#): g13cae.cs

Example program data: g13cae.d

Example program results: g13cae.r

See Also

G13 Class
G13 Members


g13cb Method

[image]

NAG Library for .NET Release 2
G13..::g13cb Method
G13 Class See Also Send Feedback
g13cb calculates the smoothed sample spectrum of a univariate time series using spectral smoothing by the trapezium frequency (Daniell) window.

Syntax

C#
public static void g13cb(
    int nx,
    int mtx,
    double px,
    int mw,
    double pw,
    int l,
    int kc,
    int lg,
    double[] xg,
    out int ng,
    double[] stats,
    out int ifail
)
Visual Basic
Public Shared Sub g13cb ( _
    nx As Integer, _
    mtx As Integer, _
    px As Double, _
    mw As Integer, _
    pw As Double, _
    l As Integer, _
    kc As Integer, _
    lg As Integer, _
    xg As Double(), _
    <OutAttribute> ByRef ng As Integer, _
    stats As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13cb(
    int nx,
    int mtx,
    double px,
    int mw,
    double pw,
    int l,
    int kc,
    int lg,
    array<double>^ xg,
    [OutAttribute] int% ng,
    array<double>^ stats,
    [OutAttribute] int% ifail
)
F#
static member g13cb :
        nx : int *
        mtx : int *
        px : float *
        mw : int *
        pw : float *
        l : int *
        kc : int *
        lg : int *
        xg : float[] *
        ng : int byref *
        stats : float[] *
        ifail : int byref -> unit

Parameters

nx
Type: System..::..Int32
On entry: n, the length of the time series.
Constraint: nx≥1.
mtx
Type: System..::..Int32
On entry: whether the data are to be initially mean or trend corrected.
mtx=0
For no correction.
mtx=1
For mean correction.
mtx=2
For trend correction.
Constraint: 0≤mtx≤2.
px
Type: System..::..Double
On entry: the proportion of the data (totalled over both ends) to be initially tapered by the split cosine bell taper. (A value of 0.0 implies no tapering.)
Constraint: 0.0≤px≤1.0.
mw
Type: System..::..Int32
On entry: the value of M which determines the frequency width of the smoothing window as 2 π/M. A value of n implies no smoothing is to be carried out.
Constraint: 1≤mw≤nx.
pw
Type: System..::..Double
On entry: p, the shape parameter of the trapezium frequency window.
A value of 0.0 gives a triangular window, and a value of 1.0 a rectangular window.
If mw=nx (i.e., no smoothing is carried out), pw is not used.
Constraint: 0.0≤pw≤1.0.
l
Type: System..::..Int32
On entry: L, the frequency division of smoothed spectral estimates as 2 π/L.
Constraints:
  • l≥1;
  • l must be a factor of kc.
kc
Type: System..::..Int32
On entry: K, the order of the fast Fourier transform (FFT) used to calculate the spectral estimates. kc should be a multiple of small primes such as 2 m where m is the smallest integer such that 2 m≥2 n, provided m≤20.
Constraints:
  • kc≥2×nx;
  • kc must be a multiple of l. The largest prime factor of kc must not exceed 19, and the total number of prime factors of kc, counting repetitions, must not exceed 20. These two restrictions are imposed by the internal FFT algorithm used.
lg
Type: System..::..Int32
On entry: indicates whether unlogged or logged spectral estimates and confidence limits are required.
lg=0
For unlogged.
lg≠0
For logged.
xg
Type: array< System..::..Double >[]()[][]
An array of size [kc]
On entry: the n data points.
On exit: contains the ng spectral estimates f^ωi, for i=0,1,…,L/2, in xg[0] to xg[ng-1] (logged if lg≠0). The elements xg[i-1], for i=ng+1,…,kc, contain 0.0.
ng
Type: System..::..Int32 %
On exit: the number of spectral estimates, L/2+1, in xg.
stats
Type: array< System..::..Double >[]()[][]
An array of size [4]
On exit: four associated statistics. These are the degrees of freedom in stats[0], the lower and upper 95% confidence limit factors in stats[1] and stats[2] respectively (logged if lg≠0), and the bandwidth in stats[3].
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The supplied time series may be mean or trend corrected (by least squares), and tapered, the tapering factors being those of the split cosine bell:
12 1-cos π t-12/T,1≤t≤T12 1-cos π n-t+12/T,n+1-T≤t≤n1,otherwise,
where T=np 2 and p is the tapering proportion.
The unsmoothed sample spectrum
f*ω=1 2 π∑t=1 n xt exp iωt 2
is then calculated for frequency values
ωk=2 πk K,  k=0,1,…,K/2,
where [ ] denotes the integer part.
The smoothed spectrum is returned as a subset of these frequencies for which k is a multiple of a chosen value r, i.e.,
ω rl=νl=2 πl L,  l=0,1,…,L/2,
where K=r×L. You will normally fix L first, then choose r so that K is sufficiently large to provide an adequate representation for the unsmoothed spectrum, i.e., K≥2×n. It is possible to take L=K, i.e., r=1.
The smoothing is defined by a trapezium window whose shape is supplied by the function
W α=1,α≤pW α=1-α1-p,p<α≤1
the proportion p being supplied by you.
The width of the window is fixed as 2 π/M by you supplying M. A set of averaging weights are constructed:
Wk=g×W ωk M π,  0≤ωk≤πM,
where g is a normalizing constant, and the smoothed spectrum obtained is
f^νl=∑ωk<πMWk f*νl+ωk.
If no smoothing is required M should be set to n, in which case the values returned are f^νl=f*νl. Otherwise, in order that the smoothing approximates well to an integration, it is essential that K≫M, and preferable, but not essential, that K be a multiple of M. A choice of L>M would normally be required to supply an adequate description of the smoothed spectrum. Typical choices of L≃n and K≃4 n should be adequate for usual smoothing situations when M<n/5.
The sampling distribution of f^ω is approximately that of a scaled χd 2 variate, whose degrees of freedom d is provided by the method, together with multiplying limits mu, ml from which approximate 95% confidence intervals for the true spectrum f ω may be constructed as ml×f^ωmu×f^ω. Alternatively, log f^ω may be returned, with additive limits.
The bandwidth b of the corresponding smoothing window in the frequency domain is also provided. Spectrum estimates separated by (angular) frequencies much greater than b may be assumed to be independent.

References

Bloomfield P (1976) Fourier Analysis of Time Series: An Introduction Wiley
Jenkins G M and Watts D G (1968) Spectral Analysis and its Applications Holden–Day

Error Indicators and Warnings

Note: g13cb may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail=1
On entry, | nx<1,
or | mtx<0,
or | mtx>2,
or | px<0.0,
or | px>1.0,
or | mw<1,
or | mw>nx,
or | pw<0.0 and mw≠nx,
or | pw>1.0 and mw≠nx,
or | l<1.
ifail=2
On entry, | kc<2×nx,
or | kc is not a multiple of l,
or | kc has a prime factor exceeding 19,
or | kc has more than 20 prime factors, counting repetitions.
ifail=3
This indicates that a serious error has occurred. Check all array subscripts and method parameter lists in calls to g13cb. Seek expert help.
ifail=4
One or more spectral estimates are negative. Unlogged spectral estimates are returned in xg, and the degrees of freedom, unlogged confidence limit factors and bandwidth in stats.
ifail=5
The calculation of confidence limit factors has failed. This error will not normally occur. Spectral estimates (logged if requested) are returned in xg, and degrees of freedom and bandwidth in stats.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The FFT is a numerically stable process, and any errors introduced during the computation will normally be insignificant compared with uncertainty in the data.

Parallelism and Performance

None.

Further Comments

g13cb carries out a FFT of length kc to calculate the sample spectrum. The time taken by the method for this is approximately proportional to kc×log kc (but see [Further Comments] in c06pa for further details).

Example

This example reads a time series of length 131. It then calls g13cb to calculate the univariate spectrum and prints the logged spectrum together with 95% confidence limits.

Example program (C#): g13cbe.cs

Example program data: g13cbe.d

Example program results: g13cbe.r

See Also

G13 Class
G13 Members


g13cc Method

[image]

NAG Library for .NET Release 2
G13..::g13cc Method
G13 Class See Also Send Feedback
g13cc calculates the smoothed sample cross spectrum of a bivariate time series using one of four lag windows: rectangular, Bartlett, Tukey or Parzen.

Syntax

C#
public static void g13cc(
    int nxy,
    int mtxy,
    double pxy,
    int iw,
    int mw,
    int ish,
    int ic,
    int nc,
    double[] cxy,
    double[] cyx,
    int kc,
    int l,
    double[] xg,
    double[] yg,
    out int ng,
    out int ifail
)
Visual Basic
Public Shared Sub g13cc ( _
    nxy As Integer, _
    mtxy As Integer, _
    pxy As Double, _
    iw As Integer, _
    mw As Integer, _
    ish As Integer, _
    ic As Integer, _
    nc As Integer, _
    cxy As Double(), _
    cyx As Double(), _
    kc As Integer, _
    l As Integer, _
    xg As Double(), _
    yg As Double(), _
    <OutAttribute> ByRef ng As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13cc(
    int nxy,
    int mtxy,
    double pxy,
    int iw,
    int mw,
    int ish,
    int ic,
    int nc,
    array<double>^ cxy,
    array<double>^ cyx,
    int kc,
    int l,
    array<double>^ xg,
    array<double>^ yg,
    [OutAttribute] int% ng,
    [OutAttribute] int% ifail
)
F#
static member g13cc :
        nxy : int *
        mtxy : int *
        pxy : float *
        iw : int *
        mw : int *
        ish : int *
        ic : int *
        nc : int *
        cxy : float[] *
        cyx : float[] *
        kc : int *
        l : int *
        xg : float[] *
        yg : float[] *
        ng : int byref *
        ifail : int byref -> unit

Parameters

nxy
Type: System..::..Int32
On entry: n, the length of the time series x and y.
Constraint: nxy≥1.
mtxy
Type: System..::..Int32
On entry: if cross-covariances are to be calculated by the method (ic=0), mtxy must specify whether the data is to be initially mean or trend corrected.
mtxy=0
For no correction.
mtxy=1
For mean correction.
mtxy=2
For trend correction.
If cross-covariances are supplied ic≠0, mtxy is not used.
Constraint: if ic=0, mtxy=0, 1 or 2.
pxy
Type: System..::..Double
On entry: if cross-covariances are to be calculated by the method (ic=0), pxy must specify the proportion of the data (totalled over both ends) to be initially tapered by the split cosine bell taper. A value of 0.0 implies no tapering.
If cross-covariances are supplied ic≠0, pxy is not used.
Constraint: if ic=0, 0.0≤pxy≤1.0.
iw
Type: System..::..Int32
On entry: the choice of lag window.
iw=1
Rectangular.
iw=2
Bartlett.
iw=3
Tukey.
iw=4
Parzen.
Constraint: 1≤iw≤4.
mw
Type: System..::..Int32
On entry: M, the ‘cut-off’ point of the lag window, relative to any alignment shift that has been applied. Windowed cross-covariances at lags -mw+ish or less, and at lags mw+ish or greater are zero.
Constraints:
  • mw≥1;
  • mw+ish≤nxy.
ish
Type: System..::..Int32
On entry: S, the alignment shift between the x and y series. If x leads y, the shift is positive.
Constraint: -mw<ish<mw.
ic
Type: System..::..Int32
On entry: indicates whether cross-covariances are to be calculated in the method or supplied in the call to the method.
ic=0
Cross-covariances are to be calculated.
ic≠0
Cross-covariances are to be supplied.
nc
Type: System..::..Int32
On entry: the number of cross-covariances to be calculated in the method or supplied in the call to the method.
Constraint: mw+ish≤nc≤nxy.
cxy
Type: array< System..::..Double >[]()[][]
An array of size [nc]
On entry: if ic≠0, cxy must contain the nc cross-covariances between values in the y series and earlier values in time in the x series, for lags from 0 to nc-1.
If ic=0, cxy need not be set.
On exit: if ic=0, cxy will contain the nc calculated cross-covariances.
If ic≠0, the contents of cxy will be unchanged.
cyx
Type: array< System..::..Double >[]()[][]
An array of size [nc]
On entry: if ic≠0, cyx must contain the nc cross-covariances between values in the y series and later values in time in the x series, for lags from 0 to nc-1.
If ic=0, cyx need not be set.
On exit: if ic=0, cyx will contain the nc calculated cross-covariances.
If ic≠0, the contents of cyx will be unchanged.
kc
Type: System..::..Int32
On entry: if ic=0, kc must specify the order of the fast Fourier transform (FFT) used to calculate the cross-covariances. kc should be a product of small primes such as 2 m where m is the smallest integer such that 2 m≥n+nc.
If ic≠0, that is if covariances are supplied, kc is not used.
Constraint: kc≥nxy+nc. The largest prime factor of kc must not exceed 19, and the total number of prime factors of kc, counting repetitions, must not exceed 20. These two restrictions are imposed by the internal FFT algorithm used.
l
Type: System..::..Int32
On entry: L, the frequency division of the spectral estimates as 2 π L. Therefore it is also the order of the FFT used to construct the sample spectrum from the cross-covariances. l should be a product of small primes such as 2 m where m is the smallest integer such that 2 m≥2 M-1.
Constraint: l≥2×mw-1. The largest prime factor of l must not exceed 19, and the total number of prime factors of l, counting repetitions, must not exceed 20. These two restrictions are imposed by the internal FFT algorithm used.
xg
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: dim1 must satisfy the constraint:
  • if ic=0, _nxyg≥max kc,l;
  • otherwise _nxyg≥l.
On entry: if the cross-covariances are to be calculated, then xg must contain the nxy data points of the x series. If covariances are supplied, xg need not be set.
On exit: contains the real parts of the ng complex spectral estimates in elements xg[0] to xg[ng-1], and xg[ng] to xg[_nxyg-1] contain 0.0. The y series leads the x series.
yg
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: dim1 must satisfy the constraint:
  • if ic=0, _nxyg≥max kc,l;
  • otherwise _nxyg≥l.
On entry: if cross-covariances are to be calculated, yg must contain the nxy data points of the y series. If covariances are supplied, yg need not be set.
On exit: contains the imaginary parts of the ng complex spectral estimates in elements yg[0] to yg[ng-1], and yg[ng] to yg[_nxyg-1] contain 0.0. The y series leads the x series.
ng
Type: System..::..Int32 %
On exit: the number, l/2+1, of complex spectral estimates, whose separate parts are held in xg and yg.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The smoothed sample cross spectrum is a complex valued function of frequency ω, f xy ω=cf ω+iqf ω, defined by its real part or co-spectrum
cf ω=1 2 π∑k=-M+1M-1 wkC xy k+S cos ωk
and imaginary part or quadrature spectrum
qf ω=1 2 π∑k=-M+1M-1 wkC xy k+S sin ωk
where wk=w-k, for k=0,1,…,M-1, is the smoothing lag window as defined in the description of g13ca. The alignment shift S is recommended to be chosen as the lag k at which the cross-covariances c xy k peak, so as to minimize bias.
The results are calculated for frequency values
ωj=2 πj L,  j=0,1,…,L/2,
where denotes the integer part.
The cross-covariances c xy k may be supplied by you, or constructed from supplied series x 1,x 2,…,xn; y 1,y 2,…,yn as
c xy k=∑t=1n-k xty t+k n,  k≥0
c xy k=∑t=1-k n xty t+k n=c yx-k,  k<0
this convolution being carried out using the finite Fourier transform.
The supplied series may be mean and trend corrected and tapered before calculation of the cross-covariances, in exactly the manner described in g13ca for univariate spectrum estimation. The results are corrected for any bias due to tapering.
The bandwidth associated with the estimates is not returned. It will normally already have been calculated in previous calls of g13ca for estimating the univariate spectra of yt and xt.

References

Bloomfield P (1976) Fourier Analysis of Time Series: An Introduction Wiley
Jenkins G M and Watts D G (1968) Spectral Analysis and its Applications Holden–Day

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (NXYG) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | nxy<1,
or | mtxy<0 and ic=0,
or | mtxy>2 and ic=0,
or | pxy<0.0 and ic=0,
or | pxy>1.0 and ic=0,
or | iw≤0,
or | iw>4,
or | mw<1,
or | mw+ish>nxy,
or | ish≥mw,
or | nc<mw+ish,
or | nc>nxy,
ifail=2
On entry, | kc<nxy+nc,
or | kc has a prime factor exceeding 19,
or | kc has more than 20 prime factors, counting repetitions.
This error only occurs when ic=0.
ifail=3
On entry, | l<2×mw-1,
or | l has a prime factor exceeding 19,
or | l has more than 20 prime factors, counting repetitions.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The FFT is a numerically stable process, and any errors introduced during the computation will normally be insignificant compared with uncertainty in the data.

Parallelism and Performance

None.

Further Comments

g13cc carries out two FFTs of length kc to calculate the sample cross-covariances and one FFT of length L to calculate the sample spectrum. The timing of g13cc is therefore dependent on the choice of these values. The time taken for an FFT of length n is approximately proportional to n log n (but see [Further Comments] in c06pa for further details).

Example

This example reads two time series of length 296. It then selects mean correction, a 10% tapering proportion, the Parzen smoothing window and a cut-off point of 35 for the lag window. The alignment shift is set to 3 and 50 cross-covariances are chosen to be calculated. The program then calls g13cc to calculate the cross spectrum and then prints the cross-covariances and cross spectrum.

Example program (C#): g13cce.cs

Example program data: g13cce.d

Example program results: g13cce.r

See Also

G13 Class
G13 Members


g13cd Method

[image]

NAG Library for .NET Release 2
G13..::g13cd Method
G13 Class See Also Send Feedback
g13cd calculates the smoothed sample cross spectrum of a bivariate time series using spectral smoothing by the trapezium frequency (Daniell) window.

Syntax

C#
public static void g13cd(
    int nxy,
    int mtxy,
    double pxy,
    int mw,
    int ish,
    double pw,
    int l,
    int kc,
    double[] xg,
    double[] yg,
    out int ng,
    out int ifail
)
Visual Basic
Public Shared Sub g13cd ( _
    nxy As Integer, _
    mtxy As Integer, _
    pxy As Double, _
    mw As Integer, _
    ish As Integer, _
    pw As Double, _
    l As Integer, _
    kc As Integer, _
    xg As Double(), _
    yg As Double(), _
    <OutAttribute> ByRef ng As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13cd(
    int nxy,
    int mtxy,
    double pxy,
    int mw,
    int ish,
    double pw,
    int l,
    int kc,
    array<double>^ xg,
    array<double>^ yg,
    [OutAttribute] int% ng,
    [OutAttribute] int% ifail
)
F#
static member g13cd :
        nxy : int *
        mtxy : int *
        pxy : float *
        mw : int *
        ish : int *
        pw : float *
        l : int *
        kc : int *
        xg : float[] *
        yg : float[] *
        ng : int byref *
        ifail : int byref -> unit

Parameters

nxy
Type: System..::..Int32
On entry: n, the length of the time series x and y.
Constraint: nxy≥1.
mtxy
Type: System..::..Int32
On entry: whether the data is to be initially mean or trend corrected.
mtxy=0
For no correction.
mtxy=1
For mean correction.
mtxy=2
For trend correction.
Constraint: 0≤mtxy≤2.
pxy
Type: System..::..Double
On entry: the proportion of the data (totalled over both ends) to be initially tapered by the split cosine bell taper.
A value of 0.0 implies no tapering.
Constraint: 0.0≤pxy≤1.0.
mw
Type: System..::..Int32
On entry: M, the frequency width of the smoothing window as 2 π M.
A value of n implies that no smoothing is to be carried out.
Constraint: 1≤mw≤nxy.
ish
Type: System..::..Int32
On entry: S, the alignment shift between the x and y series. If x leads y, the shift is positive.
Constraint: -l<ish<l.
pw
Type: System..::..Double
On entry: p, the shape parameter of the trapezium frequency window.
A value of 0.0 gives a triangular window, and a value of 1.0 a rectangular window.
If mw=nxy (i.e., no smoothing is carried out) then pw is not used.
Constraint: if mw≠nxy, 0.0≤pw≤1.0.
l
Type: System..::..Int32
On entry: L, the frequency division of smoothed cross spectral estimates as 2 π L.
Constraints:
  • l≥1;
  • l must be a factor of kc.
kc
Type: System..::..Int32
On entry: the order of the fast Fourier transform (FFT) used to calculate the spectral estimates. kc should be a product of small primes such as 2 m where m is the smallest integer such that 2 m≥2 n, provided m≤20.
Constraints:
  • kc≥2×nxy;
  • kc must be a multiple of l. The largest prime factor of kc must not exceed 19, and the total number of prime factors of kc, counting repetitions, must not exceed 20. These two restrictions are imposed by the internal FFT algorithm used.
xg
Type: array< System..::..Double >[]()[][]
An array of size [kc]
On entry: the nxy data points of the x series.
On exit: the real parts of the ng cross spectral estimates in elements xg[0] to xg[ng-1], and xg[ng] to xg[kc-1] contain 0.0. The y series leads the x series.
yg
Type: array< System..::..Double >[]()[][]
An array of size [kc]
On entry: the nxy data points of the y series.
On exit: the imaginary parts of the ng cross spectral estimates in elements yg[0] to yg[ng-1], and yg[ng] to yg[kc-1] contain 0.0. The y series leads the x series.
ng
Type: System..::..Int32 %
On exit: the number of spectral estimates, L/2+1, whose separate parts are held in xg and yg.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

The supplied time series may be mean and trend corrected and tapered as in the description of g13cb before calculation of the unsmoothed sample cross-spectrum
f xy*ω=1 2 πn∑t=1 n yt exp iωt×∑t=1 n xt exp-iωt
for frequency values ωj=2 πj K, 0≤ωj≤π.
A correction is made for bias due to any tapering.
As in the description of g13cb for univariate frequency window smoothing, the smoothed spectrum is returned as a subset of these frequencies,
νl=2 πl L,  l=0,1,…,L/2
where [ ] denotes the integer part.
Its real part or co-spectrum cf νl, and imaginary part or quadrature spectrum qf νl are defined by
f xy νl=cf νl+iqf νl=∑ωk<πMw~k f xy*νl+ωk
where the weights w~k are similar to the weights wk defined for g13cb, but allow for an implicit alignment shift S between the series:
w~k=wk exp-2 πiSk/L.
It is recommended that S is chosen as the lag k at which the cross-covariances c xy k peak, so as to minimize bias.
If no smoothing is required, the integer M, which determines the frequency window width 2 π M, should be set to n.
The bandwidth of the estimates will normally have been calculated in a previous call of g13cb for estimating the univariate spectra of yt and xt.

References

Bloomfield P (1976) Fourier Analysis of Time Series: An Introduction Wiley
Jenkins G M and Watts D G (1968) Spectral Analysis and its Applications Holden–Day

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | nxy<1,
or | mtxy<0,
or | mtxy>2,
or | pxy<0.0,
or | pxy>1.0,
or | mw<1,
or | mw>nxy,
or | pw<0.0 and mw≠nxy,
or | pw>1.0 and mw≠nxy,
or | l<1,
or | ish≥l.
ifail=2
On entry, | kc<2×nxy,
or | kc is not a multiple of l,
or | kc has a prime factor exceeding 19,
or | kc has more than 20 prime factors, counting repetitions.
ifail=3
This indicates that a serious error has occurred. Check all array subscripts in calls to g13cd. Seek expert help.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The FFT is a numerically stable process, and any errors introduced during the computation will normally be insignificant compared with uncertainty in the data.

Parallelism and Performance

None.

Further Comments

g13cd carries out an FFT of length kc to calculate the sample cross spectrum. The time taken by the method for this is approximately proportional to kc×log kc (but see method document (C06PAF not in this release) for further details).

Example

This example reads two time series of length 296. It selects mean correction and a 10% tapering proportion. It selects a 2 π/16 frequency width of smoothing window, a window shape parameter of 0.5 and an alignment shift of 3. It then calls g13cd to calculate the smoothed sample cross spectrum and prints the results.

Example program (C#): g13cde.cs

Example program data: g13cde.d

Example program results: g13cde.r

See Also

G13 Class
G13 Members


g13ce Method

[image]

NAG Library for .NET Release 2
G13..::g13ce Method
G13 Class See Also Send Feedback
For a bivariate time series, g13ce calculates the cross amplitude spectrum and squared coherency, together with lower and upper bounds from the univariate and bivariate (cross) spectra.

Syntax

C#
public static void g13ce(
    double[] xg,
    double[] yg,
    double[] xyrg,
    double[] xyig,
    int ng,
    double[] stats,
    double[] ca,
    double[] calw,
    double[] caup,
    out double t,
    double[] sc,
    double[] sclw,
    double[] scup,
    out int ifail
)
Visual Basic
Public Shared Sub g13ce ( _
    xg As Double(), _
    yg As Double(), _
    xyrg As Double(), _
    xyig As Double(), _
    ng As Integer, _
    stats As Double(), _
    ca As Double(), _
    calw As Double(), _
    caup As Double(), _
    <OutAttribute> ByRef t As Double, _
    sc As Double(), _
    sclw As Double(), _
    scup As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13ce(
    array<double>^ xg,
    array<double>^ yg,
    array<double>^ xyrg,
    array<double>^ xyig,
    int ng,
    array<double>^ stats,
    array<double>^ ca,
    array<double>^ calw,
    array<double>^ caup,
    [OutAttribute] double% t,
    array<double>^ sc,
    array<double>^ sclw,
    array<double>^ scup,
    [OutAttribute] int% ifail
)
F#
static member g13ce :
        xg : float[] *
        yg : float[] *
        xyrg : float[] *
        xyig : float[] *
        ng : int *
        stats : float[] *
        ca : float[] *
        calw : float[] *
        caup : float[] *
        t : float byref *
        sc : float[] *
        sclw : float[] *
        scup : float[] *
        ifail : int byref -> unit

Parameters

xg
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On entry: the ng univariate spectral estimates, f xx ω, for the x series.
yg
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On entry: the ng univariate spectral estimates, f yy ω, for the y series.
xyrg
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On entry: the real parts, cf ω, of the ng bivariate spectral estimates for the x and y series. The x series leads the y series.
xyig
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On entry: the imaginary parts, qf ω, of the ng bivariate spectral estimates for the x and y series. The x series leads the y series.
Note: the two univariate and the bivariate spectra must each have been calculated using the same method of smoothing. For rectangular, Bartlett, Tukey or Parzen smoothing windows, the same cut-off point of lag window and the same frequency division of the spectral estimates must be used. For the trapezium frequency smoothing window, the frequency width and the shape of the window and the frequency division of the spectral estimates must be the same. The spectral estimates and statistics must also be unlogged.
ng
Type: System..::..Int32
On entry: the number of spectral estimates in each of the arrays xg, yg, xyrg and xyig. It is also the number of cross amplitude spectral and squared coherency estimates.
Constraint: ng≥1.
stats
Type: array< System..::..Double >[]()[][]
An array of size [4]
On entry: the four associated statistics for the univariate spectral estimates for the x and y series. stats[0] contains the degrees of freedom, stats[1] and stats[2] contain the lower and upper bound multiplying factors respectively and stats[3] contains the bandwidth.
Constraints:
  • stats[0]≥3.0;
  • 0.0<stats[1]≤1.0;
  • stats[2]≥1.0.
ca
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On exit: the ng cross amplitude spectral estimates A^ω at each frequency of ω.
calw
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On exit: the ng lower bounds for the ng cross amplitude spectral estimates.
caup
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On exit: the ng upper bounds for the ng cross amplitude spectral estimates.
t
Type: System..::..Double %
On exit: the critical value for the significance of the squared coherency, T.
sc
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On exit: the ng squared coherency estimates, W^ω at each frequency ω.
sclw
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On exit: the ng lower bounds for the ng squared coherency estimates.
scup
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On exit: the ng upper bounds for the ng squared coherency estimates.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Estimates of the cross amplitude spectrum A ω and squared coherency W ω are calculated for each frequency ω as
A ω=f xy ω=cf ω 2+qf ω 2  andW ω=f xy ω 2 f xx ω f yy ω,
where
  • cf ω and qf ω are the co-spectrum and quadrature spectrum estimates between the series, i.e., the real and imaginary parts of the cross spectrum f xy ω as obtained using g13cc or g13cd;
  • f xx ω and f yy ω are the univariate spectrum estimates for the two series as obtained using g13ca or g13cb.
The same type and amount of smoothing should be used for these estimates, and this is specified by the degrees of freedom and bandwidth values which are passed from the calls of g13ca or g13cb.
Upper and lower 95% confidence limits for the cross amplitude are given approximately by
A ω1±1.96/d W ω-1+1,
except that a negative lower limit is reset to 0.0, in which case the approximation is rather poor. You are therefore particularly recommended to compare the coherency estimate W ω with the critical value T derived from the upper 5% point of the F-distribution on 2,d-2 degrees of freedom:
T=2 Fd-2+2 F,
where d is the degrees of freedom associated with the univariate spectrum estimates. The value of T is returned by the method.
The hypothesis that the series are unrelated at frequency ω, i.e., that both the true cross amplitude and coherency are zero, may be rejected at the 5% level if W ω>T. Tests at two frequencies separated by more than the bandwidth may be taken to be independent.
The confidence limits on A ω are strictly appropriate only at frequencies for which the coherency is significant. The same applies to the confidence limits on W ω which are however calculated at all frequencies using the approximation that arctanh W l is Normal with variance 1/d.

References

Bloomfield P (1976) Fourier Analysis of Time Series: An Introduction Wiley
Jenkins G M and Watts D G (1968) Spectral Analysis and its Applications Holden–Day

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | ng<1,
or | stats[0]<3.0,
or | stats[1]≤0.0,
or | stats[1]>1.0,
or | stats[2]<1.0.
ifail=2
A bivariate spectral estimate is zero. For this frequency the cross amplitude spectrum and squared coherency and their bounds are set to zero.
ifail=3
A univariate spectral estimate is negative. For this frequency the cross amplitude spectrum and squared coherency and their bounds are set to zero.
ifail=4
A univariate spectral estimate is zero. For this frequency the cross amplitude spectrum and squared coherency and their bounds are set to zero.
ifail=5
A calculated value of the squared coherency exceeds 1.0. For this frequency the squared coherency is reset to 1.0 and this value for the squared coherency is used in the formulae for the calculation of bounds for both the cross amplitude spectrum and squared coherency. This has the consequence that both squared coherency bounds are 1.0.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
If more than one failure of the types 2, 3, 4 and 5 occurs then the failure type which occurred at lowest frequency is returned in ifail. However the actions indicated above are also carried out for failures at higher frequencies.

Accuracy

All computations are very stable and yield good accuracy.

Parallelism and Performance

None.

Further Comments

The time taken by g13ce is approximately proportional to ng.

Example

This example reads the set of univariate spectrum statistics, the two univariate spectra and the cross spectrum at a frequency division of 2 π 20 for a pair of time series. It calls g13ce to calculate the cross amplitude spectrum and squared coherency and their bounds and prints the results.

Example program (C#): g13cee.cs

Example program data: g13cee.d

Example program results: g13cee.r

See Also

G13 Class
G13 Members


g13cf Method

[image]

NAG Library for .NET Release 2
G13..::g13cf Method
G13 Class See Also Send Feedback
For a bivariate time series, g13cf calculates the gain and phase together with lower and upper bounds from the univariate and bivariate spectra.

Syntax

C#
public static void g13cf(
    double[] xg,
    double[] yg,
    double[] xyrg,
    double[] xyig,
    int ng,
    double[] stats,
    double[] gn,
    double[] gnlw,
    double[] gnup,
    double[] ph,
    double[] phlw,
    double[] phup,
    out int ifail
)
Visual Basic
Public Shared Sub g13cf ( _
    xg As Double(), _
    yg As Double(), _
    xyrg As Double(), _
    xyig As Double(), _
    ng As Integer, _
    stats As Double(), _
    gn As Double(), _
    gnlw As Double(), _
    gnup As Double(), _
    ph As Double(), _
    phlw As Double(), _
    phup As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13cf(
    array<double>^ xg,
    array<double>^ yg,
    array<double>^ xyrg,
    array<double>^ xyig,
    int ng,
    array<double>^ stats,
    array<double>^ gn,
    array<double>^ gnlw,
    array<double>^ gnup,
    array<double>^ ph,
    array<double>^ phlw,
    array<double>^ phup,
    [OutAttribute] int% ifail
)
F#
static member g13cf :
        xg : float[] *
        yg : float[] *
        xyrg : float[] *
        xyig : float[] *
        ng : int *
        stats : float[] *
        gn : float[] *
        gnlw : float[] *
        gnup : float[] *
        ph : float[] *
        phlw : float[] *
        phup : float[] *
        ifail : int byref -> unit

Parameters

xg
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On entry: the ng univariate spectral estimates, f xx ω, for the x series.
yg
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On entry: the ng univariate spectral estimates, f yy ω, for the y series.
xyrg
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On entry: the real parts, cf ω, of the ng bivariate spectral estimates for the x and y series. The x series leads the y series.
xyig
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On entry: the imaginary parts, qf ω, of the ng bivariate spectral estimates for the x and y series. The x series leads the y series.
Note: the two univariate and the bivariate spectra must each have been calculated using the same method of smoothing. For rectangular, Bartlett, Tukey or Parzen smoothing windows, the same cut-off point of lag window and the same frequency division of the spectral estimates must be used. For the trapezium frequency smoothing window, the frequency width and the shape of the window and the frequency division of the spectral estimates must be the same. The spectral estimates and statistics must also be unlogged.
ng
Type: System..::..Int32
On entry: the number of spectral estimates in each of the arrays xg, yg, xyrg and xyig. It is also the number of gain and phase estimates.
Constraint: ng≥1.
stats
Type: array< System..::..Double >[]()[][]
An array of size [4]
On entry: the four associated statistics for the univariate spectral estimates for the x and y series. stats[0] contains the degrees of freedom, stats[1] and stats[2] contain the lower and upper bound multiplying factors respectively and stats[3] holds the bandwidth.
Constraint: stats[0]≥3.0.
gn
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On exit: the ng gain estimates, G^ω, at each frequency ω.
gnlw
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On exit: the ng lower bounds for the ng gain estimates.
gnup
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On exit: the ng upper bounds for the ng gain estimates.
ph
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On exit: the ng phase estimates, ϕ^ω, at each frequency ω.
phlw
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On exit: the ng lower bounds for the ng phase estimates.
phup
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On exit: the ng upper bounds for the ng phase estimates.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Estimates of the gain G ω and phase ϕ ω of the dependency of series y on series x at frequency ω are given by
G^ω=A ωf xx ωϕ^ω=arccos cf ωA ω,if ​qf ω≥0ϕ^ω=2 π-arccos cf ωA ω,if ​qf ω<0.
The quantities used in these definitions are obtained as in [Description] in g13ce.
Confidence limits are returned for both gain and phase, but should again be taken as very approximate when the coherency W ω, as calculated by g13ce, is not significant. These are based on the assumption that both G^ω/G ω-1 and ϕ^ω are Normal with variance
1 d 1 W ω-1.
Although the estimate of ϕ ω is always given in the range 0,2 π, no attempt is made to restrict its confidence limits to this range.

References

Bloomfield P (1976) Fourier Analysis of Time Series: An Introduction Wiley
Jenkins G M and Watts D G (1968) Spectral Analysis and its Applications Holden–Day

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | ng<1,
or | stats[0]<3.0.
ifail=2
A bivariate spectral estimate is zero. For this frequency the gain and the phase and their bounds are set to zero.
ifail=3
A univariate spectral estimate is negative. For this frequency the gain and the phase and their bounds are set to zero.
ifail=4
A univariate spectral estimate is zero. For this frequency the gain and the phase and their bounds are set to zero.
ifail=5
A calculated value of the squared coherency exceeds 1.0. For this frequency the squared coherency is reset to 1.0 in the formulae for the gain and phase bounds.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
If more than one failure of types 2, 3, 4 and 5 occurs then the failure type which occurred at lowest frequency is returned in ifail. However the actions indicated above are also carried out for failures at higher frequencies.

Accuracy

All computations are very stable and yield good accuracy.

Parallelism and Performance

None.

Further Comments

The time taken by g13cf is approximately proportional to ng.

Example

This example reads the set of univariate spectrum statistics, the two univariate spectra and the cross spectrum at a frequency division of 2 π 20 for a pair of time series. It calls g13cf to calculate the gain and the phase and their bounds and prints the results.

Example program (C#): g13cfe.cs

Example program data: g13cfe.d

Example program results: g13cfe.r

See Also

G13 Class
G13 Members


g13cg Method

[image]

NAG Library for .NET Release 2
G13..::g13cg Method
G13 Class See Also Send Feedback
For a bivariate time series, g13cg calculates the noise spectrum together with multiplying factors for the bounds and the impulse response function and its standard error, from the univariate and bivariate spectra.

Syntax

C#
public static void g13cg(
    double[] xg,
    double[] yg,
    double[] xyrg,
    double[] xyig,
    int ng,
    double[] stats,
    int l,
    int n,
    double[] er,
    out double erlw,
    out double erup,
    double[] rf,
    out double rfse,
    out int ifail
)
Visual Basic
Public Shared Sub g13cg ( _
    xg As Double(), _
    yg As Double(), _
    xyrg As Double(), _
    xyig As Double(), _
    ng As Integer, _
    stats As Double(), _
    l As Integer, _
    n As Integer, _
    er As Double(), _
    <OutAttribute> ByRef erlw As Double, _
    <OutAttribute> ByRef erup As Double, _
    rf As Double(), _
    <OutAttribute> ByRef rfse As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13cg(
    array<double>^ xg,
    array<double>^ yg,
    array<double>^ xyrg,
    array<double>^ xyig,
    int ng,
    array<double>^ stats,
    int l,
    int n,
    array<double>^ er,
    [OutAttribute] double% erlw,
    [OutAttribute] double% erup,
    array<double>^ rf,
    [OutAttribute] double% rfse,
    [OutAttribute] int% ifail
)
F#
static member g13cg :
        xg : float[] *
        yg : float[] *
        xyrg : float[] *
        xyig : float[] *
        ng : int *
        stats : float[] *
        l : int *
        n : int *
        er : float[] *
        erlw : float byref *
        erup : float byref *
        rf : float[] *
        rfse : float byref *
        ifail : int byref -> unit

Parameters

xg
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On entry: the ng univariate spectral estimates, f xx ω, for the x series.
yg
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On entry: the ng univariate spectral estimates, f yy ω, for the y series.
xyrg
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On entry: the real parts, cf ω, of the ng bivariate spectral estimates for the x and y series. The x series leads the y series.
xyig
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On entry: the imaginary parts, qf ω, of the ng bivariate spectral estimates for the x and y series. The x series leads the y series.
Note: the two univariate and the bivariate spectra must each have been calculated using the same method of smoothing. For rectangular, Bartlett, Tukey or Parzen smoothing windows, the same cut-off point of lag window and the same frequency division of the spectral estimates must be used. For the trapezium frequency smoothing window, the frequency width and the shape of the window and the frequency division of the spectral estimates must be the same. The spectral estimates and statistics must also be unlogged.
ng
Type: System..::..Int32
On entry: the number of spectral estimates in each of the arrays xg, yg, xyrg, xyig. It is also the number of noise spectral estimates.
Constraint: ng≥1.
stats
Type: array< System..::..Double >[]()[][]
An array of size [4]
On entry: the four associated statistics for the univariate spectral estimates for the x and y series. stats[0] contains the degree of freedom, stats[1] and stats[2] contain the lower and upper bound multiplying factors respectively and stats[3] contains the bandwidth.
Constraints:
  • stats[0]≥3.0;
  • 0.0<stats[1]≤1.0;
  • stats[2]≥1.0.
l
Type: System..::..Int32
On entry: L, the frequency division of the spectral estimates as 2 π L. It is also the order of the FFT used to calculate the impulse response function. l must relate to the parameter ng by the relationship.
Constraints:
  • ng=L/2+1;
  • The largest prime factor of l must not exceed 19, and the total number of prime factors of l, counting repetitions, must not exceed 20. These two restrictions are imposed by the internal FFT algorithm used.
n
Type: System..::..Int32
On entry: the number of points in each of the time series x and y. n should have the same value as nxy in the call of g13cc or g13cd which calculated the smoothed sample cross spectrum. n is used in calculating the impulse response function standard error (rfse).
Constraint: n≥1.
er
Type: array< System..::..Double >[]()[][]
An array of size [ng]
On exit: the ng estimates of the noise spectrum, f^y∣x ω at each frequency.
erlw
Type: System..::..Double %
On exit: the noise spectrum lower limit multiplying factor.
erup
Type: System..::..Double %
On exit: the noise spectrum upper limit multiplying factor.
rf
Type: array< System..::..Double >[]()[][]
An array of size [l]
On exit: the impulse response function. Causal responses are stored in ascending frequency in rf[0] to rf[ng-1] and anticipatory responses are stored in descending frequency in rf[ng] to rf[l-1].
rfse
Type: System..::..Double %
On exit: the impulse response function standard error.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

An estimate of the noise spectrum in the dependence of series y on series x at frequency ω is given by
f y∣x ω=f yy ω1-W ω,
where W ω is the squared coherency described in g13ce and f yy ω is the univariate spectrum estimate for series y. Confidence limits on the true spectrum are obtained using multipliers as described for g13ca, but based on d-2 degrees of freedom.
If the dependence of yt on xt can be assumed to be represented in the time domain by the one sided relationship
yt=v 0xt+v 1x t-1+⋯+nt,
where the noise nt is independent of xt, then it is the spectrum of this noise which is estimated by f y∣x ω.
Estimates of the impulse response function v 0,v 1,v 2,… may also be obtained as
vk=1 π∫0 π Re exp ikω f xy ωf xx ω,
where Re indicates the real part of the expression. For this purpose it is essential that the univariate spectrum for x, f xx ω, and the cross spectrum, f xy ω, be supplied to this method for a frequency range
ωl=2 πl L,  0≤l≤L/2,
where denotes the integer part, the integral being approximated by a finite Fourier transform.
An approximate standard error is calculated for the estimates vk. Significant values of vk in the locations described as anticipatory responses in the parameter array rf indicate that feedback exists from yt to xt. This will bias the estimates of vk in any causal dependence of yt on xt,x t-1,….

References

Bloomfield P (1976) Fourier Analysis of Time Series: An Introduction Wiley
Jenkins G M and Watts D G (1968) Spectral Analysis and its Applications Holden–Day

Error Indicators and Warnings

Note: g13cg may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail=1
On entry, | ng<1,
or | stats[0]<3.0,
or | stats[1]≤0.0,
or | stats[1]>1.0,
or | stats[2]<1.0,
or | n<1.
ifail=2
A bivariate spectral estimate is zero. For this frequency the noise spectrum is set to zero, and the contribution to the impulse response function and its standard error is set to zero.
ifail=3
A univariate spectral estimate is negative. For this frequency the noise spectrum is set to zero, and the contributions to the impulse response function and its standard error are set to zero.
ifail=4
A univariate spectral estimate is zero. For this frequency the noise spectrum is set to zero and the contributions to the impulse response function and its standard error are set to zero.
ifail=5
A calculated value of the squared coherency exceeds 1.0. For this frequency the squared coherency is reset to 1.0 with the consequence that the noise spectrum is zero and the contribution to the impulse response function at this frequency is zero.
ifail=6
On entry, | l/2+1≠ng,
or | l has a prime factor exceeding 19,
or | l has more than 20 prime factors, counting repetitions.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value
If more than one failure of types 2, 3, 4 and 5 occurs then the failure type which occurred at lowest frequency is returned in ifail. However the actions indicated above are also carried out for failures at higher frequencies.

Accuracy

The computation of the noise is stable and yields good accuracy. The FFT is a numerically stable process, and any errors introduced during the computation will normally be insignificant compared with uncertainty in the data.

Parallelism and Performance

None.

Further Comments

The time taken by g13cg is approximately proportional to ng.

Example

This example reads the set of univariate spectrum statistics, the two univariate spectra and the cross spectrum at a frequency division of 2 π 20 for a pair of time series. It calls g13cg to calculate the noise spectrum and its confidence limits multiplying factors, the impulse response function and its standard error. It then prints the results.

Example program (C#): g13cge.cs

Example program data: g13cge.d

Example program results: g13cge.r

See Also

G13 Class
G13 Members


g13dd Method

[image]

NAG Library for .NET Release 2
G13..::g13dd Method
G13 Class See Also Send Feedback
g13dd fits a vector autoregressive moving average (VARMA) model to an observed vector of time series using the method of Maximum Likelihood (ML). Standard errors of parameter estimates are computed along with their appropriate correlation matrix. The method also calculates estimates of the residual series.

Syntax

C#
public static void g13dd(
    int k,
    int n,
    int ip,
    int iq,
    bool mean,
    double[] par,
    double[,] qq,
    double[,] w,
    bool[] parhld,
    bool exact,
    int iprint,
    double cgetol,
    int maxcal,
    int ishow,
    out int niter,
    out double rlogl,
    double[,] v,
    double[] g,
    double[,] cm,
    out int ifail
)
Visual Basic
Public Shared Sub g13dd ( _
    k As Integer, _
    n As Integer, _
    ip As Integer, _
    iq As Integer, _
    mean As Boolean, _
    par As Double(), _
    qq As Double(,), _
    w As Double(,), _
    parhld As Boolean(), _
    exact As Boolean, _
    iprint As Integer, _
    cgetol As Double, _
    maxcal As Integer, _
    ishow As Integer, _
    <OutAttribute> ByRef niter As Integer, _
    <OutAttribute> ByRef rlogl As Double, _
    v As Double(,), _
    g As Double(), _
    cm As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13dd(
    int k,
    int n,
    int ip,
    int iq,
    bool mean,
    array<double>^ par,
    array<double,2>^ qq,
    array<double,2>^ w,
    array<bool>^ parhld,
    bool exact,
    int iprint,
    double cgetol,
    int maxcal,
    int ishow,
    [OutAttribute] int% niter,
    [OutAttribute] double% rlogl,
    array<double,2>^ v,
    array<double>^ g,
    array<double,2>^ cm,
    [OutAttribute] int% ifail
)
F#
static member g13dd :
        k : int *
        n : int *
        ip : int *
        iq : int *
        mean : bool *
        par : float[] *
        qq : float[,] *
        w : float[,] *
        parhld : bool[] *
        exact : bool *
        iprint : int *
        cgetol : float *
        maxcal : int *
        ishow : int *
        niter : int byref *
        rlogl : float byref *
        v : float[,] *
        g : float[] *
        cm : float[,] *
        ifail : int byref -> unit

Parameters

k
Type: System..::..Int32
On entry: k, the number of observed time series.
Constraint: k≥1.
n
Type: System..::..Int32
On entry: n, the number of observations in each time series.
ip
Type: System..::..Int32
On entry: p, the number of AR parameter matrices.
Constraint: ip≥0.
iq
Type: System..::..Int32
On entry: q, the number of MA parameter matrices.
Constraint: iq≥0.
ip=iq=0 is not permitted.
mean
Type: System..::..Boolean
On entry: mean=true, if components of μ have been estimated and mean=false, if all elements of μ are to be taken as zero.
Constraint: mean=true or false.
par
Type: array< System..::..Double >[]()[][]
An array of size [npar]
On entry: initial parameter estimates read in row by row in the order ϕ 1,ϕ 2,…,ϕp, θ 1,θ 2,…,θq,μ.
Thus,
  • if ip>0, par[l-1×k×k+i-1×k+j-1] must be set equal to an initial estimate of the i,jth element of ϕl, for l=1,2,…,p, i=1,2,…,k and j=1,2,…,k;
  • if iq>0, par[p×k×k+l-1×k×k+i-1×k+j-1] must be set equal to an initial estimate of the i,jth element of θl, l=1,2,…,q and i,j=1,2,…,k;
  • if mean=true, par[p+q×k×k+i-1] should be set equal to an initial estimate of the ith component of μ (μ i). (If you set par[p+q×k×k+i-1] to 0.0 then g13dd will calculate the mean of the ith series and use this as an initial estimate of μ i.)
The first p×k×k elements of par must satisfy the stationarity condition and the next q×k×k elements of par must satisfy the invertibility condition.
If in doubt set all elements of par to 0.0.
On exit: if ifail=0 or ifail≥4 then all the elements of par will be overwritten by the latest estimates of the corresponding ARMA parameters.
qq
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, k]
Note: dim1 must satisfy the constraint: dim1≥k
On entry: qq[i-1,j-1] must be set equal to an initial estimate of the i,jth element of Σ. The lower triangle only is needed. qq must be positive definite. It is strongly recommended that on entry the elements of qq are of the same order of magnitude as at the solution point. If you set qq[i-1,j-1]=0.0, for i=1,2,…,k and j=1,2,…,i, then g13dd will calculate the covariance matrix between the k time series and use this as an initial estimate of Σ.
On exit: if ifail=0 or ifail≥4 then qq[i-1,j-1] will contain the latest estimate of the i,jth element of Σ. The lower triangle only is returned.
w
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥k
On entry: w[i-1,t-1] must be set equal to the ith component of Wt, for i=1,2,…,k and t=1,2,…,n.
parhld
Type: array< System..::..Boolean >[]()[][]
An array of size [npar]
On entry: parhld[i-1] must be set to true if par[i-1] is to be held constant at its input value and false if par[i-1] is a free parameter, for i=1,2,…,npar.
If in doubt try setting all elements of parhld to false.
exact
Type: System..::..Boolean
On entry: must be set equal to true if you wish g13dd to compute exact maximum likelihood estimates. exact must be set equal to false if only conditional likelihood estimates are required.
iprint
Type: System..::..Int32
On entry: the frequency with which the automatic monitoring method is to be called.
iprint>0
The ML search procedure is monitored once every iprint iterations and just before exit from the search method.
iprint=0
The search method is monitored once at the final point.
iprint<0
The search method is not monitored at all.
cgetol
Type: System..::..Double
On entry: the accuracy to which the solution in par and qq is required.
If cgetol is set to 10-l and on exit ifail=0 or ifail≥6, then all the elements in par and qq should be accurate to approximately l decimal places. For most practical purposes the value 10-4 should suffice. You should be wary of setting cgetol too small since the convergence criteria may then have become too strict for the machine to handle.
If cgetol has been set to a value which is less than the machine precision, ε, then g13dd will use the value 10.0×ε instead.
maxcal
Type: System..::..Int32
On entry: the maximum number of likelihood evaluations to be permitted by the search procedure.
Suggested value: maxcal=40×npar×npar+5.
Constraint: maxcal≥1.
ishow
Type: System..::..Int32
On entry: specifies which of the following two quantities are to be printed.
(i) | table of maximum likelihood estimates and their standard errors (as returned in the output arrays par, qq and cm);
(ii) | table of residual series (as returned in the output array v).
ishow=0
None of the above are printed.
ishow=1
(i) only is printed.
ishow=2
(i) and (ii) are printed.
Constraint: 0≤ishow≤2.
niter
Type: System..::..Int32 %
On exit: if ifail=0 or ifail≥4 then niter contains the number of iterations performed by the search method.
rlogl
Type: System..::..Double %
On exit: if ifail=0 or ifail≥4 then rlogl contains the value of the log-likelihood function corresponding to the final point held in par and qq.
v
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥k
On exit: if ifail=0 or ifail≥4 then v[i-1,t-1] will contain an estimate of the ith component of εt, for i=1,2,…,k and t=1,2,…,n, corresponding to the final point held in par and qq.
g
Type: array< System..::..Double >[]()[][]
An array of size [npar]
On exit: if ifail=0 or ifail≥4 then g[i-1] will contain the estimated first derivative of the log-likelihood function with respect to the ith element in the array par. If the gradient cannot be computed then all the elements of g are returned as zero.
cm
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, npar]
Note: dim1 must satisfy the constraint: dim1≥npar
On exit: if ifail=0 or ifail≥4 then cm[i-1,j-1] will contain an estimate of the correlation coefficient between the ith and jth elements in the par array for 1≤i≤npar, 1≤j≤npar. If i=j, then cm[i-1,j-1] will contain the estimated standard error of par[i-1]. If the lth component of par has been held constant, i.e., parhld[l-1] was set to true, then the lth row and column of cm will be set to zero. If the second derivative matrix cannot be computed then all the elements of cm are returned as zero.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Let Wt=w 1 t,w 2 t,…,w kt T, for t=1,2,…,n, denote a vector of k time series which is assumed to follow a multivariate ARMA model of the form
Wt-μ=ϕ 1 W t-1-μ+ϕ 2 W t-2-μ+⋯+ϕp W t-p-μ+εt-θ 1ε t-1-θ 2ε t-2-⋯-θqε t-q (1)
where εt=ε 1 t,ε 2 t,…,ε kt T, for t=1,2,…,n, is a vector of k residual series assumed to be Normally distributed with zero mean and positive definite covariance matrix Σ. The components of εt are assumed to be uncorrelated at non-simultaneous lags. The ϕi and θj are k by k matrices of parameters. ϕi, for i=1,2,…,p, are called the autoregressive (AR) parameter matrices, and θi, for i=1,2,…,q, the moving average (MA) parameter matrices. The parameters in the model are thus the p (k by k) ϕ-matrices, the q (k by k) θ-matrices, the mean vector, μ, and the residual error covariance matrix Σ. Let
A ϕ=ϕ 1I0...0ϕ 20I0..0......ϕ p-10...0Iϕp0...00 pk×pk  and B θ=θ 1I0...0θ 20I0..0......θ q-10....Iθq0....0 qk×qk
where I denotes the k by k identity matrix.
The ARMA model (1) is said to be stationary if the eigenvalues of A ϕ lie inside the unit circle. Similarly, the ARMA model (1) is said to be invertible if the eigenvalues of B θ lie inside the unit circle.
The method of computing the exact likelihood function (using a Kalman filter algorithm) is discussed in Shea (1987). A quasi-Newton algorithm (see Gill and Murray (1972)) is then used to search for the maximum of the log-likelihood function. Stationarity and invertibility are enforced on the model using the reparameterisation discussed in Ansley and Kohn (1986). Conditional on the maximum likelihood estimates being equal to their true values the estimates of the residual series are uncorrelated with zero mean and constant variance Σ.
You have the option of setting a parameter (exact to false) so that g13dd calculates conditional maximum likelihood estimates (conditional on W 0=W-1=⋯=W 1-p=ε 0=ε-1=⋯=ε 1-q=0). This may be useful if the exact maximum likelihood estimates are close to the boundary of the invertibility region.
You also have the option (see [Parameters]) of requesting g13dd to constrain elements of the ϕ and θ matrices and μ vector to have pre-specified values.

References

Ansley C F and Kohn R (1986) A note on reparameterising a vector autoregressive moving average model to enforce stationarity J. Statist. Comput. Simulation 24 99–106
Gill P E and Murray W (1972) Quasi-Newton methods for unconstrained optimization J. Inst. Math. Appl. 9 91–108
Shea B L (1987) Estimation of multivariate time series J. Time Ser. Anal. 8 95–110

Error Indicators and Warnings

Note: g13dd may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (KMAX, LDCM) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | k<1,
or | ip<0,
or | iq<0,
or | ip=iq=0,
or | npar≠ip+iq×k×k+Δ×k, where Δ=1 if mean=true or Δ=0 if mean=false,
or | n×k≤npar+k×k+1/2,
or | maxcal<1,
or | ishow<0,
or | ishow>2,
ifail=2
On entry, either the initial estimate of Σ is not positive definite, or the initial estimates of the AR parameters are such that the model is non-stationary, or the initial estimates of the MA parameters are such that the model is non-invertible. To proceed, you must try a different starting point.
ifail=3
The method cannot compute a sufficiently accurate estimate of the gradient vector at the user-supplied starting point. This usually occurs if either the initial parameter estimates are very close to the ML parameter estimates, or you have supplied a very poor estimate of Σ or the starting point is very close to the boundary of the stationarity or invertibility region. To proceed, you must try a different starting point.
ifail=4
There have been maxcal log-likelihood evaluations made in the method. If steady increases in the log-likelihood function were monitored up to the point where this exit occurred, then the exit probably simply occurred because maxcal was set too small, so the calculations should be restarted from the final point held in par and qq. This type of exit may also indicate that there is no maximum to the likelihood surface. Output quantities (as described in [Parameters]) are computed at the final point held in par and qq, except that if g or cm cannot be computed, in which case they are set to zero.
ifail=5
The conditions for a solution have not all been met, but a point at which the log-likelihood took a larger value could not be found.
Provided that the estimated first derivatives are sufficiently small, and that the estimated condition number of the second derivative (Hessian) matrix, as printed when iprint≥0, is not too large, this error exit may simply mean that, although it has not been possible to satisfy the specified requirements, the algorithm has in fact found the solution as far as the accuracy of the machine permits.
Such a condition can arise, for instance, if cgetol has been set so small that rounding error in evaluating the likelihood function makes attainment of the convergence conditions impossible.
If the estimated condition number at the final point is large, it could be that the final point is a solution but that the smallest eigenvalue of the Hessian matrix is so close to zero at the solution that it is not possible to recognize it as a solution. Output quantities (as described in [Parameters]) are computed at the final point held in par and qq, except that if g or cm cannot be computed, in which case they are set to zero.
ifail=6
The ML solution is so close to the boundary of either the stationarity region or the invertibility region that g13dd cannot evaluate the Hessian matrix. The elements of cm will then be set to zero on exit. The elements of g will also be set to zero. All other output quantities will be correct.
ifail=7
This is an unlikely exit, which could occur in e04xaa, which computes an estimate of the second derivative matrix and the gradient vector at the solution point. Either the Hessian matrix was found to be too ill-conditioned to be evaluated accurately or the gradient vector could not be computed to an acceptable degree of accuracy. In this case the elements of cm will be set to zero on exit as will the elements of g. All other output quantities will be correct.
ifail=8
The second derivative matrix at the solution point is not positive definite. In this case the elements of cm will be set to zero on exit. All other output quantities will be correct.
ifail=-999
Internal memory allocation failed.
ifail=-9000
An error occured, see message report.
ifail=-1000
The array lengths are not the same for arrays
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

On exit from g13dd, if ifail=0 or ifail≥6 and cgetol has been set to 10-l, then all the parameters should be accurate to approximately l decimal places. If cgetol was set equal to a value less than the machine precision, ε, then all the parameters should be accurate to approximately 10.0×ε.
If ifail=4 on exit (i.e., maxcal likelihood evaluations have been made but the convergence conditions of the search method have not been satisfied), then the elements in par and qq may still be good approximations to the ML estimates. Inspection of the elements of g may help you determine whether this is likely.

Parallelism and Performance

None.

Further Comments

Memory Usage

Let r=max ip,iq and s=npar+k×k+1/2. Local workspace arrays of fixed lengths are allocated internally by g13dd. The total size of these arrays amounts to s+k×r+52 integer elements and 2×s 2+s×s-1/2+15×s+k 2×2×ip+iq+r+3 2+k×2×r 2+2×r+3×n+4+10 real elements.

Timing

The number of iterations required depends upon the number of parameters in the model and the distance of the user-supplied starting point from the solution.

Constraining for Stationarity and Invertibility

If the solution lies on the boundary of the admissibility region (stationarity and invertibility region) then g13dd may get into difficulty and exit with ifail=5. If this exit occurs you are advised to either try a different starting point or a different setting for exact. If this still continues to occur then you are urged to try fitting a more parsimonious model.

Over-parameterisation

You are advised to try and avoid fitting models with an excessive number of parameters since over-parameterisation can cause the maximization problem to become ill-conditioned.

Standardizing the Residual Series

The standardized estimates of the residual series εt (denoted by e^t) can easily be calculated by forming the Cholesky decomposition of Σ, e.g., G GT and setting e^t=G-1 ε^t. (F07FDF not in this release) may be used to calculate the array g. The components of e^t which are now uncorrelated at all lags can sometimes be more easily interpreted.

Assessing the Fit of the Model

If your time series model provides a good fit to the data then the residual series should be approximately white noise, i.e., exhibit no serial cross-correlation. An examination of the residual cross-correlation matrices should confirm whether this is likely to be so. You are advised to call (G13DSF not in this release) to provide information for diagnostic checking. (G13DSF not in this release) returns the residual cross-correlation matrices along with their asymptotic standard errors. (G13DSF not in this release) also computes a portmanteau statistic and its asymptotic significance level for testing model adequacy. If ifail=0 or 5≤ifail≤8 on exit from g13dd then the quantities output k, n, v, kmax, ip, iq, par, parhld, and qq will be suitable for input to (G13DSF not in this release).

Example

This example shows how to fit a bivariate AR(1) model to two series each of length 48. μ will be estimated and ϕ 1 2,1 will be constrained to be zero.

Example program (C#): g13dde.cs

Example program data: g13dde.d

Example program results: g13dde.r

See Also

G13 Class
G13 Members


g13dj Method

[image]

NAG Library for .NET Release 2
G13..::g13dj Method
G13 Class See Also Send Feedback
g13dj computes forecasts of a multivariate time series. It is assumed that a vector ARMA model has already been fitted to the appropriately differenced/transformed time series using g13dd. The standard deviations of the forecast errors are also returned. A reference vector is set up so that, should future series values become available, the forecasts and their standard errors may be updated by calling g13dk.

Syntax

C#
public static void g13dj(
    int k,
    int n,
    double[,] z,
    string[] tr,
    int[] id,
    double[,] delta,
    int ip,
    int iq,
    string mean,
    double[] par,
    double[,] qq,
    double[,] v,
    int lmax,
    double[,] predz,
    double[,] sefz,
    double[] dnref,
    out int ifail
)
Visual Basic
Public Shared Sub g13dj ( _
    k As Integer, _
    n As Integer, _
    z As Double(,), _
    tr As String(), _
    id As Integer(), _
    delta As Double(,), _
    ip As Integer, _
    iq As Integer, _
    mean As String, _
    par As Double(), _
    qq As Double(,), _
    v As Double(,), _
    lmax As Integer, _
    predz As Double(,), _
    sefz As Double(,), _
    dnref As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13dj(
    int k,
    int n,
    array<double,2>^ z,
    array<String^>^ tr,
    array<int>^ id,
    array<double,2>^ delta,
    int ip,
    int iq,
    String^ mean,
    array<double>^ par,
    array<double,2>^ qq,
    array<double,2>^ v,
    int lmax,
    array<double,2>^ predz,
    array<double,2>^ sefz,
    array<double>^ dnref,
    [OutAttribute] int% ifail
)
F#
static member g13dj :
        k : int *
        n : int *
        z : float[,] *
        tr : string[] *
        id : int[] *
        delta : float[,] *
        ip : int *
        iq : int *
        mean : string *
        par : float[] *
        qq : float[,] *
        v : float[,] *
        lmax : int *
        predz : float[,] *
        sefz : float[,] *
        dnref : float[] *
        ifail : int byref -> unit

Parameters

k
Type: System..::..Int32
On entry: k, the dimension of the multivariate time series.
Constraint: k≥1.
n
Type: System..::..Int32
On entry: n, the number of observations in the series, Zt, prior to differencing.
Constraint: n≥3.
The total number of observations must exceed the total number of parameters in the model; that is
  • if mean="Z", n×k>ip+iq×k×k+k×k+1/2;
  • if mean="M", n×k>ip+iq×k×k+k+k×k+1/2,
(see the parameters ip, iq and mean).
z
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1≥k
On entry: z[i,t] must contain, z it, the ith component of Zt, for i=1,2,…,k and t=1,2,…,n.
Constraints:
  • if tr[i-1]="L", z[i,t]>0.0;
  • if tr[i-1]="S", z[i,t]≥0.0, for i=0,1,…,k-1 and t=0,1,…,n-1.
tr
Type: array< System..::..String >[]()[][]
An array of size [k]
On entry: tr[i-1] indicates whether the ith time series is to be transformed, for i=1,2,…,k.
tr[i-1]="N"
No transformation is used.
tr[i-1]="L"
A log transformation is used.
tr[i-1]="S"
A square root transformation is used.
Constraint: tr[i-1]="N", "L" or "S", for i=1,2,…,k.
id
Type: array< System..::..Int32 >[]()[][]
An array of size [k]
On entry: id[i-1] must specify, di, the order of differencing required for the ith series.
Constraint: 0≤id[i-1]<n-max ip,iq, for i=1,2,…,k.
delta
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥k
Note: the second dimension of the array delta must be at least max 1,d, where d=max id[i-1].
On entry: if id[i-1]>0, then delta[i-1,j-1] must be set equal to δ ij, for j=1,2,…,di and i=1,2,…,k.
If d=0, delta is not referenced.
ip
Type: System..::..Int32
On entry: p, the number of AR parameter matrices.
Constraint: ip≥0.
iq
Type: System..::..Int32
On entry: q, the number of MA parameter matrices.
Constraint: iq≥0.
mean
Type: System..::..String
On entry: mean="M", if components of μ have been estimated and mean="Z", if all elements of μ are to be taken as zero.
Constraint: mean="M" or "Z".
par
Type: array< System..::..Double >[]()[][]
An array of size [lpar]
On entry: must contain the parameter estimates read in row by row in the order ϕ 1,ϕ 2,…,ϕp, θ 1,θ 2,…,θq, μ.
Thus,
  • if ip>0, par[l-1×k×k+i-1×k+j-1] must be set equal to an estimate of the i,jth element of ϕl, for l=1,2,…,p, i=1,2,…,k and j=1,2,…,k;
  • if iq>0, par[p×k×k+l-1×k×k+i-1×k+j-1] must be set equal to an estimate of the i,jth element of θl, for l=1,2,…,q, i=1,2,…,k and j=1,2,…,k;
  • if mean="M", par[p+q×k×k+i-1] must be set equal to an estimate of the ith component of μ, for i=1,2,…,k.
Constraint: the first ip×k×k elements of par must satisfy the stationarity condition and the next iq×k×k elements of par must satisfy the invertibility condition.
qq
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, k]
Note: dim1 must satisfy the constraint: dim1≥k
On entry: qq[i-1,j-1] must contain an estimate of the i,jth element of Σ. The lower triangle only is needed.
Constraint: qq must be positive definite.
On exit: if ifail≠1, then the upper triangle is set equal to the lower triangle.
v
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥k
Note: the second dimension of the array v must be at least max 1,n-d, where d=max id[i-1].
On entry: v[i-1,t-1] must contain an estimate of the ith component of ε t+d, for i=1,2,…,k and t=1,2,…,n-d.
If q=0, v is not used.
lmax
Type: System..::..Int32
On entry: the number, lmax, of forecasts required.
Constraint: lmax≥1.
predz
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, lmax]
Note: dim1 must satisfy the constraint: dim1≥k
On exit: predz[i-1,l-1] contains the forecast of z i,n+l, for i=1,2,…,k and l=1,2,…,lmax.
sefz
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, lmax]
Note: dim1 must satisfy the constraint: dim1≥k
On exit: sefz[i-1,l-1] contains an estimate of the standard error of the forecast of z i,n+l, for i=1,2,…,k and l=1,2,…,lmax.
dnref
Type: array< System..::..Double >[]()[][]
An array of size [lref]
On exit: the reference vector which may be used to update forecasts using g13dk. The first lmax-1×k×k elements contain the ψ weight matrices, ψ 1,ψ 2,…,ψ lmax-1. The next k×lmax elements contain the forecasts of the transformed series Z^n+1*,Z^n+2*,…,Z^n+lmax* and the next k×lmax contain the variances of the forecasts of the transformed variables. The last k elements are used to store the transformations for the series.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Let the vector Zt=z 1 t,z 2 t,…,z kt T, for t=1,2,…,n, denote a k-dimensional time series for which forecasts of Z n+1,Z n+2,…,Z n+lmax are required. Let Wt=w 1 t,w 2 t,…,w kt T be defined as follows:
w it=δi B z it*,  i=1,2,…,k,
where δi B is the differencing operator applied to the ith series and where z it* is equal to either z it, z it or loge z it depending on whether or not a transformation was required to stabilize the variance before fitting the model.
If the order of differencing required for the ith series is di, then the differencing operator for the ith series is defined by δi B=1-δ i 1 B-δ i 2 B 2-⋯-δ i di B di where B is the backward shift operator; that is, B Zt=Z t-1. The differencing parameters δ ij, for i=1,2,…,k and j=1,2,…,di, must be supplied by you. If the ith series does not require differencing, then di=0.
Wt is assumed to follow a multivariate ARMA model of the form:
Wt-μ=ϕ 1 W t-1-μ+ϕ 2 W t-2-μ+⋯+ϕp W t-p-μ+εt-θ 1ε t-1-⋯-θqε t-q, (1)
where εt=ε 1 t,ε 2 t,…,ε kt T, for t=1,2,…,n, is a vector of k residual series assumed to be Normally distributed with zero mean and positive definite covariance matrix Σ. The components of εt are assumed to be uncorrelated at non-simultaneous lags. The ϕi and θj are k by k matrices of parameters. The matrices ϕi, for i=1,2,…,p, are the autoregressive (AR) parameter matrices, and the matrices θi, for i=1,2,…,q, the moving average (MA) parameter matrices. The parameters in the model are thus the p (k by k) ϕ-matrices, the q (k by k) θ-matrices, the mean vector μ and the residual error covariance matrix Σ. The ARMA model (1) must be both stationary and invertible; see g13dx for a method of checking these conditions.
The ARMA model (1) may be rewritten as
ϕ Bδ B Zt*-μ=θ B εt,
where ϕ B and θ B are the autoregressive and moving average polynomials and δ B denotes the k by k diagonal matrix whose ith diagonal elements is δi B and Zt*=z 1 t*,z 2 t*…z kt*T.
This may be rewritten as
ϕ B δ B Zt*=ϕ B μ+θ B εt
or
Zt*=τ+ψ B εt=τ+εt+ψ 1ε t-1+ψ 2ε t-2+⋯
where ψ B=δ-1 B ϕ-1 B θ B and τ=δ-1 B μ is a vector of length k.
Forecasts are computed using a multivariate version of the procedure described in Box and Jenkins (1976). If Z^n*l denotes the forecast of Z n+l*, then Z^n*l is taken to be that linear function of Zn*,Z n-1*,… which minimizes the elements of E en l en′l where en l=Z n+l*-Z^n*l is the forecast error. Z^n*l is referred to as the linear minimum mean square error forecast of Z n+l*.
The linear predictor which minimizes the mean square error may be expressed as
Z^n*l=τ+ψlεn+ψ l+1ε n-1+ψ l+2ε n-2+⋯.
The forecast error at t for lead l is then
en l=Z n+l*-Z^n*l=ε n+l+ψ 1ε n+l-1+ψ 2ε n+l-2+⋯+ψ l-1ε n+1.
Let d=max di, for i=1,2,…,k. Unless q=0 the method requires estimates of εt, for t=d+1,…,n, which are obtainable from g13dd. The terms εt are assumed to be zero, for t=n+1,…,n+lmax. You may use g13dk to update these lmax forecasts should further observations, Z n+1,Z n+2,…, become available. Note that when lmax or more further observations are available then g13dj must be used to produce new forecasts for Z n+lmax+1,Z n+lmax+2,…, should they be required.
When a transformation has been used the forecasts and their standard errors are suitably modified to give results in terms of the original series, Zt; see Granger and Newbold (1976).

References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day
Granger C W J and Newbold P (1976) Forecasting transformed series J. Roy. Statist. Soc. Ser. B 38 189–203
Wei W W S (1990) Time Series Analysis: Univariate and Multivariate Methods Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (KMAX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | k<1,
or | n<3,
or | id[i-1]<0 for some i=1,2,…,k,
or | id[i-1]≥n-max ip,iq for some i=1,2,…,k,
or | ip<0,
or | iq<0,
or | mean≠"M" or "Z",
or | lpar<ip+iq×k×k+k, and mean="M",
or | lpar<ip+iq×k×k and mean="Z",
or | n×k≤ip+iq×k×k+k+k[k]/2, and mean="M",
or | n×k≤ip+iq×k×k+k[k]/2 and mean="Z",
or | lmax<1,
or | lref<lmax-1×k×k+2×k×lmax+k,
or | lwork is too small,
or | liwork is too small.
ifail=2
On entry, at least one of the first k elements of tr is not equal to "N", "L" or "S".
ifail=3
On entry, one or more of the transformations requested cannot be computed; that is, you may be trying to log or square-root a series, some of whose values are negative.
ifail=4
On entry, either qq is not positive definite or the autoregressive parameter matrices are extremely close to or outside the stationarity region, or the moving average parameter matrices are extremely close to or outside the invertibility region. To proceed, you must supply different parameter estimates in the arrays par and qq.
ifail=5
This is an unlikely exit brought about by an excessive number of iterations being needed to evaluate the eigenvalues of the matrices required to check for stationarity and invertibility; see g13dx. All output parameters are undefined.
ifail=6
This is an unlikely exit which could occur if qq is nearly non positive definite. In this case the standard deviations of the forecast errors may be non-positive. To proceed, you must supply different parameter estimates in the array qq.
ifail=7
This is an unlikely exit. For one of the series, overflow will occur if the forecasts are computed. You should check whether the transformations requested in the array tr are sensible. All output parameters are undefined.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The matrix computations are believed to be stable.

Parallelism and Performance

None.

Further Comments

The same differencing operator does not have to be applied to all the series. For example, suppose we have k=2, and wish to apply the second order differencing operator ∇2 to the first series and the first-order differencing operator ∇ to the second series:
w 1 t=∇2 z 1 t=1-B 2 z 1 t=1-2 B+B 2 Z 1 t,   andw 2 t=∇z 2 t=1-B z 2 t.
Then d 1=2,d 2=1, d=max d 1,d 2=2, and
delta=δ 11δ 12δ 21=2-11.
Note: although differencing may already have been applied prior to the model fitting stage, the differencing parameters supplied in delta are part of the model definition and are still required by this method to produce the forecasts.
g13dj should not be used when the moving average parameters lie close to the boundary of the invertibility region. The method does test for both invertibility and stationarity but if in doubt, you may use g13dx, before calling this method, to check that the VARMA model being used is invertible.
On a successful exit, the quantities k, lmax, kmax, ref and lref will be suitable for input to g13dk.

Example

Example program (C#): g13dje.cs

Example program data: g13dje.d

Example program results: g13dje.r

See Also

G13 Class
G13 Members


g13dk Method

[image]

NAG Library for .NET Release 2
G13..::g13dk Method
G13 Class See Also Send Feedback
g13dk accepts a sequence of new observations in a multivariate time series and updates both the forecasts and the standard deviations of the forecast errors. A call to g13dj must be made prior to calling this method in order to calculate the elements of a reference vector together with a set of forecasts and their standard errors. On a successful exit from g13dk the reference vector is updated so that should future series values become available these forecasts may be updated by recalling g13dk.

Syntax

C#
public static void g13dk(
    int k,
    int lmax,
    int m,
    ref int mlast,
    double[,] z,
    double[] dnref,
    double[,] v,
    double[,] predz,
    double[,] sefz,
    out int ifail
)
Visual Basic
Public Shared Sub g13dk ( _
    k As Integer, _
    lmax As Integer, _
    m As Integer, _
    ByRef mlast As Integer, _
    z As Double(,), _
    dnref As Double(), _
    v As Double(,), _
    predz As Double(,), _
    sefz As Double(,), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13dk(
    int k,
    int lmax,
    int m,
    int% mlast,
    array<double,2>^ z,
    array<double>^ dnref,
    array<double,2>^ v,
    array<double,2>^ predz,
    array<double,2>^ sefz,
    [OutAttribute] int% ifail
)
F#
static member g13dk :
        k : int *
        lmax : int *
        m : int *
        mlast : int byref *
        z : float[,] *
        dnref : float[] *
        v : float[,] *
        predz : float[,] *
        sefz : float[,] *
        ifail : int byref -> unit

Parameters

k
Type: System..::..Int32
On entry: k, the dimension of the multivariate time series.
Constraint: k≥1.
lmax
Type: System..::..Int32
On entry: the number, lmax, of forecasts requested in the call to g13dj.
Constraint: lmax≥2.
m
Type: System..::..Int32
On entry: m, the number of new observations available since the last call to either g13dj or g13dk. The number of new observations since the last call to g13dj is then m+mlast.
Constraint: 0<m<lmax-mlast.
mlast
Type: System..::..Int32 %
On entry: on the first call to g13dk, since calling g13dj, mlast must be set to 0 to indicate that no new observations have yet been used to update the forecasts; on subsequent calls mlast must contain the value of mlast as output on the previous call to g13dk.
On exit: is incremented by m to indicate that mlast+m observations have now been used to update the forecasts since the last call to g13dj.
mlast must not be changed between calls to g13dk, unless a call to g13dj has been made between the calls in which case mlast should be reset to 0.
Constraint: 0≤mlast<lmax-m.
z
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥k
On entry: z[i-1,j-1] must contain the value of z i,n+mlast+j, for i=1,2,…,k and j=1,2,…,m, and where n is the number of observations in the time series in the last call made to g13dj.
Constraint: if the transformation defined in tr in g13dj for the ith series is the log transformation, then z[i-1,j-1]>0.0, and if it is the square-root transformation, then z[i-1,j-1]≥0.0, for j=1,2,…,m and i=1,2,…,k.
dnref
Type: array< System..::..Double >[]()[][]
An array of size [lref]
On entry: must contain the first lmax-1×k×k+2×k×lmax+k elements of the reference vector as returned on a successful exit from g13dj (or a previous call to g13dk).
On exit: the elements of ref are updated. The first lmax-1×k×k elements store the ψ weights ψ 1,ψ 2,…,ψ lmax-1. The next k×lmax elements contain the forecasts of the transformed series and the next k×lmax elements contain the variances of the forecasts of the transformed variables; see g13dj. The last k elements are not updated.
v
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: dim1≥k
On exit: v[i-1,j-1] contains an estimate of the ith component of ε n+mlast+j, for i=1,2,…,k and j=1,2,…,m.
predz
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, lmax]
Note: dim1 must satisfy the constraint: dim1≥k
On entry: nonupdated values are kept intact.
On exit: predz[i-1,j-1] contains the updated forecast of z i,n+j, for i=1,2,…,k and j=mlast+m+1,…,lmax.
The columns of predz corresponding to the new observations since the last call to either g13dj or g13dk are set equal to the corresponding columns of z.
sefz
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, lmax]
Note: dim1 must satisfy the constraint: dim1≥k
On entry: nonupdated values are kept intact.
On exit: sefz[i-1,j-1] contains an estimate of the standard error of the corresponding element of predz, for i=1,2,…,k and j=mlast+m+1,…,lmax.
The columns of sefz corresponding to the new observations since the last call to either g13dj or g13dk are set equal to zero.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Let Zt=z 1 t,z 2 t,…,z kt T, for t=1,2,…,n, denote a k-dimensional time series for which forecasts of Z^n+1,Z^n+2,…,Z^n+lmax have been computed using g13dj. Given m further observations Z n+1,Z n+2,…,Z n+m, where m<lmax, g13dk updates the forecasts of Z n+m+1,Z n+m+2,…,Z n+lmax and their corresponding standard errors.
g13dk uses a multivariate version of the procedure described in Box and Jenkins (1976). The forecasts are updated using the ψ weights, computed in g13dj. If Zt* denotes the transformed value of Zt and Z^t*l denotes the forecast of Z t+l* from time t with a lead of l (that is the forecast of Z t+l* given observations Zt*,Z t-1*,…), then
Z^t+1*l=τ+ψlε t+1+ψ l+1εt+ψ l+2ε t-1+⋯
and
Z^t*l+1=τ+ψ l+1εt+ψ l+2ε t-1+⋯
where τ is a constant vector of length k involving the differencing parameters and the mean vector μ. By subtraction we obtain
Z^t+1*l=Z^t*l+1+ψlε t+1.
Estimates of the residuals corresponding to the new observations are also computed as ε n+l=Z n+l*-Z^n*l, for l=1,2,…,m. These may be of use in checking that the new observations conform to the previously fitted model.
On a successful exit, the reference array is updated so that g13dk may be called again should future series values become available, see [Further Comments].
When a transformation has been used the forecasts and their standard errors are suitably modified to give results in terms of the original series Zt; see Granger and Newbold (1976).

References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day
Granger C W J and Newbold P (1976) Forecasting transformed series J. Roy. Statist. Soc. Ser. B 38 189–203
Wei W W S (1990) Time Series Analysis: Univariate and Multivariate Methods Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (KMAX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | k<1,
or | lmax<2,
or | m≤0,
or | mlast+m≥lmax,
or | mlast<0,
or | lref<lmax-1×k×k+2×k×lmax+k.
ifail=2
On entry, some of the elements of the reference vector, ref, have been corrupted since the most recent call to g13dj (or g13dk).
ifail=3
On entry, one or more of the elements of z is invalid, for the transformation being used; that is you may be trying to log or square root a series, some of whose values are negative.
ifail=4
This is an unlikely exit. For one of the series, overflow will occur if the forecasts are updated. You should check whether the elements of ref have been corrupted.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The matrix computations are believed to be stable.

Parallelism and Performance

None.

Further Comments

If a further m* observations, Z n+mlast+1,Z n+mlast+2,…,Z n+mlast+m*, become available, then forecasts of Z n+mlast+m*+1,Z n+mlast+m*+2,…,Z n+lmax may be updated by recalling g13dk with m=m*. Note that m and the contents of the array z are the only quantities which need updating; mlast is updated on exit from the previous call. On a successful exit, v contains estimates of ε n+mlast+1,ε n+mlast+2,…,ε n+mlast+m*; columns mlast+1,mlast+2,…,mlast+m* of predz contain the new observed values Z n+mlast+1,Z n+mlast+2,…,Z n+mlast+m* and columns mlast+1,mlast+2,…,mlast+m* of sefz are set to zero.

Example

Example program (C#): g13dke.cs

Example program data: g13dke.d

Example program results: g13dke.r

See Also

G13 Class
G13 Members


g13dl Method

[image]

NAG Library for .NET Release 2
G13..::g13dl Method
G13 Class See Also Send Feedback
g13dl differences and/or transforms a multivariate time series. It is intended to be used prior to g13dd to fit a vector autoregressive moving average (VARMA) model to the differenced/transformed series.

Syntax

C#
public static void g13dl(
    int k,
    int n,
    double[,] z,
    string[] tr,
    int[] id,
    double[,] delta,
    double[,] w,
    out int nd,
    out int ifail
)
Visual Basic
Public Shared Sub g13dl ( _
    k As Integer, _
    n As Integer, _
    z As Double(,), _
    tr As String(), _
    id As Integer(), _
    delta As Double(,), _
    w As Double(,), _
    <OutAttribute> ByRef nd As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13dl(
    int k,
    int n,
    array<double,2>^ z,
    array<String^>^ tr,
    array<int>^ id,
    array<double,2>^ delta,
    array<double,2>^ w,
    [OutAttribute] int% nd,
    [OutAttribute] int% ifail
)
F#
static member g13dl :
        k : int *
        n : int *
        z : float[,] *
        tr : string[] *
        id : int[] *
        delta : float[,] *
        w : float[,] *
        nd : int byref *
        ifail : int byref -> unit

Parameters

k
Type: System..::..Int32
On entry: k, the dimension of the multivariate time series.
Constraint: k≥1.
n
Type: System..::..Int32
On entry: n, the number of observations in the series, prior to differencing.
Constraint: n≥1.
z
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: _kmax≥k
On entry: z[i,t] must contain, z it, the ith component of Zt, for i=1,2,…,k and t=1,2,…,n.
Constraints:
  • if tr[i-1]="L", z[i,t]>0.0;
  • if tr[i-1]="S", z[i,t]≥0.0, for i=0,1,…,k-1 and t=0,1,…,n-1.
tr
Type: array< System..::..String >[]()[][]
An array of size [k]
On entry: tr[i-1] indicates whether the ith time series is to be transformed, for i=1,2,…,k.
tr[i-1]="N"
No transformation is used.
tr[i-1]="L"
A log transformation is used.
tr[i-1]="S"
A square root transformation is used.
Constraint: tr[i-1]="N", "L" or "S", for i=1,2,…,k.
id
Type: array< System..::..Int32 >[]()[][]
An array of size [k]
On entry: the order of differencing for each series, d 1,d 2,…,dk.
Constraint: 0≤id[i]<n, for i=0,1,…,k-1.
delta
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: _kmax≥k
Note: the second dimension of the array delta must be at least max 1,d, where d=max id[i-1].
On entry: if id[i-1]>0, then delta[i-1,j-1] must be set equal to δ ij, for j=1,2,…,di and i=1,2,…,k.
If d=0, then delta is not referenced.
w
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: _kmax≥k
Note: the second dimension of the array w must be at least n-d, where d=max id[i-1].
On exit: w[i-1,t-1] contains the value of w i,t+d, for i=1,2,…,k and t=1,2,…,n-d.
nd
Type: System..::..Int32 %
On exit: the number of differenced values, n-d, in the series, where d=max id[i-1].
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

For certain time series it may first be necessary to difference the original data to obtain a stationary series before calculating autocorrelations, etc. This method also allows you to apply either a square root or a log transformation to the original time series to stabilize the variance if required.
If the order of differencing required for the ith series is di, then the differencing operator is defined by δi B=1-δ i 1 B-δ i 2 B 2-⋯-δ i di B di, where B is the backward shift operator; that is, B Zt=Z t-1. Let d denote the maximum of the orders of differencing, di, over the k series. The method computes values of the differenced/transformed series Wt=w 1 t,w 2 t,…,w kt T, for t=d+1,…,n, as follows:
w it=δi B z it*,  i=1,2,…,k
where z it* are the transformed values of the original k-dimensional time series Zt=z 1 t,z 2 t,…,z kt T.
The differencing parameters δ ij, for i=1,2,…,k and j=1,2,…,di, must be supplied by you. If the ith series does not require differencing, then di=0.

References

Box G E P and Jenkins G M (1976) Time Series Analysis: Forecasting and Control (Revised Edition) Holden–Day
Wei W W S (1990) Time Series Analysis: Univariate and Multivariate Methods Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (KMAX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | k<1,
or | n<1,
ifail=2
On entry, | id[i-1]<0, for some i=1,2,…,k,
or | id[i-1]≥n, for some i=1,2,…,k.
ifail=3
On entry, at least one of the first k elements of tr is not equal to "N", "L" or "S".
ifail=4
On entry, one or more of the elements of z is invalid, for the transformation requested; that is, you may be trying to log or square root a series, some of whose values are negative.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The computations are believed to be stable.

Parallelism and Performance

None.

Further Comments

The same differencing operator does not have to be applied to all the series. For example, suppose we have k=2, and wish to apply the second-order differencing operator ∇2 to the first series and the first-order differencing operator ∇ to the second series:
w 1 t=∇2 z 1 t=1-B 2 z 1 t=1-2 B+B 2 z 1 t,   andw 2 t=∇z 2 t=1-B z 2 t.
Then d 1=2,d 2=1, d=max d 1,d 2=2, and
delta=δ 11δ 12δ 21=2-11.

Example

A program to difference (non-seasonally) each of two time series of length 48. No transformation is to be applied to either of the series.

Example program (C#): g13dle.cs

Example program data: g13dle.d

Example program results: g13dle.r

See Also

G13 Class
G13 Members


g13dx Method

[image]

NAG Library for .NET Release 2
G13..::g13dx Method
G13 Class See Also Send Feedback
g13dx calculates the zeros of a vector autoregressive (or moving average) operator. This method is likely to be used in conjunction with g05pj g13as g13dd (G13DSF not in this release).

Syntax

C#
public static void g13dx(
    int k,
    int ip,
    double[] par,
    double[] rr,
    double[] ri,
    double[] rmod,
    out int ifail
)
Visual Basic
Public Shared Sub g13dx ( _
    k As Integer, _
    ip As Integer, _
    par As Double(), _
    rr As Double(), _
    ri As Double(), _
    rmod As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13dx(
    int k,
    int ip,
    array<double>^ par,
    array<double>^ rr,
    array<double>^ ri,
    array<double>^ rmod,
    [OutAttribute] int% ifail
)
F#
static member g13dx :
        k : int *
        ip : int *
        par : float[] *
        rr : float[] *
        ri : float[] *
        rmod : float[] *
        ifail : int byref -> unit

Parameters

k
Type: System..::..Int32
On entry: k, the dimension of the multivariate time series.
Constraint: k≥1.
ip
Type: System..::..Int32
On entry: the number of AR (or MA) parameter matrices, p (or q).
Constraint: ip≥1.
par
Type: array< System..::..Double >[]()[][]
An array of size [ip×k×k]
On entry: the AR (or MA) parameter matrices read in row by row in the order ϕ 1,ϕ 2,…,ϕp (or θ 1,θ 2,…,θq). That is, par[l-1×k×k+i-1×k+j-1] must be set equal to the i,jth element of ϕl, for l=1,2,…,p (or the i,jth element of θl, for l=1,2,…,q).
rr
Type: array< System..::..Double >[]()[][]
An array of size [k×ip]
On exit: the real parts of the eigenvalues.
ri
Type: array< System..::..Double >[]()[][]
An array of size [k×ip]
On exit: the imaginary parts of the eigenvalues.
rmod
Type: array< System..::..Double >[]()[][]
An array of size [k×ip]
On exit: the moduli of the eigenvalues.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Consider the vector autoregressive moving average (VARMA) model
Wt-μ=ϕ 1 W t-1-μ+ϕ 2 W t-2-μ+⋯+ϕp W t-p-μ+εt-θ 1ε t-1-θ 2ε t-2-⋯-θqε t-q, (1)
where Wt denotes a vector of k time series and εt is a vector of k residual series having zero mean and a constant variance-covariance matrix. The components of εt are also assumed to be uncorrelated at non-simultaneous lags. ϕ 1,ϕ 2,…,ϕp denotes a sequence of k by k matrices of autoregressive (AR) parameters and θ 1,θ 2,…,θq denotes a sequence of k by k matrices of moving average (MA) parameters. μ is a vector of length k containing the series means. Let
A ϕ=ϕ 1I0...0ϕ 20I0..0......ϕ p-10...0Iϕp0...00 pk×pk
where I denotes the k by k identity matrix.
The model (1) is said to be stationary if the eigenvalues of A ϕ lie inside the unit circle. Similarly let
B θ=θ 1I0...0θ 20I0..0......θ q-10...0Iθq0...00 qk×qk.
Then the model is said to be invertible if the eigenvalues of B θ lie inside the unit circle.
g13dx returns the pk eigenvalues of A ϕ (or the qk eigenvalues of B θ) along with their moduli, in descending order of magnitude. Thus to check for stationarity or invertibility you should check whether the modulus of the largest eigenvalue is less than one.

References

Wei W W S (1990) Time Series Analysis: Univariate and Multivariate Methods Addison–Wesley

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | k<1,
or | ip<1.
ifail=2
An excessive number of iterations are needed to evaluate the eigenvalues of A ϕ (or B θ). This is an unlikely exit. All output parameters are undefined.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The accuracy of the results depends on the original matrix and the multiplicity of the roots.

Parallelism and Performance

None.

Further Comments

The time taken is approximately proportional to k p 3 (or k q 3).

Example

This example finds the eigenvalues of A ϕ where k=2 and p=1 and ϕ 1=0.8020.0650.0000.575.

Example program (C#): g13dxe.cs

Example program data: g13dxe.d

Example program results: g13dxe.r

See Also

G13 Class
G13 Members


g13fa Method

[image]

NAG Library for .NET Release 2
G13..::g13fa Method
G13 Class See Also Send Feedback
g13fa estimates the parameters of either a standard univariate regression GARCH process, or a univariate regression-type I AGARCH p,q process (see Engle and Ng (1993)).

Syntax

C#
public static void g13fa(
    string dist,
    double[] yt,
    double[,] x,
    int num,
    int ip,
    int iq,
    int nreg,
    int mn,
    int isym,
    int npar,
    double[] theta,
    double[] se,
    double[] sc,
    double[,] covr,
    ref double hp,
    double[] et,
    double[] ht,
    out double lgf,
    bool[] copts,
    int maxit,
    double tol,
    out int ifail
)
Visual Basic
Public Shared Sub g13fa ( _
    dist As String, _
    yt As Double(), _
    x As Double(,), _
    num As Integer, _
    ip As Integer, _
    iq As Integer, _
    nreg As Integer, _
    mn As Integer, _
    isym As Integer, _
    npar As Integer, _
    theta As Double(), _
    se As Double(), _
    sc As Double(), _
    covr As Double(,), _
    ByRef hp As Double, _
    et As Double(), _
    ht As Double(), _
    <OutAttribute> ByRef lgf As Double, _
    copts As Boolean(), _
    maxit As Integer, _
    tol As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13fa(
    String^ dist,
    array<double>^ yt,
    array<double,2>^ x,
    int num,
    int ip,
    int iq,
    int nreg,
    int mn,
    int isym,
    int npar,
    array<double>^ theta,
    array<double>^ se,
    array<double>^ sc,
    array<double,2>^ covr,
    double% hp,
    array<double>^ et,
    array<double>^ ht,
    [OutAttribute] double% lgf,
    array<bool>^ copts,
    int maxit,
    double tol,
    [OutAttribute] int% ifail
)
F#
static member g13fa :
        dist : string *
        yt : float[] *
        x : float[,] *
        num : int *
        ip : int *
        iq : int *
        nreg : int *
        mn : int *
        isym : int *
        npar : int *
        theta : float[] *
        se : float[] *
        sc : float[] *
        covr : float[,] *
        hp : float byref *
        et : float[] *
        ht : float[] *
        lgf : float byref *
        copts : bool[] *
        maxit : int *
        tol : float *
        ifail : int byref -> unit

Parameters

dist
Type: System..::..String
On entry: the type of distribution to use for et.
dist="N"
A Normal distribution is used.
dist="T"
A Student's t-distribution is used.
Constraint: dist="N" or "T".
yt
Type: array< System..::..Double >[]()[][]
An array of size [num]
On entry: the sequence of observations, yt, for t=1,2,…,T.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥num
Note: the second dimension of the array x must be at least nreg.
On entry: row t of x must contain the time dependent exogenous vector xt, where xtT=xt 1,…,xtk, for t=1,2,…,T.
num
Type: System..::..Int32
On entry: T, the number of terms in the sequence.
Constraints:
  • num≥max ip,iq;
  • num≥nreg+mn.
ip
Type: System..::..Int32
On entry: the number of coefficients, βi, for i=1,2,…,p.
Constraint: ip≥0 (see also npar).
iq
Type: System..::..Int32
On entry: the number of coefficients, αi, for i=1,2,…,q.
Constraint: iq≥1 (see also npar).
nreg
Type: System..::..Int32
On entry: k, the number of regression coefficients.
Constraint: nreg≥0 (see also npar).
mn
Type: System..::..Int32
On entry: if mn=1, the mean term b 0 will be included in the model.
Constraint: mn=0 or 1.
isym
Type: System..::..Int32
On entry: if isym=1, the asymmetry term γ will be included in the model.
Constraint: isym=0 or 1.
npar
Type: System..::..Int32
On entry: the number of parameters to be included in the model. npar=1+iq+ip+isym+mn+nreg when dist="N", and npar=2+iq+ip+isym+mn+nreg when dist="T".
Constraint: npar<20.
theta
Type: array< System..::..Double >[]()[][]
An array of size [npar]
On entry: the initial parameter estimates for the vector θ.
The first element must contain the coefficient αo and the next iq elements must contain the coefficients αi, for i=1,2,…,q.
The next ip elements must contain the coefficients βj, for j=1,2,…,p.
If isym=1, the next element must contain the asymmetry parameter γ.
If dist="T", the next element must contain df, the number of degrees of freedom of the Student's t-distribution.
If mn=1, the next element must contain the mean term bo.
If copts[1]=false, the remaining nreg elements are taken as initial estimates of the linear regression coefficients bi, for i=1,2,…,k.
On exit: the estimated values θ^ for the vector θ.
The first element contains the coefficient αo, the next iq elements contain the coefficients αi, for i=1,2,…,q.
The next ip elements are the coefficients βj, for j=1,2,…,p.
If isym=1, the next element contains the estimate for the asymmetry parameter γ.
If dist="T", the next element contains an estimate for df, the number of degrees of freedom of the Student's t-distribution.
If mn=1, the next element contains an estimate for the mean term bo.
The final nreg elements are the estimated linear regression coefficients bi, for i=1,2,…,k.
se
Type: array< System..::..Double >[]()[][]
An array of size [npar]
On exit: the standard errors for θ^.
The first element contains the standard error for αo. The next iq elements contain the standard errors for αi, for i=1,2,…,q. The next ip elements are the standard errors for βj, for j=1,2,…,p.
If isym=1, the next element contains the standard error for γ.
If dist="T", the next element contains the standard error for df, the number of degrees of freedom of the Student's t-distribution.
If mn=1, the next element contains the standard error for bo.
The final nreg elements are the standard errors for bj, for j=1,2,…,k.
sc
Type: array< System..::..Double >[]()[][]
An array of size [npar]
On exit: the scores for θ^.
The first element contains the score for αo.
The next iq elements contain the score for αi, for i=1,2,…,q.
The next ip elements are the scores for βj, for j=1,2,…,p.
If isym=1, the next element contains the score for γ.
If dist="T", the next element contains the score for df, the number of degrees of freedom of the Student's t-distribution.
If mn=1, the next element contains the score for bo.
The final nreg elements are the scores for bj, for j=1,2,…,k.
covr
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, npar]
Note: dim1 must satisfy the constraint: dim1≥npar
On exit: the covariance matrix of the parameter estimates θ^, that is the inverse of the Fisher Information Matrix.
hp
Type: System..::..Double %
On entry: if copts[1]=false, hp is the value to be used for the pre-observed conditional variance; otherwise hp is not referenced.
On exit: if copts[1]=true, hp is the estimated value of the pre-observed conditional variance.
et
Type: array< System..::..Double >[]()[][]
An array of size [num]
On exit: the estimated residuals, εt, for t=1,2,…,T.
ht
Type: array< System..::..Double >[]()[][]
An array of size [num]
On exit: the estimated conditional variances, ht, for t=1,2,…,T.
lgf
Type: System..::..Double %
On exit: the value of the log-likelihood function at θ^.
copts
Type: array< System..::..Boolean >[]()[][]
An array of size [2]
On entry: the options to be used by g13fa.
copts[0]=true
Stationary conditions are enforced, otherwise they are not.
copts[1]=true
The method provides initial parameter estimates of the regression terms, otherwise these are to be provided by you.
maxit
Type: System..::..Int32
On entry: the maximum number of iterations to be used by the optimization method when estimating the GARCH p,q parameters. If maxit is set to 0, the standard errors, score vector and variance-covariance are calculated for the input value of θ in theta; however the value of θ is not updated.
Constraint: maxit≥0.
tol
Type: System..::..Double
On entry: the tolerance to be used by the optimization method when estimating the GARCH p,q parameters.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

A univariate regression-type I AGARCH p,q process, with q coefficients αi, for i=1,2,…,q, p coefficients βi, for i=1,2,…,p, and k linear regression coefficients bi, for i=1,2,…,k, can be represented by:
yt=bo+xtT b+εt (1)
ht=α 0+∑i=1 q αi ε t-i+γ 2+∑i=1 p βih t-i,  t=1,2,…,T (2)
where εt∣ψ t-1=N 0,ht or εt∣ψ t-1=St df,ht. Here St is a standardized Student's t-distribution with df degrees of freedom and variance ht, T is the number of terms in the sequence, yt denotes the endogenous variables, xt the exogenous variables, bo the regression mean, b the regression coefficients, εt the residuals, ht the conditional variance, df the number of degrees of freedom of the Student's t-distribution, and ψt the set of all information up to time t.
g13fa provides an estimate for θ^, the parameter vector θ=bo,bT,ωT where bT=b 1,…,bk, ωT=α 0,α 1,…,αq,β 1,…,βp,γ when dist="N" and ωT=α 0,α 1,…,αq,β 1,…,βp,γ,df when dist="T".
isym, mn and nreg can be used to simplify the GARCH p,q expression in (1) as follows:
No Regression and No Mean
  • yt=εt,
  • isym=0,
  • mn=0,
  • nreg=0 and
  • θ is a p+q+1 vector when dist="N" and a p+q+2 vector when dist="T".
No Regression
  • yt=bo+εt,
  • isym=0,
  • mn=1,
  • nreg=0 and
  • θ is a p+q+2 vector when dist="N" and a p+q+3 vector when dist="T".
Note: if the yt=μ+εt, where μ is known (not to be estimated by g13fa) then (1) can be written as ytμ=εt, where ytμ=yt-μ. This corresponds to the case No Regression and No Mean, with yt replaced by yt-μ.
No Mean
  • yt=xtT b+εt,
  • isym=0,
  • mn=0,
  • nreg=k and
  • θ is a p+q+k+1 vector when dist="N" and a p+q+k+2 vector when dist="T".

References

Bollerslev T (1986) Generalised autoregressive conditional heteroskedasticity Journal of Econometrics 31 307–327
Engle R (1982) Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation Econometrica 50 987–1008
Engle R and Ng V (1993) Measuring and testing the impact of news on volatility Journal of Finance 48 1749–1777
Hamilton J (1994) Time Series Analysis Princeton University Press

Error Indicators and Warnings

Note: g13fa may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDCOVR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | nreg<0,
or | mn>1,
or | mn<0,
or | isym>1,
or | isym<0,
or | iq<1,
or | ip<0,
or | npar≥20,
or | npar has an invalid value,
or | dist≠"N",
or | dist≠"T",
or | maxit<0,
or | num<max ip,iq,
or | num<nreg+mn.
ifail=2
On entry, lwork<nreg+3×num+npar+403.
ifail=3
The matrix X is not full rank.
ifail=4
The information matrix is not positive definite.
ifail=5
The maximum number of iterations has been reached.
ifail=6
The log-likelihood cannot be optimized any further.
ifail=7
No feasible model parameters could be found.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

This example fits a GARCH 1,1 model with Student's t-distributed residuals to some simulated data.

Example program (C#): g13fae.cs

Example program data: g13fae.d

Example program results: g13fae.r

See Also

G13 Class
G13 Members


g13fb Method

[image]

NAG Library for .NET Release 2
G13..::g13fb Method
G13 Class See Also Send Feedback
g13fb forecasts the conditional variances ht, for t=T+1,…,T+ξ, from a type I AGARCH p,q sequence, where ξ is the forecast horizon and T is the current time (see Engle and Ng (1993)).

Syntax

C#
public static void g13fb(
    int num,
    int nt,
    int ip,
    int iq,
    double[] theta,
    double gamma,
    double[] fht,
    double[] ht,
    double[] et,
    out int ifail
)
Visual Basic
Public Shared Sub g13fb ( _
    num As Integer, _
    nt As Integer, _
    ip As Integer, _
    iq As Integer, _
    theta As Double(), _
    gamma As Double, _
    fht As Double(), _
    ht As Double(), _
    et As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13fb(
    int num,
    int nt,
    int ip,
    int iq,
    array<double>^ theta,
    double gamma,
    array<double>^ fht,
    array<double>^ ht,
    array<double>^ et,
    [OutAttribute] int% ifail
)
F#
static member g13fb :
        num : int *
        nt : int *
        ip : int *
        iq : int *
        theta : float[] *
        gamma : float *
        fht : float[] *
        ht : float[] *
        et : float[] *
        ifail : int byref -> unit

Parameters

num
Type: System..::..Int32
On entry: the number of terms in the arrays ht and et from the modelled sequence.
Constraint: max ip,iq≤num.
nt
Type: System..::..Int32
On entry: ξ, the forecast horizon.
Constraint: nt>0.
ip
Type: System..::..Int32
On entry: the number of coefficients, βi, for i=1,2,…,p.
Constraints:
  • max ip,iq≤20;
  • ip≥0.
iq
Type: System..::..Int32
On entry: the number of coefficients, αi, for i=1,2,…,q.
Constraints:
  • max ip,iq≤20;
  • iq≥1.
theta
Type: array< System..::..Double >[]()[][]
An array of size [iq+ip+1]
On entry: the first element must contain the coefficient αo and the next iq elements must contain the coefficients αi, for i=1,2,…,q. The remaining ip elements must contain the coefficients βj, for j=1,2,…,p.
gamma
Type: System..::..Double
On entry: the asymmetry parameter γ for the GARCH p,q sequence.
fht
Type: array< System..::..Double >[]()[][]
An array of size [nt]
On exit: the forecast values of the conditional variance, ht, for t=T+1,…,T+ξ.
ht
Type: array< System..::..Double >[]()[][]
An array of size [num]
On entry: the sequence of past conditional variances for the GARCH p,q process, ht, for t=1,2,…,T.
et
Type: array< System..::..Double >[]()[][]
An array of size [num]
On entry: the sequence of past residuals for the GARCH p,q process, εt, for t=1,2,…,T.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Assume the GARCH p,q process can be represented by:
ht=α 0+∑i=1 q αi ε t-i+γ 2+∑i=1 p βih t-i,  t=1,2,…,T
where εt∣ψ t-1=N 0,ht or εt∣ψ t-1=St df,ht, has been modelled by g13fa and the estimated conditional variances and residuals are contained in the arrays ht and et respectively.
g13fb will then use the last max p,q elements of the arrays ht and et to estimate the conditional variance forecasts, ht∣ψT, where t=T+1,…,T+ξ and ξ is the forecast horizon.

References

Bollerslev T (1986) Generalised autoregressive conditional heteroskedasticity Journal of Econometrics 31 307–327
Engle R (1982) Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation Econometrica 50 987–1008
Engle R and Ng V (1993) Measuring and testing the impact of news on volatility Journal of Finance 48 1749–1777
Hamilton J (1994) Time Series Analysis Princeton University Press

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | num<max ip,iq,
or | iq<1,
or | ip<0,
or | max ip,iq>20,
or | nt≤0.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

See [Example] in g13fa.

See Also

G13 Class
G13 Members


g13fc Method

[image]

NAG Library for .NET Release 2
G13..::g13fc Method
G13 Class See Also Send Feedback
g13fc estimates the parameters of a univariate regression-type II AGARCH p,q process.

Syntax

C#
public static void g13fc(
    string dist,
    double[] yt,
    double[,] x,
    int num,
    int ip,
    int iq,
    int nreg,
    int mn,
    int npar,
    double[] theta,
    double[] se,
    double[] sc,
    double[,] covr,
    ref double hp,
    double[] et,
    double[] ht,
    out double lgf,
    bool[] copts,
    int maxit,
    double tol,
    out int ifail
)
Visual Basic
Public Shared Sub g13fc ( _
    dist As String, _
    yt As Double(), _
    x As Double(,), _
    num As Integer, _
    ip As Integer, _
    iq As Integer, _
    nreg As Integer, _
    mn As Integer, _
    npar As Integer, _
    theta As Double(), _
    se As Double(), _
    sc As Double(), _
    covr As Double(,), _
    ByRef hp As Double, _
    et As Double(), _
    ht As Double(), _
    <OutAttribute> ByRef lgf As Double, _
    copts As Boolean(), _
    maxit As Integer, _
    tol As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13fc(
    String^ dist,
    array<double>^ yt,
    array<double,2>^ x,
    int num,
    int ip,
    int iq,
    int nreg,
    int mn,
    int npar,
    array<double>^ theta,
    array<double>^ se,
    array<double>^ sc,
    array<double,2>^ covr,
    double% hp,
    array<double>^ et,
    array<double>^ ht,
    [OutAttribute] double% lgf,
    array<bool>^ copts,
    int maxit,
    double tol,
    [OutAttribute] int% ifail
)
F#
static member g13fc :
        dist : string *
        yt : float[] *
        x : float[,] *
        num : int *
        ip : int *
        iq : int *
        nreg : int *
        mn : int *
        npar : int *
        theta : float[] *
        se : float[] *
        sc : float[] *
        covr : float[,] *
        hp : float byref *
        et : float[] *
        ht : float[] *
        lgf : float byref *
        copts : bool[] *
        maxit : int *
        tol : float *
        ifail : int byref -> unit

Parameters

dist
Type: System..::..String
On entry: the type of distribution to use for et.
dist="N"
A Normal distribution is used.
dist="T"
A Student's t-distribution is used.
Constraint: dist="N" or "T".
yt
Type: array< System..::..Double >[]()[][]
An array of size [num]
On entry: the sequence of observations, yt, for t=1,2,…,T.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥num
Note: the second dimension of the array x must be at least nreg.
On entry: row t of x must contain the time dependent exogenous vector xt, where xtT=xt 1,…,xtk, for t=1,2,…,T.
num
Type: System..::..Int32
On entry: T, the number of terms in the sequence.
Constraints:
  • num≥max ip,iq;
  • num≥nreg+mn.
ip
Type: System..::..Int32
On entry: the number of coefficients, βi, for i=1,2,…,p.
Constraint: ip≥0 (see also npar).
iq
Type: System..::..Int32
On entry: the number of coefficients, αi, for i=1,2,…,q.
Constraint: iq≥1 (see also npar).
nreg
Type: System..::..Int32
On entry: k, the number of regression coefficients.
Constraint: nreg≥0 (see also npar).
mn
Type: System..::..Int32
On entry: if mn=1, the mean term b 0 will be included in the model.
Constraint: mn=0 or 1.
npar
Type: System..::..Int32
On entry: the number of parameters to be included in the model. npar=2+iq+ip+mn+nreg when dist="N" and npar=3+iq+ip+mn+nreg when dist="T".
Constraint: npar<20.
theta
Type: array< System..::..Double >[]()[][]
An array of size [npar]
On entry: the initial parameter estimates for the vector θ.
The first element must contain the coefficient αo and the next iq elements must contain the coefficients αi, for i=1,2,…,q.
The next ip elements must contain the coefficients βj, for j=1,2,…,p.
The next element must contain the asymmetry parameter γ.
If dist="T", the next element must contain df, the number of degrees of freedom of the Student's t-distribution.
If mn=1, the next element contains the mean term bo.
If copts[1]=false, the remaining nreg elements are taken as initial estimates of the linear regression coefficients bi, for i=1,2,…,k.
On exit: the estimated values θ^ for the vector θ.
The first element contains the coefficient αo, the next iq elements contain the coefficients αi, for i=1,2,…,q.
The next ip elements are the coefficients βj, for j=1,2,…,p.
The next element contains the estimate for the asymmetry parameter γ.
If dist="T", the next element contains an estimate for df, the number of degrees of freedom of the Student's t-distribution.
If mn=1, the next element contains an estimate for the mean term bo.
The final nreg elements are the estimated linear regression coefficients bi, for i=1,2,…,k.
se
Type: array< System..::..Double >[]()[][]
An array of size [npar]
On exit: the standard errors for θ^.
The first element contains the standard error for αo and the next iq elements contain the standard errors for αi, for i=1,2,…,q.
The next ip elements are the standard errors for βj, for j=1,2,…,p.
The next element contains the standard error for γ.
If dist="T", the next element contains the standard error for df, the number of degrees of freedom of the Student's t-distribution.
If mn=1, the next element contains the standard error for bo.
The final nreg elements are the standard errors for bj, for j=1,2,…,k.
sc
Type: array< System..::..Double >[]()[][]
An array of size [npar]
On exit: the scores for θ^.
The first element contains the score for αo and the next iq elements contain the score for αi, for i=1,2,…,q.
The next ip elements are the scores for βj, for j=1,2,…,p.
The next element contains the score for γ.
If dist="T", the next element contains the score for df, the number of degrees of freedom of the Student's t-distribution.
If mn=1, the next element contains the score for bo.
The final nreg elements are the scores for bj, for j=1,2,…,k.
covr
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, npar]
Note: dim1 must satisfy the constraint: dim1≥npar
On exit: the covariance matrix of the parameter estimates θ^, that is the inverse of the Fisher Information Matrix.
hp
Type: System..::..Double %
On entry: if copts[1]=false, hp is the value to be used for the pre-observed conditional variance; otherwise hp is not referenced.
On exit: if copts[1]=true, hp is the estimated value of the pre-observed conditional variance.
et
Type: array< System..::..Double >[]()[][]
An array of size [num]
On exit: the estimated residuals, εt, for t=1,2,…,T.
ht
Type: array< System..::..Double >[]()[][]
An array of size [num]
On exit: the estimated conditional variances, ht, for t=1,2,…,T.
lgf
Type: System..::..Double %
On exit: the value of the log-likelihood function at θ^.
copts
Type: array< System..::..Boolean >[]()[][]
An array of size [2]
On entry: the options to be used by g13fc.
copts[0]=true
Stationary conditions are enforced, otherwise they are not.
copts[1]=true
The method provides initial parameter estimates of the regression terms, otherwise these are to be provided by you.
maxit
Type: System..::..Int32
On entry: the maximum number of iterations to be used by the optimization method when estimating the GARCH p,q parameters. If maxit is set to 0, the standard errors, score vector and variance-covariance are calculated for the input value of θ in theta; however the value of θ is not updated.
Constraint: maxit≥0.
tol
Type: System..::..Double
On entry: the tolerance to be used by the optimization method when estimating the GARCH p,q parameters.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

A univariate regression-type II AGARCH p,q process, with q coefficients αi, for i=1,2,…,q, p coefficients, βi, for i=1,2,…,p, and k linear regression coefficients bi, for i=1,2,…,k, can be represented by:
yt=bo+xtT b+εt (1)
ht=α 0+∑i=1 q αi ε t-i+γ ε t-i 2+∑i=1 p βih t-i,  t=1,2,…,T. (2)
where εt∣ψ t-1=N 0,ht or εt∣ψ t-1=St df,ht. Here St is a standardized Student's t-distribution with df degrees of freedom and variance ht, T is the number of terms in the sequence, yt denotes the endogenous variables, xt the exogenous variables, bo the regression mean, b the regression coefficients, εt the residuals, ht the conditional variance, and ψt the set of all information up to time t.
g13fc provides an estimate for the parameter vector θ=bo,bT,ωT where bT=b 1,…,bk, ωT=α 0,α 1,…,αq,β 1,…,βp,γ when dist="N" and ωT=α 0,α 1,…,αq,β 1,…,βp,γ,df when dist="T".
mn and nreg can be used to simplify the GARCH p,q expression in (1) as follows:
No Regression and No Mean
  • yt=εt,
  • mn=0,
  • nreg=0 and
  • θ is a p+q+2 vector when dist="N" and a p+q+3 vector when dist="T".
No Regression
  • yt=bo+εt,
  • mn=1,
  • nreg=0 and
  • θ is a p+q+3 vector when dist="N" and a p+q+4×1 vector when dist="T".
Note: if the yt=μ+εt, where μ is known (not to be estimated by g13fc) then (1) can be written as ytμ=εt, where ytμ=yt-μ. This corresponds to the case No Regression and No Mean, with yt replaced by yt-μ.
No Mean
  • yt=xtT b+εt,
  • mn=0,
  • nreg=k and
  • θ is a p+q+k+2 vector when dist="N" and a p+q+k+3 vector when dist="T".

References

Bollerslev T (1986) Generalised autoregressive conditional heteroskedasticity Journal of Econometrics 31 307–327
Engle R (1982) Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation Econometrica 50 987–1008
Engle R and Ng V (1993) Measuring and testing the impact of news on volatility Journal of Finance 48 1749–1777
Hamilton J (1994) Time Series Analysis Princeton University Press

Error Indicators and Warnings

Note: g13fc may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDCOVR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | nreg<0,
or | mn>1,
or | mn<0,
or | iq<1,
or | ip<0,
or | npar≥20,
or | dist≠"N", and dist≠"T",
or | maxit<0,
or | num<nreg+mn,
or | npar has an invalid value num<max ip,iq.
ifail=2
On entry, lwork<nreg+3×num+3.
ifail=3
The matrix X is not full rank.
ifail=4
The information matrix is not positive definite.
ifail=5
The maximum number of iterations has been reached.
ifail=6
The log-likelihood cannot be optimized any further.
ifail=7
No feasible model parameters could be found.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

This example fits a GARCH 1,1 model with Student's t-distributed residuals to some simulated data.

Example program (C#): g13fce.cs

Example program data: g13fce.d

Example program results: g13fce.r

See Also

G13 Class
G13 Members


g13fd Method

[image]

NAG Library for .NET Release 2
G13..::g13fd Method
G13 Class See Also Send Feedback
g13fd forecasts the conditional variances, ht,t=T+1,…,T+ξ from a type II AGARCH p,q sequence, where ξ is the forecast horizon and T is the current time (see Engle and Ng (1993)).

Syntax

C#
public static void g13fd(
    int num,
    int nt,
    int ip,
    int iq,
    double[] theta,
    double gamma,
    double[] fht,
    double[] ht,
    double[] et,
    out int ifail
)
Visual Basic
Public Shared Sub g13fd ( _
    num As Integer, _
    nt As Integer, _
    ip As Integer, _
    iq As Integer, _
    theta As Double(), _
    gamma As Double, _
    fht As Double(), _
    ht As Double(), _
    et As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13fd(
    int num,
    int nt,
    int ip,
    int iq,
    array<double>^ theta,
    double gamma,
    array<double>^ fht,
    array<double>^ ht,
    array<double>^ et,
    [OutAttribute] int% ifail
)
F#
static member g13fd :
        num : int *
        nt : int *
        ip : int *
        iq : int *
        theta : float[] *
        gamma : float *
        fht : float[] *
        ht : float[] *
        et : float[] *
        ifail : int byref -> unit

Parameters

num
Type: System..::..Int32
On entry: the number of terms in the arrays ht and et from the modelled sequence.
Constraint: max ip,iq≤num.
nt
Type: System..::..Int32
On entry: ξ, the forecast horizon.
Constraint: nt>0.
ip
Type: System..::..Int32
On entry: the number of coefficients, βi, for i=1,2,…,p.
Constraints:
  • max ip,iq≤20;
  • ip≥0.
iq
Type: System..::..Int32
On entry: the number of coefficients, αi, for i=1,2,…,q.
Constraints:
  • max ip,iq≤20;
  • iq≥1.
theta
Type: array< System..::..Double >[]()[][]
An array of size [iq+ip+1]
On entry: the first element must contain the coefficient αo and the next iq elements must contain the coefficients αi, for i=1,2,…,q. The remaining ip elements must contain the coefficients βj, for j=1,2,…,p.
gamma
Type: System..::..Double
On entry: the asymmetry parameter γ for the GARCH p,q sequence.
fht
Type: array< System..::..Double >[]()[][]
An array of size [nt]
On exit: the forecast values of the conditional variance, ht, for t=T+1,…,T+ξ.
ht
Type: array< System..::..Double >[]()[][]
An array of size [num]
On entry: the sequence of past conditional variances for the GARCH p,q process, ht, for t=1,2,…,T.
et
Type: array< System..::..Double >[]()[][]
An array of size [num]
On entry: the sequence of past residuals for the GARCH p,q process, εt, for t=1,2,…,T.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Assume the GARCH p,q process can be represented by:
ht=α 0+∑i=1 q αi ε t-i+γ ε t-i 2+∑i=1 p βih t-i,  t=1,2,…,T.
where εt∣ψ t-1=N 0,ht or εt∣ψ t-1=St df,ht, has been modelled by g13fc and the estimated conditional variances and residuals are contained in the arrays ht and et respectively.
g13fd will then use the last max p,q elements of the arrays ht and et to estimate the conditional variance forecasts, ht∣ψT, where t=T+1,…,T+ξ and ξ is the forecast horizon.

References

Bollerslev T (1986) Generalised autoregressive conditional heteroskedasticity Journal of Econometrics 31 307–327
Engle R (1982) Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation Econometrica 50 987–1008
Engle R and Ng V (1993) Measuring and testing the impact of news on volatility Journal of Finance 48 1749–1777
Hamilton J (1994) Time Series Analysis Princeton University Press

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | num<max ip,iq,
or | iq<1,
or | ip<0,
or | max ip,iq>20,
or | nt≤0.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

See [Example] in g13fc.

See Also

G13 Class
G13 Members


g13fe Method

[image]

NAG Library for .NET Release 2
G13..::g13fe Method
G13 Class See Also Send Feedback
g13fe estimates the parameters of a univariate regression-GJR GARCH p,q process (see Glosten et al. (1993)).

Syntax

C#
public static void g13fe(
    string dist,
    double[] yt,
    double[,] x,
    int num,
    int ip,
    int iq,
    int nreg,
    int mn,
    int npar,
    double[] theta,
    double[] se,
    double[] sc,
    double[,] covr,
    ref double hp,
    double[] et,
    double[] ht,
    out double lgf,
    bool[] copts,
    int maxit,
    double tol,
    out int ifail
)
Visual Basic
Public Shared Sub g13fe ( _
    dist As String, _
    yt As Double(), _
    x As Double(,), _
    num As Integer, _
    ip As Integer, _
    iq As Integer, _
    nreg As Integer, _
    mn As Integer, _
    npar As Integer, _
    theta As Double(), _
    se As Double(), _
    sc As Double(), _
    covr As Double(,), _
    ByRef hp As Double, _
    et As Double(), _
    ht As Double(), _
    <OutAttribute> ByRef lgf As Double, _
    copts As Boolean(), _
    maxit As Integer, _
    tol As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13fe(
    String^ dist,
    array<double>^ yt,
    array<double,2>^ x,
    int num,
    int ip,
    int iq,
    int nreg,
    int mn,
    int npar,
    array<double>^ theta,
    array<double>^ se,
    array<double>^ sc,
    array<double,2>^ covr,
    double% hp,
    array<double>^ et,
    array<double>^ ht,
    [OutAttribute] double% lgf,
    array<bool>^ copts,
    int maxit,
    double tol,
    [OutAttribute] int% ifail
)
F#
static member g13fe :
        dist : string *
        yt : float[] *
        x : float[,] *
        num : int *
        ip : int *
        iq : int *
        nreg : int *
        mn : int *
        npar : int *
        theta : float[] *
        se : float[] *
        sc : float[] *
        covr : float[,] *
        hp : float byref *
        et : float[] *
        ht : float[] *
        lgf : float byref *
        copts : bool[] *
        maxit : int *
        tol : float *
        ifail : int byref -> unit

Parameters

dist
Type: System..::..String
On entry: the type of distribution to use for et.
dist="N"
A Normal distribution is used.
dist="T"
A Student's t-distribution is used.
Constraint: dist="N" or "T".
yt
Type: array< System..::..Double >[]()[][]
An array of size [num]
On entry: the sequence of observations, yt, for t=1,2,…,T.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥num
Note: the second dimension of the array x must be at least nreg.
On entry: row t of x must contain the time dependent exogenous vector xt, where xtT=xt 1,…,xtk, for t=1,2,…,T.
num
Type: System..::..Int32
On entry: T, the number of terms in the sequence.
Constraints:
  • num≥max ip,iq;
  • num≥nreg+mn.
ip
Type: System..::..Int32
On entry: the number of coefficients, βi, for i=1,2,…,p.
Constraint: ip≥0 (see also npar).
iq
Type: System..::..Int32
On entry: the number of coefficients, αi, for i=1,2,…,q.
Constraint: iq≥1 (see also npar).
nreg
Type: System..::..Int32
On entry: k, the number of regression coefficients.
Constraint: nreg≥0 (see also npar).
mn
Type: System..::..Int32
On entry: if mn=1, the mean term b 0 will be included in the model.
Constraint: mn=0 or 1.
npar
Type: System..::..Int32
On entry: the number of parameters to be included in the model. npar=2+iq+ip+mn+nreg when dist="N" and npar=3+iq+ip+mn+nreg when dist="T".
Constraint: npar<20.
theta
Type: array< System..::..Double >[]()[][]
An array of size [npar]
On entry: the initial parameter estimates for the vector θ.
The first element must contain the coefficient αo and the next iq elements contain the coefficients αi, for i=1,2,…,q.
The next ip elements must contain the coefficients βj, for j=1,2,…,p.
The next element must contain the asymmetry parameter γ.
If dist="T", the next element contains df, the number of degrees of freedom of the Student's t-distribution.
If mn=1, the next element must contain the mean term bo.
If copts[1]=false, the remaining nreg elements are taken as initial estimates of the linear regression coefficients bi, for i=1,2,…,k.
On exit: the estimated values θ^ for the vector θ.
The first element contains the coefficient αo, the next iq elements contain the coefficients αi, for i=1,2,…,q.
The next ip elements are the moving average coefficients βj, for j=1,2,…,p.
The next element contains the estimate for the asymmetry parameter γ.
If dist="T", the next element contains an estimate for df, the number of degrees of freedom of the Student's t-distribution.
If mn=1, the next element contains an estimate for the mean term bo.
The final nreg elements are the estimated linear regression coefficients bi, for i=1,2,…,k.
se
Type: array< System..::..Double >[]()[][]
An array of size [npar]
On exit: the standard errors for θ^.
The first element contains the standard error for αo and the next iq elements contain the standard errors for αi, for i=1,2,…,q.
The next ip elements are the standard errors for βj, for j=1,2,…,p.
The next element contains the standard error for γ.
If dist="T", the next element contains the standard error for df, the number of degrees of freedom of the Student's t-distribution.
If mn=1, the next element contains the standard error for bo.
The final nreg elements are the standard errors for bj, for j=1,2,…,k.
sc
Type: array< System..::..Double >[]()[][]
An array of size [npar]
On exit: the scores for θ^.
The first element contains the score for αo, the next iq elements contain the scores for αi, for i=1,2,…,q.
The next ip elements are the score for βj, for j=1,2,…,p.
The next element contains the score for γ.
If dist="T", the next element contains the score for df, the number of degrees of freedom of the Student's t-distribution.
If mn=1, the next element contains the score for bo.
The final nreg elements are the scores for bj, for j=1,2,…,k.
covr
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, npar]
Note: dim1 must satisfy the constraint: dim1≥npar
On exit: the covariance matrix of the parameter estimates θ^, that is the inverse of the Fisher Information Matrix.
hp
Type: System..::..Double %
On entry: if copts[1]=false, hp is the value to be used for the pre-observed conditional variance; otherwise hp is not referenced.
On exit: if copts[1]=true, hp is the estimated value of the pre-observed conditional variance.
et
Type: array< System..::..Double >[]()[][]
An array of size [num]
On exit: the estimated residuals, εt, for t=1,2,…,T.
ht
Type: array< System..::..Double >[]()[][]
An array of size [num]
On exit: the estimated conditional variances, ht, for t=1,2,…,T.
lgf
Type: System..::..Double %
On exit: the value of the log-likelihood function at θ^.
copts
Type: array< System..::..Boolean >[]()[][]
An array of size [2]
On entry: the options to be used by g13fe.
copts[0]=true
Stationary conditions are enforced, otherwise they are not.
copts[1]=true
The method provides initial parameter estimates of the regression terms, otherwise these are to be provided by you.
maxit
Type: System..::..Int32
On entry: the maximum number of iterations to be used by the optimization method when estimating the GARCH p,q parameters. If maxit is set to 0, the standard errors, score vector and variance-covariance are calculated for the input value of θ in theta; however the value of θ is not updated.
Constraint: maxit≥0.
tol
Type: System..::..Double
On entry: the tolerance to be used by the optimization method when estimating the GARCH p,q parameters.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

A univariate regression-GJR GARCH p,q process, with q coefficients αi, for i=1,2,…,q, p coefficients βi, for i=1,2,…,p, and k linear regression coefficients bi, for i=1,2,…,k, can be represented by:
yt=bo+xtT b+εt (1)
ht=α 0+∑i=1 q αi+γ I t-i ε t-i 2+∑i=1 p βih t-i,  t=1,2,…,T (2)
where It=1, if εt<0, It=0, if εt≥0, and εt∣ψ t-1=N 0,ht or εt∣ψ t-1=St df,ht. Here St is a standardized Student's t-distribution with df degrees of freedom and variance ht, T is the number of terms in the sequence, yt denotes the endogenous variables, xt the exogenous variables, bo the regression mean, b the regression coefficients, εt the residuals, ht is the conditional variance, and ψt the set of all information up to time t.
g13fe provides an estimate for θ^, the parameter vector θ=bo,bT,ωT where bT=b 1,…,bk, ωT=α 0,α 1,…,αq,β 1,…,βp,γ when dist="N" and ωT=α 0,α 1,…,αq,β 1,…,βp,γ,df when dist="T".
mn, nreg can be used to simplify the GARCH p,q expression in (1) as follows:
No Regression and No Mean
  • yt=εt,
  • mn=0,
  • nreg=0 and
  • θ is a p+q+2 vector when dist="N", and a p+q+3 vector when dist="T".
No Regression
  • yt=bo+εt,
  • mn=1,
  • nreg=0 and
  • θ is a p+q+3 vector when dist="N", and a p+q+4 vector when dist="T".
Note: if the yt=μ+εt, where μ is known (not to be estimated by g13fe) then (1) can be written as ytμ=εt, where ytμ=yt-μ. This corresponds to the case No Regression and No Mean, with yt replaced by yt-μ.
No Mean
  • yt=xtT b+εt,
  • mn=0,
  • nreg=k and
  • θ is a p+q+k+2 vector when dist="N", and a p+q+k+3 vector when dist="T".

References

Bollerslev T (1986) Generalised autoregressive conditional heteroskedasticity Journal of Econometrics 31 307–327
Engle R (1982) Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation Econometrica 50 987–1008
Engle R and Ng V (1993) Measuring and testing the impact of news on volatility Journal of Finance 48 1749–1777
Glosten L, Jagannathan R and Runkle D (1993) Relationship between the expected value and the volatility of nominal excess return on stocks Journal of Finance 48 1779–1801
Hamilton J (1994) Time Series Analysis Princeton University Press

Error Indicators and Warnings

Note: g13fe may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDCOVR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | nreg<0,
or | mn>1,
or | mn<0,
or | iq<1,
or | ip<0,
or | npar≥20,
or | npar has an invalid value,
or | dist≠"N",
or | dist≠"T",
or | maxit<0,
or | num<max ip,iq,
or | num<nreg+mn.
ifail=2
On entry, lwork<nreg+3×num+npar+403.
ifail=3
The matrix X is not full rank.
ifail=4
The information matrix is not positive definite.
ifail=5
The maximum number of iterations has been reached.
ifail=6
The log-likelihood cannot be optimized any further.
ifail=7
No feasible model parameters could be found.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

This example fits a GARCH 1,1 model with Student's t-distributed residuals to some simulated data.

Example program (C#): g13fee.cs

Example program data: g13fee.d

Example program results: g13fee.r

See Also

G13 Class
G13 Members


g13ff Method

[image]

NAG Library for .NET Release 2
G13..::g13ff Method
G13 Class See Also Send Feedback
g13ff forecasts the conditional variances, ht, for t=T+1,…,T+ξ from a GJR GARCH p,q sequence, where ξ is the forecast horizon and T is the current time (see Glosten et al. (1993)).

Syntax

C#
public static void g13ff(
    int num,
    int nt,
    int ip,
    int iq,
    double[] theta,
    double gamma,
    double[] fht,
    double[] ht,
    double[] et,
    out int ifail
)
Visual Basic
Public Shared Sub g13ff ( _
    num As Integer, _
    nt As Integer, _
    ip As Integer, _
    iq As Integer, _
    theta As Double(), _
    gamma As Double, _
    fht As Double(), _
    ht As Double(), _
    et As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13ff(
    int num,
    int nt,
    int ip,
    int iq,
    array<double>^ theta,
    double gamma,
    array<double>^ fht,
    array<double>^ ht,
    array<double>^ et,
    [OutAttribute] int% ifail
)
F#
static member g13ff :
        num : int *
        nt : int *
        ip : int *
        iq : int *
        theta : float[] *
        gamma : float *
        fht : float[] *
        ht : float[] *
        et : float[] *
        ifail : int byref -> unit

Parameters

num
Type: System..::..Int32
On entry: the number of terms in the arrays ht and et from the modelled sequence.
Constraint: max ip,iq≤num.
nt
Type: System..::..Int32
On entry: ξ, the forecast horizon.
Constraint: nt>0.
ip
Type: System..::..Int32
On entry: the number of coefficients, βi, for i=1,2,…,p.
Constraints:
  • max ip,iq≤20;
  • ip≥0.
iq
Type: System..::..Int32
On entry: the number of coefficients, αi, for i=1,2,…,q.
Constraints:
  • max ip,iq≤20;
  • iq≥1.
theta
Type: array< System..::..Double >[]()[][]
An array of size [iq+ip+1]
On entry: the first element must contain the coefficient αo and the next iq elements must contain the coefficients αi, for i=1,2,…,q. The remaining ip elements must contain the coefficients βj, for j=1,2,…,p.
gamma
Type: System..::..Double
On entry: the asymmetry parameter γ for the GARCH p,q sequence.
fht
Type: array< System..::..Double >[]()[][]
An array of size [nt]
On exit: the forecast values of the conditional variance, ht, for t=T+1,…,T+ξ.
ht
Type: array< System..::..Double >[]()[][]
An array of size [num]
On entry: the sequence of past conditional variances for the GARCH p,q process, ht, for t=1,2,…,T.
et
Type: array< System..::..Double >[]()[][]
An array of size [num]
On entry: the sequence of past residuals for the GARCH p,q process, εt, for t=1,2,…,T.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Assume the GARCH p,q process can be represented by:
ht=α 0+∑i=1 q αi+γ I t-i ε t-i 2+∑i=1 p βih t-i,  t=1,2,…,T.
where εt∣ψ t-1=N 0,ht or εt∣ψ t-1=St df,ht, and It=1, if εt<0, or It=0, if εt≥0, has been modelled by g13fe, and the estimated conditional variances and residuals are contained in the arrays ht and et respectively.
g13ff will then use the last max p,q elements of the arrays ht and et to estimate the conditional variance forecasts, ht∣ψT, where t=T+1,…,T+ξ and ξ is the forecast horizon.

References

Bollerslev T (1986) Generalised autoregressive conditional heteroskedasticity Journal of Econometrics 31 307–327
Engle R (1982) Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation Econometrica 50 987–1008
Engle R and Ng V (1993) Measuring and testing the impact of news on volatility Journal of Finance 48 1749–1777
Glosten L, Jagannathan R and Runkle D (1993) Relationship between the expected value and the volatility of nominal excess return on stocks Journal of Finance 48 1779–1801
Hamilton J (1994) Time Series Analysis Princeton University Press

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | num<max ip,iq,
or | iq<1,
or | ip<0,
or | max ip,iq>20,
or | nt≤0.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable

Parallelism and Performance

None.

Further Comments

None.

Example

See [Example] in g13fe.

See Also

G13 Class
G13 Members


g13fg Method

[image]

NAG Library for .NET Release 2
G13..::g13fg Method
G13 Class See Also Send Feedback
g13fg estimates the parameters of a univariate regression-exponential GARCH p,q process (see Engle and Ng (1993)).

Syntax

C#
public static void g13fg(
    string dist,
    double[] yt,
    double[,] x,
    int num,
    int ip,
    int iq,
    int nreg,
    int mn,
    int npar,
    double[] theta,
    double[] se,
    double[] sc,
    double[,] covr,
    ref double hp,
    double[] et,
    double[] ht,
    out double lgf,
    bool copts,
    int maxit,
    double tol,
    out int ifail
)
Visual Basic
Public Shared Sub g13fg ( _
    dist As String, _
    yt As Double(), _
    x As Double(,), _
    num As Integer, _
    ip As Integer, _
    iq As Integer, _
    nreg As Integer, _
    mn As Integer, _
    npar As Integer, _
    theta As Double(), _
    se As Double(), _
    sc As Double(), _
    covr As Double(,), _
    ByRef hp As Double, _
    et As Double(), _
    ht As Double(), _
    <OutAttribute> ByRef lgf As Double, _
    copts As Boolean, _
    maxit As Integer, _
    tol As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13fg(
    String^ dist,
    array<double>^ yt,
    array<double,2>^ x,
    int num,
    int ip,
    int iq,
    int nreg,
    int mn,
    int npar,
    array<double>^ theta,
    array<double>^ se,
    array<double>^ sc,
    array<double,2>^ covr,
    double% hp,
    array<double>^ et,
    array<double>^ ht,
    [OutAttribute] double% lgf,
    bool copts,
    int maxit,
    double tol,
    [OutAttribute] int% ifail
)
F#
static member g13fg :
        dist : string *
        yt : float[] *
        x : float[,] *
        num : int *
        ip : int *
        iq : int *
        nreg : int *
        mn : int *
        npar : int *
        theta : float[] *
        se : float[] *
        sc : float[] *
        covr : float[,] *
        hp : float byref *
        et : float[] *
        ht : float[] *
        lgf : float byref *
        copts : bool *
        maxit : int *
        tol : float *
        ifail : int byref -> unit

Parameters

dist
Type: System..::..String
On entry: the type of distribution to use for et.
dist="N"
A Normal distribution is used.
dist="T"
A Student's t-distribution is used.
Constraint: dist="N" or "T".
yt
Type: array< System..::..Double >[]()[][]
An array of size [num]
On entry: the sequence of observations, yt, for t=1,2,…,T.
x
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥num
Note: the second dimension of the array x must be at least nreg.
On entry: row t of x must contain the time dependent exogenous vector xt, where xtT=xt 1,…,xtk, for t=1,2,…,T.
num
Type: System..::..Int32
On entry: T, the number of terms in the sequence.
Constraints:
  • num≥max ip,iq;
  • num≥nreg+mn.
ip
Type: System..::..Int32
On entry: the number of coefficients, βi, for i=1,2,…,p.
Constraint: ip≥0 (see also npar).
iq
Type: System..::..Int32
On entry: the number of coefficients, αi, for i=1,2,…,q.
Constraint: iq≥1 (see also npar).
nreg
Type: System..::..Int32
On entry: k, the number of regression coefficients.
Constraint: nreg≥0 (see also npar).
mn
Type: System..::..Int32
On entry: if mn=1, the mean term b 0 will be included in the model.
Constraint: mn=0 or 1.
npar
Type: System..::..Int32
On entry: the number of parameters to be included in the model. npar=1+2×iq+ip+mn+nreg when dist="N" and npar=2+2×iq+ip+mn+nreg when dist="T".
Constraint: npar<20.
theta
Type: array< System..::..Double >[]()[][]
An array of size [npar]
On entry: the initial parameter estimates for the vector θ.
The first element must contain the coefficient αo and the next iq elements must contain the autoregressive coefficients αi, for i=1,2,…,q.
The next iq elements contain the coefficients ϕi, for i=1,2,…,q.
The next ip elements must contain the moving average coefficients βi, for i=1,2,…,p.
If dist="T", the next element must contain an estimate for df, the number of degrees of freedom of the Student's t-distribution.
If mn=1, the next element must contain the mean term bo.
If copts=false, the remaining nreg elements are taken as initial estimates of the linear regression coefficients bi, for i=1,2,…,k.
On exit: the estimated values θ^ for the vector θ.
The first element contains the coefficient αo and the next iq elements contain the coefficients αi, for i=1,2,…,q.
The next iq elements contain the coefficients ϕi, for i=1,2,…,q.
The next ip elements are the moving average coefficients βi, for i=1,2,…,p.
If dist="T", the next element contains an estimate for df then the number of degrees of freedom of the Student's t-distribution.
If mn=1, the next element contains an estimate for the mean term bo.
The final nreg elements are the estimated linear regression coefficients bi, for i=1,2,…,k.
se
Type: array< System..::..Double >[]()[][]
An array of size [npar]
On exit: the standard errors for θ^.
The first element contains the standard error for αo and the next iq elements contain the standard errors for αi, for i=1,2,…,q. The next iq elements contain the standard errors for ϕi, for i=1,2,…,q. The next ip elements are the standard errors for βj, for j=1,2,…,p.
If dist="T", the next element contains the standard error for df, the number of degrees of freedom of the Student's t-distribution.
If mn=1, the next element contains the standard error for bo.
The final nreg elements are the standard errors for bj, for j=1,2,…,k.
sc
Type: array< System..::..Double >[]()[][]
An array of size [npar]
On exit: the scores for θ^.
The first element contains the scores for αo, the next iq elements contain the scores for αi, for i=1,2,…,q, the next iq elements contain the scores for ϕi, for i=1,2,…,q, the next ip elements are the scores for βj, for j=1,2,…,p.
If dist="T", the next element contains the scores for df, the number of degrees of freedom of the Student's t-distribution.
If mn=1, the next element contains the score for bo.
The final nreg elements are the scores for bj, for j=1,2,…,k.
covr
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, npar]
Note: dim1 must satisfy the constraint: dim1≥npar
On exit: the covariance matrix of the parameter estimates θ^, that is the inverse of the Fisher Information Matrix.
hp
Type: System..::..Double %
On entry: if copts=false then hp is the value to be used for the pre-observed conditional variance, otherwise hp is not referenced.
On exit: if copts=true then hp is the estimated value of the pre-observed conditional variance.
et
Type: array< System..::..Double >[]()[][]
An array of size [num]
On exit: the estimated residuals, εt, for t=1,2,…,T.
ht
Type: array< System..::..Double >[]()[][]
An array of size [num]
On exit: the estimated conditional variances, ht, for t=1,2,…,T.
lgf
Type: System..::..Double %
On exit: the value of the log-likelihood function at θ^.
copts
Type: System..::..Boolean
On entry: if copts=true, the method provides initial parameter estimates of the regression terms, otherwise these are provided by you.
maxit
Type: System..::..Int32
On entry: the maximum number of iterations to be used by the optimization method when estimating the GARCH p,q parameters.
Constraint: maxit>0.
tol
Type: System..::..Double
On entry: the tolerance to be used by the optimization method when estimating the GARCH p,q parameters.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

A univariate regression-exponential GARCH p,q process, with q coefficients αi, for i=1,2,…,q, q coefficients ϕi, for i=1,2,…,q, p coefficients, βi, for i=1,2,…,p, and k linear regression coefficients bi, for i=1,2,…,k, can be represented by:
yt=bo+xtT b+εtln ht=α 0+∑i=1 q αiz t-i+∑i=1 q ϕi z t-i-E z t-i+∑i=1 p βi ln h t-i,  t=1,2,…,T (1)
where zt=εt ht, E z t-i denotes the expected value of z t-i and εt∣ψ t-1=N 0,ht or εt∣ψ t-1=St df,ht. Here St is a standardized Student's t-distribution with df degrees of freedom and variance ht, T is the number of terms in the sequence, yt denotes the endogenous variables, xt the exogenous variables, bo the regression mean, b the regression coefficients, εt the residuals, ht the conditional variance, df the number of degrees of freedom of the Student's t-distribution, and ψt the set of all information up to time t.
g13fg provides an estimate θ^, for the vector θ=bo,bT,ωT where bT=b 1,…,bk, ωT=α 0,α 1,…,αq,ϕ 1,…,ϕq,β 1,…,βp,γ when dist="N", and ωT=α 0,α 1,…,αq,ϕ 1,…,ϕq,β 1,…,βp,γ,df when dist="T".
mn, nreg can be used to simplify the GARCH p,q expression in (1) as follows:
No Regression and No Mean
  • yt=εt,
  • mn=0,
  • nreg=0 and
  • θ is a 2×q+p+1 vector when dist="N", and a 2×q+p+2 vector, when dist="T".
No Regression
  • yt=bo+εt,
  • mn=1,
  • nreg=0 and
  • θ is a 2×q+p+2 vector when dist="N" and a 2×q+p+3 vector, when dist="T".
Note: if the yt=μ+εt, where μ is known (not to be estimated by g13fg) then (1) can be written as ytμ=εt, where ytμ=yt-μ. This corresponds to the case No Regression and No Mean, with yt replaced by yt-μ.
No Mean
  • yt=xtT b+εt,
  • mn=0,
  • nreg=k and
  • θ is a 2×q+p+1+k vector when dist="N" and a 2×q+p+2+k vector, when dist="T".

References

Bollerslev T (1986) Generalised autoregressive conditional heteroskedasticity Journal of Econometrics 31 307–327
Engle R (1982) Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation Econometrica 50 987–1008
Engle R and Ng V (1993) Measuring and testing the impact of news on volatility Journal of Finance 48 1749–1777
Glosten L, Jagannathan R and Runkle D (1993) Relationship between the expected value and the volatility of nominal excess return on stocks Journal of Finance 48 1779–1801
Hamilton J (1994) Time Series Analysis Princeton University Press

Error Indicators and Warnings

Note: g13fg may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDX, LDCOVR) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, | nreg<0,
or | mn>1,
or | mn<0,
or | iq<1,
or | ip<0,
or | npar≥20,
or | npar has an invalid value,
or | dist≠"N",
or | dist≠"T",
or | maxit≤0,
or | num<max ip,iq,
or | num<nreg+mn.
ifail=2
On entry, lwork<nreg+3×num+3.
ifail=3
The matrix X is not full rank.
ifail=4
The information matrix is not positive definite.
ifail=5
The maximum number of iterations has been reached.
ifail=6
The log-likelihood cannot be optimized any further.
ifail=7
No feasible model parameters could be found.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

This example fits a GARCH 1,2 model with Student's t-distributed residuals to some simulated data.

Example program (C#): g13fge.cs

Example program data: g13fge.d

Example program results: g13fge.r

See Also

G13 Class
G13 Members


g13fh Method

[image]

NAG Library for .NET Release 2
G13..::g13fh Method
G13 Class See Also Send Feedback
g13fh forecasts the conditional variances, ht,t=T+1,…,T+ξ from an exponential GARCH p,q sequence, where ξ is the forecast horizon and T is the current time (see Engle and Ng (1993)).

Syntax

C#
public static void g13fh(
    int num,
    int nt,
    int ip,
    int iq,
    double[] theta,
    double[] fht,
    double[] ht,
    double[] et,
    out int ifail
)
Visual Basic
Public Shared Sub g13fh ( _
    num As Integer, _
    nt As Integer, _
    ip As Integer, _
    iq As Integer, _
    theta As Double(), _
    fht As Double(), _
    ht As Double(), _
    et As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g13fh(
    int num,
    int nt,
    int ip,
    int iq,
    array<double>^ theta,
    array<double>^ fht,
    array<double>^ ht,
    array<double>^ et,
    [OutAttribute] int% ifail
)
F#
static member g13fh :
        num : int *
        nt : int *
        ip : int *
        iq : int *
        theta : float[] *
        fht : float[] *
        ht : float[] *
        et : float[] *
        ifail : int byref -> unit

Parameters

num
Type: System..::..Int32
On entry: the number of terms in the arrays ht and et from the modelled sequence.
Constraint: max ip,iq≤num.
nt
Type: System..::..Int32
On entry: ξ, the forecast horizon.
Constraint: nt>0.
ip
Type: System..::..Int32
On entry: the number of coefficients, βi, for i=1,2,…,p.
Constraints:
  • max ip,iq≤20;
  • ip≥0.
iq
Type: System..::..Int32
On entry: the number of coefficients, αi, for i=1,2,…,q.
Constraints:
  • max ip,iq≤20;
  • iq≥1.
theta
Type: array< System..::..Double >[]()[][]
An array of size [2×iq+ip+1]
On entry: the initial parameter estimates for the vector θ. The first element must contain the coefficient αo and the next iq elements must contain the autoregressive coefficients αi, for i=1,2,…,q. The next iq elements must contain the coefficients ϕi, for i=1,2,…,q. The next ip elements must contain the moving average coefficients βj, for j=1,2,…,p.
fht
Type: array< System..::..Double >[]()[][]
An array of size [nt]
On exit: the forecast values of the conditional variance, ht, for t=T+1,…,T+ξ.
ht
Type: array< System..::..Double >[]()[][]
An array of size [num]
On entry: the sequence of past conditional variances for the GARCH p,q process, ht, for t=1,2,…,T.
et
Type: array< System..::..Double >[]()[][]
An array of size [num]
On entry: the sequence of past residuals for the GARCH p,q process, εt, for t=1,2,…,T.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Assume the GARCH p,q process represented by:
ln ht=α 0+∑i=1 q αiz t-i+∑j=1 q ϕi z t-j-E z t-i+∑j=1 p βi ln h t-j,  t=1,2,…,T.
where εt∣ψ t-1=N 0,ht or εt∣ψ t-1=St df,ht, and zt=εt ht, E z t-i denotes the expected value of z t-i, has been modelled by g13fg, and the estimated conditional variances and residuals are contained in the arrays ht and et respectively.
g13fh will then use the last max p,q elements of the arrays ht and et to estimate the conditional variance forecasts, ht∣ψT, where t=T+1,…,T+ξ and ξ is the forecast horizon.

References

Bollerslev T (1986) Generalised autoregressive conditional heteroskedasticity Journal of Econometrics 31 307–327
Engle R (1982) Autoregressive conditional heteroskedasticity with estimates of the variance of United Kingdom inflation Econometrica 50 987–1008
Engle R and Ng V (1993) Measuring and testing the impact of news on volatility Journal of Finance 48 1749–1777
Glosten L, Jagannathan R and Runkle D (1993) Relationship between the expected value and the volatility of nominal excess return on stocks Journal of Finance 48 1779–1801
Hamilton J (1994) Time Series Analysis Princeton University Press

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | num<max ip,iq,
or | iq<1,
or | ip<0,
or | max ip,iq>20,
or | nt≤0.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

None.

Example

See [Example] in g13fg.

See Also

G13 Class
G13 Members


H Class

[image]

NAG Library for .NET Release 2
H Class
Members See Also Send Feedback
This chapter provides methods to solve certain integer programming, transportation and shortest path problems. Additionally ‘best subset’ methods are included.

Syntax

C#
public static class H
Visual Basic
Public NotInheritable Class H
Visual C++
public ref class H abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type H =  class end

Background to the Problems

General linear programming (LP) problems (see Dantzig (1963)) are of the form:
  • find x=x 1,x 2,…,xn T to maximize F x=∑j=1 n cjxj
  • subject to linear constraints which may have the forms:
    ∑j=1 n a ijxj=bi,i=1,2,…,m 1(equality)∑j=1 n a ijxj≤bi,i=m 1+1,…,m 2(inequality)∑j=1 n a ijxj≥bi,i=m 2+1,…,m(inequality)xj≥lj,j=1,2,…,n(simple bound)xj≤uj,j=1,2,…,n(simple bound)
This chapter deals with integer programming (IP) problems in which some or all the elements of the solution vector x are further constrained to be integers. For general LP problems where x takes only real (i.e., noninteger) values, refer to E04 class.
IP problems may or may not have a solution, which may or may not be unique.
Consider for example the following problem:
minimize3 x 1+2 x 2subject to4 x 1+2 x 2≥52 x 2≤50 x 1-0 x 2≤2and0 x 1≥0,x 2≥0.
The hatched area in Figure 1 is the feasible region, the region where all the constraints are satisfied, and the points within it which have integer coordinates are circled. The lines of hatching are in fact contours of decreasing values of the objective function 3 x 1+2 x 2, and it is clear from Figure 1 that the optimum IP solution is at the point 1,1. For this problem the solution is unique.
However, there are other possible situations.
(a) There may be more than one solution; e.g., if the objective function in the above problem were changed to x 1+x 2, both 1,1 and 2,0 would be IP solutions.
(b) The feasible region may contain no points with integer coordinates, e.g., if an additional constraint
3 x 1≤2
were added to the above problem.
(c) There may be no feasible region, e.g., if an additional constraint
x 1+x 2≤1
were added to the above problem.
(d) The objective function may have no finite minimum within the feasible region; this means that the feasible region is unbounded in the direction of decreasing values of the objective function, e.g., if the constraints
4 x 1+2 x 2≥5,  x 1≥0,  x 2≥0,
were deleted from the above problem.
Figure 1
Algorithms for IP problems are usually based on algorithms for general LP problems, together with some procedure for constructing additional constraints which exclude noninteger solutions (see Beale (1977)).
The Branch and Bound (B&B) method is a well-known and widely used technique for solving IP problems (see Beale (1977) or Mitra (1973)). It involves subdividing the optimum solution to the original LP problem into two mutually exclusive sub-problems by branching an integer variable that currently has a fractional optimal value. Each sub-problem can now be solved as an LP problem, using the objective function of the original problem. The process of branching continues until a solution for one of the sub-problems is feasible with respect to the integer problem. In order to prove the optimality of this solution, the rest of the sub-problems in the B&B tree must also be solved. Naturally, if a better integer feasible solution is found for any sub-problem, it should replace the one at hand.
A common method for specifying IP and LP problems in general is the use of the MPSX file format (see IBM (1971)). A full description of this file format is provided in the method document for (H02BUF not in this release).
The efficiency in computations is enhanced by discarding inferior sub-problems. These are problems in the B&B search tree whose LP solutions are lower than (in the case of maximization) the best integer solution at hand.
The B&B method may also be applied to convex quadratic programming (QP) problems. Methods have been introduced into this chapter to formally apply the technique to dense general QP problems and to sparse LP or QP problems.
A special type of linear programming problem is the transportation problem in which there are p×q variables y kl which represent quantities of goods to be transported from each of p sources to each of q destinations.
The problem is to minimize
∑k=1 p∑l=1 q c kly kl
where c kl is the unit cost of transporting from source k to destination l. The constraints are:
∑l=1 q y kl=Akavailabilities∑k=1 p y kl=Blrequirementsy kl≥0.
Note that the availabilities must equal the requirements:
∑k=1 p Ak=∑l=1 q Bl=∑k=1 p∑l=1 q y kl
and if all the Ak and Bl are integers, then so are the optimal y kl.
The shortest path problem is that of finding a path of minimum length between two distinct vertices ns and ne through a network. Suppose the vertices in the network are labelled by the integers 1,2,…,n. Let i,j denote an ordered pair of vertices in the network (where i is the origin vertex and j the destination vertex of the arc), x ij the amount of flow in arc i,j and d ij the length of the arc i,j. The LP formulation of the problem is thus given as
minimize  ∑∑d ijx ij subject to ​Ax=b,  0≤x≤1, (1)
where
a ij=+1if arc ​j​ is directed away from vertex ​i,-1if arc ​j​ is directed towards vertex ​i,0otherwise
and
bi=+1for ​i=ns,-1for ​i=ne,0otherwise.
The above formulation only yields a meaningful solution if x ij=0​ or ​1; that is, arc i,j forms part of the shortest route only if x ij=1. In fact since the optimal LP solution will (in theory) always yield x ij=0​ or ​1, (1) can also be solved as an IP problem. Note that the problem may also be solved directly (and more efficiently) using a variant of Dijkstra's algorithm (see Ahuja et al. (1993)).
The travelling salesman problem is that of finding a minimum distance route round a given set of cities. The salesperson must visit each city only once before returning to his or her city of origin. It can be formulated as an IP problem in a number of ways. One such formulation is described in Williams (1993). There are currently no methods in the Library for solving such problems.
The best n subsets problem assumes a scoring mechanism and a set of m features. The problem is one of choosing the best n subsets of size p. It is addressed by two methods in this chapter. The first of these uses reverse communication; the second direct communication.

Recommendations on Choice and Use of Available Methods

h02bb | solves dense integer programming problems using a branch and bound method.
(H02BFF not in this release) | solves dense integer or linear programming problems defined by a MPSX data file.
(H02BUF not in this release) | converts an MPSX data file defining an integer or a linear programming problem to the form required by e04mf or h02bb.
(H02BVF not in this release) | prints the solution to an integer or a linear programming problem using specified names for rows and columns.
(H02BZF not in this release) | supplies further information on the optimum solution obtained by h02bb.
h02cb | solves dense integer general quadratic programming problems.
(H02CCF not in this release) | reads optional parameter values for h02cb from external file.
(H02CDF not in this release) | supplies optional parameter values to h02cb.
h02ce | solves sparse integer linear programming or quadratic programming problems.
(H02CFF not in this release) | reads optional parameter values for h02ce from external file.
(H02CGF not in this release) | supplies optional parameter values to h02ce.
(H03ABF not in this release) | solves transportation problems. It uses integer arithmetic throughout and so produces exact results. On a few machines, however, there is a risk of integer overflow without warning, so the integer values in the data should be kept as small as possible by dividing out any common factors from the coefficients of the constraint or objective functions.
(H03ADF not in this release) | solves shortest path problems using Dijkstra's algorithm.
h02bb (H02BFF not in this release) (H03ABF not in this release) treat all matrices as dense and hence are not intended for large sparse problems. For solving large sparse LP problems, use e04nq or e04ug.

Transportation Problem

(H03ABF not in this release) solves transportation problems. It uses integer arithmetic throughout and so produces exact results. On a few machines, however, there is a risk of integer overflow without warning, so the integer values in the data should be kept as small as possible by dividing out any common factors from the coefficients of the constraint or objective functions.

Feature Selection – Best Subset Problem

(H05AAF not in this release) selects the best n subsets of size p using a reverse communication branch and bound algorithm.
(H05ABF not in this release) selects the best n subsets of size p using a direct communication branch and bound algorithm.

References

Ahuja R K, Magnanti T L and Orlin J B (1993) Network Flows: Theory, Algorithms and Applications Prentice–Hall
Beale E M (1977) Integer programming The State of the Art in Numerical Analysis (ed D A H Jacobs) Academic Press
Dantzig G B (1963) Linear Programming and Extensions Princeton University Press
IBM (1971) MPSX – Mathematical programming system Program Number 5734 XM4 IBM Trade Corporation, New York
Mitra G (1973) Investigation of some branch and bound strategies for the solution of mixed integer linear programs Math. Programming 4 155–170
Williams H P (1993) Model Building in Mathematical Programming (3rd Edition) Wiley

Inheritance Hierarchy

System..::..Object
NagLibrary..::..H

See Also

H Members


H Members

[image] [image]

NAG Library for .NET Release 2
H Members
H Class Methods See Also Send Feedback

The H type exposes the following members.

Methods

Name | Description
h02bb | h02bb solves ‘zero-one’, ‘general’, ‘mixed’ or ‘all’ integer programming problems using a branch and bound method. The method may also be used to find either the first integer solution or the optimum integer solution. It is not intended for large sparse problems.
h02cb | h02cb solves general quadratic programming problems with integer constraints on the variables. It is not intended for large sparse problems.
h02cbu | Auxiliary for use as a delegate parameter
h02cbv | NAG supplied callback for h02cbf.
h02ce | h02ce obtains integer solutions to sparse linear programming and quadratic programming problems.

See Also

H Class


H Delegates

[image]

NAG Library for .NET Release 2
H Delegates

H Delegate Types

  • H.H02CB_MONIT Delegate
  • H.H02CB_QPHESS Delegate
  • H.H02CE_MONIT Delegate
  • H.H02CE_QPHX Delegate


H.H02CB_MONIT Delegate

[image]

NAG Library for .NET Release 2
H..::..H02CB_MONIT Delegate
H Class See Also Send Feedback
monit may be used to print out intermediate output and to affect the course of the computation. Specifically, it allows you to specify a realistic value for the cut-off value (see [Description]) and to terminate the algorithm. If you do not require any intermediate output, have no estimate of the cut-off value and require an exhaustive tree search then monit may be the dummy method H02CBU.

Syntax

C#
public delegate void H02CB_MONIT(
    int intfnd,
    int nodes,
    int depth,
    double obj,
    double[] x,
    ref double bstval,
    double[] bstsol,
    double[] bl,
    double[] bu,
    int n,
    ref bool halt,
    ref int count
)
Visual Basic
Public Delegate Sub H02CB_MONIT ( _
    intfnd As Integer, _
    nodes As Integer, _
    depth As Integer, _
    obj As Double, _
    x As Double(), _
    ByRef bstval As Double, _
    bstsol As Double(), _
    bl As Double(), _
    bu As Double(), _
    n As Integer, _
    ByRef halt As Boolean, _
    ByRef count As Integer _
)
Visual C++
public delegate void H02CB_MONIT(
    int intfnd,
    int nodes,
    int depth,
    double obj,
    array<double>^ x,
    double% bstval,
    array<double>^ bstsol,
    array<double>^ bl,
    array<double>^ bu,
    int n,
    bool% halt,
    int% count
)
F#
type H02CB_MONIT =
    delegate of
        intfnd : int *
        nodes : int *
        depth : int *
        obj : float *
        x : float[] *
        bstval : float byref *
        bstsol : float[] *
        bl : float[] *
        bu : float[] *
        n : int *
        halt : bool byref *
        count : int byref -> unit

Parameters

intfnd
Type: System..::..Int32
On entry: specifies the number of integer solutions obtained so far.
nodes
Type: System..::..Int32
On entry: specifies the number of nodes (sub-problems) solved so far.
depth
Type: System..::..Int32
On entry: specifies the depth in the tree of sub-problems the algorithm has now reached.
obj
Type: System..::..Double
On entry: specifies the value of the objective function of the end of the latest sub-problem.
x
Type: array< System..::..Double >[]()[][]
On entry: specifies the values of the independent variables at the end of the latest sub-problem.
bstval
Type: System..::..Double %
On entry: normally specifies the value of the best integer solution found so far.
On exit: may be set a cut-off value if you are an experienced user as follows. Before an integer solution has been found bstval will be set by h02cb to the largest machine representable number (see x02al). If you know that the solution being sought is a much smaller number, then bstval may be set to this number as a cut-off value (see []). Beware of setting bstval too small, since then no integer solutions will be discovered. Also make sure that bstval is set using a statement of the form
IF (intfnd.EQ.0) bstval= cut-off value
on entry to monit. This statement will not prevent the normal operation of the algorithm when subsequent integer solutions are found. It would be a grievous mistake to unconditionally set bstval and if you have any doubts whatsoever about the correct use of this parameter then you are strongly recommended to leave it unchanged.
bstsol
Type: array< System..::..Double >[]()[][]
On entry: specifies the solution vector which gives rise to the best integer solution value so far discovered.
bl
Type: array< System..::..Double >[]()[][]
On entry: bl[i] specifies the current lower bounds on the variable xi.
bu
Type: array< System..::..Double >[]()[][]
On entry: bu[i] specifies the current upper bounds on the variable xi.
n
Type: System..::..Int32
On entry: specifies the number of variables.
halt
Type: System..::..Boolean %
On entry: will have the value false.
On exit: if halt is set to true, e04nf will be brought to a halt with ifail=-1. This facility may be useful if you are content with any integer solution, or with any integer solution that fits certain criteria. Under these circumstances setting halt=true can save considerable unnecessary computation.
count
Type: System..::..Int32 %
On entry: unchanged from previous call.
On exit: may be used by you to save the last value of intfnd. If a subsequent call of monit has a value of intfnd which is greater than count, then you know that a new integer solution has been found at this node.

See Also

NagLibrary Namespace
NAG Library Overview
h02cb


H.H02CB_QPHESS Delegate

[image]

NAG Library for .NET Release 2
H..::..H02CB_QPHESS Delegate
H Class See Also Send Feedback
In general, you need not provide a version of qphess, because a ‘default’ method with name e04nfu is included in the Library. However, the algorithm of h02cb requires only the product of H or HT H and a vector x; and in some cases you may obtain increased efficiency by providing a version of qphess that avoids the need to define the elements of the matrices H or HT H explicitly. qphess is not referenced if the problem is of type FP or LP, in which case qphess may be the method e04nfu.

Syntax

C#
public delegate void H02CB_QPHESS(
    int n,
    int jthcol,
    double[,] h,
    double[] x,
    double[] hx,
    H..::..h02cbOptions options
)
Visual Basic
Public Delegate Sub H02CB_QPHESS ( _
    n As Integer, _
    jthcol As Integer, _
    h As Double(,), _
    x As Double(), _
    hx As Double(), _
    options As H..::..h02cbOptions _
)
Visual C++
public delegate void H02CB_QPHESS(
    int n,
    int jthcol,
    array<double,2>^ h,
    array<double>^ x,
    array<double>^ hx,
    H..::..h02cbOptions^ options
)
F#
type H02CB_QPHESS =
    delegate of
        n : int *
        jthcol : int *
        h : float[,] *
        x : float[] *
        hx : float[] *
        options : H..::..h02cbOptions -> unit

Parameters

n
Type: System..::..Int32
On entry: this is the same parameter n as supplied to h02cb.
jthcol
Type: System..::..Int32
On entry: specifies whether or not the vector x is a column of the identity matrix.
jthcol=j>0
The vector x is the jth column of the identity matrix, and hence Hx or hT Hx is the jth column of h or hT H, respectively, which may in some cases require very little computation and qphess may be coded to take advantage of this. However special code is not necessary because x is always stored explicitly in the array x.
jthcol=0
x has no special form.
h
Type: array< System..::..Double ,2>[,](,)[,][,]
On entry: this is the same parameter h as supplied to h02cb.
x
Type: array< System..::..Double >[]()[][]
On entry: the vector x.
hx
Type: array< System..::..Double >[]()[][]
On exit: the product Hx if the problem is of type QP1 or QP2 (the default), or the product hT Hx if the problem is of type QP3 or QP4.
options
Type: NagLibrary..::..H..::..h02cbOptions

See Also

NagLibrary Namespace
NAG Library Overview
h02cb


H.H02CE_MONIT Delegate

[image]

NAG Library for .NET Release 2
H..::..H02CE_MONIT Delegate
H Class See Also Send Feedback
To provide feed-back on the progress of the branch and bound process. Additionally monit provides, via its parameter halt, the ability to terminate the process. (You might choose to do this when an integer solution is found, rather than search for a better solution.) If you do not require any intermediate output then monit may be the dummy method (H02CEY not in this release).

Syntax

C#
public delegate void H02CE_MONIT(
    int intfnd,
    int nodes,
    int depth,
    double obj,
    double[] x,
    ref double bstval,
    double[] bstsol,
    double[] bl,
    double[] bu,
    int n,
    ref bool halt,
    ref int count
)
Visual Basic
Public Delegate Sub H02CE_MONIT ( _
    intfnd As Integer, _
    nodes As Integer, _
    depth As Integer, _
    obj As Double, _
    x As Double(), _
    ByRef bstval As Double, _
    bstsol As Double(), _
    bl As Double(), _
    bu As Double(), _
    n As Integer, _
    ByRef halt As Boolean, _
    ByRef count As Integer _
)
Visual C++
public delegate void H02CE_MONIT(
    int intfnd,
    int nodes,
    int depth,
    double obj,
    array<double>^ x,
    double% bstval,
    array<double>^ bstsol,
    array<double>^ bl,
    array<double>^ bu,
    int n,
    bool% halt,
    int% count
)
F#
type H02CE_MONIT =
    delegate of
        intfnd : int *
        nodes : int *
        depth : int *
        obj : float *
        x : float[] *
        bstval : float byref *
        bstsol : float[] *
        bl : float[] *
        bu : float[] *
        n : int *
        halt : bool byref *
        count : int byref -> unit

Parameters

intfnd
Type: System..::..Int32
On entry: contains the number of integer solutions obtained so far.
nodes
Type: System..::..Int32
On entry: contains the number of nodes (sub-problems) solved so far.
depth
Type: System..::..Int32
On entry: contains the depth reached in the tree of problems.
obj
Type: System..::..Double
On entry: contains the solution value to the sub-problem at this node.
x
Type: array< System..::..Double >[]()[][]
On entry: contains the solution vector to the sub-problem at this node.
bstval
Type: System..::..Double %
On entry: contains the value of the objective function corresponding to the best integer solution obtained so far. If no integer solution has been found bstval contains the largest machine representable number (see x02al).
On exit: may be set to a cut-off value, if you are a sophisticated user, as follows. Before an integer solution has been found bstval will be set by h02ce to the largest machine representable number (see x02al). If you know that the solution being sought is a much smaller number, then bstval may be set to this number as a cut-off value (see []). Beware of setting bstval too small, since then no integer solutions will be discovered. Also make sure that bstval is set using a statement of the form
IF (intfnd.EQ.0) bstval= cut-off value
on entry to monit. This statement will not prevent the normal operation of the algorithm when subsequent integer solutions are found. It would be a grievous mistake to unconditionally set bstval and if you have any doubts whatsoever about the correct use of this parameter then you are strongly recommended to leave it unchanged.
bstsol
Type: array< System..::..Double >[]()[][]
On entry: contains the value of the best integer solution obtained so far.
bl
Type: array< System..::..Double >[]()[][]
On entry: contains the current lower bounds on the variables at this point.
bu
Type: array< System..::..Double >[]()[][]
On entry: contains the current upper bounds on the variables at this point.
n
Type: System..::..Int32
On entry: contains the number of variables in the minimization problem.
halt
Type: System..::..Boolean %
On entry: will have the value false.
On exit: if halt is set to true, e04nk will be brought to a halt with ifail exit -1. This facility may be useful if you are content with any integer solution, or with any integer solution that fits certain criteria. Under these circumstances setting halt=true can save considerable unnecessary computation.
count
Type: System..::..Int32 %
count may be used to save the last value of intfnd. If a subsequent call of monit has a value of intfnd which is greater than count, then you know that a new integer solution has been found at this node.

See Also

NagLibrary Namespace
NAG Library Overview
h02ce


H.H02CE_QPHX Delegate

[image]

NAG Library for .NET Release 2
H..::..H02CE_QPHX Delegate
H Class See Also Send Feedback
For QP problems, you must supply a version of qphx to compute the matrix product Hx. If H has rows and columns consisting entirely of zeros, it is most efficient to order the variables x=y z T so that
Hx=H 1000yz=H 1 y0,
where the nonlinear variables y appear first as shown. For LP problems, qphx will never be called by h02ce.

Syntax

C#
public delegate void H02CE_QPHX(
    int nstate,
    int ncolh,
    double[] x,
    double[] hx
)
Visual Basic
Public Delegate Sub H02CE_QPHX ( _
    nstate As Integer, _
    ncolh As Integer, _
    x As Double(), _
    hx As Double() _
)
Visual C++
public delegate void H02CE_QPHX(
    int nstate,
    int ncolh,
    array<double>^ x,
    array<double>^ hx
)
F#
type H02CE_QPHX =
    delegate of
        nstate : int *
        ncolh : int *
        x : float[] *
        hx : float[] -> unit

Parameters

nstate
Type: System..::..Int32
On entry: if nstate=1, then h02ce is calling qphx for the first time on a sub-problem. This parameter setting allows you to save computation time if certain data must be read or calculated only once.
If nstate≥2, then h02ce is calling qphx for the last time. This parameter setting allows you to perform some additional computation on the final sub-problem solution. In general, the last call to qphx is made with nstate=2+ifail (see []).
Otherwise, nstate=0.
ncolh
Type: System..::..Int32
On entry: this is the same parameter ncolh as supplied to h02ce.
x
Type: array< System..::..Double >[]()[][]
On entry: the first ncolh elements of the vector x.
hx
Type: array< System..::..Double >[]()[][]
On exit: the product Hx.

See Also

NagLibrary Namespace
NAG Library Overview
h02ce


H Classes

[image]

NAG Library for .NET Release 2
H Classes

H Classes

  • H.h02bbOptions Class
  • H.h02cbOptions Class
  • H.h02ceOptions Class


H.h02bbOptions Class

[image]

NAG Library for .NET Release 2
H..::..h02bbOptions Class
H Class Members See Also Send Feedback
Options Class for h02bb

Syntax

C#
public class h02bbOptions
Visual Basic
Public Class h02bbOptions
Visual C++
public ref class h02bbOptions
F#
type h02bbOptions =  class end

Inheritance Hierarchy

System..::..Object
NagLibrary..::..H..::..h02bbOptions

See Also

H..::..h02bbOptions Members
NagLibrary Namespace
NAG Library Overview
h02bb


H.h02bbOptions Members

[image] [image]

NAG Library for .NET Release 2
H..::..h02bbOptions Members
H..::..h02bbOptions Class Constructors Methods Properties See Also Send Feedback

This chapter provides methods to solve certain integer programming, transportation and shortest path problems. Additionally ‘best subset’ methods are included.

The H..::..h02bbOptions type exposes the following members.

Constructors

Name | Description
H..::..h02bbOptions | Constructor

Methods

Name | Description
Set | Overloaded.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from h02bb.
Warning | Set the method used for logging any warning or error messages from h02bb.

See Also

H..::..h02bbOptions Class


H.h02bbOptions Constructor

[image]

NAG Library for .NET Release 2
H..::..h02bbOptions Constructor
H..::..h02bbOptions Class See Also Send Feedback
Constructor

Syntax

C#
public h02bbOptions()
Visual Basic
Public Sub New
Visual C++
public:
h02bbOptions()
F#
new : unit -> h02bbOptions

See Also

H..::..h02bbOptions Class
H..::..h02bbOptions Members


H.h02bbOptions Methods

[image] [image]

NAG Library for .NET Release 2
H..::..h02bbOptions Methods
H..::..h02bbOptions Class See Also Send Feedback

Methods

Name | Description
Set | Overloaded.

See Also

H..::..h02bbOptions Class


Set Method

[image] [image]

NAG Library for .NET Release 2
H..::..h02bbOptions..::Set Method
H..::..h02bbOptions Class See Also Send Feedback

Overload List

Name | Description
Set(String) | Set an Option for h02bb
Set(DataReader) | Set Options for from a DataReader Stream.

See Also

H..::..h02bbOptions Class
H..::..h02bbOptions Members


Set Method (String)

[image]

NAG Library for .NET Release 2
H..::..h02bbOptions..::Set Method (String)
H..::..h02bbOptions Class See Also Send Feedback
Set an Option for h02bb

Syntax

C#
public void Set(
    string str
)
Visual Basic
Public Sub Set ( _
    str As String _
)
Visual C++
public:
void Set(
    String^ str
)
F#
member Set :
        str : string -> unit

Parameters

str
Type: System..::..String
A string of the form option = value, or for boolean options, simply option.

See Also

H..::..h02bbOptions Class
H..::..h02bbOptions Members
Set Overload


Set Method (DataReader)

[image]

NAG Library for .NET Release 2
H..::..h02bbOptions..::Set Method (DataReader)
H..::..h02bbOptions Class See Also Send Feedback
Set Options for from a DataReader Stream.

Syntax

C#
public void Set(
    DataReader sr
)
Visual Basic
Public Sub Set ( _
    sr As DataReader _
)
Visual C++
public:
void Set(
    DataReader^ sr
)
F#
member Set :
        sr : DataReader -> unit

Parameters

sr
Type: NagLibrary..::..DataReader
A DataReader Stream, containing an option setting on each line.

See Also

H..::..h02bbOptions Class
H..::..h02bbOptions Members
Set Overload


H.h02bbOptions Properties

[image] [image]

NAG Library for .NET Release 2
H..::..h02bbOptions Properties
H..::..h02bbOptions Class See Also Send Feedback

The H..::..h02bbOptions type exposes the following members.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from h02bb.
Warning | Set the method used for logging any warning or error messages from h02bb.

See Also

H..::..h02bbOptions Class


Message Property

[image]

NAG Library for .NET Release 2
H..::..h02bbOptions..::Message Property
H..::..h02bbOptions Class See Also Send Feedback
Set the method used for logging any monitoring messages from h02bb.

Syntax

C#
public PrintManager..::..MessageLogger Message { get; set; }
Visual Basic
Public Property Message As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Message {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Message : PrintManager..::..MessageLogger with get, set

See Also

H..::..h02bbOptions Class
H..::..h02bbOptions Members


Warning Property

[image]

NAG Library for .NET Release 2
H..::..h02bbOptions..::Warning Property
H..::..h02bbOptions Class See Also Send Feedback
Set the method used for logging any warning or error messages from h02bb.

Syntax

C#
public PrintManager..::..MessageLogger Warning { get; set; }
Visual Basic
Public Property Warning As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Warning {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Warning : PrintManager..::..MessageLogger with get, set

See Also

H..::..h02bbOptions Class
H..::..h02bbOptions Members


H.h02cbOptions Class

[image]

NAG Library for .NET Release 2
H..::..h02cbOptions Class
H Class Members See Also Send Feedback
Options Class for h02cb

Syntax

C#
public class h02cbOptions
Visual Basic
Public Class h02cbOptions
Visual C++
public ref class h02cbOptions
F#
type h02cbOptions =  class end

Description of the Optional Parameters

For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
  • the keywords, where the minimum abbreviation of each keyword is underlined (if no characters of an optional qualifier are underlined, the qualifier may be omitted);
  • a parameter value, where the letters a, i​ and ​r denote options that take character, integer and real values respectively;
  • the default value, where the symbol ε is a generic notation for machine precision (see x02aj).
Keywords and character values are case and white space insensitive.
Check Frequency
Every ith iteration, a numerical test is made to see if the current solution x satisfies the constraints in the working set. If the largest residual of the constraints in the working set is judged to be too large, the current working set is refactorized and the variables are recomputed to satisfy the constraints more accurately. If i≤0, the default value is used.
Cold Start
Warm Start
This option specifies how the initial working set is chosen. With a Cold Start, h02cb chooses the initial working set based on the values of the variables and constraints at the initial point. Broadly speaking, the initial working set will include equality constraints and bounds or inequality constraints that violate or ‘nearly’ satisfy their bounds (to within Crash Tolerance).
With a Warm Start, you must provide a valid definition of every element of the array istate (see [Parameters] for the definition of this array). h02cb will override your specification of istate if necessary, so that a poor choice of the working set will not cause a fatal error. For instance, any elements of istate which are set to -2, -1​ or ​4 will be reset to zero, as will any elements which are set to 3 when the corresponding elements of bl and bu are not equal. A warm start will be advantageous if a good estimate of the initial working set is available – for example, when h02cb is called repeatedly to solve related problems.
Crash Tolerance
This value is used in conjunction with the optional parameter Cold Start (the default value) when h02cb selects an initial working set. If 0≤r≤1, the initial working set will include (if possible) bounds or general inequality constraints that lie within r of their bounds. In particular, a constraint of the form ajT x≥l will be included in the initial working set if ajT x-l≤r 1+l. If r<0 or r>1, the default value is used.
Defaults
This special keyword may be used to reset all optional parameters to their default values.
Expand Frequency
This option is part of an anti-cycling procedure designed to guarantee progress even on highly degenerate problems.
The strategy is to force a positive step at every iteration, at the expense of violating the constraints by a small amount. Suppose that the value of the optional parameter Feasibility Tolerance is δ. Over a period of i iterations, the feasibility tolerance actually used by h02cb (i.e., the working feasibility tolerance) increases from 0.5 δ to δ (in steps of 0.5 δ/i).
At certain stages the following ‘resetting procedure’ is used to remove constraint infeasibilities. First, all variables whose upper or lower bounds are in the working set are moved exactly onto their bounds. A count is kept of the number of nontrivial adjustments made. If the count is positive, iterative refinement is used to give variables that satisfy the working set to (essentially) machine precision. Finally, the working feasibility tolerance is reinitialized to 0.5 δ.
If a problem requires more than i iterations, the resetting procedure is invoked and a new cycle of i iterations is started with i incremented by 10. (The decision to resume the feasibility phase or optimality phase is based on comparing any constraint infeasibilities with δ.)
The resetting procedure is also invoked when h02cb reaches an apparently optimal, infeasible or unbounded solution, unless this situation has already occurred twice. If any nontrivial adjustments are made, iterations are continued.
If i≤0, the default value is used. If i≥9999999, no anti-cycling procedure is invoked.
Feasibility Phase Iteration Limit
Optimality Phase Iteration Limit
The scalars i 1 and i 2 specify the maximum number of iterations allowed in the feasibility and optimality phases. Optimality Phase Iteration Limit is equivalent to Iteration Limit. Setting i 1=0 and Print Level>0 means that the workspace needed will be computed and printed, but no iterations will be performed. If i 1<0 or i 2<0, the default value is used.
Feasibility Tolerance
If r≥ε, r defines the maximum acceptable absolute violation in each constraint at a ‘feasible’ point. For example, if the variables and the coefficients in the general constraints are of order unity, and the latter are correct to about 6 decimal digits, it would be appropriate to specify r as 10-6. If 0≤r<ε, the default value is used.
h02cb attempts to find a feasible solution before optimizing the objective function. If the sum of infeasibilities cannot be reduced to zero, the Minimum Sum of Infeasibilities can be used to find the minimum value of the sum. Let Sinf be the corresponding sum of infeasibilities. If Sinf is quite small, it may be appropriate to raise r by a factor of 10 or 100. Otherwise, some error in the data should be suspected.
Note that a ‘feasible solution’ is a solution that satisfies the current constraints to within the tolerance r.
Hessian Rows
Note that this option does not apply to problems of type FP or LP.
This specifies m, the number of rows of the Hessian matrix H. The default value of m is n, the number of variables of the problem.
If the problem is of type QP, m will usually be n, the number of variables. However, a value of m less than n is appropriate for QP3 or QP4 if h is an upper trapezoidal matrix with m rows. Similarly, m may be used to define the dimension of a leading block of nonzeros in the Hessian matrices of QP1 or QP2, in which case the last n-m rows and columns of h are assumed to be zero. In the QP case, m should not be greater than n; if it is, the last m-n rows of h are ignored.
If i<0 or i>n, the default value is used.
Infinite Bound Size
If r>0, r defines the ‘infinite’ bound bigbnd in the definition of the problem constraints. Any upper bound greater than or equal to bigbnd will be regarded as +∞ (and similarly any lower bound less than or equal to -bigbnd will be regarded as -∞). If r≤0, the default value is used.
Infinite Step Size
If r>0, r specifies the magnitude of the change in variables that will be considered a step to an unbounded solution. (Note that an unbounded solution can occur only when the Hessian is not positive definite.) If the change in x during an iteration would exceed the value of r, the objective function is considered to be unbounded below in the feasible region. If r≤0, the default value is used.
Iteration Limit
Iters
Itns
See optional parameter Feasibility Phase Iteration Limit.
List
Nolist
Normally each optional parameter specification is printed as it is supplied. Optional parameter Nolist may be used to suppress the printing and optional parameter List may be used to restore printing.
Maximum Degrees of Freedom
Note that this option does not apply to problems of type FP or LP.
This places a limit on the storage allocated for the triangular factor R of the reduced Hessian HR. Ideally, i should be set slightly larger than the value of nR expected at the solution. It need not be larger than mn+1, where mn is the number of variables that appear nonlinearly in the quadratic objective function. For many problems it can be much smaller than mn.
For quadratic problems, a minimizer may lie on any number of constraints, so that nR may vary between 1 and n. The default value of i is therefore the number of variables n. If Hessian Rows m is specified, the default value of i is the same number, m.
Minimum Sum of Infeasibilities
If no feasible point exists for the constraints, this option is used to control whether or not h02cb will calculate a point that minimizes the constraint violations. If Minimum Sum of Infeasibilities=NO, h02cb will terminate as soon as it is evident that no feasible point exists for the constraints. The final point will generally not be the point at which the sum of infeasibilities is minimized. If Minimum Sum of Infeasibilities=YES, h02cb will continue until the sum of infeasibilities is minimized.
Monitoring File
If i≥0 and Print Level≥5, monitoring information produced by h02cb at every iteration is sent to a file with logical unit number i. If i<0 and/or Print Level<5, no monitoring information is produced.
Optimality Tolerance
If r≥ε, r defines the tolerance used to determine if the bounds and general constraints have the right ‘sign’ for the solution to be judged to be optimal.
If 0≤r<ε, the default value is used.
Print Level
The value of i controls the amount of printout produced by h02cb, as indicated below. A detailed description of the printed output is given in [Description of the Printed Output] (summary output at each iteration and the final solution) and [Description of Monitoring Information] (monitoring information at each iteration). If i<0, the default value is used.
The following printout is sent to the current advisory message unit (as defined by (X04ABF not in this release)):
≥i | Output
≥0 0 | No output.
≥0 1 | The final solution only.
≥0 5 | One line of summary output (<80 characters; see [Description of the Printed Output]) for each iteration (no printout of the final solution).
≥10 | The final solution and one line of summary output for each iteration.
The following printout is sent to the logical unit number defined by the Monitoring File:
≥i | Output
<5 | No output.
≥5 | One long line of output (>80 characters; see [Description of Monitoring Information]) for each iteration (no printout of the final solution).
≥20 | At each iteration, the Lagrange-multipliers, the variables x, the constraint values Ax and the constraint status.
≥30 | At each iteration, the diagonal elements of the upper triangular matrix T associated with the TQ factorization (3) (see [Definition of the Search Direction]) of the working set, and the diagonal elements of the upper triangular matrix R.
If Print Level≥5 and the unit number defined by Monitoring File is the same as that defined by (X04ABF not in this release), then the summary output is suppressed.
Problem Type
This option specifies the type of objective function to be minimized during the optimality phase. The following are the five optional keywords and the dimensions of the arrays that must be specified in order to define the objective function:
LP | h not referenced, cvec[n-1] required;
QP1 | h[ldh-1,!!!!!!!!!*-1] symmetric, cvec not referenced;
QP2 | h[ldh-1,!!!!!!!!!*-1] symmetric, cvec[n-1] required;
QP3 | h[ldh-1,!!!!!!!!!*-1] upper trapezoidal, cvec not referenced;
QP4 | h[ldh-1,!!!!!!!!!*-1] upper trapezoidal, cvec[n-1] required.
For problems of type FP, the objective function is omitted and neither h nor cvec are referenced.
The following keywords are also acceptable. The minimum abbreviation of each keyword is underlined.
a | Option
Quadratic | QP2
Linear | LP
Feasible | FP
In addition, the keyword QP is equivalent to the default option QP2.
If h=0, i.e., the objective function is purely linear, the efficiency of h02cb may be increased by specifying a as LP.
Rank Tolerance
Note that this option does not apply to problems of type FP or LP.
This parameter enables you to control the condition number of the triangular factor R (see [Algorithmic Details]). If ρi denotes the function ρi=max R 11,R 22,…,R ii, the dimension of R is defined to be smallest index i such that R i+1,i+1≤r ρ i+1. If r≤0, the default value is used.

Inheritance Hierarchy

System..::..Object
NagLibrary..::..H..::..h02cbOptions

See Also

H..::..h02cbOptions Members
NagLibrary Namespace
NAG Library Overview
h02cb


H.h02cbOptions Members

[image] [image]

NAG Library for .NET Release 2
H..::..h02cbOptions Members
H..::..h02cbOptions Class Constructors Methods Properties See Also Send Feedback

This chapter provides methods to solve certain integer programming, transportation and shortest path problems. Additionally ‘best subset’ methods are included.

The H..::..h02cbOptions type exposes the following members.

Constructors

Name | Description
H..::..h02cbOptions | Constructor

Methods

Name | Description
Set | Overloaded.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from h02cb.
Warning | Set the method used for logging any warning or error messages from h02cb.

See Also

H..::..h02cbOptions Class


H.h02cbOptions Constructor

[image]

NAG Library for .NET Release 2
H..::..h02cbOptions Constructor
H..::..h02cbOptions Class See Also Send Feedback
Constructor

Syntax

C#
public h02cbOptions()
Visual Basic
Public Sub New
Visual C++
public:
h02cbOptions()
F#
new : unit -> h02cbOptions

See Also

H..::..h02cbOptions Class
H..::..h02cbOptions Members


H.h02cbOptions Methods

[image] [image]

NAG Library for .NET Release 2
H..::..h02cbOptions Methods
H..::..h02cbOptions Class See Also Send Feedback

Methods

Name | Description
Set | Overloaded.

See Also

H..::..h02cbOptions Class


Set Method

[image] [image]

NAG Library for .NET Release 2
H..::..h02cbOptions..::Set Method
H..::..h02cbOptions Class See Also Send Feedback

Overload List

Name | Description
Set(String) | Set an Option for h02cb
Set(DataReader) | Set Options for from a DataReader Stream.

See Also

H..::..h02cbOptions Class
H..::..h02cbOptions Members


Set Method (String)

[image]

NAG Library for .NET Release 2
H..::..h02cbOptions..::Set Method (String)
H..::..h02cbOptions Class See Also Send Feedback
Set an Option for h02cb

Syntax

C#
public void Set(
    string str
)
Visual Basic
Public Sub Set ( _
    str As String _
)
Visual C++
public:
void Set(
    String^ str
)
F#
member Set :
        str : string -> unit

Parameters

str
Type: System..::..String
A string of the form option = value, or for boolean options, simply option.

See Also

H..::..h02cbOptions Class
H..::..h02cbOptions Members
Set Overload


Set Method (DataReader)

[image]

NAG Library for .NET Release 2
H..::..h02cbOptions..::Set Method (DataReader)
H..::..h02cbOptions Class See Also Send Feedback
Set Options for from a DataReader Stream.

Syntax

C#
public void Set(
    DataReader sr
)
Visual Basic
Public Sub Set ( _
    sr As DataReader _
)
Visual C++
public:
void Set(
    DataReader^ sr
)
F#
member Set :
        sr : DataReader -> unit

Parameters

sr
Type: NagLibrary..::..DataReader
A DataReader Stream, containing an option setting on each line.

See Also

H..::..h02cbOptions Class
H..::..h02cbOptions Members
Set Overload


H.h02cbOptions Properties

[image] [image]

NAG Library for .NET Release 2
H..::..h02cbOptions Properties
H..::..h02cbOptions Class See Also Send Feedback

The H..::..h02cbOptions type exposes the following members.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from h02cb.
Warning | Set the method used for logging any warning or error messages from h02cb.

See Also

H..::..h02cbOptions Class


Message Property

[image]

NAG Library for .NET Release 2
H..::..h02cbOptions..::Message Property
H..::..h02cbOptions Class See Also Send Feedback
Set the method used for logging any monitoring messages from h02cb.

Syntax

C#
public PrintManager..::..MessageLogger Message { get; set; }
Visual Basic
Public Property Message As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Message {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Message : PrintManager..::..MessageLogger with get, set

See Also

H..::..h02cbOptions Class
H..::..h02cbOptions Members


Warning Property

[image]

NAG Library for .NET Release 2
H..::..h02cbOptions..::Warning Property
H..::..h02cbOptions Class See Also Send Feedback
Set the method used for logging any warning or error messages from h02cb.

Syntax

C#
public PrintManager..::..MessageLogger Warning { get; set; }
Visual Basic
Public Property Warning As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Warning {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Warning : PrintManager..::..MessageLogger with get, set

See Also

H..::..h02cbOptions Class
H..::..h02cbOptions Members


H.h02ceOptions Class

[image]

NAG Library for .NET Release 2
H..::..h02ceOptions Class
H Class Members See Also Send Feedback
Options Class for h02ce

Syntax

C#
public class h02ceOptions
Visual Basic
Public Class h02ceOptions
Visual C++
public ref class h02ceOptions
F#
type h02ceOptions =  class end

Description of the Optional Parameters

For each option, we give a summary line, a description of the optional parameter and details of constraints.
The summary line contains:
  • the keywords, where the minimum abbreviation of each keyword is underlined (if no characters of an optional qualifier are underlined, the qualifier may be omitted);
  • a parameter value, where the letters a, i​ and ​r denote options that take character, integer and real values respectively;
  • the default value is used whenever the condition i≥100000000 is satisfied and where the symbol ε is a generic notation for machine precision (see x02aj).
Keywords and character values are case and white space insensitive.
Check Frequency
Every ith iteration after the most recent basis factorization, a numerical test is made to see if the current solution x,s satisfies the linear constraints Ax-s=0. If the largest element of the residual vector r=Ax-s is judged to be too large, the current basis is refactorized and the basic variables recomputed to satisfy the constraints more accurately. If i<0, the default value is used. If i=0, the value i=99999999 is used and effectively no checks are made.
Crash Option
Note that this option does not apply when start="W" (see [Parameters]).
If start="C", an internal crash procedure is used to select an initial basis from various rows and columns of the constraint matrix A-I. The value of i determines which rows and columns are initially eligible for the basis, and how many times the crash procedure is called. If i=0, the all-slack basis B=-I is chosen. If i=1, the crash procedure is called once (looking for a triangular basis in all rows and columns of the linear constraint matrix A). If i=2, the crash procedure is called twice (looking at any equality constraints first followed by any inequality constraints). If i<0 or i>2, the default value is used.
If i=1​ or ​2, certain slacks on inequality rows are selected for the basis first. (If i=2, numerical values are used to exclude slacks that are close to a bound.) The crash procedure then makes several passes through the columns of A, searching for a basis matrix that is essentially triangular. A column is assigned to ‘pivot’ on a particular row if the column contains a suitably large element in a row that has not yet been assigned. (The pivot elements ultimately form the diagonals of the triangular basis.) For remaining unassigned rows, slack variables are inserted to complete the basis.
Crash Tolerance
This value allows the crash procedure to ignore certain ‘small’ nonzero elements in the constraint matrix A while searching for a triangular basis. For each column of A, if amax is the largest element in the column, other nonzeros in that column are ignored if they are less than (or equal to) amax×r.
When r>0, the basis obtained by the crash procedure may not be strictly triangular, but it is likely to be nonsingular and almost triangular. The intention is to obtain a starting basis with more column variables and fewer (arbitrary) slacks. A feasible solution may be reached earlier for some problems. If r<0 or r≥1, the default value is used.
Defaults
This special keyword may be used to reset all optional parameters to their default values.
Expand Frequency
This option is part of an anti-cycling procedure (see [Miscellaneous]) designed to allow progress even on highly degenerate problems.
For LP problems, the strategy is to force a positive step at every iteration, at the expense of violating the constraints by a small amount. Suppose that the value of the optional parameter Feasibility Tolerance is δ. Over a period of i iterations, the feasibility tolerance actually used by h02ce (i.e., the working feasibility tolerance) increases from 0.5 δ to δ (in steps of 0.5 δ/i).
For QP problems, the same procedure is used for iterations in which there is only one superbasic variable. (Cycling can only occur when the current solution is at a vertex of the feasible region.) Thus, zero steps are allowed if there is more than one superbasic variable, but otherwise positive steps are enforced.
Increasing the value of i helps reduce the number of slightly infeasible nonbasic basic variables (most of which are eliminated during the resetting procedure). However, it also diminishes the freedom to choose a large pivot element (see the description of the optional parameter Pivot Tolerance).
If i<0, the default value is used. If i=0, the value i=99999999 is used and effectively no anti-cycling procedure is invoked.
Factorization Frequency
If i>0, at most i basis changes will occur between factorizations of the basis matrix. For LP problems, the basis factors are usually updated at every iteration. For QP problems, fewer basis updates will occur as the solution is approached. The number of iterations between basis factorizations will therefore increase. During these iterations a test is made regularly according to the value of optional parameter Check Frequency to ensure that the linear constraints Ax-s=0 are satisfied. If necessary, the basis will be refactorized before the limit of i updates is reached. If i≤0, the default value is used.
Feasibility Tolerance
If r≥ε, r defines the maximum acceptable absolute violation in each constraint at a ‘feasible’ point (including slack variables). For example, if the variables and the coefficients in the linear constraints are of order unity, and the latter are correct to about five decimal digits, it would be appropriate to specify r as 10-5. If r<ε, the default value is used.
h02ce attempts to find a feasible solution before optimizing the objective function. If the sum of infeasibilities cannot be reduced to zero, the problem is assumed to be infeasible. Let Sinf be the corresponding sum of infeasibilities. If Sinf is quite small, it may be appropriate to raise r by a factor of 10 or 100. Otherwise, some error in the data should be suspected. Note that the method does not attempt to find the minimum value of Sinf.
If the constraints and variables have been scaled (see the description of the optional parameter Scale Option), then feasibility is defined in terms of the scaled problem (since it is more likely to be meaningful).
Infinite Bound Size
If r>0, r defines the ‘infinite’ bound bigbnd in the definition of the problem constraints. Any upper bound greater than or equal to bigbnd will be regarded as +∞ (and similarly any lower bound less than or equal to -bigbnd will be regarded as -∞). If r≤0, the default value is used.
Infinite Step Size
If r>0, r specifies the magnitude of the change in variables that will be considered a step to an unbounded solution. (Note that an unbounded solution can occur only when the Hessian is not positive definite.) If the change in x during an iteration would exceed the value of r, the objective function is considered to be unbounded below in the feasible region. If r≤0, the default value is used.
Iteration Limit
Iters
Itns
The value of i specifies the maximum number of iterations allowed before termination. Setting i=0 and Print Level>0 means that the workspace needed to start solving the problem will be computed and printed, but no iterations will be performed. If i<0, the default value is used.
List
Nolist
Normally each optional parameter specification is printed as it is supplied. Optional parameter Nolist may be used to suppress the printing and optional parameter List may be used to restore printing.
LU Factor Tolerance
LU Update Tolerance
The values of r 1 and r 2 affect the stability and sparsity of the basis factorization B=LU, during refactorization and updates respectively. The lower triangular matrix L is a product of matrices of the form
10μ1
where the multipliers μ will satisfy μ≤ri. The default values of r 1 and r 2 usually strike a good compromise between stability and sparsity. For large and relatively dense problems, setting r 1 and r 2 to 25 (say) may give a marked improvement in sparsity without impairing stability to a serious degree. Note that for band matrices it may be necessary to set r 1 in the range 1≤r 1<2 in order to achieve stability. If r 1<1 or r 2<1, the default value is used.
LU Singularity Tolerance
If r>0, r defines the singularity tolerance used to guard against ill-conditioned basis matrices. Whenever the basis is refactorized, the diagonal elements of U are tested as follows. If u jj≤r or u jj<r×maxi u ij, the jth column of the basis is replaced by the corresponding slack variable. If r≤0, the default value is used.
Minimize
Maximize
This option specifies the required direction of the optimization. It applies to both linear and nonlinear terms (if any) in the objective function. Note that if two problems are the same except that one minimizes f x and the other maximizes -f x, their solutions will be the same but the signs of the dual variables πi and the reduced gradients dj (see [The Main Iteration]) will be reversed.
Monitoring File
If i≥0 and Print Level>0, monitoring information produced by h02ce is sent to a file with logical unit number i. If i<0 and/or Print Level=0, the default value is used and hence no monitoring information is produced.
Optimality Tolerance
If r≥ε, r is used to judge the size of the reduced gradients dj=gj-πT aj. By definition, the reduced gradients for basic variables are always zero. Optimality is declared if the reduced gradients for any nonbasic variables at their lower or upper bounds satisfy -r×max 1,π≤dj≤r×max 1,π, and if dj≤r×max 1,π for any superbasic variables. If r<ε, the default value is used.
Partial Price
Note that this option does not apply to QP problems.
This option is recommended for large FP or LP problems that have significantly more variables than constraints (i.e., n≫m). It reduces the work required for each pricing operation (i.e., when a nonbasic variable is selected to enter the basis). If i=1, all columns of the constraint matrix A-I are searched. If i>1, A and -I are partitioned to give i roughly equal segments Aj,Kj, for j=1,2,…,p (modulo p). If the previous pricing search was successful on A j-1,K j-1, the next search begins on the segments Aj,Kj. If a reduced gradient is found that is larger than some dynamic tolerance, the variable with the largest such reduced gradient (of appropriate sign) is selected to enter the basis. If nothing is found, the search continues on the next segments A j+1,K j+1, and so on. If i≤0, the default value is used.
Pivot Tolerance
If r>0, r is used to prevent columns entering the basis if they would cause the basis to become almost singular. If r≤0, the default value is used.
Print Level
The value of i controls the amount of printout produced by h02ce, as indicated below. A detailed description of the printed output is given in [Description of the Printed Output] (summary output at each iteration and the final solution) and [Description of Monitoring Information] (monitoring information at each iteration). Note that the summary output will not exceed 80 characters per line and that the monitoring information will not exceed 120 characters per line. If i<0, the default value is used. The following printout is sent to the current advisory message unit (as defined by (X04ABF not in this release)):
≥0 i | Output
≥0 0 | No output.
≥0 1 | The final solution only.
≥0 5 | One line of summary output for each iteration (no printout of the final solution).
≥10 | The final solution and one line of summary output for each iteration.
The following printout is sent to the logical unit number defined by the Monitoring File:
≥0 i | Output
≥0 0 | No output.
≥0 1 | The final solution only.
≥0 5 | One long line of output for each iteration (no printout of the final solution).
≥10 | The final solution and one long line of output for each iteration.
≥20 | The final solution, one long line of output for each iteration, matrix statistics (initial status of rows and columns, number of elements, density, biggest and smallest elements, etc.), details of the scale factors resulting from the scaling procedure (if Scale Option=1 or 2), basis factorization statistics and details of the initial basis resulting from the crash procedure (if start="C"; see [Parameters]).
If Print Level>0 and the unit number defined by Monitoring File is the same as that defined by (X04ABF not in this release), then the summary output is suppressed.
Rank Tolerance
Scale Option
This option enables you to scale the variables and constraints using an iterative procedure due to Fourer (see Hock and Schittkowski (1981)), which attempts to compute row scales ri and column scales cj such that the scaled matrix coefficients a-ij=a ij×cj/ri are as close as possible to unity. This may improve the overall efficiency of the method on some problems. (The lower and upper bounds on the variables and slacks for the scaled problem are redefined as l-j=lj/cj and u-j=uj/cj respectively, where cj≡r j-n if j>n.)
If i=0, no scaling is performed. If i=1, all rows and columns of the constraint matrix A are scaled. If i=2, an additional scaling is performed that may be helpful when the solution x is large; it takes into account columns of A-I that are fixed or have positive lower bounds or negative upper bounds. If i<0 or i>2, the default value is used.
Scale Tolerance
Note that this option does not apply when Scale Option=0.
If 0<r<1, r is used to control the number of scaling passes to be made through the constraint matrix A. At least 3 (and at most 10) passes will be made. More precisely, let ap denote the largest column ratio (i.e., 'biggest'element'smallest'element in some sense) after the pth scaling pass through A. The scaling procedure is terminated if ap≥a p-1×r for some p≥3. Thus, increasing the value of r from 0.9 to 0.99 (say) will probably increase the number of passes through A. If r≤0 or r≥1, the default value is used.
Superbasics Limit
Note that this option does not apply to FP or LP problems.
The value of i specifies ‘how nonlinear’ you expect the QP problem to be. If i≤0, the default value is used.

Inheritance Hierarchy

System..::..Object
NagLibrary..::..H..::..h02ceOptions

See Also

H..::..h02ceOptions Members
NagLibrary Namespace
NAG Library Overview
h02ce


H.h02ceOptions Members

[image] [image]

NAG Library for .NET Release 2
H..::..h02ceOptions Members
H..::..h02ceOptions Class Constructors Methods Properties See Also Send Feedback

This chapter provides methods to solve certain integer programming, transportation and shortest path problems. Additionally ‘best subset’ methods are included.

The H..::..h02ceOptions type exposes the following members.

Constructors

Name | Description
H..::..h02ceOptions | Constructor

Methods

Name | Description
Set | Overloaded.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from h02ce.
Warning | Set the method used for logging any warning or error messages from h02ce.

See Also

H..::..h02ceOptions Class


H.h02ceOptions Constructor

[image]

NAG Library for .NET Release 2
H..::..h02ceOptions Constructor
H..::..h02ceOptions Class See Also Send Feedback
Constructor

Syntax

C#
public h02ceOptions()
Visual Basic
Public Sub New
Visual C++
public:
h02ceOptions()
F#
new : unit -> h02ceOptions

See Also

H..::..h02ceOptions Class
H..::..h02ceOptions Members


H.h02ceOptions Methods

[image] [image]

NAG Library for .NET Release 2
H..::..h02ceOptions Methods
H..::..h02ceOptions Class See Also Send Feedback

Methods

Name | Description
Set | Overloaded.

See Also

H..::..h02ceOptions Class


Set Method

[image] [image]

NAG Library for .NET Release 2
H..::..h02ceOptions..::Set Method
H..::..h02ceOptions Class See Also Send Feedback

Overload List

Name | Description
Set(String) | Set an Option for h02ce
Set(DataReader) | Set Options for from a DataReader Stream.

See Also

H..::..h02ceOptions Class
H..::..h02ceOptions Members


Set Method (String)

[image]

NAG Library for .NET Release 2
H..::..h02ceOptions..::Set Method (String)
H..::..h02ceOptions Class See Also Send Feedback
Set an Option for h02ce

Syntax

C#
public void Set(
    string str
)
Visual Basic
Public Sub Set ( _
    str As String _
)
Visual C++
public:
void Set(
    String^ str
)
F#
member Set :
        str : string -> unit

Parameters

str
Type: System..::..String
A string of the form option = value, or for boolean options, simply option.

See Also

H..::..h02ceOptions Class
H..::..h02ceOptions Members
Set Overload


Set Method (DataReader)

[image]

NAG Library for .NET Release 2
H..::..h02ceOptions..::Set Method (DataReader)
H..::..h02ceOptions Class See Also Send Feedback
Set Options for from a DataReader Stream.

Syntax

C#
public void Set(
    DataReader sr
)
Visual Basic
Public Sub Set ( _
    sr As DataReader _
)
Visual C++
public:
void Set(
    DataReader^ sr
)
F#
member Set :
        sr : DataReader -> unit

Parameters

sr
Type: NagLibrary..::..DataReader
A DataReader Stream, containing an option setting on each line.

See Also

H..::..h02ceOptions Class
H..::..h02ceOptions Members
Set Overload


H.h02ceOptions Properties

[image] [image]

NAG Library for .NET Release 2
H..::..h02ceOptions Properties
H..::..h02ceOptions Class See Also Send Feedback

The H..::..h02ceOptions type exposes the following members.

Properties

Name | Description
Message | Set the method used for logging any monitoring messages from h02ce.
Warning | Set the method used for logging any warning or error messages from h02ce.

See Also

H..::..h02ceOptions Class


Message Property

[image]

NAG Library for .NET Release 2
H..::..h02ceOptions..::Message Property
H..::..h02ceOptions Class See Also Send Feedback
Set the method used for logging any monitoring messages from h02ce.

Syntax

C#
public PrintManager..::..MessageLogger Message { get; set; }
Visual Basic
Public Property Message As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Message {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Message : PrintManager..::..MessageLogger with get, set

See Also

H..::..h02ceOptions Class
H..::..h02ceOptions Members


Warning Property

[image]

NAG Library for .NET Release 2
H..::..h02ceOptions..::Warning Property
H..::..h02ceOptions Class See Also Send Feedback
Set the method used for logging any warning or error messages from h02ce.

Syntax

C#
public PrintManager..::..MessageLogger Warning { get; set; }
Visual Basic
Public Property Warning As PrintManager..::..MessageLogger
    Get
    Set
Visual C++
public:
property PrintManager..::..MessageLogger^ Warning {
    PrintManager..::..MessageLogger^ get ();
    void set (PrintManager..::..MessageLogger^ value);
}
F#
member Warning : PrintManager..::..MessageLogger with get, set

See Also

H..::..h02ceOptions Class
H..::..h02ceOptions Members


H Methods

[image] [image]

NAG Library for .NET Release 2
H Methods
H Class See Also Send Feedback

The H type exposes the following members.

Methods

Name | Description
h02bb | h02bb solves ‘zero-one’, ‘general’, ‘mixed’ or ‘all’ integer programming problems using a branch and bound method. The method may also be used to find either the first integer solution or the optimum integer solution. It is not intended for large sparse problems.
h02cb | h02cb solves general quadratic programming problems with integer constraints on the variables. It is not intended for large sparse problems.
h02cbu | Auxiliary for use as a delegate parameter
h02cbv | NAG supplied callback for h02cbf.
h02ce | h02ce obtains integer solutions to sparse linear programming and quadratic programming problems.

See Also

H Class


h02bb Method

[image]

NAG Library for .NET Release 2
H..::h02bb Method
H Class See Also Send Feedback
h02bb solves ‘zero-one’, ‘general’, ‘mixed’ or ‘all’ integer programming problems using a branch and bound method. The method may also be used to find either the first integer solution or the optimum integer solution. It is not intended for large sparse problems.

Syntax

C#
public static void h02bb(
    ref int itmax,
    int msglvl,
    int n,
    int m,
    double[,] a,
    double[] bl,
    double[] bu,
    int[] intvar,
    double[] cvec,
    int maxnod,
    int intfst,
    int maxdpt,
    ref double toliv,
    ref double tolfes,
    ref double bigbnd,
    double[] x,
    out double objmip,
    int[] iwork,
    double[] rwork,
    H..::..h02bbOptions options,
    out int ifail
)
Visual Basic
Public Shared Sub h02bb ( _
    ByRef itmax As Integer, _
    msglvl As Integer, _
    n As Integer, _
    m As Integer, _
    a As Double(,), _
    bl As Double(), _
    bu As Double(), _
    intvar As Integer(), _
    cvec As Double(), _
    maxnod As Integer, _
    intfst As Integer, _
    maxdpt As Integer, _
    ByRef toliv As Double, _
    ByRef tolfes As Double, _
    ByRef bigbnd As Double, _
    x As Double(), _
    <OutAttribute> ByRef objmip As Double, _
    iwork As Integer(), _
    rwork As Double(), _
    options As H..::..h02bbOptions, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void h02bb(
    int% itmax,
    int msglvl,
    int n,
    int m,
    array<double,2>^ a,
    array<double>^ bl,
    array<double>^ bu,
    array<int>^ intvar,
    array<double>^ cvec,
    int maxnod,
    int intfst,
    int maxdpt,
    double% toliv,
    double% tolfes,
    double% bigbnd,
    array<double>^ x,
    [OutAttribute] double% objmip,
    array<int>^ iwork,
    array<double>^ rwork,
    H..::..h02bbOptions^ options,
    [OutAttribute] int% ifail
)
F#
static member h02bb :
        itmax : int byref *
        msglvl : int *
        n : int *
        m : int *
        a : float[,] *
        bl : float[] *
        bu : float[] *
        intvar : int[] *
        cvec : float[] *
        maxnod : int *
        intfst : int *
        maxdpt : int *
        toliv : float byref *
        tolfes : float byref *
        bigbnd : float byref *
        x : float[] *
        objmip : float byref *
        iwork : int[] *
        rwork : float[] *
        options : H..::..h02bbOptions *
        ifail : int byref -> unit

Parameters

itmax
Type: System..::..Int32 %
On entry: an upper bound on the number of iterations for each LP problem.
On exit: unchanged if on entry itmax>0, else itmax=max 50,5×n+m.
msglvl
Type: System..::..Int32
On entry: the amount of printout produced by h02bb, as indicated below (see [Description of Printed Output] for a description of the printed output). All output is written to the current advisory message unit (as defined by (X04ABF not in this release)).
Value | Definition
0 | No output.
1 | The final IP solution only.
5 | One line of output for each node investigated and the final IP solution.
10 | The original LP solution (first node), one line of output for each node investigated and the final IP solution.
n
Type: System..::..Int32
On entry: n, the number of variables.
Constraint: n>0.
m
Type: System..::..Int32
On entry: m, the number of general linear constraints.
Constraint: m≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,m
Note: the second dimension of the array a must be at least n if m>0 and at least 1 if m=0.
On entry: the ith row of a must contain the coefficients of the ith general constraint, for i=1,2,…,m.
If m=0 then the array a is not referenced.
bl
Type: array< System..::..Double >[]()[][]
An array of size [n+m]
On entry: bl must contain the lower bounds and bu the upper bounds, for all the constraints in the following order. The first n elements of each array must contain the bounds on the variables, and the next m elements the bounds for the general linear constraints (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j]≤-bigbnd and to specify a nonexistent upper bound (i.e., uj=+∞), set bu[j]≥bigbnd. To specify the jth constraint as an equality, set bl[j]=bu[j]=β, say, where β<bigbnd.
Constraints:
  • bl[j]≤bu[j], for j=0,1,…,n+m-1;
  • if bl[j]=bu[j]=β, β<bigbnd.
bu
Type: array< System..::..Double >[]()[][]
An array of size [n+m]
On entry: bl must contain the lower bounds and bu the upper bounds, for all the constraints in the following order. The first n elements of each array must contain the bounds on the variables, and the next m elements the bounds for the general linear constraints (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j]≤-bigbnd and to specify a nonexistent upper bound (i.e., uj=+∞), set bu[j]≥bigbnd. To specify the jth constraint as an equality, set bl[j]=bu[j]=β, say, where β<bigbnd.
Constraints:
  • bl[j]≤bu[j], for j=0,1,…,n+m-1;
  • if bl[j]=bu[j]=β, β<bigbnd.
intvar
Type: array< System..::..Int32 >[]()[][]
An array of size [n]
On entry: indicates which are the integer variables in the problem. For example, if xj is an integer variable then intvar[j] must be set to 1, and 0 otherwise.
Constraints:
  • intvar[j]=0 or 1, for j=0,1,…,n-1;
  • intvar[j]=1 for at least one value of j.
cvec
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: the coefficients cj of the objective function F x=c 1x 1+c 2x 2+…+cnxn. The method attempts to find a minimum of F x. If a maximum of F x is desired, cvec[j] should be set to -cj, for j=1,2,…,n, so that the method will find a minimum of -F x.
maxnod
Type: System..::..Int32
On entry: the maximum number of nodes that are to be searched in order to find a solution (optimum integer solution). If maxnod≤0 and intfst≤0, then the B&B tree search is continued until all the nodes have been investigated.
intfst
Type: System..::..Int32
On entry: specifies whether to terminate the B&B tree search after the first integer solution (if any) is obtained. If intfst>0 then the B&B tree search is terminated at node k say, which contains the first integer solution. For maxnod>0 this applies only if k≤maxnod.
maxdpt
Type: System..::..Int32
On entry: the maximum depth of the B&B tree used for branch and bound.
Suggested value: maxdpt=3×n/2.
Constraint: maxdpt≥2.
toliv
Type: System..::..Double %
On entry: the integer feasibility tolerance; i.e., an integer variable is considered to take an integer value if its violation does not exceed toliv. For example, if the integer variable xj is near unity then xj is considered to be integer only if 1-toliv≤xj≤1+toliv.
On exit: unchanged if on entry toliv>0.0, else toliv=10-5.
tolfes
Type: System..::..Double %
On entry: the maximum acceptable absolute violation in each constraint at a ‘feasible’ point (feasibility tolerance); i.e., a constraint is considered satisfied if its violation does not exceed tolfes.
On exit: unchanged if on entry tolfes>0.0, else tolfes=ε (where ε is the machine precision).
bigbnd
Type: System..::..Double %
On entry: the ‘infinite’ bound size in the definition of the problem constraints. More precisely, any upper bound greater than or equal to bigbnd will be regarded as +∞ and any lower bound less than or equal to -bigbnd will be regarded as -∞.
On exit: unchanged if on entry bigbnd>0.0, else bigbnd=1020.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: an initial estimate of the original LP solution.
On exit: with ifail=0, x contains a solution which will be an estimate of either the optimum integer solution or the first integer solution, depending on the value of intfst. If ifail=9, then x contains a solution which will be an estimate of the best integer solution that was obtained by searching maxnod nodes.
objmip
Type: System..::..Double %
On exit: with ifail=0 or 9, objmip contains the value of the objective function for the IP solution.
iwork
Type: array< System..::..Int32 >[]()[][]
An array of size [liwork]
the dimension of the array iwork.
On entry: the dimension of the array iwork as declared in the (sub)program from which h02bb is called.
Constraint: liwork≥25+n+m×maxdpt+5×n+m+4.
rwork
Type: array< System..::..Double >[]()[][]
An array of size [lrwork]
the dimension of the array rwork.
On entry: the dimension of the array rwork as declared in the (sub)program from which h02bb is called.
Constraint: lrwork≥maxdpt×n+1+2×min n,m+1 2+14×n+12×m.
If msglvl>0, the amounts of workspace provided and required (with maxdpt=3×n/2) are printed. As an alternative to computing maxdpt, liwork and lrwork from the formulas given above, you may prefer to obtain appropriate values from the output of a preliminary run with the values of maxdpt, liwork and lrwork set to 1. If however only liwork and lrwork are set to 1, then the appropriate values of these parameters for the given value of maxdpt will be computed and printed unless maxdpt<2. In both cases h02bb will then terminate with ifail=6.
options
Type: NagLibrary..::..H..::..h02bbOptions
An Object of type H.h02bbOptions. Used to configure optional parameters to this method.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

h02bb is capable of solving certain types of integer programming (IP) problems using a branch and bound (B&B) method, see Taha (1987). In order to describe these types of integer programs and to briefly state the B&B method, we define the following linear programming (LP) problem:
Minimize
F x=c 1x 1+c 2x 2+⋯+cnxn
subject to
∑j=1 n a ijxj=≤≥bi,  i=1,2,…,m
lj≤xj≤uj,  j=1,2,…,n (1)
If, in (1), it is required that (some or) all the variables take integer values, then the integer program is of type (mixed or) all general IP problem. If additionally, the integer variables are restricted to take only 0–1 values (i.e., lj=0 and uj=1) then the integer program is of type (mixed or all) zero-one IP problem.
The B&B method applies directly to these integer programs. The general idea of B&B (for a full description see Dakin (1965) or Mitra (1973)) is to solve the problem without the integral restrictions as an LP problem (first node). If in the optimal solution an integer variable xk takes a noninteger value xk*, two LP sub-problems are created by branching, imposing xk≤xk* and xk≥xk*+1 respectively, where xk* denotes the integer part of xk*. This method of branching continues until the first integer solution (bound) is obtained. The hanging nodes are then solved and investigated in order to prove the optimality of the solution. At each node, an LP problem is solved using e04mf.

References

Dakin R J (1965) A tree search algorithm for mixed integer programming problems Comput. J. 8 250–255
Mitra G (1973) Investigation of some branch and bound strategies for the solution of mixed integer linear programs Math. Programming 4 155–170
Taha H A (1987) Operations Research: An Introduction Macmillan, New York

Error Indicators and Warnings

Note: h02bb may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
No feasible integer point was found, i.e., it was not possible to satisfy all the integer variables to within the integer feasibility tolerance (determined by toliv). Increase toliv and rerun h02bb.
ifail=2
The original LP solution appears to be unbounded. This value of ifail implies that a step as large as bigbnd would have to be taken in order to continue the algorithm (see [Further Comments]).
ifail=3
No feasible point was found for the original LP problem, i.e., it was not possible to satisfy all the constraints to within the feasibility tolerance (determined by tolfes). If the data for the constraints are accurate only to the absolute precision σ, you should ensure that the value of the feasibility tolerance is greater than σ. For example, if all elements of A are of order unity and are accurate only to three decimal places, the feasibility tolerance should be at least 10-3 (see [Further Comments]).
ifail=4
The maximum number of iterations (determined by itmax) was reached before normal termination occurred for the original LP problem (see [Further Comments]).
ifail=5
Not used by this method.
ifail=6
An input parameter is invalid.
ifail=7
The IP solution reported is not the optimum IP solution. In other words, the B&B tree search for at least one of the branches had to be terminated since an LP sub-problem in the branch did not have a solution (see [Further Comments]).
ifail=8
The maximum depth of the B&B tree used for branch and bound (determined by maxdpt) is too small. Increase maxdpt (along with liwork and/or lrwork if appropriate) and rerun h02bb.
ifail=9
The IP solution reported is the best IP solution for the number of nodes (determined by maxnod) investigated in the B&B tree.
ifail=10
No feasible integer point was found for the number of nodes (determined by maxnod) investigated in the B&B tree.
ifail=11
Although the workspace sizes are sufficient to meet the documented restriction, they are not sufficiently large to accommodate an internal partition of the workspace that meets the requirements of the problem. Increase the workspace sizes.
Overflow
It may be possible to avoid the difficulty by increasing the magnitude of the feasibility tolerance (tolfes) and rerunning the program. If the message recurs even after this change, see [Further Comments].
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

h02bb implements a numerically stable active set strategy and returns solutions that are as accurate as the condition of the problem warrants on the machine.

Parallelism and Performance

None.

Further Comments

The original LP problem may not have an optimum solution, i.e., h02bb terminates with ifail=2, 3 or 4 or overflow may occur. In this case, you are recommended to relax the integer restrictions of the problem and try to find the optimum LP solution by using e04mf instead.
In the B&B method, it is possible for an LP sub-problem to terminate without finding a solution. This may occur due to the number of iterations exceeding the maximum allowed. Therefore the B&B tree search for that particular branch cannot be continued. Thus the returned solution may not be optimal. (ifail=7). For the second and unlikely case, a solution could not be found despite a second attempt at an LP solution.

Example

This example solves the integer programming problem:
maximize
F x=3 x 1+4 x 2
subject to the bounds
x 1≥0x 2≥0
and to the general constraints
2 x 1+5 x 2≤152 x 1-2 x 2≤53 x 1+2 x 2≥5
where x 1 and x 2 are integer variables.
The initial point, which is feasible, is
x 0=1,1 T,
and F x 0=7.
The optimal solution is
x*=2,2 T,
and F x*=14.
Note that maximizing F x is equivalent to minimizing -F x.

Example program (C#): h02bbe.cs

Example program data: h02bbe.d

Example program results: h02bbe.r

See Also

H Class
H Members


h02cb Method

[image]

NAG Library for .NET Release 2
H..::h02cb Method
H Class See Also Send Feedback
h02cb solves general quadratic programming problems with integer constraints on the variables. It is not intended for large sparse problems.

Syntax

C#
public static void h02cb(
    int n,
    int nclin,
    double[,] a,
    double[] bl,
    double[] bu,
    double[] cvec,
    double[,] h,
    H..::..H02CB_QPHESS qphess,
    int[] intvar,
    int mdepth,
    int[] istate,
    double[] xs,
    out double obj,
    double[] ax,
    double[] clamda,
    int strtgy,
    H..::..H02CB_MONIT monit,
    H..::..h02cbOptions options,
    out int ifail
)
Visual Basic
Public Shared Sub h02cb ( _
    n As Integer, _
    nclin As Integer, _
    a As Double(,), _
    bl As Double(), _
    bu As Double(), _
    cvec As Double(), _
    h As Double(,), _
    qphess As H..::..H02CB_QPHESS, _
    intvar As Integer(), _
    mdepth As Integer, _
    istate As Integer(), _
    xs As Double(), _
    <OutAttribute> ByRef obj As Double, _
    ax As Double(), _
    clamda As Double(), _
    strtgy As Integer, _
    monit As H..::..H02CB_MONIT, _
    options As H..::..h02cbOptions, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void h02cb(
    int n,
    int nclin,
    array<double,2>^ a,
    array<double>^ bl,
    array<double>^ bu,
    array<double>^ cvec,
    array<double,2>^ h,
    H..::..H02CB_QPHESS^ qphess,
    array<int>^ intvar,
    int mdepth,
    array<int>^ istate,
    array<double>^ xs,
    [OutAttribute] double% obj,
    array<double>^ ax,
    array<double>^ clamda,
    int strtgy,
    H..::..H02CB_MONIT^ monit,
    H..::..h02cbOptions^ options,
    [OutAttribute] int% ifail
)
F#
static member h02cb :
        n : int *
        nclin : int *
        a : float[,] *
        bl : float[] *
        bu : float[] *
        cvec : float[] *
        h : float[,] *
        qphess : H..::..H02CB_QPHESS *
        intvar : int[] *
        mdepth : int *
        istate : int[] *
        xs : float[] *
        obj : float byref *
        ax : float[] *
        clamda : float[] *
        strtgy : int *
        monit : H..::..H02CB_MONIT *
        options : H..::..h02cbOptions *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of variables.
Constraint: n>0.
nclin
Type: System..::..Int32
On entry: mL, the number of general linear constraints.
Constraint: nclin≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,nclin
Note: the second dimension of the array a must be at least n if nclin>0 and at least 1 if nclin=0.
On entry: the ith row of a must contain the coefficients of the ith general linear constraint, for i=1,2,…,mL.
If nclin=0 then the array a is not referenced.
bl
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin]
On entry: bl must contain the lower bounds and bu the upper bounds, for all the constraints in the following order. The first n elements of each array must contain the bounds on the variables, and the next mL elements the bounds for the general linear constraints (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j]≤-bigbnd, and to specify a nonexistent upper bound (i.e., uj=+∞), set bu[j]≥bigbnd; the default value of bigbnd is 1020, but this may be changed by the Infinite Bound Size. To specify the jth constraint as an equality, set bl[j]=bu[j]=β, say, where β<bigbnd.
Constraints:
  • bl[j]≤bu[j], for j=0,1,…,n+nclin-1;
  • if bl[j]=bu[j]=β, β<bigbnd.
bu
Type: array< System..::..Double >[]()[][]
An array of size [n+nclin]
On entry: bl must contain the lower bounds and bu the upper bounds, for all the constraints in the following order. The first n elements of each array must contain the bounds on the variables, and the next mL elements the bounds for the general linear constraints (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j]≤-bigbnd, and to specify a nonexistent upper bound (i.e., uj=+∞), set bu[j]≥bigbnd; the default value of bigbnd is 1020, but this may be changed by the Infinite Bound Size. To specify the jth constraint as an equality, set bl[j]=bu[j]=β, say, where β<bigbnd.
Constraints:
  • bl[j]≤bu[j], for j=0,1,…,n+nclin-1;
  • if bl[j]=bu[j]=β, β<bigbnd.
cvec
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array cvec must be at least n if the problem is of type LP, QP2 (the default) or QP4, and at least 1 otherwise.
On entry: the coefficients of the explicit linear term of the objective function when the problem is of type LP, QP2 (the default) and QP4.
If the problem is of type FP, QP1, or QP3, cvec is not referenced.
h
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint:
  • if the problem is of type QP1, QP2 (the default), QP3 or QP4, dim1≥n or at least the value of the optional parameter Hessian Rows (default value=n)
  • if the problem is of type FP or LP, dim1≥1
    • Note: the second dimension of the array h must be at least n.
    On entry: may be used to store the quadratic term H of the QP objective function if desired. In some cases, you need not use h to store H explicitly (see the specification of qphess). The elements of h are referenced only by qphess. The number of rows of H is denoted by m, whose default value is n. (The Hessian Rows may be used to specify a value of m<n.)
    If the default version of qphess is used and the problem is of type QP1 or QP2 (the default), the first m rows and columns of h must contain the leading m by m rows and columns of the symmetric Hessian matrix H. Only the diagonal and upper triangular elements of the leading m rows and columns of h are referenced. The remaining elements need not be assigned.
    If the default version of qphess is used and the problem is of type QP3 or QP4, the first m rows of h must contain an m by n upper trapezoidal factor of the symmetric Hessian matrix HT H. The factor need not be of full rank, i.e., some of the diagonal elements may be zero. However, as a general rule, the larger the dimension of the leading nonsingular sub-matrix of h, the fewer iterations will be required. Elements outside the upper trapezoidal part of the first m rows of h need not be assigned.
    In other situations, it may be desirable to compute Hx or HT Hx without accessing h – for example, if H or HT H is sparse or has special structure. The parameters h and ldh may then refer to any convenient array.
    If the problem is of type FP or LP, h is not referenced.
    qphess
    Type: NagLibrary..::..H..::..H02CB_QPHESS
    In general, you need not provide a version of qphess, because a ‘default’ method with name e04nfu is included in the Library. However, the algorithm of h02cb requires only the product of H or HT H and a vector x; and in some cases you may obtain increased efficiency by providing a version of qphess that avoids the need to define the elements of the matrices H or HT H explicitly. qphess is not referenced if the problem is of type FP or LP, in which case qphess may be the method e04nfu.

    A delegate of type H02CB_QPHESS.

    intvar
    Type: array< System..::..Int32 >[]()[][]
    An array of size [lintvr]
    On entry: intvar[i] must contain the index of the solution vector x which is required to be integer. For example, if x 1 and x 3 are constrained to take integer values then intvar[0] might be set to 1 and intvar[1] to 3. The order in which the indices are specified is important, since this determines the order in which the sub-problems are generated. As a rule-of-thumb, the important variables should always be specified first. Thus, in the above example, if x 3 relates to a more important quantity than x 1, then it might be advantageous to set intvar[0]=3 and intvar[1]=1. If k is the smallest integer such that intvar[k] is less than or equal to zero then h02cb assumes that k-1 variables are constrained to be integer; components intvar[k+1], …, intvar[lintvr-1] are not referenced.
    mdepth
    Type: System..::..Int32
    On entry: the maximum depth (i.e., number of extra constraints) that h02cb may insert before admitting failure.
    Suggested value: mdepth=3×n/2.
    Constraint: mdepth≥1.
    istate
    Type: array< System..::..Int32 >[]()[][]
    An array of size [n+nclin]
    On entry: need not be set if the (default) optional parameter Cold Start is used.
    If the optional parameter Warm Start has been chosen, istate specifies the desired status of the constraints at the start of the feasibility phase. More precisely, the first n elements of istate refer to the upper and lower bounds on the variables, and the next mL elements refer to the general linear constraints (if any). Possible values for istate[j] are as follows:
    istate[j] | Meaning
    0 | The corresponding constraint should not be in the initial working set.
    1 | The constraint should be in the initial working set at its lower bound.
    2 | The constraint should be in the initial working set at its upper bound.
    3 | The constraint should be in the initial working set as an equality. This value must not be specified unless bl[j]=bu[j].
    The values -2, -1 and 4 are also acceptable but will be reset to zero by the method. If h02cb has been called previously with the same values of n and nclin, istate already contains satisfactory information. (See also the description of the optional parameter Warm Start.) The method also adjusts (if necessary) the values supplied in xs to be consistent with istate.
    Constraint: -2≤istate[j]≤4, for j=0,1,…,n+nclin-1.
    On exit: the status of the constraints in the working set at the point returned in xs. The significance of each possible value of istate[j] is as follows:
    istate[j] | Meaning
    -2 | The constraint violates its lower bound by more than the feasibility tolerance.
    -1 | The constraint violates its upper bound by more than the feasibility tolerance.
    -0 | The constraint is satisfied to within the feasibility tolerance, but is not in the working set.
    -1 | This inequality constraint is included in the working set at its lower bound.
    -2 | This inequality constraint is included in the working set at its upper bound.
    -3 | This constraint is included in the working set as an equality. This value of istate can occur only when bl[j]=bu[j].
    -4 | This corresponds to optimality being declared with xs[j] being temporarily fixed at its current value. This value of istate can occur only when ifail=1 on exit.
    xs
    Type: array< System..::..Double >[]()[][]
    An array of size [n]
    On entry: an initial estimate of the solution.
    On exit: the point at which h02cb terminated. If ifail=0, 1 or 3, xs contains an estimate of the solution.
    obj
    Type: System..::..Double %
    On exit: the value of the objective function at x if x is feasible, or the sum of infeasibilities at x otherwise. If the problem is of type FP and x is feasible, obj is set to zero.
    ax
    Type: array< System..::..Double >[]()[][]
    An array of size [max 1,nclin]
    On exit: the final values of the linear constraints Ax.
    If nclin=0, ax is not referenced.
    clamda
    Type: array< System..::..Double >[]()[][]
    An array of size [n+nclin]
    On exit: the values of the Lagrange-multipliers for each constraint with respect to the current working set. The first n elements contain the multipliers for the bound constraints on the variables, and the next mL elements contain the multipliers for the general linear constraints (if any). If istate[j]=0 (i.e., constraint j is not in the working set), clamda[j] is zero. If x is optimal, clamda[j] should be non-negative if istate[j]=1, non-positive if istate[j]=2 and zero if istate[j]=4.
    strtgy
    Type: System..::..Int32
    On entry: determines a branching strategy to be used throughout the computation, as follows:
    strtgy | Meaning
    0 | Always left branch first, i.e., impose an upper bound constraint on the variable first.
    1 | Always right branch first, i.e., impose a lower bound constraint on the variable first.
    2 | Branch towards the nearest integer, i.e., if xk=2.4 then impose an upper bound constraint xk≤2, whereas if xk=2.6 then impose the lower bound constraint xk≥3.0.
    3 | A random choice is made between a left-hand and a right-hand branch.
    Constraint: strtgy=0, 1, 2 or 3.
    monit
    Type: NagLibrary..::..H..::..H02CB_MONIT
    monit may be used to print out intermediate output and to affect the course of the computation. Specifically, it allows you to specify a realistic value for the cut-off value (see [Description]) and to terminate the algorithm. If you do not require any intermediate output, have no estimate of the cut-off value and require an exhaustive tree search then monit may be the dummy method H02CBU.

    A delegate of type H02CB_MONIT.

    options
    Type: NagLibrary..::..H..::..h02cbOptions
    An Object of type H.h02cbOptions. Used to configure optional parameters to this method.
    ifail
    Type: System..::..Int32 %
    On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

    Description

    h02cb uses a ‘Branch and Bound’ algorithm in conjunction with e04nf to try and determine integer solutions to a general quadratic programming problem. The problem is assumed to be stated in the following general form:
    minimize x∈Rn f x  subject to  l≤xAx≤u,
    where A is an mL by n matrix and f x may be specified in a variety of ways depending upon the particular problem to be solved. The available forms for f x are listed in Table 1, in which the prefixes FP, LP and QP stand for ‘feasible point’, ‘linear programming’ and ‘quadratic programming’ respectively and c is an n-element vector.
    Problem type | f x | Matrix H
FP | Not applicable | Not applicable
LP | cT x | Not applicable
QP1 | cT x+12 xT Hx | symmetric
QP2 | cT x+12 xT Hx | symmetric
QP3 | cT x+12 xTHT Hx | m by n upper trapezoidal
QP4 | cT x+12 xTHT Hx | m by n upper trapezoidal
    Table 1
    Only when the problem is linear or the matrix H is positive definite can the technique be guaranteed to work; but often useful results can be obtained for a wider class of problems.
    The default problem type is QP2 and other objective functions are selected by using the optional parameter Problem Type. For problems of type FP, the objective function is omitted and h02cb attempts to find a feasible point for the set of constraints.
    Branch and bound consists firstly of obtaining a solution without any of the variables x=x 1,x 2,…,xn T constrained to be integer. Suppose x 1 ought to be integer, but at the optimal value just computed x 1=2.4. A constraint x 1≤2 is added to the system and the second problem solved. A constraint x 1≥3 gives rise to a third sub-problem. In a similar manner a whole series of sub-problems may be generated, corresponding to integer constraints on the variables. The sub-problems are all solved using e04nf.
    In practice the method tries to compute an integer solution as quickly as possible using a depth-first approach, since this helps determine a realistic cut-off value. If we have a cut-off value, say the value of the function at this first integer solution, and any sub-problem, W say, has a solution value greater than this cut-off value, then subsequent sub-problems of W must have solutions greater than the value of the solution at W and therefore need not be computed. Thus a knowledge of a good cut-off value can result in fewer sub-problems being solved and thus speed up the operation of the method. (See the description of monit in [Parameters] for details of how you can supply your own cut-off value.)

    References

    Gill P E, Hammarling S, Murray W, Saunders M A and Wright M H (1986) Users' guide for LSSOL (Version 1.0) Report SOL 86-1 Department of Operations Research, Stanford University
    Gill P E and Murray W (1978) Numerically stable methods for quadratic programming Math. Programming 14 349–372
    Gill P E, Murray W, Saunders M A and Wright M H (1984) Procedures for optimization problems with a mixture of bounds and general linear constraints ACM Trans. Math. Software 10 282–298
    Gill P E, Murray W, Saunders M A and Wright M H (1989) A practical anti-cycling procedure for linearly constrained optimization Math. Programming 45 437–474
    Gill P E, Murray W, Saunders M A and Wright M H (1991) Inertia-controlling methods for general quadratic programming SIAM Rev. 33 1–36
    Gill P E, Murray W and Wright M H (1981) Practical Optimization Academic Press
    Pardalos P M and Schnitger G (1988) Checking local optimality in constrained quadratic programming is NP-hard Operations Research Letters 7 33–35

    Error Indicators and Warnings

    Errors or warnings detected by the method:
    Some error messages may refer to parameters that are dropped from this interface (LDA, LDH) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
    ifail=-1
    Algorithm terminated at your request (halt=true).
    ifail=1
    Input parameter error immediately detected.
    ifail=2
    No integer solution found. (Check that bstval has not been set too small.)
    ifail=3
    mdepth is too small. Increase the value of mdepth and re-enter h02cb.
    ifail=4
    The basic problem (without integer constraints) is unbounded.
    ifail=5
    The basic problem is infeasible.
    ifail=6
    The basic problem requires too many iterations.
    ifail=7
    The basic problem has a reduced Hessian which exceeds its assigned dimension.
    ifail=8
    The basic problem has an invalid parameter setting.
    ifail=9
    The basic problem, as defined, is not standard.
    ifail=10
    liwrk is too small.
    ifail=11
    lwrk is too small.
    ifail=12
    An internal error has occurred within the method. Please contact NAG with details of the call to h02cb.
    ifail=-9000
    An error occured, see message report.
    ifail=-6000
    Invalid Parameters value
    ifail=-4000
    Invalid dimension for array value
    ifail=-8000
    Negative dimension for array value
    ifail=-6000
    Invalid Parameters value

    Accuracy

    h02cb implements a numerically stable active set strategy and returns solutions that are as accurate as the condition of the problem warrants on the machine.

    Parallelism and Performance

    None.

    Further Comments

    This section contains some comments on scaling and a description of the printed output.

    Scaling

    Sensible scaling of the problem is likely to reduce the number of iterations required and make the problem less sensitive to perturbations in the data, thus improving the condition of the problem. In the absence of better information it is usually sensible to make the Euclidean lengths of each constraint of comparable magnitude. See E04 class and Gill et al. (1981) for further information and advice.

    Description of the Printed Output

    This section describes the (default) intermediate printout and final printout produced by h02cb. The intermediate printout is a subset of the monitoring information produced by the method at every iteration (see [Description of Monitoring Information]). You can control the level of printed output (see the description of the Print Level in [Description of the Optional Parameters]). Note that the intermediate printout and final printout are produced only if Print Level≥10 (the default).
    The following line of summary output (<80 characters) is produced at every iteration. In all cases, the values of the quantities printed are those in effect on completion of the given iteration.
    Itn | is the iteration count.
Step | is the step taken along the computed search direction. If a constraint is added during the current iteration, Step will be the step to the nearest constraint. When the problem is of type LP, the step can be greater than one during the optimality phase.
Ninf | is the number of violated constraints (infeasibilities). This will be zero during the optimality phase.
Sinf/Objective | is the value of the current objective function. If x is not feasible, Sinf gives a weighted sum of the magnitudes of constraint violations. If x is feasible, Objective is the value of the objective function. The output line for the final iteration of the feasibility phase (i.e., the first iteration for which Ninf is zero) will give the value of the true objective at the first feasible point. During the optimality phase, the value of the objective function will be nonincreasing. During the feasibility phase, the number of constraint infeasibilities will not increase until either a feasible point is found, or the optimality of the multipliers implies that no feasible point exists. Once optimal multipliers are obtained, the number of infeasibilities can increase, but the sum of infeasibilities will either remain constant or be reduced until the minimum sum of infeasibilities is found.
Norm Gz | is ZRT gFR, the Euclidean norm of the reduced gradient with respect to ZR (see [Definition of the Search Direction] and [Choosing the Initial Working Set]). During the optimality phase, this norm will be approximately zero after a unit step.
    The final printout includes a listing of the status of every variable and constraint.
    The following describes the printout for each variable. A full stop (.) is printed for any numerical value that is zero.
    A key is sometimes printed before State to give some additional information about the state of a variable.
    Varbl | gives the name (V) and index j, for j=1,2,…,n, of the variable.
    State gives the state of the variable (FR if neither bound is in the working set, EQ if a fixed variable, LL if on its lower bound, UL if on its upper bound, TF if temporarily fixed at its current value). If Value lies outside the upper or lower bounds by more than the Feasibility Tolerance (default value=ε, where ε is the machine precision; see [Description of the Optional Parameters]), State will be ++ or -- respectively.
    A | Alternative optimum possible. The variable is active at one of its bounds, but its Lagrange-multiplier is essentially zero. This means that if the variable were allowed to start moving away from its bound, there would be no change to the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case the values of the Lagrange-multipliers might also change.
D | Degenerate. The variable is free, but it is equal to (or very close to) one of its bounds.
I | Infeasible. The variable is currently violating one of its bounds by more than the Feasibility Tolerance.
    Value | is the value of the variable at the final iterate.
    Lower Bound | is the lower bound specified for the variable. None indicates that bl[j]≤-bigbnd.
    Upper Bound | is the upper bound specified for the variable. None indicates that bu[j]≥bigbnd.
    Slack | is the difference between the variable Value and the nearer of its (finite) bounds bl[j] and bu[j]. A blank entry indicates that the associated variable is not bounded (i.e., bl[j]≤-bigbnd and bu[j]≥bigbnd).
    The meaning of the printout for general constraints is the same as that given above for variables, with ‘variable’ replaced by ‘constraint’, bl[j] and bu[j] are replaced by bl[n+j] and bu[n+j] respectively, and with the following change in the heading.
    L Con gives the name (L) and index j, for j=1,2,…,m, of the constraint.
    Note that movement off a constraint (as opposed to a variable moving away from its bound) can be interpreted as allowing the entry in the Slack column to become positive.
    Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.

    Example

    This example minimizes the quadratic function f x=cT x+12 xT Hx, where
    c=-0.02,-0.2,-0.2,-0.2,-0.2,0.04,0.04 T
    h=2000000020000000220000022000000020000000-2-200000-2-2
    subject to the bounds
    -0.01≤x 1≤0.01-0.1 0≤x 2≤0.15-0.01≤x 3≤0.03-0.04≤x 4≤0.02-0.1 0≤x 5≤0.05-0.01≤x 6-0.01≤x 7
    to the general constraints
    x 1+x 2+x 3+x 4+x 5+x 6+x 7=-0.130.15 x 1+0.04 x 2+0.02 x 3+0.04 x 4+0.02 x 5+0.01 x 6+0.03 x 7≤-0.00490.03 x 1+0.05 x 2+0.08 x 3+0.02 x 4+0.06 x 5+0.01 x 6≤-0.00640.02 x 1+0.04 x 2+0.01 x 3+0.02 x 4+0.02 x 5≤-0.00370.02 x 1+0.03 x 2+0.01 x 5≤-0.0012-0.0992≤0.70 x 1+0.75 x 2+0.80 x 3+0.75 x 4+0.80 x 5+0.97 x 6-0.003≤0.02 x 1+0.06 x 2+0.08 x 3+0.12 x 4+0.02 x 5+0.01 x 6+0.97 x 7≤-0.002
    and the variable x 4 is constrained to be integer.
    The initial point, which is infeasible, is
    x 0=-0.01,-0.03,0.0,-0.01,-0.1,0.02,0.01 T.
    The optimal solution (to five figures) is
    x*=-0.01,-0.073328,-0.00025809,0.0,-0.063354,0.014109,0.0028312 T.

    Example program (C#): h02cbe.cs

    Example program data: h02cbe.d

    Example program results: h02cbe.r

    Algorithmic Details

    h02cb implements a basic branch and bound algorithm (see [Description]) using e04nf as its basic sub-problem solver. See below for details of its algorithm.

    Overview

    h02cb is based on an inertia-controlling method that maintains a Cholesky factorization of the reduced Hessian (see below). The method is based on that of Gill and Murray (1978), and is described in detail by Gill et al. (1991). Here we briefly summarise the main features of the method. Where possible, explicit reference is made to the names of variables that are parameters of h02cb or appear in the printed output. h02cb has two phases:
    (i) | finding an initial feasible point by minimizing the sum of infeasibilities (the feasibility phase), and
(ii) | minimizing the quadratic objective function within the feasible region (the optimality phase).
    The computations in both phases are performed by the same methods. The two-phase nature of the algorithm is reflected by changing the function being minimized from the sum of infeasibilities to the quadratic objective function. The feasibility phase does not perform the standard simplex method (i.e., it does not necessarily find a vertex), except in the LP case when mL≤n. Once any iterate is feasible, all subsequent iterates remain feasible.
    h02cb has been designed to be efficient when used to solve a sequence of related problems – for example, within a sequential quadratic programming method for nonlinearly constrained optimization (e.g., e04wd). In particular, you may specify an initial working set (the indices of the constraints believed to be satisfied exactly at the solution); see the discussion of the Warm Start in [Description of the Optional Parameters].
    In general, an iterative process is required to solve a quadratic program. (For simplicity, we shall always consider a typical iteration and avoid reference to the index of the iteration.) Each new iterate x- is defined by
    x-=x+αp (1)
    where the step length α is a non-negative scalar, and p is called the search direction.
    At each point x, a working set of constraints is defined to be a linearly independent subset of the constraints that are satisfied ‘exactly’ (to within the tolerance defined by the Feasibility Tolerance; see [Description of the Optional Parameters]). The working set is the current prediction of the constraints that hold with equality at the solution of a linearly constrained QP problem. The search direction is constructed so that the constraints in the working set remain unaltered for any value of the step length. For a bound constraint in the working set, this property is achieved by setting the corresponding element of the search direction to zero. Thus, the associated variable is fixed, and specification of the working set induces a partition of x into fixed and free variables. During a given iteration, the fixed variables are effectively removed from the problem; since the relevant elements of the search direction are zero, the columns of A corresponding to fixed variables may be ignored.
    Let mW denote the number of general constraints in the working set and let nFX denote the number of variables fixed at one of their bounds (mW and nFX are the quantities Lin and Bnd in the monitoring file output from h02cb; see [Description of Monitoring Information]). Similarly, let nFR (nFR=n-nFX) denote the number of free variables. At every iteration, the variables are reordered so that the last nFX variables are fixed, with all other relevant vectors and matrices ordered accordingly.

    Definition of the Search Direction

    Let AFR denote the mW by nFR sub-matrix of general constraints in the working set corresponding to the free variables, and let pFR denote the search direction with respect to the free variables only. The general constraints in the working set will be unaltered by any move along p if
    AFRpFR=0. (2)
    In order to compute pFR, the TQ factorization of AFR is used:
    AFRQFR=0 T, (3)
    where T is a nonsingular mW by mW upper triangular matrix (i.e., t ij=0 if i>j), and the nonsingular nFR by nFR matrix QFR is the product of orthogonal transformations (see Gill et al. (1984)). If the columns of QFR are partitioned so that
    QFR=Z Y,
    where Y is nFR by mW, then the nZ nZ=nFR-mW columns of Z form a basis for the null space of AFR. Let nR be an integer such that 0≤nR≤nZ, and let ZR denote a matrix whose nR columns are a subset of the columns of Z. (The integer nR is the quantity Zr in the monitoring output from h02cb. In many cases, ZR will include all the columns of Z.) The direction pFR will satisfy (2) if
    pFR=ZRpR, (4)
    where pR is any nR-vector.
    Let Q denote the n by n matrix
    Q=QFRIFX,
    where IFX is the identity matrix of order nFX. Let HQ and gQ denote the n by n transformed Hessian and transformed gradient
    HQ=QT HQ  and  gQ=QT c+Hx
    and let the matrix of first nR rows and columns of HQ be denoted by HR and the vector of the first nR elements of gQ be denoted by gR. The quantities HR and gR are known as the reduced Hessian and reduced gradient of f x, respectively. Roughly speaking, gR and HR describe the first and second derivatives of an unconstrained problem for the calculation of pR.
    At each iteration, a triangular factorization of HR is available. If HR is positive definite, HR=RT R, where R is the upper triangular Cholesky factor of HR. If HR is not positive definite, HR=RT DR, where D=diag 1,1,…,1,μ, with μ≤0.
    The computation is arranged so that the reduced-gradient vector is a multiple of eR, a vector of all zeros except in the last (i.e., nRth) position. This allows the vector pR in (4) to be computed from a single back-substitution
    R pR=γ eR (5)
    where γ is a scalar that depends on whether or not the reduced Hessian is positive definite at x. In the positive definite case, x+p is the minimizer of the objective function subject to the constraints (bounds and general) in the working set treated as equalities. If HR is not positive definite, pR satisfies the conditions
    pRT HRpR<0  and  gRT pR≤0,
    which allow the objective function to be reduced by any positive step of the form x+αp.

    The Main Iteration

    If the reduced gradient is zero, x is a constrained stationary point in the subspace defined by Z. During the feasibility phase, the reduced gradient will usually be zero only at a vertex (although it may be zero at non-vertices in the presence of constraint dependencies). During the optimality phase, a zero reduced gradient implies that x minimizes the quadratic objective when the constraints in the working set are treated as equalities. At a constrained stationary point, Lagrange-multipliers λC and λB for the general and bound constraints are defined from the equations
    AFRT λC=gFR  and  λB=gFX-AFXT λC. (6)
    Given a positive constant δ of the order of the machine precision, a Lagrange-multiplier λj corresponding to an inequality constraint in the working set is said to be optimal if λj≤δ when the associated constraint is at its upper bound, or if λj≥-δ when the associated constraint is at its lower bound. If a multiplier is nonoptimal, the objective function (either the true objective or the sum of infeasibilities) can be reduced by deleting the corresponding constraint (with index Jdel; see [Description of Monitoring Information]) from the working set.
    If optimal multipliers occur during the feasibility phase and the sum of infeasibilities is nonzero, there is no feasible point, and you can force h02cb to continue until the minimum value of the sum of infeasibilities has been found; see the discussion of the Minimum Sum of Infeasibilities in [Description of the Optional Parameters]. At such a point, the Lagrange-multiplier λj corresponding to an inequality constraint in the working set will be such that -1+δ≤λj≤δ when the associated constraint is at its upper bound, and -δ≤λj≤1+δ when the associated constraint is at its lower bound. Lagrange-multipliers for equality constraints will satisfy λj≤1+δ.
    If the reduced gradient is not zero, Lagrange-multipliers need not be computed and the nonzero elements of the search direction p are given by ZRpR (see (4) and (5)). The choice of step length is influenced by the need to maintain feasibility with respect to the satisfied constraints. If HR is positive definite and x+p is feasible, α will be taken as unity. In this case, the reduced gradient at x- will be zero, and Lagrange-multipliers are computed. Otherwise, α is set to αM, the step to the ‘nearest’ constraint (with index Jadd; see [Description of Monitoring Information]), which is added to the working set at the next iteration.
    Each change in the working set leads to a simple change to AFR: if the status of a general constraint changes, a row of AFR is altered; if a bound constraint enters or leaves the working set, a column of AFR changes. Explicit representations are recurred of the matrices T, QFR and R; and of vectors QT g, and QT c. The triangular factor R associated with the reduced Hessian is only updated during the optimality phase.
    One of the most important features of h02cb is its control of the conditioning of the working set, whose nearness to linear dependence is estimated by the ratio of the largest to smallest diagonal elements of the TQ factor T (the printed value Cond T; see [Description of Monitoring Information]). In constructing the initial working set, constraints are excluded that would result in a large value of Cond T.
    h02cb includes a rigorous procedure that prevents the possibility of cycling at a point where the active constraints are nearly linearly dependent (see Gill et al. (1989)). The main feature of the anti-cycling procedure is that the feasibility tolerance is increased slightly at the start of every iteration. This not only allows a positive step to be taken at every iteration, but also provides, whenever possible, a choice of constraints to be added to the working set. Let αM denote the maximum step at which x+αM p does not violate any constraint by more than its feasibility tolerance. All constraints at a distance α (α≤αM) along p from the current point are then viewed as acceptable candidates for inclusion in the working set. The constraint whose normal makes the largest angle with the search direction is added to the working set.

    Choosing the Initial Working Set

    At the start of the optimality phase, a positive definite HR can be defined if enough constraints are included in the initial working set. (The matrix with no rows and columns is positive definite by definition, corresponding to the case when AFR contains nFR constraints.) The idea is to include as many general constraints as necessary to ensure that the reduced Hessian is positive definite.
    Let HZ denote the matrix of the first nZ rows and columns of the matrix HQ=QT HQ at the beginning of the optimality phase. A partial Cholesky factorization is used to find an upper triangular matrix R that is the factor of the largest positive definite leading sub-matrix of HZ. The use of interchanges during the factorization of HZ tends to maximize the dimension of R. (The condition of R may be controlled using the Rank Tolerance. Let ZR denote the columns of Z corresponding to R, and let Z be partitioned as Z=ZRZA. A working set for which ZR defines the null space can be obtained by including the rows of ZAT as ‘artificial constraints’. Minimization of the objective function then proceeds within the subspace defined by ZR, as described in [Definition of the Search Direction].
    The artificially augmented working set is given by
    A-FR=ZATAFR, (7)
    so that pFR will satisfy AFRpFR=0 and ZAT pFR=0. By definition of the TQ factorization, A-FR automatically satisfies the following:
    A-FRQFR=ZATAFR QFR=ZATAFRZRZAY=0T-,
    where
    T-=I00T,
    and hence the TQ factorization of (7) is available trivially from T and QFR without additional expense.
    The matrix ZA is not kept fixed, since its role is purely to define an appropriate null space; the TQ factorization can therefore be updated in the normal fashion as the iterations proceed. No work is required to ‘delete’ the artificial constraints associated with ZA when ZRT gFR=0, since this simply involves repartitioning QFR. The ‘artificial’ multiplier vector associated with the rows of ZAT is equal to ZAT gFR, and the multipliers corresponding to the rows of the ‘true’ working set are the multipliers that would be obtained if the artificial constraints were not present. If an artificial constraint is ‘deleted’ from the working set, an A appears alongside the entry in the Jdel column of the monitoring file output (see [Description of Monitoring Information]).
    The number of columns in ZA and ZR, the Euclidean norm of ZRT gFR, and the condition estimator of R appear in the monitoring file output as Art, Zr, Norm Gz and Cond Rz respectively (see [Description of Monitoring Information]).
    Under some circumstances, a different type of artificial constraint is used when solving a linear program. Although the algorithm of h02cb does not usually perform simplex steps (in the traditional sense), there is one exception: a linear program with fewer general constraints than variables (i.e., mL≤n). (Use of the simplex method in this situation leads to savings in storage.) At the starting point, the ‘natural’ working set (the set of constraints exactly or nearly satisfied at the starting point) is augmented with a suitable number of ‘temporary’ bounds, each of which has the effect of temporarily fixing a variable at its current value. In subsequent iterations, a temporary bound is treated as a standard constraint until it is deleted from the working set, in which case it is never added again. If a temporary bound is ‘deleted’ from the working set, an F (for ‘Fixed’) appears alongside the entry in the Jdel column of the monitoring file output (see [Description of Monitoring Information]).

    Description of Monitoring Information

    This section describes the long line of output (>80 characters) which forms part of the monitoring information produced by h02cb. (See also the description of the optional parameters Monitoring File and Print Level in [Description of the Optional Parameters].) You can control the level of printed output.
    To aid interpretation of the printed results, the following convention is used for numbering the constraints: indices 1 through n refer to the bounds on the variables, and indices n+1 through n+mL refer to the general constraints. When the status of a constraint changes, the index of the constraint is printed, along with the designation L (lower bound), U (upper bound), E (equality), F (temporarily fixed variable) or A (artificial constraint).
    When Print Level≥5 and Monitoring File≥0, the following line of output is produced at every iteration on the unit number specified by Monitoring File. In all cases, the values of the quantities printed are those in effect on completion of the given iteration.
    Itn | is the iteration count.
Jdel | is the index of the constraint deleted from the working set. If Jdel is zero, no constraint was deleted.
Jadd | is the index of the constraint added to the working set. If Jadd is zero, no constraint was added.
Step | is the step taken along the computed search direction. If a constraint is added during the current iteration, Step will be the step to the nearest constraint. When the problem is of type LP, the step can be greater than one during the optimality phase.
Ninf | is the number of violated constraints (infeasibilities). This will be zero during the optimality phase.
Sinf/Objective | is the value of the current objective function. If x is not feasible, Sinf gives a weighted sum of the magnitudes of constraint violations. If x is feasible, Objective is the value of the objective function. The output line for the final iteration of the feasibility phase (i.e., the first iteration for which Ninf is zero) will give the value of the true objective at the first feasible point. During the optimality phase, the value of the objective function will be nonincreasing. During the feasibility phase, the number of constraint infeasibilities will not increase until either a feasible point is found, or the optimality of the multipliers implies that no feasible point exists. Once optimal multipliers are obtained, the number of infeasibilities can increase, but the sum of infeasibilities will either remain constant or be reduced until the minimum sum of infeasibilities is found.
Bnd | is the number of simple bound constraints in the current working set.
Lin | is the number of general linear constraints in the current working set.
Art | is the number of artificial constraints in the working set, i.e., the number of columns of ZA (see [Choosing the Initial Working Set]).
Zr | is the number of columns of ZR (see [Definition of the Search Direction]). Zr is the dimension of the subspace in which the objective function is currently being minimized. The value of Zr is the number of variables minus the number of constraints in the working set; i.e., Zr=n-Bnd+Lin+Art. The value of nZ, the number of columns of Z (see [Definition of the Search Direction]) can be calculated as nZ=n-Bnd+Lin. A zero value of nZ implies that x lies at a vertex of the feasible region.
Norm Gz | is ZRT gFR, the Euclidean norm of the reduced gradient with respect to ZR (see [Definition of the Search Direction] and [Choosing the Initial Working Set]). During the optimality phase, this norm will be approximately zero after a unit step.
NOpt | is the number of nonoptimal Lagrange-multipliers at the current point. NOpt is not printed if the current x is infeasible or no multipliers have been calculated. At a minimizer, NOpt will be zero.
Min Lm | is the value of the Lagrange-multiplier associated with the deleted constraint. If Min Lm is negative, a lower bound constraint has been deleted, if Min Lm is positive, an upper bound constraint has been deleted. If no multipliers are calculated during a given iteration, Min Lm will be zero.
Cond T | is a lower bound on the condition number of the working set.
Cond Rz | is a lower bound on the condition number of the triangular factor R (the Cholesky factor of the current reduced Hessian; see [Definition of the Search Direction]). If the problem is specified to be of type LP, Cond Rz is not printed.
Rzz | is the last diagonal element μ of the matrix D associated with the RT DR factorization of the reduced Hessian HR (see [Definition of the Search Direction]). Rzz is only printed if HR is not positive definite (in which case μ≠1). If the printed value of Rzz is small in absolute value, then HR is approximately singular. A negative value of Rzz implies that the objective function has negative curvature on the current working set.

    See Also

    H Class
    H Members


h02cbu Method

[image]

NAG Library for .NET Release 2
H..::h02cbu Method
H Class See Also Send Feedback
Auxiliary for use as a delegate parameter

Syntax

C#
public static void h02cbu(
    int intfnd,
    int nodes,
    int depth,
    double obj,
    double[] x,
    ref double bstval,
    double[] bstsol,
    double[] bl,
    double[] bu,
    int n,
    ref bool halt,
    ref int count
)
Visual Basic
Public Shared Sub h02cbu ( _
    intfnd As Integer, _
    nodes As Integer, _
    depth As Integer, _
    obj As Double, _
    x As Double(), _
    ByRef bstval As Double, _
    bstsol As Double(), _
    bl As Double(), _
    bu As Double(), _
    n As Integer, _
    ByRef halt As Boolean, _
    ByRef count As Integer _
)
Visual C++
public:
static void h02cbu(
    int intfnd,
    int nodes,
    int depth,
    double obj,
    array<double>^ x,
    double% bstval,
    array<double>^ bstsol,
    array<double>^ bl,
    array<double>^ bu,
    int n,
    bool% halt,
    int% count
)
F#
static member h02cbu :
        intfnd : int *
        nodes : int *
        depth : int *
        obj : float *
        x : float[] *
        bstval : float byref *
        bstsol : float[] *
        bl : float[] *
        bu : float[] *
        n : int *
        halt : bool byref *
        count : int byref -> unit

Parameters

intfnd
Type: System..::..Int32
On entry: specifies the number of integer solutions obtained so far.
nodes
Type: System..::..Int32
On entry: specifies the number of nodes (sub-problems) solved so far.
depth
Type: System..::..Int32
On entry: specifies the depth in the tree of sub-problems the algorithm has now reached.
obj
Type: System..::..Double
On entry: specifies the value of the objective function of the end of the latest sub-problem.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: specifies the values of the independent variables at the end of the latest sub-problem.
bstval
Type: System..::..Double %
On entry: normally specifies the value of the best integer solution found so far.
On exit: may be set a cut-off value if you are an experienced user as follows. Before an integer solution has been found bstval will be set by h02cb to the largest machine representable number (see x02al). If you know that the solution being sought is a much smaller number, then bstval may be set to this number as a cut-off value (see [Description]). Beware of setting bstval too small, since then no integer solutions will be discovered. Also make sure that bstval is set using a statement of the form
IF (intfnd.EQ.0) bstval= cut-off value
on entry to _monit. This statement will not prevent the normal operation of the algorithm when subsequent integer solutions are found. It would be a grievous mistake to unconditionally set bstval and if you have any doubts whatsoever about the correct use of this parameter then you are strongly recommended to leave it unchanged.
bstsol
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: specifies the solution vector which gives rise to the best integer solution value so far discovered.
bl
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: bl[i] specifies the current lower bounds on the variable xi.
bu
Type: array< System..::..Double >[]()[][]
An array of size [n]
On entry: bu[i] specifies the current upper bounds on the variable xi.
n
Type: System..::..Int32
On entry: specifies the number of variables.
halt
Type: System..::..Boolean %
On entry: will have the value false.
On exit: if halt is set to true, e04nf will be brought to a halt with ifail=-1. This facility may be useful if you are content with any integer solution, or with any integer solution that fits certain criteria. Under these circumstances setting halt=true can save considerable unnecessary computation.
count
Type: System..::..Int32 %
On entry: unchanged from previous call.
On exit: may be used by you to save the last value of intfnd. If a subsequent call of _monit has a value of intfnd which is greater than count, then you know that a new integer solution has been found at this node.

Description

Auxiliary for use as a delegate parameter

References

None.

Error Indicators and Warnings

None.

Accuracy

Not applicable.

Further Comments

None.

Example

None.

See Also

H Class
H Members


h02cbv Method

[image]

NAG Library for .NET Release 2
H..::h02cbv Method
H Class See Also Send Feedback
NAG supplied callback for h02cbf.

Syntax

C#
public static void h02cbv(
    int n,
    int jthcol,
    double[,] h,
    double[] x,
    double[] hx,
    H..::..h02cbOptions options
)
Visual Basic
Public Shared Sub h02cbv ( _
    n As Integer, _
    jthcol As Integer, _
    h As Double(,), _
    x As Double(), _
    hx As Double(), _
    options As H..::..h02cbOptions _
)
Visual C++
public:
static void h02cbv(
    int n,
    int jthcol,
    array<double,2>^ h,
    array<double>^ x,
    array<double>^ hx,
    H..::..h02cbOptions^ options
)
F#
static member h02cbv :
        n : int *
        jthcol : int *
        h : float[,] *
        x : float[] *
        hx : float[] *
        options : H..::..h02cbOptions -> unit

Parameters

n
Type: System..::..Int32
n
jthcol
Type: System..::..Int32
jthcol
h
Type: array< System..::..Double ,2>[,](,)[,][,]
h
x
Type: array< System..::..Double >[]()[][]
x
hx
Type: array< System..::..Double >[]()[][]
hx
options
Type: NagLibrary..::..H..::..h02cbOptions
options

See Also

H Class
H Members


h02ce Method

[image]

NAG Library for .NET Release 2
H..::h02ce Method
H Class See Also Send Feedback
h02ce obtains integer solutions to sparse linear programming and quadratic programming problems.

Syntax

C#
public static void h02ce(
    int n,
    int m,
    int nnz,
    int iobj,
    int ncolh,
    H..::..H02CE_QPHX qphx,
    double[] a,
    int[] ha,
    int[] ka,
    double[] bl,
    double[] bu,
    string start,
    string[] names,
    int nname,
    string[] crname,
    ref int ns,
    double[] xs,
    int[] intvar,
    int lintvr,
    int mdepth,
    int[] istate,
    out int miniz,
    out int minz,
    out double obj,
    double[] clamda,
    int strtgy,
    int[] iz,
    double[] z,
    H..::..H02CE_MONIT monit,
    H..::..h02ceOptions options,
    out int ifail
)
Visual Basic
Public Shared Sub h02ce ( _
    n As Integer, _
    m As Integer, _
    nnz As Integer, _
    iobj As Integer, _
    ncolh As Integer, _
    qphx As H..::..H02CE_QPHX, _
    a As Double(), _
    ha As Integer(), _
    ka As Integer(), _
    bl As Double(), _
    bu As Double(), _
    start As String, _
    names As String(), _
    nname As Integer, _
    crname As String(), _
    ByRef ns As Integer, _
    xs As Double(), _
    intvar As Integer(), _
    lintvr As Integer, _
    mdepth As Integer, _
    istate As Integer(), _
    <OutAttribute> ByRef miniz As Integer, _
    <OutAttribute> ByRef minz As Integer, _
    <OutAttribute> ByRef obj As Double, _
    clamda As Double(), _
    strtgy As Integer, _
    iz As Integer(), _
    z As Double(), _
    monit As H..::..H02CE_MONIT, _
    options As H..::..h02ceOptions, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void h02ce(
    int n,
    int m,
    int nnz,
    int iobj,
    int ncolh,
    H..::..H02CE_QPHX^ qphx,
    array<double>^ a,
    array<int>^ ha,
    array<int>^ ka,
    array<double>^ bl,
    array<double>^ bu,
    String^ start,
    array<String^>^ names,
    int nname,
    array<String^>^ crname,
    int% ns,
    array<double>^ xs,
    array<int>^ intvar,
    int lintvr,
    int mdepth,
    array<int>^ istate,
    [OutAttribute] int% miniz,
    [OutAttribute] int% minz,
    [OutAttribute] double% obj,
    array<double>^ clamda,
    int strtgy,
    array<int>^ iz,
    array<double>^ z,
    H..::..H02CE_MONIT^ monit,
    H..::..h02ceOptions^ options,
    [OutAttribute] int% ifail
)
F#
static member h02ce :
        n : int *
        m : int *
        nnz : int *
        iobj : int *
        ncolh : int *
        qphx : H..::..H02CE_QPHX *
        a : float[] *
        ha : int[] *
        ka : int[] *
        bl : float[] *
        bu : float[] *
        start : string *
        names : string[] *
        nname : int *
        crname : string[] *
        ns : int byref *
        xs : float[] *
        intvar : int[] *
        lintvr : int *
        mdepth : int *
        istate : int[] *
        miniz : int byref *
        minz : int byref *
        obj : float byref *
        clamda : float[] *
        strtgy : int *
        iz : int[] *
        z : float[] *
        monit : H..::..H02CE_MONIT *
        options : H..::..h02ceOptions *
        ifail : int byref -> unit

Parameters

n
Type: System..::..Int32
On entry: n, the number of variables (excluding slacks). This is the number of columns in the linear constraint matrix A.
Constraint: n≥1.
m
Type: System..::..Int32
On entry: m, the number of general linear constraints (or slacks). This is the number of rows in A, including the free row (if any; see iobj).
Constraint: m≥1.
nnz
Type: System..::..Int32
On entry: the number of nonzero elements in A.
Constraint: 1≤nnz≤n×m.
iobj
Type: System..::..Int32
On entry: if iobj>0, row iobj of A is a free row containing the nonzero elements of the vector c appearing in the linear objective term cT x.
If iobj=0, there is no free row, i.e., the problem is either an FP problem (in which case iobj must be set to zero), or a QP problem with c=0.
Constraint: 0≤iobj≤m.
ncolh
Type: System..::..Int32
On entry: nH, the number of leading nonzero columns of the Hessian matrix H. For FP and LP problems, ncolh must be set to zero.
Constraint: 0≤ncolh≤n.
qphx
Type: NagLibrary..::..H..::..H02CE_QPHX
For QP problems, you must supply a version of qphx to compute the matrix product Hx. If H has rows and columns consisting entirely of zeros, it is most efficient to order the variables x=y z T so that
Hx=H 1000yz=H 1 y0,
where the nonlinear variables y appear first as shown. For LP problems, qphx will never be called by h02ce.

A delegate of type H02CE_QPHX.

a
Type: array< System..::..Double >[]()[][]
An array of size [nnz]
On entry: the nonzero elements of A, ordered by increasing column index. Note that multiple elements with the same row and column indices are not allowed.
On exit: used as internal workspace prior to being restored and hence is unchanged.
ha
Type: array< System..::..Int32 >[]()[][]
An array of size [nnz]
On entry: ha[i] must contain the row index of the nonzero element stored in a[i], for i=1,2,…,nnz. Note that the row indices for a column may be supplied in any order.
Constraint: 1≤ha[i]≤m, for i=0,1,…,nnz-1.
ka
Type: array< System..::..Int32 >[]()[][]
An array of size [n+1]
On entry: ka[j] must contain the index in a of the start of the jth column, for j=1,2,…,n. To specify the jth column as empty, set ka[j]=ka[j+1]. Note that the first and last elements of ka must be such that ka[0]=1 and ka[n]=nnz+1.
Constraints:
  • ka[0]=1;
  • ka[j]≥1, for j=1,2,…,n-1;
  • ka[n]=nnz+1;
  • 0≤ka[j+1]-ka[j]≤m, for j=0,1,…,n-1.
bl
Type: array< System..::..Double >[]()[][]
An array of size [n+m]
On entry: l, the lower bounds for all the variables and general constraints, in the following order. The first n elements of bl must contain the bounds on the variables x, and the next m elements the bounds for the general linear constraints Ax (or slacks s) and the free row (if any). To specify a nonexistent lower bound (i.e., lj=-∞), set bl[j]≤-bigbnd, where bigbnd is the value of the optional parameter Infinite Bound Size (default value=1020). To specify the jth constraint as an equality, set bl[j]=bu[j]=β, say, where β<bigbnd. Note that the lower bound corresponding to the free row must be set to -∞ and stored in bl[n+iobj-1].
Constraint: if iobj>0, bl[n+iobj-1]≤-bigbnd
(See also the description for bu.)
bu
Type: array< System..::..Double >[]()[][]
An array of size [n+m]
On entry: u, the upper bounds for all the variables and general constraints, in the following order. The first n elements of bl must contain the bounds on the variables x, and the next m elements the bounds for the general linear constraints Ax (or slacks s) and the free row (if any). To specify a nonexistent upper bound (i.e., uj=+∞), set bu[j]≥bigbnd. Note that the upper bound corresponding to the free row must be set to +∞ and stored in bu[n+iobj-1].
On exit: used as internal workspace prior to being restored and hence is unchanged.
Constraints:
  • if iobj>0, bu[n+iobj-1]≥bigbnd;
  • bl[j]≤bu[j], for j=0,1,…,n+m-1;
  • if bl[j]=bu[j]=β, β<bigbnd.
start
Type: System..::..String
On entry: indicates how a starting basis is to be obtained.
start="C"
An internal crash procedure will be used to choose an initial basis matrix B.
start="W"
A basis is already defined in istate (probably from a previous call).
Constraint: start="C" or "W".
names
Type: array< System..::..String >[]()[][]
An array of size [5]
On entry: a set of names associated with the so-called MPSX form of the problem.
names[0]
Must contain the name for the problem (or be blank).
names[1]
Must contain the name for the free row (or be blank).
names[2]
Must contain the name for the constraint right-hand side (or be blank).
names[3]
Must contain the name for the ranges (or be blank).
names[4]
Must contain the name for the bounds (or be blank).
(These names are used in the monitoring file output; see [Description of Monitoring Information].)
nname
Type: System..::..Int32
On entry: the number of column (i.e., variable) and row names supplied in the array names.
nname=1
There are no names. Default names will be used in the printed output.
nname=n+m
All names must be supplied.
Constraint: nname=1 or n+m.
crname
Type: array< System..::..String >[]()[][]
An array of size [nname]
On entry: the optional column and row names.
If nname=1, crname is not referenced and the printed output will use default names for the columns and rows.
If nname=n+m, the first n elements must contain the names for the columns and the next m elements must contain the names for the rows. Note that the name for the free row (if any) must be stored in crname[n+iobj].
ns
Type: System..::..Int32 %
On entry: nS, the number of superbasics. For QP problems, ns need not be specified if start="C", but must retain its value from a previous call when start="W". For FP and LP problems, ns need not be initialized.
On exit: the final number of superbasics. This will be zero for FP and LP problems.
xs
Type: array< System..::..Double >[]()[][]
An array of size [n+m]
On entry: the initial values of the variables and slacks x,s. (See the description for istate.)
On exit: xs[i-1] contains the final value of xi, for i=1,2,…,n.
intvar
Type: array< System..::..Int32 >[]()[][]
An array of size [lintvr]
On entry: specifies which components of the solution vector x are constrained to be integer. Specifically, if k elements of x are required to take integer values then intvar[i]=li, for i=1,2,…,k, where li is the integer index such that x li is integer. If k<lintvr then intvar[k+1] must be set to -1 to signal the end of the integer variable indices.
The order in which the indices of those components of x required to be integer is presented determines the order in which the sub-problems are treated and solved. As such it can be a powerful tool to assist the method in achieving a solution efficiently. The general advice is to enter the important integer variables in the model early in intvar; secondary or less important variables should be entered near the end of the list. However some experimentation might be required to find the optimal order.
lintvr
Type: System..::..Int32
On entry: k, the number of components of x required to be integer. If k=0, then lintvr must be set to 1 and intvar[0] set to -1.
mdepth
Type: System..::..Int32
On entry: specifies the maximum depth the tree of sub-problems may be developed.
Suggested value: mdepth=2×n+20.
Constraint: mdepth>0.
istate
Type: array< System..::..Int32 >[]()[][]
An array of size [n+m]
On entry: if start="C", the first n elements of istate and xs must specify the initial states and values, respectively, of the variables x. (The slacks s need not be initialized.) An internal crash procedure is then used to select an initial basis matrix B. The initial basis matrix will be triangular (neglecting certain small elements in each column). It is chosen from various rows and columns of columns of A-I. Possible values for istate[j] are as follows:
istate[j] | State of xs[j] during crash procedure
0 or 1 | Eligible for the basis
2 | Ignored
3 | Eligible for the basis (given preference over 0 or 1)
4 or 5 | Ignored
If nothing special is known about the problem, or there is no wish to provide special information, you may set istate[j]=0 and xs[j]=0.0, for j=1,2,…,n. All variables will then be eligible for the initial basis. Less trivially, to say that the jth variable will probably be equal to one of its bounds, set istate[j]=4 and xs[j]=bl[j] or istate[j]=5 and xs[j]=bu[j] as appropriate.
Following the crash procedure, variables for which istate[j]=2 are made superbasic. Other variables not selected for the basis are then made nonbasic at the value xs[j] if bl[j]≤xs[j]≤bu[j], or at the value bl[j] or bu[j] closest to xs[j].
If start="W", istate and xs must specify the initial states and values, respectively, of the variables and slacks x,s. If h02ce has been called previously with the same values of n and m, istate already contains satisfactory information.
Constraints:
  • if start="C", 0≤istate[j]≤5, for j=0,1,…,n-1;
  • if start="W", 0≤istate[j]≤3, for j=0,1,…,n+m-1.
On exit: the final states of the variables and slacks x,s from the solution of the last sub-problem tackled. The significance of each possible value of istate[j] is as follows:
istate[j] | State of variable j | Normal value of xs[j]
0 | Nonbasic | bl[j]
1 | Nonbasic | bu[j]
2 | Superbasic | Between bl[j] and bu[j]
3 | Basic | Between bl[j] and bu[j]
If Ninf=0 (see [Description of the Printed Output]), basic and superbasic variables may be outside their bounds by as much as the value of the optional parameter Feasibility Tolerance (default value=max 10-6,ε, where ε is the machine precision). Note that unless the optional parameter Scale Option=0 (default value=2) is specified, the Feasibility Tolerance applies to the variables of the scaled problem. In this case, the variables of the original problem may be as much as 0.1 outside their bounds, but this is unlikely unless the problem is very badly scaled.
Very occasionally some nonbasic variables may be outside their bounds by as much as the Feasibility Tolerance, and there may be some nonbasic variables for which xs[j] lies strictly between its bounds.
If Ninf>0, some basic and superbasic variables may be outside their bounds by an arbitrary amount (bounded by Sinf (see [Description of the Printed Output]) if Scale Option=0).
miniz
Type: System..::..Int32 %
On exit: the minimum value of leniz required to start solving the problem. If ifail=14, h02ce may be called again with leniz suitably larger than miniz. (The bigger the better, since it is not certain how much workspace the basis factors need.)
minz
Type: System..::..Int32 %
On exit: the minimum value of lenz required to start solving the problem. If ifail=15, h02ce may be called again with lenz suitably larger than minz. (The bigger the better, since it is not certain how much workspace the basis factors need.)
obj
Type: System..::..Double %
On exit: the value of the objective function.
If Ninf=0, obj includes the quadratic objective term 12 xT Hx (if any).
If Ninf>0, obj is just the linear objective term cT x (if any). For FP problems, obj is set to zero.
clamda
Type: array< System..::..Double >[]()[][]
An array of size [n+m]
On exit: a set of Lagrange-multipliers for the bounds on the variables and the general constraints. More precisely, the first n elements contain the multipliers (reduced costs) for the bounds on the variables, and the next m elements contain the multipliers (shadow prices) for the general linear constraints.
strtgy
Type: System..::..Int32
On entry: defines the branching strategy adopted by the method.
strtgy=0
Each sub-problem first explored imposes a tighter upper bound on the component of x.
strtgy=1
Each sub-problem first explored imposes a tighter lower bound on the component of x.
strtgy=2
Each branch explored imposes a tighter upper bound on the component of x if its fractional part is less than 0.5, otherwise it imposes a tighter lower bound.
strtgy=3
Random choice is made between first exploring a tighter lower bound or a tighter upper bound sub-problem.
Constraint: strtgy=0, 1, 2 or 3.
iz
Type: array< System..::..Int32 >[]()[][]
An array of size [leniz]
the dimension of the array iz.
On entry: the dimension of the array iz as declared in the (sub)program from which h02ce is called.
Constraint: leniz≥1.
z
Type: array< System..::..Double >[]()[][]
An array of size [lenz]
the dimension of the array z.
On entry: the dimension of the array z as declared in the (sub)program from which h02ce is called.
Constraint: lenz≥1.
The amounts of workspace provided (i.e., leniz and lenz) and required (i.e., miniz and minz) are (by default) output on the current advisory message unit (as defined by (X04ABF not in this release)). Since the minimum values of leniz and lenz required to start solving the problem are returned in miniz and minz, respectively, you may prefer to obtain appropriate values from the output of a preliminary run with leniz and lenz set to 1. (h02ce will then terminate with ifail=14.)
monit
Type: NagLibrary..::..H..::..H02CE_MONIT
To provide feed-back on the progress of the branch and bound process. Additionally monit provides, via its parameter halt, the ability to terminate the process. (You might choose to do this when an integer solution is found, rather than search for a better solution.) If you do not require any intermediate output then monit may be the dummy method (H02CEY not in this release).

A delegate of type H02CE_MONIT.

options
Type: NagLibrary..::..H..::..h02ceOptions
An Object of type H.h02ceOptions. Used to configure optional parameters to this method.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

h02ce is designed to obtain integer solutions to a class of quadratic programming problems addressed by e04nk. Specifically it solves the following problem:
minimize x∈Rn f x  subject to  l≤xAx≤u, (1)
where x=x 1,x 2,…,xn T is a set of variables (some of which may be required to be integer), A is an m by n matrix and the objective function f x may be specified in a variety of ways depending upon the particular problem to be solved. The optional parameter Maximize may be used to specify an alternative problem in which f x is maximized. The possible forms for f x are listed in Table 1, in which the prefixes LP and QP stand for ‘linear programming’ and ‘quadratic programming’ respectively, c is an n-element vector and H is the n by n second-derivative matrix ∇2 f x (the Hessian matrix).
Problem type | Objective function f x | Hessian matrix H
LP | cT x | Not applicable
QP | cT x+12 xT Hx | Symmetric positive semidefinite
Table 1
For LP and QP problems, the unique global minimum value of f x is found. For QP problems, you must also provide a method that computes Hx for any given vector x. (H need not be stored explicitly.)
(It is not expected that the feasibility problem of e04nk would be relevant here.)
The method employs a ‘Branch and Bound’ technique to enforce the integer constraints. In this technique the problem is first solved without the integer constraints. If a variable is found to be non-integral when it is required to have an integer value then two additional problems are constructed. One bounds the variable above by the nearest integer value below the optimal value previously obtained. The second problem is formed by bounding the variable below by the nearest integer value above the optimal value. This process is continued until an integer solution is found. At this point you may elect to stop, or may continue to search for better integer solutions by examining any other sub-problems that remain to be explained.
In practice the method tries to compute an integer solution as quickly as possible using a depth-first approach, since this helps determine a realistic cut-off value. If we have a cut-off value, say the value of the function at this first integer solution, and any sub-problem, W say, has a solution value greater than this cut-off value, then subsequent sub-problems of W must have solutions greater than the value of the solution at W and therefore need not be computed. Thus a knowledge of a good cut-off value can result in fewer sub-problems being solved and thus speed up the operation of the method. (See the description of monit in [Parameters] for details of how you can supply your own cut-off value.)
Each sub-problem is solved using (E04NKA not in this release). You are referred to the method document for e04nk for details of the algorithm used.

References

Gill P E, Hammarling S, Murray W, Saunders M A and Wright M H (1986) Users' guide for LSSOL (Version 1.0) Report SOL 86-1 Department of Operations Research, Stanford University
Gill P E and Murray W (1978) Numerically stable methods for quadratic programming Math. Programming 14 349–372
Gill P E, Murray W, Saunders M A and Wright M H (1986) Some theoretical properties of an augmented Lagrangian merit function Report SOL 86–6R Department of Operations Research, Stanford University
Gill P E, Murray W, Saunders M A and Wright M H (1989) A practical anti-cycling procedure for linearly constrained optimization Math. Programming 45 437–474
Gill P E, Murray W, Saunders M A and Wright M H (1991) Inertia-controlling methods for general quadratic programming SIAM Rev. 33 1–36
Hock W and Schittkowski K (1981) Test Examples for Nonlinear Programming Codes. Lecture Notes in Economics and Mathematical Systems 187 Springer–Verlag
Lawson C L, Hanson R J, Kincaid D R and Krogh F T (1979) Basic linear algebra supbrograms for Fortran usage ACM Trans. Math. Software 5 308–325
Murtagh B A and Saunders M A (1983) MINOS 5.0 user's guide Report SOL 83-20 Department of Operations Research, Stanford University

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=-1
Halted at your request.
ifail=0
Successful exit.
ifail=1
Input parameter error immediately detected.
ifail=2
No integer solution found.
ifail=3
mdepth is too small.
ifail=4
The problem is unbounded (or badly scaled). The objective function is not bounded below in the feasible region.
ifail=5
The problem is infeasible. The general constraints cannot all be satisfied simultaneously to within the value of the optional parameter Feasibility Tolerance (default value=max 10-6,ε, where ε is the machine precision).
ifail=6
Too many iterations. The value of the optional parameter Iteration Limit (default value=max 50,5 n+m) is too small.
ifail=7
The reduced Hessian matrix zT HZ (see [Definition of the Working Set and Search Direction]) exceeds its assigned dimension. The value of the optional parameter Superbasics Limit (default value=min nH+1,n) is too small.
ifail=8
The Hessian matrix H appears to be indefinite. Check that qphx has been coded correctly and that all relevant elements of Hx have been assigned their correct values.
ifail=9
An input parameter is invalid for an internal call to e04nk.
ifail=10
Numerical error in trying to satisfy the general constraints. The basis is very ill-conditioned.
ifail=11
Not enough integer workspace for the basis factors. Increase leniz and rerun h02ce.
ifail=12
Not enough real workspace for the basis factors. Increase lenz and rerun h02ce.
ifail=13
The basis is singular after 15 attempts to factorize it (adding slacks where necessary). Either the problem is badly scaled or the value of the optional parameter LU Factor Tolerance (default value=100.0) is too large.
ifail=14
Not enough integer workspace to start solving the problem. Increase leniz to at least miniz and rerun h02ce.
ifail=15
Not enough real workspace to start solving the problem. Increase lenz to at least minz and rerun h02ce.
ifail=16
An internal error has occurred. Contact NAG with details of your program.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

h02ce implements a numerically stable active-set strategy and returns solutions that are as accurate as the condition of the problem warrants on the machine.

Parallelism and Performance

None.

Further Comments

This section contains a description of the printed output.

Description of the Printed Output

This section describes the (default) intermediate printout and final printout produced by h02ce. The intermediate printout is a subset of the monitoring information produced by the method at every iteration (see [Description of Monitoring Information]). You can control the level of printed output (see the description of the optional parameter Print Level in [Description of the Optional Parameters]). Note that the intermediate printout and final printout are produced only if Print Level≥10 (the default).
The following line of summary output (<80 characters) is produced at every iteration. In all cases, the values of the quantities printed are those in effect on completion of the given iteration.
Itn | is the iteration count.
Step | is the step taken along the computed search direction. If a constraint is added during the current iteration, Step will be the step to the nearest constraint. When the problem is of type LP, the step can be greater than one during the optimality phase.
Ninf | is the number of violated constraints (infeasibilities). This will be zero during the optimality phase.
Sinf/Objective | is the value of the current objective function. If x is not feasible, Sinf gives a weighted sum of the magnitudes of constraint violations. If x is feasible, Objective is the value of the objective function. The output line for the final iteration of the feasibility phase (i.e., the first iteration for which Ninf is zero) will give the value of the true objective at the first feasible point. During the optimality phase, the value of the objective function will be nonincreasing. During the feasibility phase, the number of constraint infeasibilities will not increase until either a feasible point is found, or the optimality of the multipliers implies that no feasible point exists. Once optimal multipliers are obtained, the number of infeasibilities can increase, but the sum of infeasibilities will either remain constant or be reduced until the minimum sum of infeasibilities is found.
Norm rg | is dS, the Euclidean norm of the reduced gradient (see [The Main Iteration]). During the optimality phase, this norm will be approximately zero after a unit step. For FP and LP problems, Norm rg is not printed.
The final printout includes a listing of the status of every variable and constraint.
The following describes the printout for each variable. A full stop (.) is printed for any numerical value that is zero.
Variable | gives the name of the variable. If nname=1, a default name is assigned to the jth variable, for j=1,2,…,n. If nname=n+m, the name supplied in crname[j] is assigned to the jth variable.
State gives the state of the variable (LL if nonbasic on its lower bound, UL if nonbasic on its upper bound, EQ if nonbasic and fixed, FR if nonbasic and strictly between its bounds, BS if basic and SBS if superbasic).
A key is sometimes printed before State to give some additional information about the state of a variable. Note that unless the optional parameter Scale Option=0 (default value=2) is specified, the tests for assigning a key are applied to the variables of the scaled problem.
A | Alternative optimum possible. The variable is nonbasic, but its reduced gradient is essentially zero. This means that if the variable were allowed to start moving away from its bound, there would be no change to the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case the values of the Lagrange-multipliers might also change.
D | Degenerate. The variable is basic or superbasic, but it is equal to (or very close to) one of its bounds.
I | Infeasible. The variable is basic or superbasic and is currently violating one of its bounds by more than the value of the optional parameter Feasibility Tolerance (default value=max 10-6,ε, where ε is the machine precision).
N | Not precisely optimal. The variable is nonbasic or superbasic. If the value of the reduced gradient for the variable exceeds the value of the optional parameter Optimality Tolerance (default value=max 10-6,ε), the solution would not be declared optimal because the reduced gradient for the variable would not be considered negligible.
Value | is the value of the variable at the final iterate.
Lower Bound | is the lower bound specified for the variable. None indicates that bl[j]≤-bigbnd.
Upper Bound | is the upper bound specified for the variable. None indicates that bu[j]≥bigbnd.
Lagr Mult | is the Lagrange-multiplier for the associated bound. This will be zero if State is FR. If x is optimal, the multiplier should be non-negative if State is LL, non-positive if State is UL, and zero if State is BS or SBS.
Residual | is the difference between the variable Value and the nearer of its (finite) bounds bl[j] and bu[j]. A blank entry indicates that the associated variable is not bounded (i.e., bl[j]≤-bigbnd and bu[j]≥bigbnd).
The meaning of the printout for linear constraints is the same as that given above for variables, with ‘variable’ replaced by ‘constraint’, n replaced by m, crname[j] replaced by crname[n+j], bl[j] and bu[j] are replaced by bl[n+j] and bu[n+j] respectively, and with the following change in the heading.
Constrnt gives the name of the linear constraint.
Note that movement off a constraint (as opposed to a variable moving away from its bound) can be interpreted as allowing the entry in the Residual column to become positive.
Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.

Example

This example minimizes the quadratic function f x=cT x+12 xT Hx, where
c=-200.0,-2000.0,-2000.0,-2000.0,-2000.0,400.0,400.0 T
H=2000000020000000220000022000000020000000220000022
subject to the bounds
00 0≤x 1≤0 20000 0≤x 2≤2500400≤x 3≤0 800100≤x 4≤0 70000 0≤x 5≤150000 0≤x 600 0≤x 7
to the linear constraints
x 1+x 2+x 3+x 4+x 5+x 6+x 7=20000.15 x 1+0.04 x 2+0.02 x 3+0.04 x 4+0.02 x 5+0.01 x 6+0.03 x 7≤600.03 x 1+0.05 x 2+0.08 x 3+0.02 x 4+0.06 x 5+0.01 x 6≤1000.02 x 1+0.04 x 2+0.01 x 3+0.02 x 4+0.02 x 5≤400.02 x 1+0.03 x 2+0.01 x 5≤301500≤0.70 x 1+0.75 x 2+0.80 x 3+0.75 x 4+0.80 x 5+0.97 x 6250≤0.02 x 1+0.06 x 2+0.08 x 3+0.12 x 4+0.02 x 5+0.01 x 6+0.97 x 7≤300
and the variables x 2, x 3, x 4, x 5, x 6, x 7, are constrained to be integer.
The initial point, which is infeasible, is
x 0=0.0,0.0,0.0,0.0,0.0,0.0,0.0 T.
The optimal solution (to five figures) is
x*=0.0,355.0,645.0,164.0,410.0,275.0,151.0 T.
One bound constraint and one linear constraint are active at the solution. Note that the Hessian matrix H is positive semidefinite.

Example program (C#): h02cee.cs

Example program data: h02cee.d

Example program results: h02cee.r

Algorithmic Details

This section contains a detailed description of the method used by h02ce.

Overview

h02ce employs a Branch and Bound technique (see [Description]) based on an inertia-controlling method to solve the sub-problems that maintains a Cholesky factorization of the reduced Hessian (see below). The method is similar to that of Gill and Murray (1978), and is described in detail by Gill et al. (1991). Here we briefly summarise the main features of the method. Where possible, explicit reference is made to the names of variables that are parameters of the method or appear in the printed output.
The method used has two distinct phases: finding an initial feasible point by minimizing the sum of infeasibilities (the feasibility phase), and minimizing the quadratic objective function within the feasible region (the optimality phase). The computations in both phases are performed by the same methods. The two-phase nature of the algorithm is reflected by changing the function being minimized from the sum of infeasibilities (the printed quantity Sinf; see [Description of Monitoring Information]) to the quadratic objective function (the printed quantity Objective; see [Description of Monitoring Information]).
In general, an iterative process is required to solve a quadratic program. Given an iterate x,s in both the original variables x and the slack variables s, a new iterate x-,s- is defined by
x-s-=xs+αp, (2)
where the step length α is a non-negative scalar (the printed quantity Step; see [Description of Monitoring Information]), and p is called the search direction. (For simplicity, we shall consider a typical iteration and avoid reference to the index of the iteration.) Once an iterate is feasible (i.e., satisfies the constraints), all subsequent iterates remain feasible.

Definition of the Working Set and Search Direction

At each iterate x,s, a working set of constraints is defined to be a linearly independent subset of the constraints that are satisfied ‘exactly’ (to within the value of the optional parameter Feasibility Tolerance; see [Description of the Optional Parameters]). The working set is the current prediction of the constraints that hold with equality at a solution of the LP or QP problem. Let mW denote the number of constraints in the working set (including bounds), and let W denote the associated mW by n+m working set matrix consisting of the mW gradients of the working set constraints.
The search direction is defined so that constraints in the working set remain unaltered for any value of the step length. It follows that p must satisfy the identity
Wp=0. (3)
This characterisation allows p to be computed using any n by nz full-rank matrix Z that spans the null space of W. (Thus, nz=n-mW and WZ=0.) The null space matrix Z is defined from a sparse LU factorization of part of W (see (6) and (7) below). The direction p will satisfy (3) if
p=Z pZ, (4)
where pz is any nz-vector.
The working set contains the constraints Ax-s=0 and a subset of the upper and lower bounds on the variables x,s. Since the gradient of a bound constraint xj≥lj or xj≤uj is a vector of all zeros except for ±1 in position j, it follows that the working set matrix contains the rows of A-I and the unit rows associated with the upper and lower bounds in the working set.
The working set matrix W can be represented in terms of a certain column partition of the matrix A-I. As in [Description] we partition the constraints Ax-s=0 so that
B xB+S xS+N xN=0, (5)
where B is a square nonsingular basis and xB, xS and xn are the basic, superbasic and nonbasic variables respectively. The nonbasic variables are equal to their upper or lower bounds at x,s, and the superbasic variables are independent variables that are chosen to improve the value of the current objective function. The number of superbasic variables is nS (the printed quantity Ns; see [Description of Monitoring Information]). Given values of xN and xS, the basic variables xB are adjusted so that x,s satisfies (5).
If P is a permutation matrix such that A-I P=B S N, then the working set matrix W satisfies
WP=BSN00IN, (6)
where IN is the identity matrix with the same number of columns as N.
The null space matrix Z is defined from a sparse LU factorization of part of W. In particular, z is maintained in ‘reduced gradient’ form, using the LUSOL package (see Gill et al. (1986)) to maintain sparse LU factors of the basis matrix B that alters as the working set W changes. Given the permutation P, the null space basis is given by
Z=P-B-1 SI0. (7)
This matrix is used only as an operator, i.e., it is never computed explicitly. Products of the form Zv and ZT g are obtained by solving with B or BT. This choice of Z implies that nZ, the number of ‘degrees of freedom’ at x,s, is the same as nS, the number of superbasic variables.
Let gZ and HZ denote the reduced gradient and reduced Hessian of the objective function:
gZ=ZT g  and  HZ=ZT HZ, (8)
where g is the objective gradient at x,s. Roughly speaking, gz and Hz describe the first and second derivatives of an nS-dimensional unconstrained problem for the calculation of pZ. (The condition estimator of HZ is the quantity Cond Hz in the monitoring file output; see [Description of Monitoring Information].)
At each iteration, an upper triangular factor R is available such that HZ=RT R. Normally, R is computed from RT R=ZT HZ at the start of the optimality phase and then updated as the QP working set changes. For efficiency, the dimension of R should not be excessive (say, nS≤1000). This is guaranteed if the number of nonlinear variables is ‘moderate’.
If the QP problem contains linear variables, H is positive semidefinite and R may be singular with at least one zero diagonal element. However, an inertia-controlling strategy is used to ensure that only the last diagonal element of R can be zero. (See Gill et al. (1991) for a discussion of a similar strategy for indefinite quadratic programming.)
If the initial R is singular, enough variables are fixed at their current value to give a nonsingular R. This is equivalent to including temporary bound constraints in the working set. Thereafter, R can become singular only when a constraint is deleted from the working set (in which case no further constraints are deleted until R becomes nonsingular).

The Main Iteration

If the reduced gradient is zero, x,s is a constrained stationary point on the working set. During the feasibility phase, the reduced gradient will usually be zero only at a vertex (although it may be zero elsewhere in the presence of constraint dependencies). During the optimality phase, a zero reduced gradient implies that x minimizes the quadratic objective function when the constraints in the working set are treated as equalities. At a constrained stationary point, Lagrange-multipliers λ are defined from the equations
WT λ=g x. (9)
A Lagrange-multiplier λj corresponding to an inequality constraint in the working set is said to be optimal if λj≤σ when the associated constraint is at its upper bound, or if λj≥-σ when the associated constraint is at its lower bound, where σ depends on the value of the optional parameter Optimality Tolerance (see [Description of the Optional Parameters]). If a multiplier is nonoptimal, the objective function (either the true objective or the sum of infeasibilities) can be reduced by continuing the minimization with the corresponding constraint excluded from the working set. (This step is sometimes referred to as ‘deleting’ a constraint from the working set.) If optimal multipliers occur during the feasibility phase but the sum of infeasibilities is nonzero, there is no feasible point and the method terminates immediately with ifail=3 (see [Error Indicators and Warnings]).
The special form (6) of the working set allows the multiplier vector λ, the solution of (9), to be written in terms of the vector
d=g0-A-I T π=g-AT ππ, (10)
where π satisfies the equations BT π=gB, and gB denotes the basic elements of g. The elements of π are the Lagrange-multipliers λj associated with the equality constraints Ax-s=0. The vector dN of nonbasic elements of d consists of the Lagrange-multipliers λj associated with the upper and lower bound constraints in the working set. The vector dS of superbasic elements of d is the reduced gradient gz in (8). The vector dB of basic elements of d is zero, by construction. (The Euclidean norm of dS and the final values of dS, g and π are the quantities Norm rg, Reduced Gradnt, Obj Gradient and Dual Activity in the monitoring file output; see [Description of Monitoring Information].)
If the reduced gradient is not zero, Lagrange-multipliers need not be computed and the search direction is given by p=Z pz (see (7) and (11)). The step length is chosen to maintain feasibility with respect to the satisfied constraints.
There are two possible choices for pz, depending on whether or not Hz is singular. If Hz is nonsingular, R is nonsingular and pz in (4) is computed from the equations
RT R pZ=-gZ, (11)
where gz is the reduced gradient at x. In this case, x,s+p is the minimizer of the objective function subject to the working set constraints being treated as equalities. If x,s+p is feasible, α is defined to be unity. In this case, the reduced gradient at x-,s- will be zero, and Lagrange-multipliers are computed at the next iteration. Otherwise, α is set to αm, the step to the ‘nearest’ constraint along p. This constraint is added to the working set at the next iteration.
If Hz is singular, then R must also be singular, and an inertia-controlling strategy is used to ensure that only the last diagonal element of R is zero. (See Gill et al. (1991) for a discussion of a similar strategy for indefinite quadratic programming.) In this case, pz satisfies
pZT HZpZ=0  and  gZT pZ≤0, (12)
which allows the objective function to be reduced by any step of the form x,s+αp, where α>0. The vector p=Z pZ is a direction of unbounded descent for the QP problem in the sense that the QP objective is linear and decreases without bound along p. If no finite step of the form x,s+αp (where α>0) reaches a constraint not in the working set, the QP problem is unbounded and the method terminates immediately with ifail=2 (see [Error Indicators and Warnings]). Otherwise, α is defined as the maximum feasible step along p and a constraint active at x,s+αp is added to the working set for the next iteration.

Miscellaneous

If the basis matrix is not chosen carefully, the condition of the null space matrix Z in (7) could be arbitrarily high. To guard against this, the method implements a ‘basis repair’ feature in which the LUSOL package (see Gill et al. (1986)) is used to compute the rectangular factorization
BS T=LU, (13)
returning just the permutation P that makes PL PT unit lower triangular. The pivot tolerance is set to require PL PTij≤2, and the permutation is used to define P in (6). It can be shown that Z is likely to be little more than unity. Hence, z should be well-conditioned regardless of the condition of W. This feature is applied at the beginning of the optimality phase if a potential B-S ordering is known.
The EXPAND procedure (see Gill et al. (1989)) is used to reduce the possibility of cycling at a point where the active constraints are nearly linearly dependent. Although there is no absolute guarantee that cycling will not occur, the probability of cycling is extremely small (see Gill et al. (1986)). The main feature of EXPAND is that the feasibility tolerance is increased at the start of every iteration. This allows a positive step to be taken at every iteration, perhaps at the expense of violating the bounds on x,s by a small amount.
Suppose that the value of the optional parameter Feasibility Tolerance is δ. Over a period of K iterations (where K is the value of the optional parameter Expand Frequency; see [Description of the Optional Parameters]), the feasibility tolerance actually used by h02ce (i.e., the working feasibility tolerance) increases from 0.5 δ to δ (in steps of 0.5 δ/K).
At certain stages the following ‘resetting procedure’ is used to remove small constraint infeasibilities. First, all nonbasic variables are moved exactly onto their bounds. A count is kept of the number of nontrivial adjustments made. If the count is nonzero, the basic variables are recomputed. Finally, the working feasibility tolerance is reinitialized to 0.5 δ.
If a problem requires more than K iterations, the resetting procedure is invoked and a new cycle of iterations is started. (The decision to resume the feasibility phase or optimality phase is based on comparing any constraint infeasibilities with δ.)
The resetting procedure is also invoked when h02ce reaches an apparently optimal, infeasible or unbounded solution, unless this situation has already occurred twice. If any nontrivial adjustments are made, iterations are continued.
The EXPAND procedure not only allows a positive step to be taken at every iteration, but also provides a potential choice of constraints to be added to the working set. All constraints at a distance α (where α≤αm) along p from the current point are then viewed as acceptable candidates for inclusion in the working set. The constraint whose normal makes the largest angle with the search direction is added to the working set. This strategy helps keep the basis matrix B well-conditioned.

Description of Monitoring Information

This section describes the intermediate printout and final printout which constitutes the monitoring information produced by h02ce. (See also the description of the optional parameters Monitoring File and Print Level in [Description of the Optional Parameters].) You can control the level of printed output.
When Print Level=5 or ≥10 and Monitoring File≥0, the following line of intermediate printout (<120 characters) is produced at every iteration on the unit number specified by Monitoring File. Unless stated otherwise, the values of the quantities printed are those in effect on completion of the given iteration.
Itn | is the iteration count.
pp | is the partial price indicator. The variable selected by the last pricing operation came from the ppth partition of A and -I. Note that pp is reset to zero whenever the basis is refactorized.
dj | is the value of the reduced gradient (or reduced cost) for the variable selected by the pricing operation at the start of the current iteration.
+S | is the variable selected by the pricing operation to be added to the superbasic set.
-S | is the variable chosen to leave the superbasic set.
-B | is the variable removed from the basis (if any) to become nonbasic.
-B | is the variable chosen to leave the set of basics (if any) in a special basic ↔ superbasic swap. The entry under -S has become basic if this entry is nonzero, and nonbasic otherwise. The swap is done to ensure that there are no superbasic slacks.
Step | is the value of the step length α taken along the computed search direction p. The variables x have been changed to x+αp. If a variable is made superbasic during the current iteration (i.e., +S is positive), Step will be the step to the nearest bound. During the optimality phase, the step can be greater than unity only if the reduced Hessian is not positive definite.
Pivot | is the rth element of a vector y satisfying By=aq whenever aq (the qth column of the constraint matrix A-I) replaces the rth column of the basis matrix B. Wherever possible, Step is chosen so as to avoid extremely small values of Pivot (since they may cause the basis to be nearly singular). In extreme cases, it may be necessary to increase the value of the optional parameter Pivot Tolerance (default value=ε 0.67, where ε is the machine precision) to exclude very small elements of y from consideration during the computation of Step.
Ninf | is the number of violated constraints (infeasibilities). This will be zero during the optimality phase.
Sinf/Objective | is the value of the current objective function. If x is not feasible, Sinf gives a weighted sum of the magnitudes of constraint violations. If x is feasible, Objective is the value of the objective function. The output line for the final iteration of the feasibility phase (i.e., the first iteration for which Ninf is zero) will give the value of the true objective at the first feasible point. During the optimality phase, the value of the objective function will be nonincreasing. During the feasibility phase, the number of constraint infeasibilities will not increase until either a feasible point is found, or the optimality of the multipliers implies that no feasible point exists. Once optimal multipliers are obtained, the number of infeasibilities can increase, but the sum of infeasibilities will either remain constant or be reduced until the minimum sum of infeasibilities is found.
L | is the number of nonzeros in the basis factor L. Immediately after a basis factorization B=LU, this is lenL, the number of subdiagonal elements in the columns of a lower triangular matrix. Further nonzeros are added to L when various columns of B are later replaced. (Thus, L increases monotonically.)
U | is the number of nonzeros in the basis factor U. Immediately after a basis factorization, this is lenU, the number of diagonal and superdiagonal elements in the rows of an upper triangular matrix. As columns of B are replaced, the matrix U is maintained explicitly (in sparse form). The value of U may fluctuate up or down; in general, it will tend to increase.
Ncp | is the number of compressions required to recover workspace in the data structure for U. This includes the number of compressions needed during the previous basis factorization. Normally, Ncp should increase very slowly. If it does not, increase lenz by at least L+U and rerun h02ce (possibly using start="W"; see [Parameters]).
Norm rg | is dS, the Euclidean norm of the reduced gradient (see [The Main Iteration]). During the optimality phase, this norm will be approximately zero after a unit step. For FP and LP problems, Norm rg is not printed.
Ns | is the current number of superbasic variables. For FP and LP problems, Ns is not printed.
Cond Hz | is a lower bound on the condition number of the reduced Hessian (see [Definition of the Working Set and Search Direction]). The larger this number, the more difficult the problem. For FP and LP problems, Cond Hz is not printed.
When Print Level≥20 and Monitoring File≥0, the following lines of intermediate printout (<120 characters) are produced on the unit number specified by Monitoring File whenever the matrix B or BS=BS T is factorized. Gaussian elimination is used to compute an LU factorization of B or BS, where PL PT is a lower triangular matrix and PUQ is an upper triangular matrix for some permutation matrices P and Q. The factorization is stabilized in the manner described under the LU Factor Tolerance (default value=100.0; see [Description of the Optional Parameters]).
Factorize | is the factorization count.
Demand is a code giving the reason for the present factorization as follows:
Code | Meaning
01 0 | First LU factorization.
01 1 | Number of updates reached the value of the optional parameter Factorization Frequency (default value=100).
01 2 | Excessive nonzeros in updated factors.
01 7 | Not enough storage to update factors.
0 10 | Row residuals too large (see the description for the optional parameter Check Frequency).
0 11 | Ill-conditioning has caused inconsistent results.
Iteration | is the iteration count.
Nonlinear | is the number of nonlinear variables in B (not printed if BS is factorized).
Linear | is the number of linear variables in B (not printed if BS is factorized).
Slacks | is the number of slack variables in B (not printed if BS is factorized).
Elems | is the number of nonzeros in B (not printed if BS is factorized).
Density | is the percentage nonzero density of B (not printed if BS is factorized). More precisely, Density=100×Elems/Nonlinear+Linear+Slacks 2.
Compressns | is the number of times the data structure holding the partially factorized matrix needed to be compressed, in order to recover unused workspace. Ideally, it should be zero. If it is more than 3 or 4, increase leniz and lenz and rerun h02ce (possibly using start="W"; see [Parameters]).
Merit | is the average Markowitz merit count for the elements chosen to be the diagonals of PUQ. Each merit count is defined to be c-1r-1, where c and r are the number of nonzeros in the column and row containing the element at the time it is selected to be the next diagonal. Merit is the average of m such quantities. It gives an indication of how much work was required to preserve sparsity during the factorization.
lenL | is the number of nonzeros in L.
lenU | is the number of nonzeros in U.
Increase | is the percentage increase in the number of nonzeros in L and U relative to the number of nonzeros in B. More precisely, Increase=100×lenL+lenU-Elems/Elems.
m | is the number of rows in the problem. Note that m=Ut+Lt+bp.
Ut | is the number of triangular rows of B at the top of U.
d1 | is the number of columns remaining when the density of the basis matrix being factorized reached 0.3.
Lmax | is the maximum subdiagonal element in the columns of L (not printed if BS is factorized). This will not exceed the value of the LU Factor Tolerance.
Bmax | is the maximum nonzero element in B (not printed if BS is factorized).
BSmax | is the maximum nonzero element in BS (not printed if B is factorized).
Umax is the maximum nonzero element in U, excluding elements of B that remain in U unchanged. (For example, if a slack variable is in the basis, the corresponding row of B will become a row of U without modification. Elements in such rows will not contribute to Umax. If the basis is strictly triangular, none of the elements of B will contribute, and Umax will be zero.)
Ideally, Umax should not be significantly larger than Bmax. If it is several orders of magnitude larger, it may be advisable to reset the LU Factor Tolerance to a value near 1.0.
Umax is not printed if BS is factorized.
Umin | is the magnitude of the smallest diagonal element of PUQ (not printed if BS is factorized).
Growth is the value of the ratio Umax/Bmax, which should not be too large.
Providing Lmax is not large (say <10.0), the ratio max Bmax,Umax/Umin is an estimate of the condition number of B. If this number is extremely large, the basis is nearly singular and some numerical difficulties could occur in subsequent computations. (However, an effort is made to avoid near singularity by using slacks to replace columns of B that would have made Umin extremely small, and the modified basis is refactorized.)
Growth is not printed if BS is factorized.
Lt | is the number of triangular columns of B at the beginning of L.
bp | is the size of the ‘bump’ or block to be factorized nontrivially after the triangular rows and columns have been removed.
d2 | is the number of columns remaining when the density of the basis matrix being factorized reached 0.6.
When Print Level≥20 and Monitoring File≥0, the following lines of intermediate printout (<80 characters) are produced on the unit number specified by Monitoring File whenever start="C" (see [Parameters]). They refer to the number of columns selected by the crash procedure during each of several passes through A, whilst searching for a triangular basis matrix.
Slacks | is the number of slacks selected initially.
Free cols | is the number of free columns in the basis.
Preferred | is the number of ‘preferred’ columns in the basis (i.e., istate[j]=3 for some j≤n).
Unit | is the number of unit columns in the basis.
Double | is the number of double columns in the basis.
Triangle | is the number of triangular columns in the basis.
Pad | is the number of slacks used to pad the basis.
When Print Level≥20 and Monitoring File≥0, the following lines of intermediate printout (<80 characters) are produced on the unit number specified by Monitoring File. They refer to the elements of the names array (see [Parameters]).
Name | gives the name for the problem (blank if none).
Objective | gives the name of the free row for the problem (blank if none).
RHS | gives the name of the constraint right-hand side for the problem (blank if none).
Ranges | gives the name of the ranges for the problem (blank if none).
Bounds | gives the name of the bounds for the problem (blank if none).
When Print Level=1 or ≥10 and Monitoring File≥0, the following lines of final printout (<120 characters) are produced on the unit number specified by Monitoring File.
Let aj denote the jth column of A, for j=1,2,…,n. The following describes the printout for each column (or variable). A full stop (.) is printed for any numerical value that is zero.
Number | is the column number j. (This is used internally to refer to xj in the intermediate output.)
Column | gives the name of xj.
State gives the state of the variable (LL if nonbasic on its lower bound, UL if nonbasic on its upper bound, EQ if nonbasic and fixed, FR if nonbasic and strictly between its bounds, BS if basic and SBS if superbasic).
A key is sometimes printed before State to give some additional information about the state of xj. Note that unless the optional parameter Scale Option=0 (default value=2) is specified, the tests for assigning a key are applied to the variables of the scaled problem.
A | Alternative optimum possible. The variable is nonbasic, but its reduced gradient is essentially zero. This means that if the variable were allowed to start moving away from its bound, there would be no change to the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case the values of the Lagrange-multipliers might also change.
D | Degenerate. The variable is basic or superbasic, but it is equal to (or very close to) one of its bounds.
I | Infeasible. The variable is basic or superbasic and is currently violating one of its bounds by more than the value of the optional parameter Feasibility Tolerance (default value=max 10-6,ε, where ε is the machine precision).
N | Not precisely optimal. The variable is nonbasic or superbasic. If the value of the reduced gradient for the variable exceeds the value of the optional parameter Optimality Tolerance (default value=max 10-6,ε), the solution would not be declared optimal because the reduced gradient for the variable would not be considered negligible.
Activity | is the value of xj at the final iterate.
Obj Gradient | is the value of gj at the final iterate. For FP problems, gj is set to zero.
Lower Bound | is the lower bound specified for the variable. None indicates that bl[j]≤-bigbnd.
Upper Bound | is the upper bound specified for the variable. None indicates that bu[j]≥bigbnd.
Reduced Gradnt | is the value of dj at the final iterate (see [The Main Iteration]). For FP problems, dj is set to zero.
m + j | is the value of m+j.
Let vi denote the ith row of A, for i=1,2,…,m. The following describes the printout for each row (or constraint). A full stop (.) is printed for any numerical value that is zero.
Number | is the value of n+i. (This is used internally to refer to si in the intermediate output.)
Row | gives the name of νi.
State gives the state of the variable (LL if active on its lower bound, UL if active on its upper bound, EQ if active and fixed, BS if inactive when si is basic and SBS if inactive when si is superbasic).
A key is sometimes printed before State to give some additional information about the state of si. Note that unless the optional parameter Scale Option=0 (default value=2) is specified, the tests for assigning a key are applied to the variables of the scaled problem.
A | Alternative optimum possible. The variable is nonbasic, but its reduced gradient is essentially zero. This means that if the variable were allowed to start moving away from its bound, there would be no change to the objective function. The values of the other free variables might change, giving a genuine alternative solution. However, if there are any degenerate variables (labelled D), the actual change might prove to be zero, since one of them could encounter a bound immediately. In either case the values of the Lagrange-multipliers might also change.
D | Degenerate. The variable is basic or superbasic, but it is equal to (or very close to) one of its bounds.
I | Infeasible. The variable is basic or superbasic and is currently violating one of its bounds by more than the value of the optional parameter Feasibility Tolerance (default value=max 10-6,ε, where ε is the machine precision).
N | Not precisely optimal. The variable is nonbasic or superbasic. If the value of the reduced gradient for the variable exceeds the value of the optional parameter Optimality Tolerance (default value=max 10-6,ε), the solution would not be declared optimal because the reduced gradient for the variable would not be considered negligible.
Activity | is the value of vi at the final iterate.
Slack Activity | is the value by which vi differs from its nearest bound. (For the free row (if any), it is set to Activity.)
Lower Bound | is the lower bound specified for the variable. None indicates that bl[j]≤-bigbnd.
Upper Bound | is the upper bound specified for the variable. None indicates that bu[j]≥bigbnd.
i | gives the index i of vi.
Numerical values are output with a fixed number of digits; they are not guaranteed to be accurate to this precision.

See Also

H Class
H Members


S Class

[image]

NAG Library for .NET Release 2
S Class
Members See Also Send Feedback
This chapter is concerned with the provision of some commonly occurring physical and mathematical functions.

Syntax

C#
public static class S
Visual Basic
Public NotInheritable Class S
Visual C++
public ref class S abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type S =  class end

Background to the Problems

The majority of the methods in this chapter approximate real-valued functions of a single real argument, and the techniques involved are described in [Functions of a Single Real Argument]. In addition the chapter contains methods for elliptic integrals (see [Approximations to Elliptic Integrals]), Bessel and Airy functions of a complex argument (see [Bessel and Airy Functions of a Complex Argument]), complementary error function of a complex argument, hypergeometric functions and various option pricing methods for use in financial applications.

Functions of a Single Real Argument

Most of the methods provided for functions of a single real argument have been based on truncated Chebyshev expansions. This method of approximation was adopted as a compromise between the conflicting requirements of efficiency and ease of implementation on many different machine ranges. For details of the reasons behind this choice and the production and testing procedures followed in constructing this chapter see Schonfelder (1976).
Basically, if the function to be approximated is f x, then for x∈a,b an approximation of the form
f x=g x∑′r=0 CrTr t
is used (∑′ denotes, according to the usual convention, a summation in which the first term is halved), where g x is some suitable auxiliary function which extracts any singularities, asymptotes and, if possible, zeros of the function in the range in question and t=t x is a mapping of the general range a,b to the specific range [-1,+1] required by the Chebyshev polynomials, Tr t. For a detailed description of the properties of the Chebyshev polynomials see Clenshaw (1962) and Fox and Parker (1968).
The essential property of these polynomials for the purposes of function approximation is that Tn t oscillates between ±1 and it takes its extreme values n+1 times in the interval [-1,+1]. Therefore, provided the coefficients Cr decrease in magnitude sufficiently rapidly the error made by truncating the Chebyshev expansion after n terms is approximately given by
E t≃CnTn t.
That is, the error oscillates between ±Cn and takes its extreme value n+1 times in the interval in question. Now this is just the condition that the approximation be a minimax representation, one which minimizes the maximum error. By suitable choice of the interval, [a,b], the auxiliary function, g x, and the mapping of the independent variable, t x, it is almost always possible to obtain a Chebyshev expansion with rapid convergence and hence truncations that provide near minimax polynomial approximations to the required function. The difference between the true minimax polynomial and the truncated Chebyshev expansion is seldom sufficiently great enough to be of significance.
The evaluation of the Chebyshev expansions follows one of two methods. The first and most efficient, and hence the most commonly used, works with the equivalent simple polynomial. The second method, which is used on the few occasions when the first method proves to be unstable, is based directly on the truncated Chebyshev series, and uses backward recursion to evaluate the sum. For the first method, a suitably truncated Chebyshev expansion (truncation is chosen so that the error is less than the machine precision) is converted to the equivalent simple polynomial. That is, we evaluate the set of coefficients br such that
y t=∑r=0n-1 br tr=∑′r=0n-1 CrTr t.
The polynomial can then be evaluated by the efficient Horner's method of nested multiplications,
y t=b 0+t b 1+t b 2+…t b n-2+t b n-1….
This method of evaluation results in efficient methods but for some expansions there is considerable loss of accuracy due to cancellation effects. In these cases the second method is used. It is well known that if
b n-1=C n-1b n-2=2 t b n-1+C n-2b j-0=2 t b j+1-b j+2+Cj,  j=n-3,n-4,…,0
then
∑′r=0 CrTr t=12 b 0-b 2
and this is always stable. This method is most efficiently implemented by using three variables cyclically and explicitly constructing the recursion.
That is,
α=C n-1β=2 tα+C n-2γ=2 tβ-α+C n-3α=2 tγ-β+C n-4β=2 tα-γ+C n-5⋮say ​α=2 tγ-β+C 2β=2 tα-γ+C 1y t=tβ-α+12 C 0
The auxiliary functions used are normally functions compounded of simple polynomial (usually linear) factors extracting zeros, and the primary compiler-provided functions, sin, cos, ln, exp, sqrt, which extract singularities and/or asymptotes or in some cases basic oscillatory behaviour, leaving a smooth well-behaved function to be approximated by the Chebyshev expansion which can therefore be rapidly convergent.
The mappings of [a,b] to [-1,+1] used range from simple linear mappings to the case when b is infinite, and considerable improvement in convergence can be obtained by use of a bilinear form of mapping. Another common form of mapping is used when the function is even; that is, it involves only even powers in its expansion. In this case an approximation over the whole interval [-a,a] can be provided using a mapping t=2 x/a 2-1. This embodies the evenness property but the expansion in t involves all powers and hence removes the necessity of working with an expansion with half its coefficients zero.
For many of the methods an analysis of the error in principle is given, namely, if E and ∇ are the absolute errors in function and argument and ε and δ are the corresponding relative errors, then
E≃f′x∇E≃x f′x δε≃x f′xf x δ.
If we ignore errors that arise in the argument of the function by propagation of data errors, etc., and consider only those errors that result from the fact that a real number is being represented in the computer in floating-point form with finite precision, then δ is bounded and this bound is independent of the magnitude of x. For example, on an 11-digit machine
δ≤10-11.
(This of course implies that the absolute error ∇=xδ is also bounded but the bound is now dependent on x.) However, because of this the last two relations above are probably of more interest. If possible the relative error propagation is discussed; that is, the behaviour of the error amplification factor x f′x/f x is described, but in some cases, such as near zeros of the function which cannot be extracted explicitly, absolute error in the result is the quantity of significance and here the factor x f′x is described. In general, testing of the functions has shown that their error behaviour follows fairly well these theoretical error behaviours. In regions where the error amplification factors are less than or of the order of one, the errors are slightly larger than the above predictions. The errors are here limited largely by the finite precision of arithmetic in the machine, but ε is normally no more than a few times greater than the bound on δ. In regions where the amplification factors are large, of order ten or greater, the theoretical analysis gives a good measure of the accuracy obtainable.
It should be noted that the definitions and notations used for the functions in this chapter are all taken from Abramowitz and Stegun (1972). You are strongly recommended to consult this book for details before using the methods in this chapter.

Approximations to Elliptic Integrals

Four functions provided here are symmetrised variants of the classical (Legendre) elliptic integrals. These alternative definitions have been suggested by Carlson (1965), Carlson (1977b) and Carlson (1977a) and he also developed the basic algorithms used in this chapter.
The symmetrised elliptic integral of the first kind is represented by
RF x,y,z=12∫0∞dtt+xt+yt+z,
where x,y,z≥0 and at most one may be equal to zero.
The normalization factor, 12, is chosen so as to make
RF x,x,x=1/x.
If any two of the variables are equal, RF degenerates into the second function
RC x,y=RF x,y,y=12∫0∞dtt+y.t+x,
where the argument restrictions are now x≥0 and y≠0.
This function is related to the logarithm or inverse hyperbolic functions if 0<y<x, and to the inverse circular functions if 0≤x≤y.
The symmetrised elliptic integral of the second kind is defined by
RD x,y,z=32∫0∞dtt+xt+y t+z 3
with z>0, x≥0 and y≥0, but only one of x or y may be zero.
The function is a degenerate special case of the symmetrised elliptic integral of the third kind
RJ x,y,z,ρ=32∫0∞dtt+xt+yt+z t+ρ
with ρ≠0 and x,y,z≥0 with at most one equality holding. Thus RD x,y,z=RJ x,y,z,z. The normalization of both these functions is chosen so that
RD x,x,x=RJ x,x,x,x=1/x⁢x.
The algorithms used for all these functions are based on duplication theorems. These allow a recursion system to be established which constructs a new set of arguments from the old using a combination of arithmetic and geometric means. The value of the function at the original arguments can then be simply related to the value at the new arguments. These recursive reductions are used until the arguments differ from the mean by an amount small enough for a Taylor series about the mean to give sufficient accuracy when retaining terms of order less than six. Each step of the recurrences reduces the difference from the mean by a factor of four, and as the truncation error is of order six, the truncation error goes like 4096-n, where n is the number of iterations.
The above forms can be related to the more traditional canonical forms (see Section 17.2 of Abramowitz and Stegun (1972)), as follows.
If we write q=cos 2 ϕ,r=1-m sin 2 ϕ,s=1-n sin 2 ϕ, where 0≤ϕ≤12 π, we have
the classical elliptic integral of the first kind:
F ϕ∣m=∫0 ϕ 1-m sin 2 θ-12 dθ=sin ϕ RF q,r,1;
the classical elliptic integral of the second kind:
E ϕ∣m=∫0 ϕ 1-m sin 2 θ 12 dθ=sin ϕ RF q,r,1-13 m sin 3 ϕ RD q,r,1
the classical elliptic integral of the third kind:
Π n;ϕ∣m=∫0 ϕ 1-n sin 2 θ-11-m sin 2 θ-12 dθ=sin ϕ RF q,r,1+13 n sin 3 ϕ RJ q,r,1,s.
Also the classical complete elliptic integral of the first kind:
K m=∫0 π 2 1-m sin 2 θ-12 dθ=RF 0,1-m,1;
the classical complete elliptic integral of the second kind:
E m=∫0 π 2 1-m sin 2 θ 12 dθ=RF 0,1-m,1-13 m RD 0,1-m,1.
For convenience, (S not in this release) contains methods to evaluate classical and symmetrised elliptic integrals.

Bessel and Airy Functions of a Complex Argument

The methods for Bessel and Airy functions of a real argument are based on Chebyshev expansions, as described in [Functions of a Single Real Argument]. The methods provided for functions of a complex argument, however, use different methods. These methods relate all functions to the modified Bessel functions Iν z and Kν z computed in the right-half complex plane, including their analytic continuations. Iν and Kν are computed by different methods according to the values of z and ν. The methods include power series, asymptotic expansions and Wronskian evaluations. The relations between functions are based on well known formulae (see Abramowitz and Stegun (1972)).

Option Pricing Methods

The option pricing methods evaluate the closed form solutions or approximations to the equations that define mathematical models for the prices of selected financial option contracts. These solutions can be viewed as special functions determined by the underlying equations. The terminology associated with these methods arises from their setting in financial markets and is briefly outlined below. See Joshi (2003) for a comprehensive introduction to this subject. An option is a contract which gives the holder the right, but not the obligation, to buy (if it is a call) or sell (if it is a put) a particular asset, S. A European option can be exercised only at the specified expiry time, T, while an American option can be exercised at any time up to T. For Asian options the average underlying price over a pre-set time period determines the payoff.
The asset is bought (if a call) or sold (if a put) at a pre-specified strike price X. Thus, an option contract has a payoff to the holder of max ST-X,0 for a call or max X-ST,0, for a put, which depends on whether the asset price at the time of exercise is above (call) or below (put) the strike, X. If at any moment in time a contract is currently showing a theoretical profit then it is deemed ‘in-the-money’; otherwise it is deemed ‘out-of-the-money’.
The option contract itself therefore has a value and, in many cases, can be traded in markets. Mathematical models (e.g., Black–Scholes, Merton, Vasicek, Hull–White, Heston, CEV, SABR, …) give theoretical prices for particular option contracts using a number of assumptions about the behaviour of financial markets. Typically the price St of the underlying asset at time t is modelled as the solution of a stochastic differential equation (SDE). Depending on the complexity of this equation, the model may admit closed form formulae for the prices of various options. The options described in this chapter introduction are detailed below. We let 𝔼 denote expectation with respect to the risk neutral measure and we define 𝕀A to be 1 on the set A and 0 otherwise.
– The price of a standard European call option is 𝔼 e-rT max ST-X,0 and the price of a standard European put option is 𝔼 e-rT max X-ST,0.
– For continuously averaged geometric Asian options define
G T=exp∫0 T log St dt.
Then the price of an Asian call option is 𝔼 e-rT max G T-X,0 and the price of an Asian put option is 𝔼 e-rT max X-G T,0.
– For a binary asset-or-nothing option the price of a call is 𝔼 e-rT ST𝕀 ST>X and the price of a put is 𝔼 e-rT ST𝕀 ST<X.
– For a binary cash-or-nothing option the price of a call is 𝔼 e-rT X 𝕀 ST>X and the price of a put is 𝔼 e-rT X 𝕀 ST<X.
– For a floating-strike lookback option the price of a call is 𝔼 e-rT ST-min 0≤t≤TSt and the price of a put is 𝔼 e-rT max 0≤t≤TSt-ST.
– For an up-and-in barrier option with barrier level H and cash rebate K, set A=max 0≤t≤TSt>H. Then the price of a call is
𝔼 e-rT max ST-X,0 𝕀A+e-rT K 1-𝕀A
and the price of a put is
𝔼 e-rT max X-ST,0 𝕀A+e-rT K 1-𝕀A
– For a down-and-in barrier option with barrier level H and cash rebate K, set A=min 0≤t≤TSt<H. Then the price of a call is
𝔼 e-rT max ST-X,0 𝕀A+e-rT K 1-𝕀A
and the price of a put is
𝔼 e-rT max X-ST,0 𝕀A+e-rT K 1-𝕀A
– For an up-and-out barrier option with barrier level H and cash rebate K, set A=max 0≤t≤TSt>H. Then the price of a call is
𝔼 e-rT max ST-X,0 1-𝕀A+e-rT K 𝕀A
and the price of a put is
𝔼 e-rT max X-ST,0 1-𝕀A+e-rT K 𝕀A
– For a down-and-out barrier option with barrier level H and cash rebate K, set A=min 0≤t≤TSt<H. Then the price of a call is
𝔼 e-rT max ST-X,0 1-𝕀A+e-rT K 𝕀A
and the price of a put is
𝔼 e-rT max X-ST,0 1-𝕀A+e-rT K 𝕀A
– The price of an American call option is ess sup 0≤τ≤T 𝔼 e-rτ max Sτ-X,0 and the price of an American put option is ess sup 0≤τ≤T 𝔼 e-rτ max X-Sτ,0. Here ess sup 0≤τ≤T denotes the essential supremum over all stopping times τ for the process S which take values in 0,T. If S is a Markov process, then the essential supremum may be replaced with the normal supremum. Note that if the asset S pays no dividends then the price of an American call option is the same as a European call option.

The Black–Scholes Model

The best known model of asset behaviour is the Black–Scholes model. Under the risk-neutral measure, the asset is governed by the SDE
d StSt=r-q dt+σ dW t
where r is the continuously compounded risk-free interest rate, q is the continuously compounded dividend yield, σ is the volatility of log-asset returns (i.e., log S t+dt/St) and W=Wt t≥0 is a standard Brownian motion. Under this model, the price of any option P must solve the Black–Scholes PDE
∂P∂t+∂P∂S r-q S+12∂2 P∂S 2 σ 2S 2-rP=0
at all times before the option is exercised. This PDE admits a closed form solution for a number of different options.

The Black–Scholes Model with Term Structure

The simplest extension of the Black–Scholes model is to allow r, q and σ to be deterministic functions of time so that
d St St=rt-qt dt+σtdW t.
In this case one can still obtain closed form solutions for some options, e.g., European calls and puts.

The Heston Model

Heston (1993) proposed a stochastic volatility model with the following form
d St St=r-q dt+vt d Wt 1d vt=κ η-vt dt+σ vt d Wt 2
where W 1 and W 2 are two Brownian motions with quadratic covariation given by d W 1,W 2 t=ρdt. In this model r and q are the continuously compounded risk free interest rate and dividend rate respectively, v=vt t≥0 is the stochastic volatility process, η is the long term mean of volatility, κ is the rate of mean reversion, and σ is the volatility of volatility. The prices of European call and put options in the Heston model are available in closed form up to the evaluation of an integral transform (see Lewis (2000)).

The Heston Model with Term Structure

The Heston model can be extended by allowing the coefficients to become deterministic functions of time:
d St St=rt-qt dt+vt d Wt 1d vt=κt ηt-vt dt+σt vt d Wt 2
where W 1 and W 2 are two Brownian motions with quadratic covariation given by d W 1,W 2 t=ρt dt. When the coefficients are restricted to being piecewise constant functions of time, the prices of European call and put options can be calculated as described in Elices (2008) and Mikhailov and Nögel (2003).

Hypergeometric Functions

The confluent hypergeometric function M a,b,x (or F 1 1 a;b;x) requires a number of techniques to approximate it over the whole parameter a,b space and for all argument x values. For x well within the unit circle x≤ρ<1 (where ρ=0.8 say), and for relatively small parameter values, the function can be well approximated by Taylor expansions, continued fractions or through the solution of the related ordinary differential equation by an explicit, adaptive integrator. For values of x>ρ, one of several transformations can be performed (depending on the value of x) to reformulate the problem in terms of a new argument x′ such that x′≤ρ. If one or more of the parameters is relatively large (e.g., a>30) then recurrence relations can be used in combination to reformulate the problem in terms of parameter values of small size (e.g., a<1).
Approximations to the hypergeometric functions can therefore require all of the above techniques in sequence: a transformation to get an argument well inside the unit circle, a combination of recurrence relations to reduce the parameter sizes, and the approximation of the resulting hypergeometric function by one of a set of approximation techniques. Similar complications arise in the computation of the Gaussian Hypergeometric Function F 1 2.
All the techniques described above are based on those described in Pearson (2009).

Recommendations on Choice and Use of Available Methods

Vectorized Method Variants

Many methods in (S not in this release) which compute functions of a single real argument have variants which operate on vectors of arguments. For example, s18ae computes the value of the I 0 Bessel function for a single argument, and (S18ASF not in this release) computes the same function for multiple arguments. In general it should be more efficient to use vectorized methods where possible, though to some extent this will depend on the environment from which you call the methods. See [] for a complete list of vectorized methods.

Elliptic Integrals

IMPORTANT ADVICE: users who encounter elliptic integrals in the course of their work are strongly recommended to look at transforming their analysis directly to one of the Carlson forms, rather than to the traditional canonical Legendre forms. In general, the extra symmetry of the Carlson forms is likely to simplify the analysis, and these symmetric forms are much more stable to calculate.
The method s21ba for RC is largely included as an auxiliary to the other methods for elliptic integrals. This integral essentially calculates elementary functions, e.g.,
ln x=x-1 RC 1+x 2 2,x,  x>0;arcsin x=x RC 1-x 2,1,x≤1;arcsinh x=x RC 1+x 2,1,etc.
In general this method of calculating these elementary functions is not recommended as there are usually much more efficient specific methods available in the Library. However, s21ba may be used, for example, to compute ln x/x-1 when x is close to 1, without the loss of significant figures that occurs when ln x and x-1 are computed separately.

Bessel and Airy Functions

For computing the Bessel functions Jν x, Yν x, Iν x and Kν x where x is real and ν=0​ or ​1, special methods are provided, which are much faster than the more general methods that allow a complex argument and arbitrary real ν≥0. Similarly, special methods are provided for computing the Airy functions and their derivatives Ai x, Bi x, Ai′x, Bi′x for a real argument which are much faster than the methods for complex arguments.

Option Pricing Functions

For the Black–Scholes model, functions are provided to compute prices and derivatives (Greeks) of all the European options listed in [Option Pricing Methods]. Prices for American call and put options can be obtained by calling (S30QCF not in this release) which uses the Bjerksund and Stensland (2002) approximation to the theoretical value. For the Black–Scholes model with term structure, prices for European call and put options can be obtained by calling (D03NDF not in this release). The prices of European call and put options in the standard Heston model can be obtained by calling (S30NAF not in this release), while (S30NCF not in this release) returns the same prices in the Heston model with term structure.

Hypergeometric Functions

Two methods are provided for the confluent hypergeometric function F 1 1. Both return values for F 1 1 a;b;x where parameters a and b, and argument x, are all real, but one variant works in a scaled form designed to avoid unnecessary loss of precision. The unscaled method (S22BAF not in this release) is easier to use and should be chosen in the first instance, changing to the scaled method (S22BBF not in this release) only if problems are encountered. Similar considerations apply to the Gaussian hypergeometric function methods (S22BEF not in this release) (S22BFF not in this release).

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Bjerksund P and Stensland G (2002) Closed form valuation of American options Discussion Paper 2002/09 NHH Bergen Norway http://www.nhh.no/
Carlson B C (1965) On computing elliptic integrals and functions J. Math. Phys. 44 36–51
Carlson B C (1977a) Special Functions of Applied Mathematics Academic Press
Carlson B C (1977b) Elliptic integrals of the first kind SIAM J. Math. Anal. 8 231–242
Clenshaw C W (1962) Chebyshev Series for Mathematical Functions Mathematical tables HMSO
Elices A (2008) Models with time-dependent parameters using transform methods: application to Heston’s model arXiv:0708.2020v2
Fox L and Parker I B (1968) Chebyshev Polynomials in Numerical Analysis Oxford University Press
Haug E G (2007) The Complete Guide to Option Pricing Formulas (2nd Edition) McGraw-Hill
Heston S (1993) A closed-form solution for options with stochastic volatility with applications to bond and currency options Review of Financial Studies 6 327–343
Joshi M S (2003) The Concepts and Practice of Mathematical Finance Cambridge University Press
Lewis A L (2000) Option valuation under stochastic volatility Finance Press, USA
Mikhailov S and Nögel U (2003) Heston’s Stochastic Volatility Model Implementation, Calibration and Some Extensions Wilmott Magazine July/August 74–79
Pearson J (2009) Computation of hypergeometric functions MSc Dissertation, Mathematical Institute, University of Oxford
Schonfelder J L (1976) The production of special function routines for a multi-machine library Softw. Pract. Exper. 6(1)

Inheritance Hierarchy

System..::..Object
NagLibrary..::..S

See Also

S Members


S Members

[image] [image]

NAG Library for .NET Release 2
S Members
S Class Methods See Also Send Feedback

The S type exposes the following members.

Methods

Name Description
s01ba
s01ba returns a value of the shifted logarithmic function, ln 1+x.
s07aa
s07aa returns the value of the circular tangent, tan x.
s09aa
s09aa returns the value of the inverse circular sine, arcsin x. The value is in the principal range -π/2,π/2.
s09ab
s09ab returns the value of the inverse circular cosine, arccos x; the result is in the principal range 0,π.
s10aa
s10aa returns a value for the hyperbolic tangent, tanh x.
s10ab
s10ab returns the value of the hyperbolic sine, sinh x.
s10ac
s10ac returns the value of the hyperbolic cosine, cosh x.
s11aa
s11aa returns the value of the inverse hyperbolic tangent, arctanh x.
s11ab
s11ab returns the value of the inverse hyperbolic sine, arcsinh x.
s11ac
s11ac returns the value of the inverse hyperbolic cosine, arccosh x. The result is in the principal positive branch.
s13aa
s13aa returns the value of the exponential integral E 1 x.
s13ac
s13ac returns the value of the cosine integral
Ci x=γ+ln x+∫0 x cos u-1 u du,  x>0
where γ denotes Euler's constant.
s13ad
s13ad returns the value of the sine integral
Si x=∫0 x sin u u du,
.
s14aa
s14aa returns the value of the gamma function Γ x.
s14ab
s14ab returns the value of the logarithm of the gamma function, ln Γ x.
s14ac
s14ac returns a value of the function ψ x-ln x, where ψ is the psi function ψ x=d dx ln Γ x=Γ′xΓ x.
s14ad
s14ad returns a sequence of values of scaled derivatives of the psi function ψ x (also known as the digamma function).
s14ae
s14ae returns the value of the kth derivative of the psi function ψ x for real x and k=0,1,…,6.
s14ba
s14ba computes values for the incomplete gamma functions P a,x and Q a,x.
s15ab
s15ab returns the value of the cumulative Normal distribution function, P x.
s15ac
s15ac returns the value of the complement of the cumulative Normal distribution function, Q x.
s15ad
s15ad returns the value of the complementary error function, erfc x.
s15ae
s15ae returns the value of the error function erf x.
s15af
s15af returns a value for Dawson's Integral, F x.
s15ag
s15ag returns the value of the scaled complementary error function erfcx x.
s17ac
s17ac returns the value of the Bessel function Y 0 x.
s17ad
s17ad returns the value of the Bessel function Y 1 x.
s17ae
s17ae returns the value of the Bessel function J 0 x.
s17af
s17af returns the value of the Bessel function J 1 x.
s17ag
s17ag returns a value for the Airy function, Ai x.
s17ah
s17ah returns a value of the Airy function, Bi x.
s17aj
s17aj returns a value of the derivative of the Airy function Ai x.
s17ak
s17ak returns a value for the derivative of the Airy function Bi x.
s17al
s17al determines the leading n zeros of one of the Bessel functions Jα x, Yα x, Jα′x or Yα′x for real x and non-negative α.
s17dg
s17dg returns the value of the Airy function Ai z or its derivative Ai′z for complex z, with an option for exponential scaling.
s17dh
s17dh returns the value of the Airy function Bi z or its derivative Bi′z for complex z, with an option for exponential scaling.
s18ac
s18ac returns the value of the modified Bessel function K 0 x.
s18ad
s18ad returns the value of the modified Bessel function K 1 x.
s18ae
s18ae returns the value of the modified Bessel function I 0 x.
s18af
s18af returns a value for the modified Bessel function I 1 x.
s18cc
s18cc returns a value of the scaled modified Bessel function ex K 0 x.
s18cd
s18cd returns a value of the scaled modified Bessel function ex K 1 x.
s18ce
s18ce returns a value of the scaled modified Bessel function e-x I 0 x.
s18cf
s18cf returns a value of the scaled modified Bessel function e-x I 1 x.
s19aa
s19aa returns a value for the Kelvin function ber x.
s19ab
s19ab returns a value for the Kelvin function bei x.
s19ac
s19ac returns a value for the Kelvin function ker x.
s19ad
s19ad returns a value for the Kelvin function kei x.
s20ac
s20ac returns a value for the Fresnel integral S x.
s20ad
s20ad returns a value for the Fresnel integral C x.
s21ba
s21ba returns a value of an elementary integral, which occurs as a degenerate case of an elliptic integral of the first kind.
s21bb
s21bb returns a value of the symmetrised elliptic integral of the first kind.
s21bc
s21bc returns a value of the symmetrised elliptic integral of the second kind.
s21bd
s21bd returns a value of the symmetrised elliptic integral of the third kind.
s21be
s21be returns a value of the classical (Legendre) form of the incomplete elliptic integral of the first kind.
s21bf
s21bf returns a value of the classical (Legendre) form of the incomplete elliptic integral of the second kind.
s21bg
s21bg returns a value of the classical (Legendre) form of the incomplete elliptic integral of the third kind.
s21bh
s21bh returns a value of the classical (Legendre) form of the complete elliptic integral of the first kind.
s21bj
s21bj returns a value of the classical (Legendre) form of the complete elliptic integral of the second kind.
s21ca
s21ca evaluates the Jacobian elliptic functions sn, cn and dn.
s21cb
s21cb evaluates the Jacobian elliptic functions sn z, cn z and dn z for a complex argument z.
s21cc
s21cc returns the value of one of the Jacobian theta functions θ 0 x,q, θ 1 x,q, θ 2 x,q, θ 3 x,q or θ 4 x,q for a real argument x and non-negative q<1.
s22aa
s22aa returns a sequence of values for either the unnormalized or normalized Legendre functions of the first kind Pnm x or Pnm¯x for real x of a given order m and degree n=0,1,…,N.

See Also

S Class


S Methods

[image] [image]

NAG Library for .NET Release 2
S Methods
S Class See Also Send Feedback

The S type exposes the following members.

Methods

Name Description
s01ba
s01ba returns a value of the shifted logarithmic function, ln 1+x.
s07aa
s07aa returns the value of the circular tangent, tan x.
s09aa
s09aa returns the value of the inverse circular sine, arcsin x. The value is in the principal range -π/2,π/2.
s09ab
s09ab returns the value of the inverse circular cosine, arccos x; the result is in the principal range 0,π.
s10aa
s10aa returns a value for the hyperbolic tangent, tanh x.
s10ab
s10ab returns the value of the hyperbolic sine, sinh x.
s10ac
s10ac returns the value of the hyperbolic cosine, cosh x.
s11aa
s11aa returns the value of the inverse hyperbolic tangent, arctanh x.
s11ab
s11ab returns the value of the inverse hyperbolic sine, arcsinh x.
s11ac
s11ac returns the value of the inverse hyperbolic cosine, arccosh x. The result is in the principal positive branch.
s13aa
s13aa returns the value of the exponential integral E 1 x.
s13ac
s13ac returns the value of the cosine integral
Ci x=γ+ln x+∫0 x cos u-1 u du,  x>0
where γ denotes Euler's constant.
s13ad
s13ad returns the value of the sine integral
Si x=∫0 x sin u u du,
.
s14aa
s14aa returns the value of the gamma function Γ x.
s14ab
s14ab returns the value of the logarithm of the gamma function, ln Γ x.
s14ac
s14ac returns a value of the function ψ x-ln x, where ψ is the psi function ψ x=d dx ln Γ x=Γ′xΓ x.
s14ad
s14ad returns a sequence of values of scaled derivatives of the psi function ψ x (also known as the digamma function).
s14ae
s14ae returns the value of the kth derivative of the psi function ψ x for real x and k=0,1,…,6.
s14ba
s14ba computes values for the incomplete gamma functions P a,x and Q a,x.
s15ab
s15ab returns the value of the cumulative Normal distribution function, P x.
s15ac
s15ac returns the value of the complement of the cumulative Normal distribution function, Q x.
s15ad
s15ad returns the value of the complementary error function, erfc x.
s15ae
s15ae returns the value of the error function erf x.
s15af
s15af returns a value for Dawson's Integral, F x.
s15ag
s15ag returns the value of the scaled complementary error function erfcx x.
s17ac
s17ac returns the value of the Bessel function Y 0 x.
s17ad
s17ad returns the value of the Bessel function Y 1 x.
s17ae
s17ae returns the value of the Bessel function J 0 x.
s17af
s17af returns the value of the Bessel function J 1 x.
s17ag
s17ag returns a value for the Airy function, Ai x.
s17ah
s17ah returns a value of the Airy function, Bi x.
s17aj
s17aj returns a value of the derivative of the Airy function Ai x.
s17ak
s17ak returns a value for the derivative of the Airy function Bi x.
s17al
s17al determines the leading n zeros of one of the Bessel functions Jα x, Yα x, Jα′x or Yα′x for real x and non-negative α.
s17dg
s17dg returns the value of the Airy function Ai z or its derivative Ai′z for complex z, with an option for exponential scaling.
s17dh
s17dh returns the value of the Airy function Bi z or its derivative Bi′z for complex z, with an option for exponential scaling.
s18ac
s18ac returns the value of the modified Bessel function K 0 x.
s18ad
s18ad returns the value of the modified Bessel function K 1 x.
s18ae
s18ae returns the value of the modified Bessel function I 0 x.
s18af
s18af returns a value for the modified Bessel function I 1 x.
s18cc
s18cc returns a value of the scaled modified Bessel function ex K 0 x.
s18cd
s18cd returns a value of the scaled modified Bessel function ex K 1 x.
s18ce
s18ce returns a value of the scaled modified Bessel function e-x I 0 x.
s18cf
s18cf returns a value of the scaled modified Bessel function e-x I 1 x.
s19aa
s19aa returns a value for the Kelvin function ber x.
s19ab
s19ab returns a value for the Kelvin function bei x.
s19ac
s19ac returns a value for the Kelvin function ker x.
s19ad
s19ad returns a value for the Kelvin function kei x.
s20ac
s20ac returns a value for the Fresnel integral S x.
s20ad
s20ad returns a value for the Fresnel integral C x.
s21ba
s21ba returns a value of an elementary integral, which occurs as a degenerate case of an elliptic integral of the first kind.
s21bb
s21bb returns a value of the symmetrised elliptic integral of the first kind.
s21bc
s21bc returns a value of the symmetrised elliptic integral of the second kind.
s21bd
s21bd returns a value of the symmetrised elliptic integral of the third kind.
s21be
s21be returns a value of the classical (Legendre) form of the incomplete elliptic integral of the first kind.
s21bf
s21bf returns a value of the classical (Legendre) form of the incomplete elliptic integral of the second kind.
s21bg
s21bg returns a value of the classical (Legendre) form of the incomplete elliptic integral of the third kind.
s21bh
s21bh returns a value of the classical (Legendre) form of the complete elliptic integral of the first kind.
s21bj
s21bj returns a value of the classical (Legendre) form of the complete elliptic integral of the second kind.
s21ca
s21ca evaluates the Jacobian elliptic functions sn, cn and dn.
s21cb
s21cb evaluates the Jacobian elliptic functions sn z, cn z and dn z for a complex argument z.
s21cc
s21cc returns the value of one of the Jacobian theta functions θ 0 x,q, θ 1 x,q, θ 2 x,q, θ 3 x,q or θ 4 x,q for a real argument x and non-negative q<1.
s22aa
s22aa returns a sequence of values for either the unnormalized or normalized Legendre functions of the first kind Pnm x or Pnm¯x for real x of a given order m and degree n=0,1,…,N.

See Also

S Class


s01ba Method

[image]

NAG Library for .NET Release 2
S..::s01ba Method
S Class See Also Send Feedback
s01ba returns a value of the shifted logarithmic function, ln 1+x.

Syntax

C#
public static double s01ba(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s01ba ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s01ba(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s01ba :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
Constraint: x>-1.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s01ba returns a value of the shifted logarithmic function, ln 1+x.

Description

s01ba computes values of ln 1+x, retaining full relative precision even when x is small. The method is based on the Chebyshev expansion
ln 1+p 2+2 p x-1+p 2-2 p x-=4∑k=0∞p 2 k+12 k+1 T 2 k+1 x-.
Setting x-=x 1+p 22 p x+2, and choosing p=q-1q+1, q=24 the expansion is valid in the domain x∈1 2-1,2-1.
Outside this domain, ln 1+x is computed by the standard logarithmic function.

References

Lyusternik L A, Chervonenkis O A and Yanpolskii A R (1965) Handbook for Computing Elementary Functions p. 57 Pergamon Press

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, x≤-1.0.
The result is returned as zero.
ifail=-9000
An error occured, see message report.

Accuracy

The returned result should be accurate almost to machine precision, with a limit of about 20 significant figures due to the precision of internal constants. Note however that if x lies very close to -1.0 and is not exact (for example if x is the result of some previous computation and has been rounded), then precision will be lost in the computation of 1+x, and hence ln 1+x, in s01ba.

Parallelism and Performance

None.

Further Comments

Empirical tests show that the time taken for a call of s01ba usually lies between about 1.25 and 2.5 times the time for a call to the standard logarithm function.

Example

The example program reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s01bae.cs

Example program data: s01bae.d

Example program results: s01bae.r

See Also

S Class
S Members


s07aa Method

[image]

NAG Library for .NET Release 2
S..::s07aa Method
S Class See Also Send Feedback
s07aa returns the value of the circular tangent, tan x.

Syntax

C#
public static double s07aa(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s07aa ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s07aa(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s07aa :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s07aa returns the value of the circular tangent, tan x.

Description

s07aa calculates an approximate value for the circular tangent of its argument, tan x. It is based on the Chebyshev expansion
tan θ=θy t=θ∑′r=0 crTr t
where -π 4<θ<π 4 and -1<t<+1,  t=2 4 θ π 2-1.
The reduction to the standard range is accomplished by taking
x=Nπ/2+θ
where N is an integer and -π 4<θ<π 4,
i.e., θ=x-2 x π π 2 where N=2 x π=​ the nearest integer to ​2 x π.
From the properties of tan x it follows that
tan x=tan θ,Neven-1/tan θ,Nodd

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
The method has been called with an argument that is larger in magnitude than F; the default result returned is zero. The value of F is given in the Users' Note for your implementation.
ifail=2
The method has been called with an argument that is too close (as determined using the relative tolerance F) to an odd multiple of π/2, at which the function is infinite; the method returns a value with the correct sign but a more or less arbitrary but large magnitude (see [Accuracy]). The value of F is given in the Users' Note for your implementation.
ifail=-9000
An error occured, see message report.

Accuracy

If δ and ε are the relative errors in the argument and result respectively, then in principle
ε≥2 xsin 2 x δ.
That is a relative error in the argument, x, is amplified by at least a factor 2 x/sin 2 x in the result.
Similarly if E is the absolute error in the result this is given by
E≥x cos 2 x δ.
The equalities should hold if δ is greater than the machine precision (δ is a result of data errors etc.) but if δ is simply the round-off error in the machine it is possible that internal calculation rounding will lose an extra figure.
The graphs below show the behaviour of these amplification factors.
Figure 1
Figure 2
In the principal range it is possible to preserve relative accuracy even near the zero of tan x at x=0 but at the other zeros only absolute accuracy is possible. Near the infinities of tan x both the relative and absolute errors become infinite and the method must fail (error 2).
If N is odd and θ≤x F 2 the method could not return better than two figures and in all probability would produce a result that was in error in its most significant figure. Therefore the method fails and it returns the value
-sign θ 1 x F 2≃-sign θtan π 2-x F 2
which is the value of the tangent at the nearest argument for which a valid call could be made.
Accuracy is also unavoidably lost if the method is called with a large argument. If x>F 1 the method fails (error 1) and returns zero. (See the Users' Note for your implementation for specific values of F 1 and F 2.)

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s07aae.cs

Example program data: s07aae.d

Example program results: s07aae.r

See Also

S Class
S Members


s09aa Method

[image]

NAG Library for .NET Release 2
S..::s09aa Method
S Class See Also Send Feedback
s09aa returns the value of the inverse circular sine, arcsin x. The value is in the principal range -π/2,π/2.

Syntax

C#
public static double s09aa(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s09aa ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s09aa(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s09aa :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
Constraint: x≤1.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s09aa returns the value of the inverse circular sine, arcsin x. The value is in the principal range -π/2,π/2.

Description

s09aa calculates an approximate value for the inverse circular sine, arcsin x. It is based on the Chebyshev expansion
arcsin x=x×y x=x∑′r=0 arTr t
where -1 2≤x≤1 2 and t=4 x 2-1.
For x 2≤12,  arcsin x=x×y x.
For 12<x 2≤1,  arcsin x=sign x π 2-arcsin 1-x 2.
For x 2>1,  arcsin x is undefined and the method fails.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
The method has been called with an argument greater than 1.0 in absolute value; arcsin x is undefined and the method returns zero.
ifail=-9000
An error occured, see message report.

Accuracy

If δ and ε are the relative errors in the argument and result, respectively, then in principle
ε≃x arcsin x 1-x 2×δ.
That is, a relative error in the argument x is amplified by at least a factor x arcsin x 1-x 2 in the result.
The equality should hold if δ is greater than the machine precision (δ is a result of data errors etc.) but if δ is produced simply by round-off error in the machine it is possible that rounding in internal calculations may lose an extra figure in the result.
This factor stays close to one except near x=1 where its behaviour is shown in the following graph.
Figure 1
For x close to unity, 1-x∼δ, the above analysis is no longer applicable owing to the fact that both argument and result are subject to finite bounds, (x≤1 and arcsin x≤12 π). In this region ε∼δ; that is the result will have approximately half as many correct significant figures as the argument.
For x=1 the result will be correct to full machine precision.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s09aae.cs

Example program data: s09aae.d

Example program results: s09aae.r

See Also

S Class
S Members


s09ab Method

[image]

NAG Library for .NET Release 2
S..::s09ab Method
S Class See Also Send Feedback
s09ab returns the value of the inverse circular cosine, arccos x; the result is in the principal range 0,π.

Syntax

C#
public static double s09ab(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s09ab ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s09ab(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s09ab :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
Constraint: x≤1.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s09ab returns the value of the inverse circular cosine, arccos x; the result is in the principal range 0,π.

Description

s09ab calculates an approximate value for the inverse circular cosine, arccos x. It is based on the Chebyshev expansion
arcsin x=x×y t=x∑′r=0 arTr t
where -1 2≤x≤1 2,   and  t=4 x 2-1.
For x 2≤12,  arccos x=π 2-arcsin x.
For -1≤x<-1 2,  arccos x=π-arcsin 1-x 2.
For 1 2<x≤1,  arccos x=arcsin 1-x 2.
For x>1,  arccos x is undefined and the method fails.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
s09ab has been called with x>1.0, for which arccos is undefined. A zero result is returned.
ifail=-9000
An error occured, see message report.

Accuracy

If δ and ε are the relative errors in the argument and the result, respectively, then in principle
ε≃x arccos x 1-x 2×δ.
The equality should hold if δ is greater than the machine precision (δ is due to data errors etc.), but if δ is due simply to round-off in the machine it is possible that rounding etc. in internal calculations may lose one extra figure.
The behaviour of the amplification factor x arccos x 1-x 2 is shown in the graph below.
In the region of x=0 this factor tends to zero and the accuracy will be limited by the machine precision. For x close to one, 1-x∼δ, the above analysis is not applicable owing to the fact that both the argument and the result are bounded x≤1, 0≤arccos x≤π.
In the region of x∼-1 we have ε∼δ, that is the result will have approximately half as many correct significant figures as the argument.
In the region x∼+1, we have that the absolute error in the result, E, is given by E∼δ, that is the result will have approximately half as many decimal places correct as there are correct figures in the argument.
Figure 1

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s09abe.cs

Example program data: s09abe.d

Example program results: s09abe.r

See Also

S Class
S Members


s10aa Method

[image]

NAG Library for .NET Release 2
S..::s10aa Method
S Class See Also Send Feedback
s10aa returns a value for the hyperbolic tangent, tanh x.

Syntax

C#
public static double s10aa(
    double x
)
Visual Basic
Public Shared Function s10aa ( _
    x As Double _
) As Double
Visual C++
public:
static double s10aa(
    double x
)
F#
static member s10aa :
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.

Return Value

s10aa returns a value for the hyperbolic tangent, tanh x.

Description

s10aa calculates an approximate value for the hyperbolic tangent of its argument, tanh x.
For x≤1 it is based on the Chebyshev expansion
tanh x=x×y t=x∑′r=0 arTr t
where -1≤x≤1,  -1≤t≤1,   and  t=2 x 2-1.
For 1<x<E 1 (see the Users' Note for your implementation for value of E 1)
tanh x=e 2 x-1e 2 x+1.
For x≥E 1, tanh x=sign x to within the representation accuracy of the machine and so this approximation is used.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

None.

Accuracy

If δ and ε are the relative errors in the argument and the result respectively, then in principle,
ε≃2 xsinh 2 x δ.
That is, a relative error in the argument, x, is amplified by a factor approximately 2 xsinh 2 x, in the result.
The equality should hold if δ is greater than the machine precision (δ due to data errors etc.) but if δ is due simply to the round-off in the machine representation it is possible that an extra figure may be lost in internal calculation round-off.
The behaviour of the amplification factor is shown in the following graph:
Figure 1
It should be noted that this factor is always less than or equal to 1.0 and away from x=0 the accuracy will eventually be limited entirely by the precision of machine representation.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s10aae.cs

Example program data: s10aae.d

Example program results: s10aae.r

See Also

S Class
S Members


s10ab Method

[image]

NAG Library for .NET Release 2
S..::s10ab Method
S Class See Also Send Feedback
s10ab returns the value of the hyperbolic sine, sinh x.

Syntax

C#
public static double s10ab(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s10ab ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s10ab(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s10ab :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s10ab returns the value of the hyperbolic sine, sinh x.

Description

s10ab calculates an approximate value for the hyperbolic sine of its argument, sinh x.
For x≤1 it uses the Chebyshev expansion
sinh x=x×y t=x∑′r=0 arTr t
where t=2 x 2-1.
For 1<x≤E 1,  sinh x=12 ex-e-x
where E 1 is a machine-dependent constant, details of which are given in the Users' Note for your implementation.
For x>E 1, the method fails owing to the danger of setting overflow in calculating ex. The result returned for such calls is sinh sign x E 1, i.e., it returns the result for the nearest valid argument.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
The method has been called with an argument too large in absolute magnitude. There is a danger of setting overflow. The result is the value of sinh x at the closest argument for which a valid call could be made. (See [Description] and the Users' Note for your implementation.)
ifail=-9000
An error occured, see message report.

Accuracy

If δ and ε are the relative errors in the argument and result, respectively, then in principle
ε≃x coth x×δ.
That is the relative error in the argument, x, is amplified by a factor, approximately x coth x. The equality should hold if δ is greater than the machine precision (δ is a result of data errors etc.) but, if δ is simply a result of round-off in the machine representation of x, then it is possible that an extra figure may be lost in internal calculation round-off.
The behaviour of the error amplification factor can be seen in the following graph:
Figure 1
It should be noted that for x≥2
ε∼xδ=Δ
where Δ is the absolute error in the argument.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s10abe.cs

Example program data: s10abe.d

Example program results: s10abe.r

See Also

S Class
S Members


s10ac Method

[image]

NAG Library for .NET Release 2
S..::s10ac Method
S Class See Also Send Feedback
s10ac returns the value of the hyperbolic cosine, cosh x.

Syntax

C#
public static double s10ac(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s10ac ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s10ac(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s10ac :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s10ac returns the value of the hyperbolic cosine, cosh x.

Description

s10ac calculates an approximate value for the hyperbolic cosine, cosh x.
For x≤E 1,  cosh x=12 ex+e-x.
For x>E 1, the method fails owing to danger of setting overflow in calculating ex. The result returned for such calls is cosh E 1, i.e., it returns the result for the nearest valid argument. The value of machine-dependent constant E 1 may be given in the Users' Note for your implementation.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
The method has been called with an argument too large in absolute magnitude. There is a danger of overflow. The result returned is the value of cosh x at the nearest valid argument.
ifail=-9000
An error occured, see message report.

Accuracy

If δ and ε are the relative errors in the argument and result, respectively, then in principle
ε≃x tanh x×δ.
That is, the relative error in the argument, x, is amplified by a factor, at least x tanh x. The equality should hold if δ is greater than the machine precision (δ is due to data errors etc.) but if δ is simply a result of round-off in the machine representation of x then it is possible that an extra figure may be lost in internal calculation round-off.
The behaviour of the error amplification factor is shown by the following graph:
Figure 1
It should be noted that near x=0 where this amplification factor tends to zero the accuracy will be limited eventually by the machine precision. Also for x≥2
ε∼xδ=Δ
where Δ is the absolute error in the argument x.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s10ace.cs

Example program data: s10ace.d

Example program results: s10ace.r

See Also

S Class
S Members


s11aa Method

[image]

NAG Library for .NET Release 2
S..::s11aa Method
S Class See Also Send Feedback
s11aa returns the value of the inverse hyperbolic tangent, arctanh x.

Syntax

C#
public static double s11aa(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s11aa ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s11aa(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s11aa :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
Constraint: x<1.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s11aa returns the value of the inverse hyperbolic tangent, arctanh x.

Description

s11aa calculates an approximate value for the inverse hyperbolic tangent of its argument, arctanh x.
For x 2≤12 it is based on the Chebyshev expansion
arctanh x=x×y t=x∑′r=0 arTr t
where -1 2≤x≤1 2,  -1≤t≤1,   and  t=4 x 2-1.
For 12<x 2<1, it uses
arctanh x=12 ln 1+x1-x.
For x≥1, the method fails as arctanh x is undefined.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
The method has been called with an argument greater than or equal to 1.0 in magnitude, for which arctanh is not defined. On failure, the result is returned as zero.
ifail=-9000
An error occured, see message report.

Accuracy

If δ and ε are the relative errors in the argument and result, respectively, then in principle
ε≃x 1-x 2 arctanh x×δ.
That is, the relative error in the argument, x, is amplified by at least a factor x 1-x 2 arctanh x in the result. The equality should hold if δ is greater than the machine precision (δ due to data errors etc.) but if δ is simply due to round-off in the machine representation then it is possible that an extra figure may be lost in internal calculation round-off.
The behaviour of the amplification factor is shown in the following graph:
Figure 1
The factor is not significantly greater than one except for arguments close to x=1. However in the region where x is close to one, 1-x∼δ, the above analysis is inapplicable since x is bounded by definition, x<1. In this region where arctanh is tending to infinity we have
ε∼1/ln δ
which implies an obvious, unavoidable serious loss of accuracy near x∼1, e.g., if x and 1 agree to 6 significant figures, the result for arctanh x would be correct to at most about one figure.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s11aae.cs

Example program data: s11aae.d

Example program results: s11aae.r

See Also

S Class
S Members


s11ab Method

[image]

NAG Library for .NET Release 2
S..::s11ab Method
S Class See Also Send Feedback
s11ab returns the value of the inverse hyperbolic sine, arcsinh x.

Syntax

C#
public static double s11ab(
    double x
)
Visual Basic
Public Shared Function s11ab ( _
    x As Double _
) As Double
Visual C++
public:
static double s11ab(
    double x
)
F#
static member s11ab :
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.

Return Value

s11ab returns the value of the inverse hyperbolic sine, arcsinh x.

Description

s11ab calculates an approximate value for the inverse hyperbolic sine of its argument, arcsinh x.
For x≤1 it is based on the Chebyshev expansion
arcsinh x=x×y t=x∑′r=0 crTr t,   where ​t=2 x 2-1.
For x>1 it uses the fact that
arcsinh x=sign x×ln x+x 2+1.
This form is used directly for 1<x<10 k, where k=n/2+1, and the machine uses approximately n decimal place arithmetic.
For x≥10 k, x 2+1 is equal to x to within the accuracy of the machine and hence we can guard against premature overflow and, without loss of accuracy, calculate
arcsinh x=sign x×ln 2+ln x.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

None.

Accuracy

If δ and ε are the relative errors in the argument and the result, respectively, then in principle
ε≃x 1+x 2 arcsinh x δ.
That is, the relative error in the argument, x, is amplified by a factor at least x 1+x 2 arcsinh x, in the result.
The equality should hold if δ is greater than the machine precision (δ due to data errors etc.) but if δ is simply due to round-off in the machine representation it is possible that an extra figure may be lost in internal calculation round-off.
The behaviour of the amplification factor is shown in the following graph:
Figure 1
It should be noted that this factor is always less than or equal to one. For large x we have the absolute error in the result, E, in principle, given by
E∼δ.
This means that eventually accuracy is limited by machine precision.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s11abe.cs

Example program data: s11abe.d

Example program results: s11abe.r

See Also

S Class
S Members


s11ac Method

[image]

NAG Library for .NET Release 2
S..::s11ac Method
S Class See Also Send Feedback
s11ac returns the value of the inverse hyperbolic cosine, arccosh x. The result is in the principal positive branch.

Syntax

C#
public static double s11ac(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s11ac ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s11ac(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s11ac :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
Constraint: x≥1.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s11ac returns the value of the inverse hyperbolic cosine, arccosh x. The result is in the principal positive branch.

Description

s11ac calculates an approximate value for the inverse hyperbolic cosine, arccosh x. It is based on the relation
arccosh x=ln x+x 2-1.
This form is used directly for 1<x<10 k, where k=n/2+1, and the machine uses approximately n decimal place arithmetic.
For x≥10 k, x 2-1 is equal to x to within the accuracy of the machine and hence we can guard against premature overflow and, without loss of accuracy, calculate
arccosh x=ln 2+ln x.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
The method has been called with an argument less than 1.0, for which arccosh x is not defined. The result returned is zero.
ifail=-9000
An error occured, see message report.

Accuracy

If δ and ε are the relative errors in the argument and result respectively, then in principle
ε≃x x 2-1 arccosh x×δ.
That is the relative error in the argument is amplified by a factor at least x x 2-1 arccosh x in the result. The equality should apply if δ is greater than the machine precision (δ due to data errors etc.) but if δ is simply a result of round-off in the machine representation it is possible that an extra figure may be lost in internal calculation and round-off. The behaviour of the amplification factor is shown in the following graph:
Figure 1
It should be noted that for x>2 the factor is always less than 1.0. For large x we have the absolute error E in the result, in principle, given by
E∼δ.
This means that eventually accuracy is limited by machine precision. More significantly for x close to 1, x-1∼δ, the above analysis becomes inapplicable due to the fact that both function and argument are bounded, x≥1, arccosh x≥0. In this region we have
E∼δ.
That is, there will be approximately half as many decimal places correct in the result as there were correct figures in the argument.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s11ace.cs

Example program data: s11ace.d

Example program results: s11ace.r

See Also

S Class
S Members


s13aa Method

[image]

NAG Library for .NET Release 2
S..::s13aa Method
S Class See Also Send Feedback
s13aa returns the value of the exponential integral E 1 x.

Syntax

C#
public static double s13aa(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s13aa ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s13aa(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s13aa :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
Constraint: -xhi≤x<0.0 or x>0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s13aa returns the value of the exponential integral E 1 x.

Description

s13aa calculates an approximate value for
E 1 x=-Ei-x=∫x∞e-u u du.
using Chebyshev expansions, where x is real. For x<0, the real part of the principal value of the integral is taken. The value E 1 0 is infinite, and so, when x=0, s13aa exits with an error and returns the largest representable machine number.
For 0<x≤4,
E 1 x=y t-ln x=∑′r arTr t-ln x,
where t=12 x-1.
For x>4,
E 1 x=e-x x y t=e-x x∑′r arTr t,
where t=-1.0+14.5 x+3.25=11.25-x3.25+x.
In both cases, -1≤t≤+1.
For x<0, the approximation is based on expansions proposed by Cody and Thatcher Jr. (1969). Precautions are taken to maintain good relative accuracy in the vicinity of x 0≈-0.372507…, which corresponds to a simple zero of Ei(-x).
s13aa guards against producing underflows and overflows by using the parameter xhi; see the Users' Note for your implementation for the value of xhi. To guard against overflow, if x<-xhi the method terminates and returns the negative of the largest representable machine number. To guard against underflow, if x>xhi the result is set directly to zero.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Cody W J and Thatcher Jr. H C (1969) Rational Chebyshev approximations for the exponential integral Eix Math. Comp. 23 289–303

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, x=0.0 and the function is infinite. The result returned is the largest representable machine number.
ifail=2
The evaluation has been abandoned due to the likelihood of overflow. The argument x<-xhi, and the result is returned as the negative of the largest representable machine number.
ifail=-9000
An error occured, see message report.

Accuracy

Unless stated otherwise, it is assumed that x>0.
If δ and ε are the relative errors in argument and result respectively, then in principle,
ε≃e-x E 1 x×δ
so the relative error in the argument is amplified in the result by at least a factor e-x/E 1 x. The equality should hold if δ is greater than the machine precision (δ due to data errors etc.) but if δ is simply a result of round-off in the machine representation, it is possible that an extra figure may be lost in internal calculation and round-off.
The behaviour of this amplification factor is shown in the following graph:
Figure 1
It should be noted that, for absolutely small x, the amplification factor tends to zero and eventually the error in the result will be limited by machine precision.
For absolutely large x,
ε∼xδ=Δ,
the absolute error in the argument.
For x<0, empirical tests have shown that the maximum relative error is a loss of approximately 1 decimal place.

Parallelism and Performance

None.

Further Comments

None.

Example

The following program reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s13aae.cs

Example program data: s13aae.d

Example program results: s13aae.r

See Also

S Class
S Members


s13ac Method

[image]

NAG Library for .NET Release 2
S..::s13ac Method
S Class See Also Send Feedback
s13ac returns the value of the cosine integral
Ci x=γ+ln x+∫0 x cos u-1 u du,  x>0
where γ denotes Euler's constant.

Syntax

C#
public static double s13ac(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s13ac ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s13ac(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s13ac :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
Constraint: x>0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s13ac returns the value of the cosine integral
Ci x=γ+ln x+∫0 x cos u-1 u du,  x>0
where γ denotes Euler's constant.

Description

s13ac calculates an approximate value for Ci x.
For 0<x≤16 it is based on the Chebyshev expansion
Ci x=ln x+∑r=0′arTr t,t=2 x 16 2-1.
For 16<x<xhi where the value of xhi is given in the Users' Note for your implementation,
Ci x=f x sin x x-g x cos x x 2
where f x=∑′r=0 frTr t and g x=∑′r=0 grTr t, t=2 16 x 2-1.
For x≥xhi, Ci x=0 to within the accuracy possible (see [Accuracy]).

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
The method has been called with an argument less than or equal to zero for which the function is not defined. The result returned is zero.
ifail=-9000
An error occured, see message report.

Accuracy

If E and ε are the absolute and relative errors in the result and δ is the relative error in the argument then in principle these are related by
E≃δ cos x and ​ε≃δ cos xCi x.
That is accuracy will be limited by machine precision near the origin and near the zeros of cos x, but near the zeros of Ci x only absolute accuracy can be maintained.
The behaviour of this amplification is shown in Figure 1.
Figure 1
For large values of x, Ci x∼sin x x therefore ε∼δx cot x and since δ is limited by the finite precision of the machine it becomes impossible to return results which have any relative accuracy. That is, when x≥1/δ we have that Ci x≤1/x∼E and hence is not significantly different from zero.
Hence xhi is chosen such that for values of x≥xhi, Ci x in principle would have values less than the machine precision and so is essentially zero.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s13ace.cs

Example program data: s13ace.d

Example program results: s13ace.r

See Also

S Class
S Members


s13ad Method

[image]

NAG Library for .NET Release 2
S..::s13ad Method
S Class See Also Send Feedback
s13ad returns the value of the sine integral
Si x=∫0 x sin u u du,
.

Syntax

C#
public static double s13ad(
    double x
)
Visual Basic
Public Shared Function s13ad ( _
    x As Double _
) As Double
Visual C++
public:
static double s13ad(
    double x
)
F#
static member s13ad :
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.

Return Value

s13ad returns the value of the sine integral
Si x=∫0 x sin u u du,
.

Description

s13ad calculates an approximate value for Si x.
For x≤16.0 it is based on the Chebyshev expansion
Si x=x∑r=0′arTr t,t=2 x 16 2-1.
For 16<x<xhi, where xhi is an implementation-dependent number,
Si x=sign x π 2-f x cos x x-g x sin x x 2
where f x=∑′r=0 frTr t and g x=∑′r=0 grTr t, t=2 16 x 2-1.
For x≥xhi, Si x=12 π sign x to within machine precision.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

There are no failure exits from s13ad. The parameter _ifail has been included for consistency with other methods in this chapter.

Accuracy

If δ and ε are the relative errors in the argument and result, respectively, then in principle
ε≃δ sin xSi x.
The equality may hold if δ is greater than the machine precision (δ due to data errors etc.) but if δ is simply due to round-off in the machine representation, then since the factor relating δ to ε is always less than one, the accuracy will be limited by machine precision.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s13ade.cs

Example program data: s13ade.d

Example program results: s13ade.r

See Also

S Class
S Members


s14aa Method

[image]

NAG Library for .NET Release 2
S..::s14aa Method
S Class See Also Send Feedback
s14aa returns the value of the gamma function Γ x.

Syntax

C#
public static double s14aa(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s14aa ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s14aa(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s14aa :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
Constraint: x must not be zero or a negative integer.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s14aa returns the value of the gamma function Γ x.

Description

s14aa evaluates an approximation to the gamma function Γ x. The method is based on the Chebyshev expansion:
Γ 1+u=∑r=0′arTr t,   where ​0≤u<1,t=2 u-1,
and uses the property Γ 1+x=xΓ x. If x=N+1+u where N is integral and 0≤u<1 then it follows that:
  • for N>0,  Γ x=x-1x-2⋯x-N Γ 1+u,
  • for N=0,  Γ x=Γ 1+u,
  • for N<0,  Γ x=Γ 1+ux x+1x+2⋯x-N-1.
There are four possible failures for this method:
(i) | if x is too large, there is a danger of overflow since Γ x could become too large to be represented in the machine;
(ii) | if x is too large and negative, there is a danger of underflow;
(iii) | if x is equal to a negative integer, Γ x would overflow since it has poles at such points;
(iv) | if x is too near zero, there is again the danger of overflow on some machines. For small x, Γ x≃1/x, and on some machines there exists a range of nonzero but small values of x for which 1/x is larger than the greatest representable value.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
The argument is too large. On failure the method returns the approximate value of Γ x at the nearest valid argument.
ifail=2
The argument is too large and negative. On failure the method returns zero.
ifail=3
The argument is too close to zero. On failure the method returns the approximate value of Γ x at the nearest valid argument.
ifail=4
The argument is a negative integer, at which value Γ x is infinite. On failure the method returns a large positive value.
ifail=-9000
An error occured, see message report.

Accuracy

Let δ and ε be the relative errors in the argument and the result respectively. If δ is somewhat larger than the machine precision (i.e., is due to data errors etc.), then ε and δ are approximately related by:
ε≃xΨ x δ
(provided ε is also greater than the representation error). Here Ψ x is the digamma function Γ′xΓ x. Figure 1 shows the behaviour of the error amplification factor xΨ x.
If δ is of the same order as machine precision, then rounding errors could make ε slightly larger than the above relation predicts.
There is clearly a severe, but unavoidable, loss of accuracy for arguments close to the poles of Γ x at negative integers. However relative accuracy is preserved near the pole at x=0 right up to the point of failure arising from the danger of overflow.
Also accuracy will necessarily be lost as x becomes large since in this region
ε≃δx ln x.
However since Γ x increases rapidly with x, the method must fail due to the danger of overflow before this loss of accuracy is too great. (For example, for x=20, the amplification factor ≃60.)
Figure 1

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s14aae.cs

Example program data: s14aae.d

Example program results: s14aae.r

See Also

S Class
S Members


s14ab Method

[image]

NAG Library for .NET Release 2
S..::s14ab Method
S Class See Also Send Feedback
s14ab returns the value of the logarithm of the gamma function, ln Γ x.

Syntax

C#
public static double s14ab(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s14ab ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s14ab(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s14ab :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
Constraint: x>0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s14ab returns the value of the logarithm of the gamma function, ln Γ x.

Description

s14ab calculates an approximate value for ln Γ x. It is based on rational Chebyshev expansions.
Denote by R n,m i x=Pni x/Qmi x a ratio of polynomials of degree n in the numerator and m in the denominator. Then:
  • for 0<x≤1/2,
    ln Γ x≈-ln x+x R n,m 1 x+1;
  • for 1/2<x≤3/2,
    ln Γ x≈x-1 R n,m 1 x;
  • for 3/2<x≤4,
    ln Γ x≈x-2 R n,m 2 x;
  • for 4<x≤12,
    ln Γ x≈R n,m 3 x;
  • and for 12<x,
    ln Γ x≈x-12 ln x-x+ln 2π+1 x R n,m 4 1/x 2. (1)
For each expansion, the specific values of n and m are selected to be minimal such that the maximum relative error in the expansion is of the order 10-d, where d is the maximum number of decimal digits that can be accurately represented for the particular implementation (see x02be).
Let ε denote machine precision and let xhuge denote the largest positive model number (see x02al). For x<0.0 the value ln Γ x is not defined; s14ab returns zero and exits with ifail=1. It also exits with ifail=1 when x=0.0, and in this case the value xhuge is returned. For x in the interval 0.0,ε, the function ln Γ x=-ln x to machine accuracy.
Now denote by xbig the largest allowable argument for ln Γ x on the machine. For xbig 1/4<x≤xbig the R n,m 4 1/x 2 term in Equation (1) is negligible. For x>xbig there is a danger of setting overflow, and so s14ab exits with ifail=2 and returns xhuge. The value of xbig is given in the Users' Note for your implementation.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Cody W J and Hillstrom K E (1967) Chebyshev approximations for the natural logarithm of the gamma function Math.Comp. 21 198–203

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, x≤0.0. If x<0.0 the function is undefined; on failure, the function value returned is zero. If x=0.0 and failure is selected, the function value returned is the largest machine number (see x02al).
ifail=2
On entry, x>xbig (see [Description]). On failure, the function value returned is the largest machine number (see x02al).
ifail=-9000
An error occured, see message report.

Accuracy

Let δ and ε be the relative errors in the argument and result respectively, and E be the absolute error in the result.
If δ is somewhat larger than machine precision, then
E≃x×Ψ x δ  and  ε≃x×Ψ xln Γ x δ
where Ψ x is the digamma function Γ′xΓ x. Figure 1 and Figure 2 show the behaviour of these error amplification factors.
Figure 1
Figure 2
These show that relative error can be controlled, since except near x=1​ or ​2 relative error is attenuated by the function or at least is not greatly amplified.
For large x, ε≃1+1 ln x δ and for small x, ε≃1 ln x δ.
The function ln Γ x has zeros at x=1 and 2 and hence relative accuracy is not maintainable near those points. However absolute accuracy can still be provided near those zeros as is shown above.
If however, δ is of the order of machine precision, then rounding errors in the method's internal arithmetic may result in errors which are slightly larger than those predicted by the equalities. It should be noted that even in areas where strong attenuation of errors is predicted the relative precision is bounded by the effective machine precision.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s14abe.cs

Example program data: s14abe.d

Example program results: s14abe.r

See Also

S Class
S Members


s14ac Method

[image]

NAG Library for .NET Release 2
S..::s14ac Method
S Class See Also Send Feedback
s14ac returns a value of the function ψ x-ln x, where ψ is the psi function ψ x=d dx ln Γ x=Γ′xΓ x.

Syntax

C#
public static double s14ac(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s14ac ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s14ac(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s14ac :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
Constraint: x>0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s14ac returns a value of the function ψ x-ln x, where ψ is the psi function ψ x=d dx ln Γ x=Γ′xΓ x.

Description

s14ac returns a value of the function ψ x-ln x. The psi function is computed without the logarithmic term so that when x is large, sums or differences of psi functions may be computed without unnecessary loss of precision, by analytically combining the logarithmic terms. For example, the difference d=ψ x+12-ψ x has an asymptotic behaviour for large x given by d∼ln x+12-ln x+O 1 x 2∼ln 1+1 2 x∼1 2 x.
Computing d directly would amount to subtracting two large numbers which are close to ln x+12 and ln x to produce a small number close to 1 2 x, resulting in a loss of significant digits. However, using this method to compute f x=ψ x-ln x, we can compute d=f x+12-f x+ln 1+1 2 x, and the dominant logarithmic term may be computed accurately from its power series when x is large. Thus we avoid the unnecessary loss of precision.
The method is derived from the method PSIFN in Amos (1983).

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Amos D E (1983) Algorithm 610: A portable FORTRAN subroutine for derivatives of the psi function ACM Trans. Math. Software 9 494–502

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, x≤0.0. s14ac returns the value zero.
ifail=2
No result is computed because underflow is likely. The value of x is too large. s14ac returns the value zero.
ifail=3
No result is computed because overflow is likely. The value of x is too small. s14ac returns the value zero.
ifail=-9000
An error occured, see message report.

Accuracy

All constants in s14ac are given to approximately 18 digits of precision. Calling the number of digits of precision in the floating-point arithmetic being used t, then clearly the maximum number of correct digits in the results obtained is limited by p=min t,18.
With the above proviso, results returned by this method should be accurate almost to full precision, except at points close to the zero of ψ x, x≃1.461632, where only absolute rather than relative accuracy can be obtained.

Parallelism and Performance

None.

Further Comments

None.

Example

The example program reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s14ace.cs

Example program data: s14ace.d

Example program results: s14ace.r

See Also

S Class
S Members


s14ad Method

[image]

NAG Library for .NET Release 2
S..::s14ad Method
S Class See Also Send Feedback
s14ad returns a sequence of values of scaled derivatives of the psi function ψ x (also known as the digamma function).

Syntax

C#
public static void s14ad(
    double x,
    int n,
    int m,
    double[] ans,
    out int ifail
)
Visual Basic
Public Shared Sub s14ad ( _
    x As Double, _
    n As Integer, _
    m As Integer, _
    ans As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void s14ad(
    double x,
    int n,
    int m,
    array<double>^ ans,
    [OutAttribute] int% ifail
)
F#
static member s14ad :
        x : float *
        n : int *
        m : int *
        ans : float[] *
        ifail : int byref -> unit

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
Constraint: x>0.0.
n
Type: System..::..Int32
On entry: the index of the first member n of the sequence of functions.
Constraint: n≥0.
m
Type: System..::..Int32
On entry: the number of members m required in the sequence w k,x, for k=n,…,n+m-1.
Constraint: m≥1.
ans
Type: array< System..::..Double >[]()[][]
An array of size [m]
On exit: the first m elements of ans contain the required values w k,x, for k=n,…,n+m-1.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

s14ad computes m values of the function
w k,x=-1 k+1ψ k xk!,
for x>0, k=n, n+1,…,n+m-1, where ψ is the psi function
ψ x=d dx ln Γ x=Γ′xΓ x,
and ψ k denotes the kth derivative of ψ.
The method is derived from the method PSIFN in Amos (1983). The basic method of evaluation of w k,x is the asymptotic series
w k,x∼ε k,x+1 2 x k+1+1 xk∑j=1∞B 2 j 2 j+k-1!2 j!k!x 2 j
for large x greater than a machine-dependent value xmin, followed by backward recurrence using
w k,x=w k,x+1+x-k-1
for smaller values of x, where ε k,x=-ln x when k=0, ε k,x=1 k xk when k>0, and B 2 j, j=1,2,…, are the Bernoulli numbers.
When k is large, the above procedure may be inefficient, and the expansion
w k,x=∑j=1∞1 x+j k+1,
which converges rapidly for large k, is used instead.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Amos D E (1983) Algorithm 610: A portable FORTRAN subroutine for derivatives of the psi function ACM Trans. Math. Software 9 494–502

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, x≤0.0.
ifail=2
On entry, n<0.
ifail=3
On entry, m<1.
ifail=4
No results are returned because underflow is likely. Either x or n+m-1 is too large. If possible, reduce the value of m and call s14ad again.
ifail=5
No results are returned because overflow is likely. Either x is too small, or n+m-1 is too large. If possible, reduce the value of m and call s14ad again.
ifail=6
No results are returned because there is not enough internal workspace to continue computation. n+m-1 may be too large. If possible, reduce the value of m and call s14ad again.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

All constants in s14ad are given to approximately 18 digits of precision. Calling the number of digits of precision in the floating-point arithmetic being used t, then clearly the maximum number of correct digits in the results obtained is limited by p=min t,18. Empirical tests of s14ad, taking values of x in the range 0.0<x<50.0, and n in the range 1≤n≤50, have shown that the maximum relative error is a loss of approximately two decimal places of precision. Tests with n=0, i.e., testing the function -ψ x, have shown somewhat better accuracy, except at points close to the zero of ψ x, x≃1.461632, where only absolute accuracy can be obtained.

Parallelism and Performance

None.

Further Comments

The time taken for a call of s14ad is approximately proportional to m, plus a constant. In general, it is much cheaper to call s14ad with m greater than 1 to evaluate the function w k,x, for k=n,…,n+m-1, rather than to make m separate calls of s14ad.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s14ade.cs

Example program data: s14ade.d

Example program results: s14ade.r

See Also

S Class
S Members


s14ae Method

[image]

NAG Library for .NET Release 2
S..::s14ae Method
S Class See Also Send Feedback
s14ae returns the value of the kth derivative of the psi function ψ x for real x and k=0,1,…,6.

Syntax

C#
public static double s14ae(
    double x,
    int k,
    out int ifail
)
Visual Basic
Public Shared Function s14ae ( _
    x As Double, _
    k As Integer, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s14ae(
    double x,
    int k,
    [OutAttribute] int% ifail
)
F#
static member s14ae :
        x : float *
        k : int *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
Constraint: x must not be ‘too close’ (see [Error Indicators and Warnings]) to a non-positive integer.
k
Type: System..::..Int32
On entry: the function ψ k x to be evaluated.
Constraint: 0≤k≤6.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s14ae returns the value of the kth derivative of the psi function ψ x for real x and k=0,1,…,6.

Description

s14ae evaluates an approximation to the kth derivative of the psi function ψ x given by
ψ k x=dk d xk ψ x=dk d xk d dx loge Γ x,
where x is real with x≠0,-1,-2,… and k=0,1,…,6. For negative noninteger values of x, the recurrence relationship
ψ k x+1=ψ k x+dk d xk 1 x
is used. The value of -1 k+1ψ k xk! is obtained by a call to s14ad, which is based on the method PSIFN in Amos (1983).
Note that ψ k x is also known as the polygamma function. Specifically, ψ 0 x is often referred to as the digamma function and ψ 1 x as the trigamma function in the literature. Further details can be found in Abramowitz and Stegun (1972).

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Amos D E (1983) Algorithm 610: A portable FORTRAN subroutine for derivatives of the psi function ACM Trans. Math. Software 9 494–502

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | k<0,
or | k>6,
or | x is ‘too close’ to a non-positive integer. That is, abs x-nint x<machine precision×nint abs x.
ifail=2
The evaluation has been abandoned due to the likelihood of underflow. The result is returned as zero.
ifail=3
The evaluation has been abandoned due to the likelihood of overflow. The result is returned as zero.
ifail=-9000
An error occured, see message report.

Accuracy

All constants in s14ad are given to approximately 18 digits of precision. If t denotes the number of digits of precision in the floating-point arithmetic being used, then clearly the maximum number in the results obtained is limited by p=min t,18. Empirical tests by Amos (1983) have shown that the maximum relative error is a loss of approximately two decimal places of precision. Further tests with the function -ψ 0 x have shown somewhat improved accuracy, except at points near the positive zero of ψ 0 x at x=1.46…, where only absolute accuracy can be obtained.

Parallelism and Performance

None.

Further Comments

None.

Example

This example evaluates ψ 2 x at x=2.5, and prints the results.

Example program (C#): s14aee.cs

Example program data: s14aee.d

Example program results: s14aee.r

See Also

S Class
S Members


s14ba Method

[image]

NAG Library for .NET Release 2
S..::s14ba Method
S Class See Also Send Feedback
s14ba computes values for the incomplete gamma functions P a,x and Q a,x.

Syntax

C#
public static void s14ba(
    double a,
    double x,
    double tol,
    out double p,
    out double q,
    out int ifail
)
Visual Basic
Public Shared Sub s14ba ( _
    a As Double, _
    x As Double, _
    tol As Double, _
    <OutAttribute> ByRef p As Double, _
    <OutAttribute> ByRef q As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void s14ba(
    double a,
    double x,
    double tol,
    [OutAttribute] double% p,
    [OutAttribute] double% q,
    [OutAttribute] int% ifail
)
F#
static member s14ba :
        a : float *
        x : float *
        tol : float *
        p : float byref *
        q : float byref *
        ifail : int byref -> unit

Parameters

a
Type: System..::..Double
On entry: the argument a of the functions.
Constraint: a>0.0.
x
Type: System..::..Double
On entry: the argument x of the functions.
Constraint: x≥0.0.
tol
Type: System..::..Double
On entry: the relative accuracy required by you in the results. If s14ba is entered with tol greater than 1.0 or less than machine precision, then the value of machine precision is used instead.
p
Type: System..::..Double %
On exit: the values of the functions P a,x and Q a,x respectively.
q
Type: System..::..Double %
On exit: the values of the functions P a,x and Q a,x respectively.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

s14ba evaluates the incomplete gamma functions in the normalized form
P a,x=1 Γ a∫0 x t a-1e-t dt,
Q a,x=1 Γ a∫x∞t a-1e-t dt,
with x≥0 and a>0, to a user-specified accuracy. With this normalization, P a,x+Q a,x=1.
Several methods are used to evaluate the functions depending on the arguments a and x, the methods including Taylor expansion for P a,x, Legendre's continued fraction for Q a,x, and power series for Q a,x. When both a and x are large, and a≃x, the uniform asymptotic expansion of Temme (1987) is employed for greater efficiency – specifically, this expansion is used when a≥20 and 0.7 a≤x≤1.4 a.
Once either P or Q is computed, the other is obtained by subtraction from 1. In order to avoid loss of relative precision in this subtraction, the smaller of P and Q is computed first.
This method is derived from the method GAM in Gautschi (1979b).

References

Gautschi W (1979a) A computational procedure for incomplete gamma functions ACM Trans. Math. Software 5 466–481
Gautschi W (1979b) Algorithm 542: Incomplete gamma functions ACM Trans. Math. Software 5 482–489
Temme N M (1987) On the computation of the incomplete gamma functions for large values of the parameters Algorithms for Approximation (eds J C Mason and M G Cox) Oxford University Press

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, a≤0.0.
ifail=2
On entry, x<0.0.
ifail=3
Convergence of the Taylor series or Legendre continued fraction fails within 600 iterations. This error is extremely unlikely to occur; if it does, contact NAG.
ifail=-9000
An error occured, see message report.

Accuracy

There are rare occasions when the relative accuracy attained is somewhat less than that specified by parameter tol. However, the error should never exceed more than one or two decimal places. Note also that there is a limit of 18 decimal places on the achievable accuracy, because constants in the method are given to this precision.

Parallelism and Performance

None.

Further Comments

The time taken for a call of s14ba depends on the precision requested through tol, and also varies slightly with the input arguments a and x.

Example

This example reads values of the argument a and x from a file, evaluates the function and prints the results.

Example program (C#): s14bae.cs

Example program data: s14bae.d

Example program results: s14bae.r

See Also

S Class
S Members


s15ab Method

[image]

NAG Library for .NET Release 2
S..::s15ab Method
S Class See Also Send Feedback
s15ab returns the value of the cumulative Normal distribution function, P x.

Syntax

C#
public static double s15ab(
    double x
)
Visual Basic
Public Shared Function s15ab ( _
    x As Double _
) As Double
Visual C++
public:
static double s15ab(
    double x
)
F#
static member s15ab :
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.

Return Value

s15ab returns the value of the cumulative Normal distribution function, P x.

Description

s15ab evaluates an approximate value for the cumulative Normal distribution function
P x=1 2 π∫-∞x e-u 2/2 du.
The method is based on the fact that
P x=12 erfc-x 2
and it calls s15ad to obtain a value of erfc for the appropriate argument.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

None.

Accuracy

Because of its close relationship with erfc, the accuracy of this method is very similar to that in s15ad. If ε and δ are the relative errors in result and argument, respectively, they are in principle related by
ε≃x e-12 x 22 π P x δ
so that the relative error in the argument, x, is amplified by a factor, x e-12 x 22 π P x, in the result.
For x small and for x positive this factor is always less than one and accuracy is mainly limited by machine precision.
For large negative x the factor behaves like ∼x 2 and hence to a certain extent relative accuracy is unavoidably lost.
However the absolute error in the result, E, is given by
E≃x e-12 x 2 2 π δ
so absolute accuracy can be guaranteed for all x.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s15abe.cs

Example program data: s15abe.d

Example program results: s15abe.r

See Also

S Class
S Members


s15ac Method

[image]

NAG Library for .NET Release 2
S..::s15ac Method
S Class See Also Send Feedback
s15ac returns the value of the complement of the cumulative Normal distribution function, Q x.

Syntax

C#
public static double s15ac(
    double x
)
Visual Basic
Public Shared Function s15ac ( _
    x As Double _
) As Double
Visual C++
public:
static double s15ac(
    double x
)
F#
static member s15ac :
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.

Return Value

s15ac returns the value of the complement of the cumulative Normal distribution function, Q x.

Description

s15ac evaluates an approximate value for the complement of the cumulative Normal distribution function
Q x=1 2 π∫x∞e-u 2/2 du.
The method is based on the fact that
Q x=12 erfc x 2
and it calls s15ad to obtain the necessary value of erfc, the complementary error function.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

None.

Accuracy

Because of its close relationship with erfc the accuracy of this method is very similar to that in s15ad. If ε and δ are the relative errors in result and argument, respectively, then in principle they are related by
ε≃x e-x 2/22 π Q x δ.
For x negative or small positive this factor is always less than one and accuracy is mainly limited by machine precision. For large positive x we find ε∼x 2 δ and hence to a certain extent relative accuracy is unavoidably lost. However the absolute error in the result, E, is given by
E≃x e-x 2/2 2 π δ
and since this factor is always less than one absolute accuracy can be guaranteed for all x.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s15ace.cs

Example program data: s15ace.d

Example program results: s15ace.r

See Also

S Class
S Members


s15ad Method

[image]

NAG Library for .NET Release 2
S..::s15ad Method
S Class See Also Send Feedback
s15ad returns the value of the complementary error function, erfc x.

Syntax

C#
public static double s15ad(
    double x
)
Visual Basic
Public Shared Function s15ad ( _
    x As Double _
) As Double
Visual C++
public:
static double s15ad(
    double x
)
F#
static member s15ad :
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.

Return Value

s15ad returns the value of the complementary error function, erfc x.

Description

s15ad calculates an approximate value for the complement of the error function
erfc x=2 π∫x∞e-t 2 dt=1-erf x.
Let x^ be the root of the equation erfc x-erf x=0 (then x^≈0.46875). For x≤x^ the value of erfc x is based on the following rational Chebyshev expansion for erf x:
erf x≈x R ℓ,m x 2,
where R ℓ,m denotes a rational function of degree ℓ in the numerator and m in the denominator.
For x>x^ the value of erfc x is based on a rational Chebyshev expansion for erfc x: for x^<x≤4 the value is based on the expansion
erfc x≈e x 2 R ℓ,m x;
and for x>4 it is based on the expansion
erfc x≈e x 2 x 1 π+1 x 2 R ℓ,m 1/x 2.
For each expansion, the specific values of ℓ and m are selected to be minimal such that the maximum relative error in the expansion is of the order 10-d, where d is the maximum number of decimal digits that can be accurately represented for the particular implementation (see x02be).
For x≥xhi there is a danger of setting underflow in erfc x (the value of xhi is given in the Users' Note for your implementation). For x≥xhi, s15ad returns erfc x=0; for x≤-xhi it returns erfc x=2.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Cody W J (1969) Rational Chebyshev approximations for the error function Math.Comp. 23 631–637

Error Indicators and Warnings

There are no failure exits from s15ad. The parameter _ifail has been included for consistency with other methods in this chapter.

Accuracy

If δ and ε are relative errors in the argument and result, respectively, then in principle
ε≃2 x e-x 2π erfc x δ.
That is, the relative error in the argument, x, is amplified by a factor 2 x e-x 2π erfc x in the result.
The behaviour of this factor is shown in Figure 1.
Figure 1
It should be noted that near x=0 this factor behaves as 2 x π and hence the accuracy is largely determined by the machine precision. Also for large negative x, where the factor is ∼x e-x 2 π, accuracy is mainly limited by machine precision. However, for large positive x, the factor becomes ∼2 x 2 and to an extent relative accuracy is necessarily lost. The absolute accuracy E is given by
E≃2 x e-x 2 π δ
so absolute accuracy is guaranteed for all x.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s15ade.cs

Example program data: s15ade.d

Example program results: s15ade.r

See Also

S Class
S Members


s15ae Method

[image]

NAG Library for .NET Release 2
S..::s15ae Method
S Class See Also Send Feedback
s15ae returns the value of the error function erf x.

Syntax

C#
public static double s15ae(
    double x
)
Visual Basic
Public Shared Function s15ae ( _
    x As Double _
) As Double
Visual C++
public:
static double s15ae(
    double x
)
F#
static member s15ae :
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.

Return Value

s15ae returns the value of the error function erf x.

Description

s15ae calculates an approximate value for the error function
erf x=2 π∫0 x e-t 2 dt=1-erfc x.
Let x^ be the root of the equation erfc x-erf x=0 (then x^≈0.46875). For x≤x^ the value of erf x is based on the following rational Chebyshev expansion for erf x:
erf x≈x R ℓ,m x 2,
where R ℓ,m denotes a rational function of degree ℓ in the numerator and m in the denominator.
For x>x^ the value of erf x is based on a rational Chebyshev expansion for erfc x: for x^<x≤4 the value is based on the expansion
erfc x≈e x 2 R ℓ,m x;
and for x>4 it is based on the expansion
erfc x≈e x 2 x 1 π+1 x 2 R ℓ,m 1/x 2.
For each expansion, the specific values of ℓ and m are selected to be minimal such that the maximum relative error in the expansion is of the order 10-d, where d is the maximum number of decimal digits that can be accurately represented for the particular implementation (see x02be).
For x≥xhi there is a danger of setting underflow in erfc x (the value of xhi is given in the Users' Note for your implementation). For x≥xhi, s15ae returns erf x=1; for x≤-xhi it returns erf x=-1.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Cody W J (1969) Rational Chebyshev approximations for the error function Math.Comp. 23 631–637

Error Indicators and Warnings

There are no failure exits from s15ae. The parameter _ifail has been included for consistency with other methods in this chapter.

Accuracy

See [Accuracy] in s15ad.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s15aee.cs

Example program data: s15aee.d

Example program results: s15aee.r

See Also

S Class
S Members


s15af Method

[image]

NAG Library for .NET Release 2
S..::s15af Method
S Class See Also Send Feedback
s15af returns a value for Dawson's Integral, F x.

Syntax

C#
public static double s15af(
    double x
)
Visual Basic
Public Shared Function s15af ( _
    x As Double _
) As Double
Visual C++
public:
static double s15af(
    double x
)
F#
static member s15af :
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.

Return Value

s15af returns a value for Dawson's Integral, F x.

Description

s15af evaluates an approximation for Dawson's Integral
F x=e-x 2∫0 x e t 2 dt.
The method is based on two Chebyshev expansions:
For 0<x≤4,
F x=x∑r=0′arTr t,   where  t=2 x 4 2-1.
For x>4,
F x=1 x∑r=0′brTr t,   where  t=2 4 x 2-1.
For x near zero, F x≃x, and for x large, F x≃1 2 x. These approximations are used for those values of x for which the result is correct to machine precision.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

None.

Accuracy

Let δ and ε be the relative errors in the argument and result respectively.
If δ is considerably greater than the machine precision (i.e., if δ is due to data errors etc.), then ε and δ are approximately related by:
ε≃x 1-2 xF xF x δ.
The following graph shows the behaviour of the error amplification factor x 1-2 xF xF x:
Figure 1
However if δ is of the same order as machine precision, then rounding errors could make ε somewhat larger than the above relation indicates. In fact ε will be largely independent of x or δ, but will be of the order of a few times the machine precision.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s15afe.cs

Example program data: s15afe.d

Example program results: s15afe.r

See Also

S Class
S Members


s15ag Method

[image]

NAG Library for .NET Release 2
S..::s15ag Method
S Class See Also Send Feedback
s15ag returns the value of the scaled complementary error function erfcx x.

Syntax

C#
public static double s15ag(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s15ag ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s15ag(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s15ag :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s15ag returns the value of the scaled complementary error function erfcx x.

Description

s15ag calculates an approximate value for the scaled complementary error function
erfcx x=e x 2 erfc x=2 π e x 2∫x∞e-t 2 dt=e x 2 1-erf x.
Let x^ be the root of the equation erfc x-erf x=0 (then x^≈0.46875). For x≤x^ the value of erfcx x is based on the following rational Chebyshev expansion for erf x:
erf x≈x R ℓ,m x 2,
where R ℓ,m denotes a rational function of degree ℓ in the numerator and m in the denominator.
For x>x^ the value of erfcx x is based on a rational Chebyshev expansion for erfc x: for x^<x≤4 the value is based on the expansion
erfc x≈e x 2 R ℓ,m x;
and for x>4 it is based on the expansion
erfc x≈e x 2 x 1 π+1 x 2 R ℓ,m 1/x 2.
For each expansion, the specific values of ℓ and m are selected to be minimal such that the maximum relative error in the expansion is of the order 10-d, where d is the maximum number of decimal digits that can be accurately represented for the particular implementation (see x02be).
Asymptotically, erfcx x∼1/π x. There is a danger of setting underflow in erfcx x whenever x≥xhi=min xhuge,1/π xtiny, where xhuge is the largest positive model number (see x02al) and xtiny is the smallest positive model number (see x02ak). In this case s15ag exits with ifail=1 and returns erfcx x=0. For x in the range 1/2 ε≤x<xhi, where ε is the machine precision, the asymptotic value 1/π x is returned for erfcx x and s15ag exits with ifail=2.
There is a danger of setting overflow in e x 2 whenever x<xneg=-log xhuge/2. In this case s15ag exits with ifail=3 and returns erfcx x=xhuge.
The values of xhi, 1/2 ε and xneg are given in the Users' Note for your implementation.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Cody W J (1969) Rational Chebyshev approximations for the error function Math.Comp. 23 631–637

Error Indicators and Warnings

Note: s15ag may return useful information for one or more of the following detected errors or warnings.
Errors or warnings detected by the method:
ifail=1
On entry, x≥xhi (see [Description]). On failure the function value returned is 0.
ifail=2
On entry, 1/2 ε≤x<xhi (see [Description]). On failure the function value returned is 1/π abs x.
ifail=3
On entry, x<xneg (see [Description]). On failure the function value returned is the largest positive model number.
ifail=-9000
An error occured, see message report.

Accuracy

The relative error in computing erfcx x may be estimated by evaluating
E=erfcx x-e x 2∑n=1∞In erfc xerfcx x,
where In denotes repeated integration. Empirical results suggest that on the interval x^,2 the loss in base b significant digits for maximum relative error is around 3.3, while for root-mean-square relative error on that interval it is 1.2 (see x02bh for the definition of the model parameter b). On the interval 2,20 the values are around 3.5 for maximum and 0.45 for root-mean-square relative errors; note that on these two intervals erfc x is the primary computation. See also [Accuracy] in s15ad.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s15age.cs

Example program data: s15age.d

Example program results: s15age.r

See Also

S Class
S Members


s17ac Method

[image]

NAG Library for .NET Release 2
S..::s17ac Method
S Class See Also Send Feedback
s17ac returns the value of the Bessel function Y 0 x.

Syntax

C#
public static double s17ac(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s17ac ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s17ac(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s17ac :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
Constraint: x>0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s17ac returns the value of the Bessel function Y 0 x.

Description

s17ac evaluates an approximation to the Bessel function of the second kind Y 0 x.
Note: Y 0 x is undefined for x≤0 and the method will fail for such arguments.
The method is based on four Chebyshev expansions:
For 0<x≤8,
Y 0 x=2 π ln x∑r=0′arTr t+∑r=0′brTr t,   with ​t=2 x 8 2-1.
For x>8,
Y 0 x=2 πx P 0 x sin x-π 4+Q 0 x cos x-π 4
where P 0 x=∑′r=0 crTr t,
and Q 0 x=8 x∑′r=0 drTr t,with ​t=2 8 x 2-1.
For x near zero, Y 0 x≃2 π ln x 2+γ, where γ denotes Euler's constant. This approximation is used when x is sufficiently small for the result to be correct to machine precision.
For very large x, it becomes impossible to provide results with any reasonable accuracy (see [Accuracy]), hence the method fails. Such arguments contain insufficient information to determine the phase of oscillation of Y 0 x; only the amplitude, 2 πn, can be determined and this is returned on failure. The range for which this occurs is roughly related to machine precision; the method will fail if x≳1/machine precision (see the Users' Note for your implementation for details).

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Clenshaw C W (1962) Chebyshev Series for Mathematical Functions Mathematical tables HMSO

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
x is too large. On failure the method returns the amplitude of the Y 0 oscillation, 2/πx.
ifail=2
x≤0.0, Y 0 is undefined. On failure the method returns zero.
ifail=-9000
An error occured, see message report.

Accuracy

Let δ be the relative error in the argument and E be the absolute error in the result. (Since Y 0 x oscillates about zero, absolute error and not relative error is significant, except for very small x.)
If δ is somewhat larger than the machine representation error (e.g., if δ is due to data errors etc.), then E and δ are approximately related by
E≃x Y 1 x δ
(provided E is also within machine bounds). Figure 1 displays the behaviour of the amplification factor x Y 1 x.
However, if δ is of the same order as the machine representation errors, then rounding errors could make E slightly larger than the above relation predicts.
For very small x, the errors are essentially independent of δ and the method should provide relative accuracy bounded by the machine precision.
For very large x, the above relation ceases to apply. In this region, Y 0 x≃2 πx sin x-π 4. The amplitude 2 πx can be calculated with reasonable accuracy for all x, but sin x-π 4 cannot. If x-π 4 is written as 2 Nπ+θ where N is an integer and 0≤θ<2 π, then sin x-π 4 is determined by θ only. If x≳δ-1, θ cannot be determined with any accuracy at all. Thus if x is greater than, or of the order of the inverse of machine precision, it is impossible to calculate the phase of Y 0 x and the method must fail.
Figure 1

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s17ace.cs

Example program data: s17ace.d

Example program results: s17ace.r

See Also

S Class
S Members


s17ad Method

[image]

NAG Library for .NET Release 2
S..::s17ad Method
S Class See Also Send Feedback
s17ad returns the value of the Bessel function Y 1 x.

Syntax

C#
public static double s17ad(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s17ad ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s17ad(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s17ad :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
Constraint: x>0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s17ad returns the value of the Bessel function Y 1 x.

Description

s17ad evaluates an approximation to the Bessel function of the second kind Y 1 x.
Note: Y 1 x is undefined for x≤0 and the method will fail for such arguments.
The method is based on four Chebyshev expansions:
For 0<x≤8,
Y 1 x=2 π ln x x 8∑′r=0 arTr t-2 πx+x 8∑′r=0 brTr t,   with ​t=2 x 8 2-1.
For x>8,
Y 1 x=2 πx P 1 x sin x-3 π 4+Q 1 x cos x-3 π 4
where P 1 x=∑′r=0 crTr t,
and Q 1 x=8 x∑′r=0 drTr t, with t=2 8 x 2-1.
For x near zero, Y 1 x≃-2 πx. This approximation is used when x is sufficiently small for the result to be correct to machine precision. For extremely small x, there is a danger of overflow in calculating -2 πx and for such arguments the method will fail.
For very large x, it becomes impossible to provide results with any reasonable accuracy (see [Accuracy]), hence the method fails. Such arguments contain insufficient information to determine the phase of oscillation of Y 1 x; only the amplitude, 2 πx, can be determined and this is returned on failure. The range for which this occurs is roughly related to machine precision; the method will fail if x≳1/machine precision (see the Users' Note for your implementation for details).

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Clenshaw C W (1962) Chebyshev Series for Mathematical Functions Mathematical tables HMSO

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
x is too large. On failure the method returns the amplitude of the Y 1 oscillation, 2 πx.
ifail=2
x≤0.0, Y 1 is undefined. On failure the method returns zero.
ifail=3
x is too close to zero, there is a danger of overflow. On failure, the method returns the value of Y 1 x at the smallest valid argument.
ifail=-9000
An error occured, see message report.

Accuracy

Let δ be the relative error in the argument and E be the absolute error in the result. (Since Y 1 x oscillates about zero, absolute error and not relative error is significant, except for very small x.)
If δ is somewhat larger than the machine precision (e.g., if δ is due to data errors etc.), then E and δ are approximately related by:
E≃x Y 0 x-Y 1 x δ
(provided E is also within machine bounds). Figure 1 displays the behaviour of the amplification factor x Y 0 x-Y 1 x.
However, if δ is of the same order as machine precision, then rounding errors could make E slightly larger than the above relation predicts.
For very small x, absolute error becomes large, but the relative error in the result is of the same order as δ.
For very large x, the above relation ceases to apply. In this region, Y 1 x≃2 πx sin x-3 π 4. The amplitude 2 πx can be calculated with reasonable accuracy for all x, but sin x-3 π 4 cannot. If x-3 π 4 is written as 2 Nπ+θ where N is an integer and 0≤θ<2 π, then sin x-3 π 4 is determined by θ only. If x>δ-1, θ cannot be determined with any accuracy at all. Thus if x is greater than, or of the order of, the inverse of the machine precision, it is impossible to calculate the phase of Y 1 x and the method must fail.
Figure 1

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s17ade.cs

Example program data: s17ade.d

Example program results: s17ade.r

See Also

S Class
S Members


s17ae Method

[image]

NAG Library for .NET Release 2
S..::s17ae Method
S Class See Also Send Feedback
s17ae returns the value of the Bessel function J 0 x.

Syntax

C#
public static double s17ae(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s17ae ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s17ae(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s17ae :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s17ae returns the value of the Bessel function J 0 x.

Description

s17ae evaluates an approximation to the Bessel function of the first kind J 0 x.
Note: J 0-x=J 0 x, so the approximation need only consider x≥0.
The method is based on three Chebyshev expansions:
For 0<x≤8,
J 0 x=∑′r=0 arTr t,   with ​t=2 x 8 2-1.
For x>8,
J 0 x=2 πx P 0 x cos x-π 4-Q 0 x sin x-π 4,
where P 0 x=∑′r=0 brTr t,
and Q 0 x=8 x∑′r=0 crTr t,
with t=2 8 x 2-1.
For x near zero, J 0 x≃1. This approximation is used when x is sufficiently small for the result to be correct to machine precision.
For very large x, it becomes impossible to provide results with any reasonable accuracy (see [Accuracy]), hence the method fails. Such arguments contain insufficient information to determine the phase of oscillation of J 0 x; only the amplitude, 2 π x, can be determined and this is returned on failure. The range for which this occurs is roughly related to machine precision; the method will fail if x≳1/machine precision (see the Users' Note for your implementation for details).

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Clenshaw C W (1962) Chebyshev Series for Mathematical Functions Mathematical tables HMSO

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
x is too large. On failure the method returns the amplitude of the J 0 oscillation, 2 π x.
ifail=-9000
An error occured, see message report.

Accuracy

Let δ be the relative error in the argument and E be the absolute error in the result. (Since J 0 x oscillates about zero, absolute error and not relative error is significant.)
If δ is somewhat larger than the machine precision (e.g., if δ is due to data errors etc.), then E and δ are approximately related by:
E≃x J 1 x δ
(provided E is also within machine bounds). Figure 1 displays the behaviour of the amplification factor x J 1 x.
However, if δ is of the same order as machine precision, then rounding errors could make E slightly larger than the above relation predicts.
For very large x, the above relation ceases to apply. In this region, J 0 x≃2 π x cos x-π 4. The amplitude 2 π x can be calculated with reasonable accuracy for all x, but cos x-π 4 cannot. If x-π 4 is written as 2 Nπ+θ where N is an integer and 0≤θ<2 π, then cos x-π 4 is determined by θ only. If x≳δ-1, θ cannot be determined with any accuracy at all. Thus if x is greater than, or of the order of, the inverse of the machine precision, it is impossible to calculate the phase of J 0 x and the method must fail.
Figure 1

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s17aee.cs

Example program data: s17aee.d

Example program results: s17aee.r

See Also

S Class
S Members


s17af Method

[image]

NAG Library for .NET Release 2
S..::s17af Method
S Class See Also Send Feedback
s17af returns the value of the Bessel function J 1 x.

Syntax

C#
public static double s17af(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s17af ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s17af(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s17af :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s17af returns the value of the Bessel function J 1 x.

Description

s17af evaluates an approximation to the Bessel function of the first kind J 1 x.
Note: J 1-x=-J 1 x, so the approximation need only consider x≥0.
The method is based on three Chebyshev expansions:
For 0<x≤8,
J 1 x=x 8∑′r=0 arTr t,   with ​t=2 x 8 2-1.
For x>8,
J 1 x=2 πx P 1 x cos x-3 π 4-Q 1 x sin x-3 π 4
where P 1 x=∑′r=0 brTr t,
and Q 1 x=8 x∑′r=0 crTr t,
with t=2 8 x 2-1.
For x near zero, J 1 x≃x 2. This approximation is used when x is sufficiently small for the result to be correct to machine precision.
For very large x, it becomes impossible to provide results with any reasonable accuracy (see [Accuracy]), hence the method fails. Such arguments contain insufficient information to determine the phase of oscillation of J 1 x; only the amplitude, 2 π x, can be determined and this is returned on failure. The range for which this occurs is roughly related to machine precision; the method will fail if x≳1/machine precision (see the Users' Note for your implementation for details).

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Clenshaw C W (1962) Chebyshev Series for Mathematical Functions Mathematical tables HMSO

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
x is too large. On failure the method returns the amplitude of the J 1 oscillation, 2 π x.
ifail=-9000
An error occured, see message report.

Accuracy

Let δ be the relative error in the argument and E be the absolute error in the result. (Since J 1 x oscillates about zero, absolute error and not relative error is significant.)
If δ is somewhat larger than machine precision (e.g., if δ is due to data errors etc.), then E and δ are approximately related by:
E≃x J 0 x-J 1 x δ
(provided E is also within machine bounds). Figure 1 displays the behaviour of the amplification factor x J 0 x-J 1 x.
However, if δ is of the same order as machine precision, then rounding errors could make E slightly larger than the above relation predicts.
For very large x, the above relation ceases to apply. In this region, J 1 x≃2 π x cos x-3 π 4. The amplitude 2 π x can be calculated with reasonable accuracy for all x, but cos x-3 π 4 cannot. If x-3 π 4 is written as 2 Nπ+θ where N is an integer and 0≤θ<2 π, then cos x-3 π 4 is determined by θ only. If x≳δ-1, θ cannot be determined with any accuracy at all. Thus if x is greater than, or of the order of, the reciprocal of machine precision, it is impossible to calculate the phase of J 1 x and the method must fail.
Figure 1

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s17afe.cs

Example program data: s17afe.d

Example program results: s17afe.r

See Also

S Class
S Members


s17ag Method

[image]

NAG Library for .NET Release 2
S..::s17ag Method
S Class See Also Send Feedback
s17ag returns a value for the Airy function, Ai x.

Syntax

C#
public static double s17ag(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s17ag ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s17ag(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s17ag :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s17ag returns a value for the Airy function, Ai x.

Description

s17ag evaluates an approximation to the Airy function, Ai x. It is based on a number of Chebyshev expansions:
For x<-5,
Ai x=a t sin z-b t cos z-x 1/4
where z=π 4+23-x 3, and a t and b t are expansions in the variable t=-2 5 x 3-1.
For -5≤x≤0,
Ai x=f t-xg t,
where f and g are expansions in t=-2 x 5 3-1.
For 0<x<4.5,
Ai x=e-3 x/2 y t,
where y is an expansion in t=4 x/9-1.
For 4.5≤x<9,
Ai x=e-5 x/2 u t,
where u is an expansion in t=4 x/9-3.
For x≥9,
Ai x=e-z v t x 1/4,
where z=23 x 3 and v is an expansion in t=2 18 z-1.
For x<machine precision, the result is set directly to Ai 0. This both saves time and guards against underflow in intermediate calculations.
For large negative arguments, it becomes impossible to calculate the phase of the oscillatory function with any precision and so the method must fail. This occurs if x<-3 2 ε 2/3, where ε is the machine precision.
For large positive arguments, where Ai decays in an essentially exponential manner, there is a danger of underflow so the method must fail.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
x is too large and positive. On failure, the method returns zero. See also the Users' Note for your implementation.
ifail=2
x is too large and negative. On failure, the method returns zero. See also the Users' Note for your implementation.
ifail=-9000
An error occured, see message report.

Accuracy

For negative arguments the function is oscillatory and hence absolute error is the appropriate measure. In the positive region the function is essentially exponential-like and here relative error is appropriate. The absolute error, E, and the relative error, ε, are related in principle to the relative error in the argument, δ, by
E≃x Ai′x δ,ε≃x Ai′xAi x δ.
In practice, approximate equality is the best that can be expected. When δ, ε or E is of the order of the machine precision, the errors in the result will be somewhat larger.
For small x, errors are strongly damped by the function and hence will be bounded by the machine precision.
For moderate negative x, the error behaviour is oscillatory but the amplitude of the error grows like
amplitude Eδ∼x 5/4 π.
However the phase error will be growing roughly like 23 x 3 and hence all accuracy will be lost for large negative arguments due to the impossibility of calculating sin and cos to any accuracy if 23 x 3>1 δ.
For large positive arguments, the relative error amplification is considerable:
εδ∼x 3.
This means a loss of roughly two decimal places accuracy for arguments in the region of 20. However very large arguments are not possible due to the danger of setting underflow and so the errors are limited in practice.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s17age.cs

Example program data: s17age.d

Example program results: s17age.r

See Also

S Class
S Members


s17ah Method

[image]

NAG Library for .NET Release 2
S..::s17ah Method
S Class See Also Send Feedback
s17ah returns a value of the Airy function, Bi x.

Syntax

C#
public static double s17ah(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s17ah ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s17ah(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s17ah :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s17ah returns a value of the Airy function, Bi x.

Description

s17ah evaluates an approximation to the Airy function Bi x. It is based on a number of Chebyshev expansions.
For x<-5,
Bi x=a t cos z+b t sin z-x 1/4,
where z=π 4+23-x 3 and a t and b t are expansions in the variable t=-2 5 x 3-1.
For -5≤x≤0,
Bi x=3 f t+xg t,
where f and g are expansions in t=-2 x 5 3-1.
For 0<x<4.5,
Bi x=e 11 x/8 y t,
where y is an expansion in t=4 x/9-1.
For 4.5≤x<9,
Bi x=e 5 x/2 v t,
where v is an expansion in t=4 x/9-3.
For x≥9,
Bi x=ez u t x 1/4,
where z=23 x 3 and u is an expansion in t=2 18 z-1.
For x<machine precision, the result is set directly to Bi 0. This both saves time and avoids possible intermediate underflows.
For large negative arguments, it becomes impossible to calculate the phase of the oscillating function with any accuracy so the method must fail. This occurs if x<-3 2 ε 2/3, where ε is the machine precision.
For large positive arguments, there is a danger of causing overflow since Bi grows in an essentially exponential manner, so the method must fail.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
x is too large and positive. On failure, the method returns zero. (see the Users' Note for your implementation for details)
ifail=2
x is too large and negative. On failure, the method returns zero. See also the Users' Note for your implementation.
ifail=-9000
An error occured, see message report.

Accuracy

For negative arguments the function is oscillatory and hence absolute error is the appropriate measure. In the positive region the function is essentially exponential-like and here relative error is appropriate. The absolute error, E, and the relative error, ε, are related in principle to the relative error in the argument, δ, by
E≃x Bi′x δ,ε≃x Bi′xBi x δ.
In practice, approximate equality is the best that can be expected. When δ, ε or E is of the order of the machine precision, the errors in the result will be somewhat larger.
For small x, errors are strongly damped and hence will be bounded essentially by the machine precision.
For moderate to large negative x, the error behaviour is clearly oscillatory but the amplitude of the error grows like amplitude Eδ∼x 5/4 π.
However the phase error will be growing roughly as 23 x 3 and hence all accuracy will be lost for large negative arguments. This is due to the impossibility of calculating sin and cos to any accuracy if 23 x 3>1 δ.
For large positive arguments, the relative error amplification is considerable:
εδ∼x 3.
This means a loss of roughly two decimal places accuracy for arguments in the region of 20. However very large arguments are not possible due to the danger of causing overflow and errors are therefore limited in practice.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s17ahe.cs

Example program data: s17ahe.d

Example program results: s17ahe.r

See Also

S Class
S Members


s17aj Method

[image]

NAG Library for .NET Release 2
S..::s17aj Method
S Class See Also Send Feedback
s17aj returns a value of the derivative of the Airy function Ai x.

Syntax

C#
public static double s17aj(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s17aj ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s17aj(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s17aj :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s17aj returns a value of the derivative of the Airy function Ai x.

Description

s17aj evaluates an approximation to the derivative of the Airy function Ai x. It is based on a number of Chebyshev expansions.
For x<-5,
Ai′x=-x 4 a t cos z+b t ζ sin z,
where z=π 4+ζ, ζ=23-x 3 and a t and b t are expansions in variable t=-2 5 x 3-1.
For -5≤x≤0,
Ai′x=x 2 f t-g t,
where f and g are expansions in t=-2 x 5 3-1.
For 0<x<4.5,
Ai′x=e-11 x/8 y t,
where y t is an expansion in t=4 x 9-1.
For 4.5≤x<9,
Ai′x=e-5 x/2 v t,
where v t is an expansion in t=4 x 9-3.
For x≥9,
Ai′x=x 4 e-z u t,
where z=23 x 3 and u t is an expansion in t=2 18 z-1.
For x< the square of the machine precision, the result is set directly to Ai′0. This both saves time and avoids possible intermediate underflows.
For large negative arguments, it becomes impossible to calculate a result for the oscillating function with any accuracy and so the method must fail. This occurs for x<-π ε 4/7, where ε is the machine precision.
For large positive arguments, where Ai′ decays in an essentially exponential manner, there is a danger of underflow so the method must fail.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
x is too large and positive. On failure, the method returns zero. (see the Users' Note for your implementation for details)
ifail=2
x is too large and negative. On failure, the method returns zero. See also the Users' Note for your implementation.
ifail=-9000
An error occured, see message report.

Accuracy

For negative arguments the function is oscillatory and hence absolute error is the appropriate measure. In the positive region the function is essentially exponential in character and here relative error is needed. The absolute error, E, and the relative error, ε, are related in principle to the relative error in the argument, δ, by
E≃x 2 Ai x δ ε≃x 2 Ai xAi′x δ.
In practice, approximate equality is the best that can be expected. When δ, ε or E is of the order of the machine precision, the errors in the result will be somewhat larger.
For small x, positive or negative, errors are strongly attenuated by the function and hence will be roughly bounded by the machine precision.
For moderate to large negative x, the error, like the function, is oscillatory; however the amplitude of the error grows like
x 7/4 π.
Therefore it becomes impossible to calculate the function with any accuracy if x 7/4>π δ.
For large positive x, the relative error amplification is considerable:
εδ≃x 3.
However, very large arguments are not possible due to the danger of underflow. Thus in practice error amplification is limited.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s17aje.cs

Example program data: s17aje.d

Example program results: s17aje.r

See Also

S Class
S Members


s17ak Method

[image]

NAG Library for .NET Release 2
S..::s17ak Method
S Class See Also Send Feedback
s17ak returns a value for the derivative of the Airy function Bi x.

Syntax

C#
public static double s17ak(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s17ak ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s17ak(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s17ak :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s17ak returns a value for the derivative of the Airy function Bi x.

Description

s17ak calculates an approximate value for the derivative of the Airy function Bi x. It is based on a number of Chebyshev expansions.
For x<-5,
Bi′x=-x 4-a t sin z+b t ζ cos z,
where z=π 4+ζ, ζ=23-x 3 and a t and b t are expansions in the variable t=-2 5 x 3-1.
For -5≤x≤0,
Bi′x=3 x 2 f t+g t,
where f and g are expansions in t=-2 x 5 3-1.
For 0<x<4.5,
Bi′x=e 3 x/2 y t,
where y t is an expansion in t=4 x/9-1.
For 4.5≤x<9,
Bi′x=e 21 x/8 u t,
where u t is an expansion in t=4 x/9-3.
For x≥9,
Bi′x=x 4 ez v t,
where z=23 x 3 and v t is an expansion in t=2 18 z-1.
For x< the square of the machine precision, the result is set directly to Bi′0. This saves time and avoids possible underflows in calculation.
For large negative arguments, it becomes impossible to calculate a result for the oscillating function with any accuracy so the method must fail. This occurs for x<-π ε 4/7, where ε is the machine precision.
For large positive arguments, where Bi′ grows in an essentially exponential manner, there is a danger of overflow so the method must fail.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
x is too large and positive. On failure, the method returns zero. (see the Users' Note for your implementation for details)
ifail=2
x is too large and negative. On failure the method returns zero. (see the Users' Note for your implementation for details)
ifail=-9000
An error occured, see message report.

Accuracy

For negative arguments the function is oscillatory and hence absolute error is appropriate. In the positive region the function has essentially exponential behaviour and hence relative error is needed. The absolute error, E, and the relative error ε, are related in principle to the relative error in the argument δ, by
E≃x 2 Bi x δ ε≃x 2 Bi xBi′x δ.
In practice, approximate equality is the best that can be expected. When δ, ε or E is of the order of the machine precision, the errors in the result will be somewhat larger.
For small x, positive or negative, errors are strongly attenuated by the function and hence will effectively be bounded by the machine precision.
For moderate to large negative x, the error is, like the function, oscillatory. However, the amplitude of the absolute error grows like x 7/4 π. Therefore it becomes impossible to calculate the function with any accuracy if x 7/4>π δ.
For large positive x, the relative error amplification is considerable: εδ∼x 3. However, very large arguments are not possible due to the danger of overflow. Thus in practice the actual amplification that occurs is limited.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s17ake.cs

Example program data: s17ake.d

Example program results: s17ake.r

See Also

S Class
S Members


s17al Method

[image]

NAG Library for .NET Release 2
S..::s17al Method
S Class See Also Send Feedback
s17al determines the leading n zeros of one of the Bessel functions Jα x, Yα x, Jα′x or Yα′x for real x and non-negative α.

Syntax

C#
public static void s17al(
    double a,
    int n,
    int mode,
    double rel,
    double[] x,
    out int ifail
)
Visual Basic
Public Shared Sub s17al ( _
    a As Double, _
    n As Integer, _
    mode As Integer, _
    rel As Double, _
    x As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void s17al(
    double a,
    int n,
    int mode,
    double rel,
    array<double>^ x,
    [OutAttribute] int% ifail
)
F#
static member s17al :
        a : float *
        n : int *
        mode : int *
        rel : float *
        x : float[] *
        ifail : int byref -> unit

Parameters

a
Type: System..::..Double
On entry: the order α of the function.
Constraint: 0.0≤a≤100000.0.
n
Type: System..::..Int32
On entry: the number N of zeros required.
Constraint: n≥1.
mode
Type: System..::..Int32
On entry: specifies the form of the function whose zeros are required.
mode=1
The zeros of Jα x are required.
mode=2
The zeros of Yα x are required;
mode=3
The zeros of Jα′x are required;
mode=4
The zeros of Yα′x are required.
Constraint: 1≤mode≤4.
rel
Type: System..::..Double
On entry: the relative accuracy to which the zeros are required.
Suggested value: the square root of the machine precision.
Constraint: rel>0.0.
x
Type: array< System..::..Double >[]()[][]
An array of size [n]
On exit: the N required zeros of the function specified by mode.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

s17al attempts to find the leading N zeros of one of the Bessel functions Jα x, Yα x, Jα′x or Yα′x, where x is real. When α is real, these functions each have an infinite number of real zeros, all of which are simple with the possible exception of x=0. If α≥0, the nth positive zero is denoted by j α,n,j α,n′,y α,n and y α,n′, respectively, for n=1,2,…,N, except that x=0 is counted as the first zero of Jα′x when α=0. Since J 0′x=-J 1 x, it therefore follows that j 0,1′=0 and j 0,n′=-j 1,n-1 for n=2,3,…,N-1. Further details can be found in Section 9.5 of Abramowitz and Stegun (1972).
s17al is based on Algol 60 procedures given by Temme (1979). Initial approximations to the zeros are computed from asymptotic expansions. These are then improved by higher-order Newton iteration making use of the differential equation for the Bessel functions.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Temme N M (1976) On the numerical evaluation of the ordinary Bessel function of the second kind J. Comput. Phys. 21 343–350
Temme N M (1979) An algorithm with Algol 60 program for the computation of the zeros of ordinary Bessel functions and those of their derivatives J. Comput. Phys. 32 270–279

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | a<0.0,
or | a>100000.0,
or | n≤0,
or | mode<1,
or | mode>4,
or | rel≤0.0.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

If the value of rel is set to 10-d, then the required zeros should have approximately d correct significant digits.

Parallelism and Performance

None.

Further Comments

None.

Example

This example determines the leading five positive zeros of the Bessel function J 0 x.

Example program (C#): s17ale.cs

Example program data: s17ale.d

Example program results: s17ale.r

See Also

S Class
S Members


s17dg Method

[image]

NAG Library for .NET Release 2
S..::s17dg Method
S Class See Also Send Feedback
s17dg returns the value of the Airy function Ai z or its derivative Ai′z for complex z, with an option for exponential scaling.

Syntax

C#
public static void s17dg(
    string deriv,
    Complex z,
    string scal,
    out Complex ai,
    out int nz,
    out int ifail
)
Visual Basic
Public Shared Sub s17dg ( _
    deriv As String, _
    z As Complex, _
    scal As String, _
    <OutAttribute> ByRef ai As Complex, _
    <OutAttribute> ByRef nz As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void s17dg(
    String^ deriv,
    Complex z,
    String^ scal,
    [OutAttribute] Complex% ai,
    [OutAttribute] int% nz,
    [OutAttribute] int% ifail
)
F#
static member s17dg :
        deriv : string *
        z : Complex *
        scal : string *
        ai : Complex byref *
        nz : int byref *
        ifail : int byref -> unit

Parameters

deriv
Type: System..::..String
On entry: specifies whether the function or its derivative is required.
deriv="F"
Ai z is returned.
deriv="D"
Ai′z is returned.
Constraint: deriv="F" or "D".
z
Type: NagLibrary..::..Complex
On entry: the argument z of the function.
scal
Type: System..::..String
On entry: the scaling option.
scal="U"
The result is returned unscaled.
scal="S"
The result is returned scaled by the factor e 2 z⁢z/3.
Constraint: scal="U" or "S".
ai
Type: NagLibrary..::..Complex %
On exit: the required function or derivative value.
nz
Type: System..::..Int32 %
On exit: indicates whether or not ai is set to zero due to underflow. This can only occur when scal="U".
nz=0
ai is not set to zero.
nz=1
ai is set to zero.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

s17dg returns a value for the Airy function Ai z or its derivative Ai′z, where z is complex, -π<argz≤π. Optionally, the value is scaled by the factor e 2 z⁢z/3.
The method is derived from the method CAIRY in Amos (1986). It is based on the relations Ai z=z K 1/3 wπ⁢3, and Ai′z=-z K 2/3 wπ⁢3, where Kν is the modified Bessel function and w=2 z⁢z/3.
For very large z, argument reduction will cause total loss of accuracy, and so no computation is performed. For slightly smaller z, the computation is performed but results are accurate to less than half of machine precision. If Re w is too large, and the unscaled function is required, there is a risk of overflow and so no computation is performed. In all the above cases, a warning is given by the method.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Amos D E (1986) Algorithm 644: A portable package for Bessel functions of a complex argument and non-negative order ACM Trans. Math. Software 12 265–273

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | deriv≠"F" or "D".
or | scal≠"U" or "S".
ifail=2
No computation has been performed due to the likelihood of overflow, because Re w is too large, where w=2⁢z z/3 – how large depends on z and the overflow threshold of the machine. This error exit can only occur when scal="U".
ifail=3
The computation has been performed, but the errors due to argument reduction in elementary functions make it likely that the result returned by s17dg is accurate to less than half of machine precision. This error exit may occur if abs z is greater than a machine-dependent threshold value (given in the Users' Note for your implementation).
ifail=4
No computation has been performed because the errors due to argument reduction in elementary functions mean that all precision in the result returned by s17dg would be lost. This error exit may occur if abs z is greater than a machine-dependent threshold value (given in the Users' Note for your implementation).
ifail=5
No result is returned because the algorithm termination condition has not been met. This may occur because the parameters supplied to s17dg would have caused overflow or underflow.
ifail=-9000
An error occured, see message report.

Accuracy

All constants in s17dg are given to approximately 18 digits of precision. Calling the number of digits of precision in the floating-point arithmetic being used t, then clearly the maximum number of correct digits in the results obtained is limited by p=min t,18. Because of errors in argument reduction when computing elementary functions inside s17dg, the actual number of correct digits is limited, in general, by p-s, where s≈max 1,log 10 z represents the number of digits lost due to the argument reduction. Thus the larger the value of z, the less the precision in the result.
Empirical tests with modest values of z, checking relations between Airy functions Ai z, Ai′z, Bi z and Bi′z, have shown errors limited to the least significant 3 – 4 digits of precision.

Parallelism and Performance

None.

Further Comments

Note that if the function is required to operate on a real argument only, then it may be much cheaper to call s17ag or s17aj.

Example

This example prints a caption and then proceeds to read sets of data from the input data stream. The first datum is a value for the parameter deriv, the second is a complex value for the argument, z, and the third is a character value to set the parameter scal. The program calls the method and prints the results. The process is repeated until the end of the input data stream is encountered.

Example program (C#): s17dge.cs

Example program data: s17dge.d

Example program results: s17dge.r

See Also

S Class
S Members


s17dh Method

[image]

NAG Library for .NET Release 2
S..::s17dh Method
S Class See Also Send Feedback
s17dh returns the value of the Airy function Bi z or its derivative Bi′z for complex z, with an option for exponential scaling.

Syntax

C#
public static void s17dh(
    string deriv,
    Complex z,
    string scal,
    out Complex bi,
    out int ifail
)
Visual Basic
Public Shared Sub s17dh ( _
    deriv As String, _
    z As Complex, _
    scal As String, _
    <OutAttribute> ByRef bi As Complex, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void s17dh(
    String^ deriv,
    Complex z,
    String^ scal,
    [OutAttribute] Complex% bi,
    [OutAttribute] int% ifail
)
F#
static member s17dh :
        deriv : string *
        z : Complex *
        scal : string *
        bi : Complex byref *
        ifail : int byref -> unit

Parameters

deriv
Type: System..::..String
On entry: specifies whether the function or its derivative is required.
deriv="F"
Bi z is returned.
deriv="D"
Bi′z is returned.
Constraint: deriv="F" or "D".
z
Type: NagLibrary..::..Complex
On entry: the argument z of the function.
scal
Type: System..::..String
On entry: the scaling option.
scal="U"
The result is returned unscaled.
scal="S"
The result is returned scaled by the factor e Re 2 z⁢z/3.
Constraint: scal="U" or "S".
bi
Type: NagLibrary..::..Complex %
On exit: the required function or derivative value.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

s17dh returns a value for the Airy function Bi z or its derivative Bi′z, where z is complex, -π<argz≤π. Optionally, the value is scaled by the factor e Re 2 z⁢z/3.
The method is derived from the method CBIRY in Amos (1986). It is based on the relations Bi z=z 3 I-1/3 w+I 1/3 w, and Bi′z=z 3 I-2/3 w+I 2/3 w, where Iν is the modified Bessel function and w=2 z⁢z/3.
For very large z, argument reduction will cause total loss of accuracy, and so no computation is performed. For slightly smaller z, the computation is performed but results are accurate to less than half of machine precision. If Re z is too large, and the unscaled function is required, there is a risk of overflow and so no computation is performed. In all the above cases, a warning is given by the method.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Amos D E (1986) Algorithm 644: A portable package for Bessel functions of a complex argument and non-negative order ACM Trans. Math. Software 12 265–273

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | deriv≠"F" or "D".
or | scal≠"U" or "S".
ifail=2
No computation has been performed due to the likelihood of overflow, because real(z) is too large – how large depends on the overflow threshold of the machine. This error exit can only occur when scal="U".
ifail=3
The computation has been performed, but the errors due to argument reduction in elementary functions make it likely that the result returned by s17dh is accurate to less than half of machine precision. This error exit may occur if abs z is greater than a machine-dependent threshold value (given in the Users' Note for your implementation).
ifail=4
No computation has been performed because the errors due to argument reduction in elementary functions mean that all precision in the result returned by s17dh would be lost. This error exit may occur if abs z is greater than a machine-dependent threshold value (given in the Users' Note for your implementation).
ifail=5
No result is returned because the algorithm termination condition has not been met. This may occur because the parameters supplied to s17dh would have caused overflow or underflow.
ifail=-9000
An error occured, see message report.

Accuracy

All constants in s17dh are given to approximately 18 digits of precision. Calling the number of digits of precision in the floating-point arithmetic being used t, then clearly the maximum number of correct digits in the results obtained is limited by p=min t,18. Because of errors in argument reduction when computing elementary functions inside s17dh, the actual number of correct digits is limited, in general, by p-s, where s≈max 1,log 10 z represents the number of digits lost due to the argument reduction. Thus the larger the value of z, the less the precision in the result.
Empirical tests with modest values of z, checking relations between Airy functions Ai z, Ai′z, Bi z and Bi′z, have shown errors limited to the least significant 3 – 4 digits of precision.

Parallelism and Performance

None.

Further Comments

Note that if the function is required to operate on a real argument only, then it may be much cheaper to call s17ah or s17ak.

Example

This example prints a caption and then proceeds to read sets of data from the input data stream. The first datum is a value for the parameter deriv, the second is a complex value for the argument, z, and the third is a character value to set the parameter scal. The program calls the method and prints the results. The process is repeated until the end of the input data stream is encountered.

Example program (C#): s17dhe.cs

Example program data: s17dhe.d

Example program results: s17dhe.r

See Also

S Class
S Members


s18ac Method

[image]

NAG Library for .NET Release 2
S..::s18ac Method
S Class See Also Send Feedback
s18ac returns the value of the modified Bessel function K 0 x.

Syntax

C#
public static double s18ac(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s18ac ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s18ac(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s18ac :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
Constraint: x>0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s18ac returns the value of the modified Bessel function K 0 x.

Description

s18ac evaluates an approximation to the modified Bessel function of the second kind K 0 x.
Note: K 0 x is undefined for x≤0 and the method will fail for such arguments.
The method is based on five Chebyshev expansions:
For 0<x≤1,
K 0 x=-ln x∑′r=0 arTr t+∑′r=0 brTr t,   where ​t=2 x 2-1.
For 1<x≤2,
K 0 x=e-x∑′r=0 crTr t,   where ​t=2 x-3.
For 2<x≤4,
K 0 x=e-x∑′r=0 drTr t,   where ​t=x-3.
For x>4,
K 0 x=e-x x∑′r=0 erTr t,where ​t=9-x1+x.
For x near zero, K 0 x≃-γ-ln x 2, where γ denotes Euler's constant. This approximation is used when x is sufficiently small for the result to be correct to machine precision.
For large x, where there is a danger of underflow due to the smallness of K 0, the result is set exactly to zero.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
x≤0.0, K 0 is undefined. On failure the method returns zero.
ifail=-9000
An error occured, see message report.

Accuracy

Let δ and ε be the relative errors in the argument and result respectively.
If δ is somewhat larger than the machine precision (i.e., if δ is due to data errors etc.), then ε and δ are approximately related by:
ε≃x K 1 xK 0 x δ.
Figure 1 shows the behaviour of the error amplification factor
x K 1 xK 0 x.
However, if δ is of the same order as machine precision, then rounding errors could make ε slightly larger than the above relation predicts.
For small x, the amplification factor is approximately 1 ln x, which implies strong attenuation of the error, but in general ε can never be less than the machine precision.
For large x, ε≃xδ and we have strong amplification of the relative error. Eventually K 0, which is asymptotically given by e-x x, becomes so small that it cannot be calculated without underflow and hence the method will return zero. Note that for large x the errors will be dominated by those of the standard function exp.
Figure 1

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s18ace.cs

Example program data: s18ace.d

Example program results: s18ace.r

See Also

S Class
S Members


s18ad Method

[image]

NAG Library for .NET Release 2
S..::s18ad Method
S Class See Also Send Feedback
s18ad returns the value of the modified Bessel function K 1 x.

Syntax

C#
public static double s18ad(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s18ad ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s18ad(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s18ad :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
Constraint: x>0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s18ad returns the value of the modified Bessel function K 1 x.

Description

s18ad evaluates an approximation to the modified Bessel function of the second kind K 1 x.
Note: K 1 x is undefined for x≤0 and the method will fail for such arguments.
The method is based on five Chebyshev expansions:
For 0<x≤1,
K 1 x=1 x+x ln x∑′r=0 arTr t-x∑′r=0 brTr t,   where ​t=2 x 2-1.
For 1<x≤2,
K 1 x=e-x∑′r=0 crTr t,   where ​t=2 x-3.
For 2<x≤4,
K 1 x=e-x∑′r=0 drTr t,   where ​t=x-3.
For x>4,
K 1 x=e-x x∑′r=0 erTr t,   where ​t=9-x1+x.
For x near zero, K 1 x≃1 x. This approximation is used when x is sufficiently small for the result to be correct to machine precision. For very small x on some machines, it is impossible to calculate 1 x without overflow and the method must fail.
For large x, where there is a danger of underflow due to the smallness of K 1, the result is set exactly to zero.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
x≤0.0, K 1 is undefined. On failure the method returns zero.
ifail=2
x is too small, there is a danger of overflow. On failure the method returns approximately the largest representable value. (see the Users' Note for your implementation for details)
ifail=-9000
An error occured, see message report.

Accuracy

Let δ and ε be the relative errors in the argument and result respectively.
If δ is somewhat larger than the machine precision (i.e., if δ is due to data errors etc.), then ε and δ are approximately related by:
ε≃x K 0 x-K 1 xK 1 x δ.
Figure 1 shows the behaviour of the error amplification factor
x K 0 x-K 1 xK 1 x.
However if δ is of the same order as the machine precision, then rounding errors could make ε slightly larger than the above relation predicts.
For small x, ε≃δ and there is no amplification of errors.
For large x, ε≃xδ and we have strong amplification of the relative error. Eventually K 1, which is asymptotically given by e-x x, becomes so small that it cannot be calculated without underflow and hence the method will return zero. Note that for large x the errors will be dominated by those of the standard function exp.
Figure 1

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s18ade.cs

Example program data: s18ade.d

Example program results: s18ade.r

See Also

S Class
S Members


s18ae Method

[image]

NAG Library for .NET Release 2
S..::s18ae Method
S Class See Also Send Feedback
s18ae returns the value of the modified Bessel function I 0 x.

Syntax

C#
public static double s18ae(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s18ae ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s18ae(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s18ae :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s18ae returns the value of the modified Bessel function I 0 x.

Description

s18ae evaluates an approximation to the modified Bessel function of the first kind I 0 x.
Note: I 0-x=I 0 x, so the approximation need only consider x≥0.
The method is based on three Chebyshev expansions:
For 0<x≤4,
I 0 x=ex∑′r=0 arTr t,   where ​t=2 x 4-1.
For 4<x≤12,
I 0 x=ex∑′r=0 brTr t,   where ​t=x-8 4.
For x>12,
I 0 x=ex x∑′r=0 crTr t,   where ​t=2 12 x-1.
For small x, I 0 x≃1. This approximation is used when x is sufficiently small for the result to be correct to machine precision.
For large x, the method must fail because of the danger of overflow in calculating ex.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
x is too large. On failure the method returns the approximate value of I 0 x at the nearest valid argument. (see the Users' Note for your implementation for details)
ifail=-9000
An error occured, see message report.

Accuracy

Let δ and ε be the relative errors in the argument and result respectively.
If δ is somewhat larger than the machine precision (i.e., if δ is due to data errors etc.), then ε and δ are approximately related by:
ε≃x I 1 xI 0 x δ.
Figure 1 shows the behaviour of the error amplification factor
x I 1 xI 0 x.
Figure 1
However if δ is of the same order as machine precision, then rounding errors could make ε slightly larger than the above relation predicts.
For small x the amplification factor is approximately x 2 2, which implies strong attenuation of the error, but in general ε can never be less than the machine precision.
For large x, ε≃xδ and we have strong amplification of errors. However the method must fail for quite moderate values of x, because I 0 x would overflow; hence in practice the loss of accuracy for large x is not excessive. Note that for large x the errors will be dominated by those of the standard function exp.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s18aee.cs

Example program data: s18aee.d

Example program results: s18aee.r

See Also

S Class
S Members


s18af Method

[image]

NAG Library for .NET Release 2
S..::s18af Method
S Class See Also Send Feedback
s18af returns a value for the modified Bessel function I 1 x.

Syntax

C#
public static double s18af(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s18af ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s18af(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s18af :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s18af returns a value for the modified Bessel function I 1 x.

Description

s18af evaluates an approximation to the modified Bessel function of the first kind I 1 x.
Note: I 1-x=-I 1 x, so the approximation need only consider x≥0.
The method is based on three Chebyshev expansions:
For 0<x≤4,
I 1 x=x∑′r=0 arTr t,   where ​t=2 x 4 2-1;
For 4<x≤12,
I 1 x=ex∑′r=0 brTr t,   where ​t=x-8 4;
For x>12,
I 1 x=ex x∑′r=0 crTr t,   where ​t=2 12 x-1.
For small x, I 1 x≃x. This approximation is used when x is sufficiently small for the result to be correct to machine precision.
For large x, the method must fail because I 1 x cannot be represented without overflow.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
x is too large. On failure the method returns the approximate value of I 1 x at the nearest valid argument. See also the Users' Note for your implementation.
ifail=-9000
An error occured, see message report.

Accuracy

Let δ and ε be the relative errors in the argument and result respectively.
If δ is somewhat larger than the machine precision (i.e., if δ is due to data errors etc.), then ε and δ are approximately related by:
ε≃x I 0 x-I 1 xI 1 x δ.
Figure 1 shows the behaviour of the error amplification factor
x I 0 x-I 1 xI 1 x.
Figure 1
However, if δ is of the same order as machine precision, then rounding errors could make ε slightly larger than the above relation predicts.
For small x, ε≃δ and there is no amplification of errors.
For large x, ε≃xδ and we have strong amplification of errors. However the method must fail for quite moderate values of x because I 1 x would overflow; hence in practice the loss of accuracy for large x is not excessive. Note that for large x, the errors will be dominated by those of the standard function exp.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s18afe.cs

Example program data: s18afe.d

Example program results: s18afe.r

See Also

S Class
S Members


s18cc Method

[image]

NAG Library for .NET Release 2
S..::s18cc Method
S Class See Also Send Feedback
s18cc returns a value of the scaled modified Bessel function ex K 0 x.

Syntax

C#
public static double s18cc(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s18cc ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s18cc(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s18cc :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
Constraint: x>0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s18cc returns a value of the scaled modified Bessel function ex K 0 x.

Description

s18cc evaluates an approximation to ex K 0 x, where K 0 is a modified Bessel function of the second kind. The scaling factor ex removes most of the variation in K 0 x.
The method uses the same Chebyshev expansions as s18ac, which returns the unscaled value of K 0 x.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, x≤0.0, K 0 is undefined.
On failure, s18cc returns zero.
ifail=-9000
An error occured, see message report.

Accuracy

Relative errors in the argument are attenuated when propagated into the function value. When the accuracy of the argument is essentially limited by the machine precision, the accuracy of the function value will be similarly limited by at most a small multiple of the machine precision.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s18cce.cs

Example program data: s18cce.d

Example program results: s18cce.r

See Also

S Class
S Members


s18cd Method

[image]

NAG Library for .NET Release 2
S..::s18cd Method
S Class See Also Send Feedback
s18cd returns a value of the scaled modified Bessel function ex K 1 x.

Syntax

C#
public static double s18cd(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s18cd ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s18cd(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s18cd :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
Constraint: x>0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s18cd returns a value of the scaled modified Bessel function ex K 1 x.

Description

s18cd evaluates an approximation to ex K 1 x, where K 1 is a modified Bessel function of the second kind. The scaling factor ex removes most of the variation in K 1 x.
The method uses the same Chebyshev expansions as s18ad, which returns the unscaled value of K 1 x.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, x≤0.0: K 1 is undefined. On failure s18cd returns zero.
ifail=2
On entry, x is too close to zero, as determined by the value of the safe-range parameter x02am: there is a danger of causing overflow. On failure, s18cd returns the reciprocal of the safe-range parameter.
ifail=-9000
An error occured, see message report.

Accuracy

Relative errors in the argument are attenuated when propagated into the function value. When the accuracy of the argument is essentially limited by the machine precision, the accuracy of the function value will be similarly limited by at most a small multiple of the machine precision.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s18cde.cs

Example program data: s18cde.d

Example program results: s18cde.r

See Also

S Class
S Members


s18ce Method

[image]

NAG Library for .NET Release 2
S..::s18ce Method
S Class See Also Send Feedback
s18ce returns a value of the scaled modified Bessel function e-x I 0 x.

Syntax

C#
public static double s18ce(
    double x
)
Visual Basic
Public Shared Function s18ce ( _
    x As Double _
) As Double
Visual C++
public:
static double s18ce(
    double x
)
F#
static member s18ce :
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.

Return Value

s18ce returns a value of the scaled modified Bessel function e-x I 0 x.

Description

s18ce evaluates an approximation to e-x I 0 x, where I 0 is a modified Bessel function of the first kind. The scaling factor e-x removes most of the variation in I 0 x.
The method uses the same Chebyshev expansions as s18ae, which returns the unscaled value of I 0 x.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

There are no actual failure exits from this method. _ifail is always set to zero. This parameter is included for compatibility with other methods in this chapter.

Accuracy

Relative errors in the argument are attenuated when propagated into the function value. When the accuracy of the argument is essentially limited by the machine precision, the accuracy of the function value will be similarly limited by at most a small multiple of the machine precision.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s18cee.cs

Example program data: s18cee.d

Example program results: s18cee.r

See Also

S Class
S Members


s18cf Method

[image]

NAG Library for .NET Release 2
S..::s18cf Method
S Class See Also Send Feedback
s18cf returns a value of the scaled modified Bessel function e-x I 1 x.

Syntax

C#
public static double s18cf(
    double x
)
Visual Basic
Public Shared Function s18cf ( _
    x As Double _
) As Double
Visual C++
public:
static double s18cf(
    double x
)
F#
static member s18cf :
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.

Return Value

s18cf returns a value of the scaled modified Bessel function e-x I 1 x.

Description

s18cf evaluates an approximation to e-x I 1 x, where I 1 is a modified Bessel function of the first kind. The scaling factor e-x removes most of the variation in I 1 x.
The method uses the same Chebyshev expansions as s18af, which returns the unscaled value of I 1 x.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

There are no actual failure exits from this method. _ifail is always set to zero. This parameter is included for compatibility with other methods in this chapter.

Accuracy

Relative errors in the argument are attenuated when propagated into the function value. When the accuracy of the argument is essentially limited by the machine precision, the accuracy of the function value will be similarly limited by at most a small multiple of the machine precision.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s18cfe.cs

Example program data: s18cfe.d

Example program results: s18cfe.r

See Also

S Class
S Members


s19aa Method

[image]

NAG Library for .NET Release 2
S..::s19aa Method
S Class See Also Send Feedback
s19aa returns a value for the Kelvin function ber x.

Syntax

C#
public static double s19aa(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s19aa ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s19aa(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s19aa :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s19aa returns a value for the Kelvin function ber x.

Description

s19aa evaluates an approximation to the Kelvin function ber x.
Note: ber-x=ber x, so the approximation need only consider x≥0.0.
The method is based on several Chebyshev expansions:
For 0≤x≤5,
ber x=∑′r=0 arTr t,   with ​t=2 x 5 4-1.
For x>5,
ber x=e x/2 2 πx 1+1 x a t cos α+1 x b t sin α+e-x/2 2 πx 1+1 x c t sin β+1 x d t cos β,
where α=x 2-π 8, β=x 2+π 8,
and a t, b t, c t, and d t are expansions in the variable t=10 x-1.
When x is sufficiently close to zero, the result is set directly to ber 0=1.0.
For large x, there is a danger of the result being totally inaccurate, as the error amplification factor grows in an essentially exponential manner; therefore the method must fail.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, abs x is too large for an accurate result to be returned. On failure, the method returns zero. See also the Users' Note for your implementation.
ifail=-9000
An error occured, see message report.

Accuracy

Since the function is oscillatory, the absolute error rather than the relative error is important. Let E be the absolute error in the result and δ be the relative error in the argument. If δ is somewhat larger than the machine precision, then we have:
E≃x 2 ber 1 x+bei 1 x δ
(provided E is within machine bounds).
For small x the error amplification is insignificant and thus the absolute error is effectively bounded by the machine precision.
For medium and large x, the error behaviour is oscillatory and its amplitude grows like x 2 π e x/2. Therefore it is not possible to calculate the function with any accuracy when x e x/2>2 π δ. Note that this value of x is much smaller than the minimum value of x for which the function overflows.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s19aae.cs

Example program data: s19aae.d

Example program results: s19aae.r

See Also

S Class
S Members


s19ab Method

[image]

NAG Library for .NET Release 2
S..::s19ab Method
S Class See Also Send Feedback
s19ab returns a value for the Kelvin function bei x.

Syntax

C#
public static double s19ab(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s19ab ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s19ab(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s19ab :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s19ab returns a value for the Kelvin function bei x.

Description

s19ab evaluates an approximation to the Kelvin function bei x.
Note: bei-x=bei x, so the approximation need only consider x≥0.0.
The method is based on several Chebyshev expansions:
For 0≤x≤5,
bei x=x 2 4∑r=0′arTr t,   with ​t=2 x 5 4-1;
For x>5,
bei x=e x/2 2 πx 1+1 x a t sin α-1 x b t cos α
+e x/2 2 πx 1+1 x c t cos β-1 x d t sin β
where α=x 2-π 8, β=x 2+π 8,
and a t, b t, c t, and d t are expansions in the variable t=10 x-1.
When x is sufficiently close to zero, the result is computed as bei x=x 2 4. If this result would underflow, the result returned is bei x=0.0.
For large x, there is a danger of the result being totally inaccurate, as the error amplification factor grows in an essentially exponential manner; therefore the method must fail.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, abs x is too large for an accurate result to be returned. On failure, the method returns zero. See also the Users' Note for your implementation.
ifail=-9000
An error occured, see message report.

Accuracy

Since the function is oscillatory, the absolute error rather than the relative error is important. Let E be the absolute error in the function, and δ be the relative error in the argument. If δ is somewhat larger than the machine precision, then we have:
E≃x 2-ber 1 x+bei 1 x δ
(provided E is within machine bounds).
For small x the error amplification is insignificant and thus the absolute error is effectively bounded by the machine precision.
For medium and large x, the error behaviour is oscillatory and its amplitude grows like x 2 π e x/2. Therefore it is impossible to calculate the functions with any accuracy when x e x/2>2 π δ. Note that this value of x is much smaller than the minimum value of x for which the function overflows.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s19abe.cs

Example program data: s19abe.d

Example program results: s19abe.r

See Also

S Class
S Members


s19ac Method

[image]

NAG Library for .NET Release 2
S..::s19ac Method
S Class See Also Send Feedback
s19ac returns a value for the Kelvin function ker x.

Syntax

C#
public static double s19ac(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s19ac ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s19ac(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s19ac :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
Constraint: x>0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s19ac returns a value for the Kelvin function ker x.

Description

s19ac evaluates an approximation to the Kelvin function ker x.
Note: for x<0 the function is undefined and at x=0 it is infinite so we need only consider x>0.
The method is based on several Chebyshev expansions:
For 0<x≤1,
ker x=-f t log x+π 16 x 2 g t+y t
where f t, g t and y t are expansions in the variable t=2 x 4-1.
For 1<x≤3,
ker x=exp-1116 x q t
where q t is an expansion in the variable t=x-2.
For x>3,
ker x=π 2 x e-x/2 1+1 x c t cos β-1 x d t sin β
where β=x 2+π 8, and c t and d t are expansions in the variable t=6 x-1.
When x is sufficiently close to zero, the result is computed as
ker x=-γ-log x 2+π-38 x 2 x 2 16
and when x is even closer to zero, simply as ker x=-γ-log x 2.
For large x, ker x is asymptotically given by π 2 x e-x/2 and this becomes so small that it cannot be computed without underflow and the method fails.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, x is too large: the result underflows. On failure, the method returns zero. See also the Users' Note for your implementation.
ifail=2
On entry, x≤0.0: the function is undefined. On failure the method returns zero.
ifail=-9000
An error occured, see message report.

Accuracy

Let E be the absolute error in the result, ε be the relative error in the result and δ be the relative error in the argument. If δ is somewhat larger than the machine precision, then we have:
E≃x 2 ker 1 x+kei 1 x δ,
ε≃x 2ker 1 x+kei 1 xker x δ.
For very small x, the relative error amplification factor is approximately given by 1 log x, which implies a strong attenuation of relative error. However, ε in general cannot be less than the machine precision.
For small x, errors are damped by the function and hence are limited by the machine precision.
For medium and large x, the error behaviour, like the function itself, is oscillatory, and hence only the absolute accuracy for the function can be maintained. For this range of x, the amplitude of the absolute error decays like πx 2 e-x/2 which implies a strong attenuation of error. Eventually, ker x, which asymptotically behaves like π 2 x e-x/2, becomes so small that it cannot be calculated without causing underflow, and the method returns zero. Note that for large x the errors are dominated by those of the standard function exp.

Parallelism and Performance

None.

Further Comments

Underflow may occur for a few values of x close to the zeros of ker x, below the limit which causes a failure with ifail=1.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s19ace.cs

Example program data: s19ace.d

Example program results: s19ace.r

See Also

S Class
S Members


s19ad Method

[image]

NAG Library for .NET Release 2
S..::s19ad Method
S Class See Also Send Feedback
s19ad returns a value for the Kelvin function kei x.

Syntax

C#
public static double s19ad(
    double x,
    out int ifail
)
Visual Basic
Public Shared Function s19ad ( _
    x As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s19ad(
    double x,
    [OutAttribute] int% ifail
)
F#
static member s19ad :
        x : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.
Constraint: x≥0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s19ad returns a value for the Kelvin function kei x.

Description

s19ad evaluates an approximation to the Kelvin function kei x.
Note: for x<0 the function is undefined, so we need only consider x≥0.
The method is based on several Chebyshev expansions:
For 0≤x≤1,
kei x=-π 4 f t+x 2 4-g t log x+v t
where f t, g t and v t are expansions in the variable t=2 x 4-1;
For 1<x≤3,
kei x=exp-98 x u t
where u t is an expansion in the variable t=x-2;
For x>3,
kei x=π 2 x e-x/2 1+1 x c t sin β+1 x d t cos β
where β=x 2+π 8, and c t and d t are expansions in the variable t=6 x-1.
For x<0, the function is undefined, and hence the method fails and returns zero.
When x is sufficiently close to zero, the result is computed as
kei x=-π 4+1-γ-log x 2 x 2 4
and when x is even closer to zero simply as
kei x=-π 4.
For large x, kei x is asymptotically given by π 2 x e-x/2 and this becomes so small that it cannot be computed without underflow and the method fails.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, x is too large: the result underflows. On failure, the method returns zero. See also the Users' Note for your implementation.
ifail=2
On entry, x<0.0: the function is undefined. On failure the method returns zero.
ifail=-9000
An error occured, see message report.

Accuracy

Let E be the absolute error in the result, and δ be the relative error in the argument. If δ is somewhat larger than the machine representation error, then we have:
E≃x 2-ker 1 x+kei 1 x δ.
For small x, errors are attenuated by the function and hence are limited by the machine precision.
For medium and large x, the error behaviour, like the function itself, is oscillatory and hence only absolute accuracy of the function can be maintained. For this range of x, the amplitude of the absolute error decays like πx 2 e-x/2, which implies a strong attenuation of error. Eventually, kei x, which is asymptotically given by π 2 x e-x/2,becomes so small that it cannot be calculated without causing underflow and therefore the method returns zero. Note that for large x, the errors are dominated by those of the standard function exp.

Parallelism and Performance

None.

Further Comments

Underflow may occur for a few values of x close to the zeros of kei x, below the limit which causes a failure with ifail=1.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s19ade.cs

Example program data: s19ade.d

Example program results: s19ade.r

See Also

S Class
S Members


s20ac Method

[image]

NAG Library for .NET Release 2
S..::s20ac Method
S Class See Also Send Feedback
s20ac returns a value for the Fresnel integral S x.

Syntax

C#
public static double s20ac(
    double x
)
Visual Basic
Public Shared Function s20ac ( _
    x As Double _
) As Double
Visual C++
public:
static double s20ac(
    double x
)
F#
static member s20ac :
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.

Return Value

s20ac returns a value for the Fresnel integral S x.

Description

s20ac evaluates an approximation to the Fresnel integral
S x=∫0 x sin π 2 t 2dt.
Note: S x=-S-x, so the approximation need only consider x≥0.0.
The method is based on three Chebyshev expansions:
For 0<x≤3,
S x=x 3∑′r=0 arTr t,   with ​t=2 x 3 4-1.
For x>3,
S x=12-f x x cos π 2 x 2-g x x 3 sin π 2 x 2,
where f x=∑′r=0 brTr t,
and g x=∑′r=0 crTr t,
with t=2 3 x 4-1.
For small x, S x≃π 6 x 3. This approximation is used when x is sufficiently small for the result to be correct to machine precision. For very small x, this approximation would underflow; the result is then set exactly to zero.
For large x, f x≃1 π and g x≃1 π 2. Therefore for moderately large x, when 1 π 2x 3 is negligible compared with 12, the second term in the approximation for x>3 may be dropped. For very large x, when 1 πx becomes negligible, S x≃12. However there will be considerable difficulties in calculating cos π 2 x 2 accurately before this final limiting value can be used. Since cos π 2 x 2 is periodic, its value is essentially determined by the fractional part of x 2. If x 2=N+θ where N is an integer and 0≤θ<1, then cos π 2 x 2 depends on θ and on N modulo 4. By exploiting this fact, it is possible to retain significance in the calculation of cos π 2 x 2 either all the way to the very large x limit, or at least until the integer part of x 2 is equal to the maximum integer allowed on the machine.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

There are no failure exits from s20ac. The parameter _ifail has been included for consistency with other methods in this chapter.

Accuracy

Let δ and ε be the relative errors in the argument and result respectively.
If δ is somewhat larger than the machine precision (i.e., if δ is due to data errors etc.), then ε and δ are approximately related by:
ε≃x sin π 2 x 2S x δ.
Figure 1 shows the behaviour of the error amplification factor x sin π 2 x 2S x.
However if δ is of the same order as the machine precision, then rounding errors could make ε slightly larger than the above relation predicts.
For small x, ε≃3 δ and hence there is only moderate amplification of relative error. Of course for very small x where the correct result would underflow and exact zero is returned, relative error-control is lost.
For moderately large values of x,
ε≃2 x sin π 2 x 2δ
and the result will be subject to increasingly large amplification of errors. However the above relation breaks down for large values of x (i.e., when 1 x 2 is of the order of the machine precision); in this region the relative error in the result is essentially bounded by 2 πx.
Hence the effects of error amplification are limited and at worst the relative error loss should not exceed half the possible number of significant figures.
Figure 1

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s20ace.cs

Example program data: s20ace.d

Example program results: s20ace.r

See Also

S Class
S Members


s20ad Method

[image]

NAG Library for .NET Release 2
S..::s20ad Method
S Class See Also Send Feedback
s20ad returns a value for the Fresnel integral C x.

Syntax

C#
public static double s20ad(
    double x
)
Visual Basic
Public Shared Function s20ad ( _
    x As Double _
) As Double
Visual C++
public:
static double s20ad(
    double x
)
F#
static member s20ad :
        x : float -> float

Parameters

x
Type: System..::..Double
On entry: the argument x of the function.

Return Value

s20ad returns a value for the Fresnel integral C x.

Description

s20ad evaluates an approximation to the Fresnel integral
C x=∫0 x cos π 2 t 2dt.
Note: C x=-C-x, so the approximation need only consider x≥0.0.
The method is based on three Chebyshev expansions:
For 0<x≤3,
C x=x∑′r=0 arTr t,   with ​t=2 x 3 4-1.
For x>3,
C x=12+f x x sin π 2 x 2-g x x 3 cos π 2 x 2,
where f x=∑′r=0 brTr t,
and g x=∑′r=0 crTr t,
with t=2 3 x 4-1.
For small x, C x≃x. This approximation is used when x is sufficiently small for the result to be correct to machine precision.
For large x, f x≃1 π and g x≃1 π 2. Therefore for moderately large x, when 1 π 2x 3 is negligible compared with 12, the second term in the approximation for x>3 may be dropped. For very large x, when 1 πx becomes negligible, C x≃12. However there will be considerable difficulties in calculating sin π 2 x 2 accurately before this final limiting value can be used. Since sin π 2 x 2 is periodic, its value is essentially determined by the fractional part of x 2. If x 2=N+θ, where N is an integer and 0≤θ<1, then sin π 2 x 2 depends on θ and on N modulo 4. By exploiting this fact, it is possible to retain some significance in the calculation of sin π 2 x 2 either all the way to the very large x limit, or at least until the integer part of x 2 is equal to the maximum integer allowed on the machine.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

There are no failure exits from s20ad. The parameter _ifail has been included for consistency with other methods in this chapter.

Accuracy

Let δ and ε be the relative errors in the argument and result respectively.
If δ is somewhat larger than the machine precision (i.e if δ is due to data errors etc.), then ε and δ are approximately related by:
ε≃x cos π 2 x 2C x δ.
Figure 1 shows the behaviour of the error amplification factor x cos π 2 x 2C x.
However, if δ is of the same order as the machine precision, then rounding errors could make ε slightly larger than the above relation predicts.
For small x, ε≃δ and there is no amplification of relative error.
For moderately large values of x,
ε≃2 x cos π 2 x 2δ
and the result will be subject to increasingly large amplification of errors. However the above relation breaks down for large values of x (i.e., when 1 x 2 is of the order of the machine precision); in this region the relative error in the result is essentially bounded by 2 πx.
Hence the effects of error amplification are limited and at worst the relative error loss should not exceed half the possible number of significant figures.
Figure 1

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument x from a file, evaluates the function at each value of x and prints the results.

Example program (C#): s20ade.cs

Example program data: s20ade.d

Example program results: s20ade.r

See Also

S Class
S Members


s21ba Method

[image]

NAG Library for .NET Release 2
S..::s21ba Method
S Class See Also Send Feedback
s21ba returns a value of an elementary integral, which occurs as a degenerate case of an elliptic integral of the first kind.

Syntax

C#
public static double s21ba(
    double x,
    double y,
    out int ifail
)
Visual Basic
Public Shared Function s21ba ( _
    x As Double, _
    y As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s21ba(
    double x,
    double y,
    [OutAttribute] int% ifail
)
F#
static member s21ba :
        x : float *
        y : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the arguments x and y of the function, respectively.
Constraint: x≥0.0 and y≠0.0.
y
Type: System..::..Double
On entry: the arguments x and y of the function, respectively.
Constraint: x≥0.0 and y≠0.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s21ba returns a value of an elementary integral, which occurs as a degenerate case of an elliptic integral of the first kind.

Description

s21ba calculates an approximate value for the integral
RC x,y=12∫0∞dtt+y.t+x
where x≥0 and y≠0.
This function, which is related to the logarithm or inverse hyperbolic functions for y<x and to inverse circular functions if x<y, arises as a degenerate form of the elliptic integral of the first kind. If y<0, the result computed is the Cauchy principal value of the integral.
The basic algorithm, which is due to Carlson (1979) and Carlson (1988), is to reduce the arguments recursively towards their mean by the system:
x 0=xy 0=yμn=xn+2 yn/3,Sn=yn-xn/3 μnλn=yn+2 xnynx n+1=xn+λn/4,y n+1=yn+λn/4.
The quantity Sn for n=0,1,2,3,… decreases with increasing n, eventually Sn∼1/4 n. For small enough Sn the required function value can be approximated by the first few terms of the Taylor series about the mean. That is
RC x,y=1+3 Sn 2 10+Sn 3 7+3 Sn 4 8+9 Sn 5 22/μn.
The truncation error involved in using this approximation is bounded by 16 Sn 6/1-2 Sn and the recursive process is stopped when Sn is small enough for this truncation error to be negligible compared to the machine precision.
Within the domain of definition, the function value is itself representable for all representable values of its arguments. However, for values of the arguments near the extremes the above algorithm must be modified so as to avoid causing underflows or overflows in intermediate steps. In extreme regions arguments are prescaled away from the extremes and compensating scaling of the result is done before returning to the calling program.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Carlson B C (1979) Computing elliptic integrals by duplication Numerische Mathematik 33 1–16
Carlson B C (1988) A table of elliptic integrals of the third kind Math. Comput. 51 267–280

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, x<0.0; the function is undefined.
ifail=2
On entry, y=0.0; the function is undefined.
On failure the method returns zero.
ifail=-9000
An error occured, see message report.

Accuracy

In principle the method is capable of producing full machine precision. However round-off errors in internal arithmetic will result in slight loss of accuracy. This loss should never be excessive as the algorithm does not involve any significant amplification of round-off error. It is reasonable to assume that the result is accurate to within a small multiple of the machine precision.

Parallelism and Performance

None.

Further Comments

You should consult (S not in this release) which shows the relationship of this function to the classical definitions of the elliptic integrals.

Example

This example simply generates a small set of nonextreme arguments which are used with the method to produce the table of low accuracy results.

Example program (C#): s21bae.cs

Example program results: s21bae.r

See Also

S Class
S Members


s21bb Method

[image]

NAG Library for .NET Release 2
S..::s21bb Method
S Class See Also Send Feedback
s21bb returns a value of the symmetrised elliptic integral of the first kind.

Syntax

C#
public static double s21bb(
    double x,
    double y,
    double z,
    out int ifail
)
Visual Basic
Public Shared Function s21bb ( _
    x As Double, _
    y As Double, _
    z As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s21bb(
    double x,
    double y,
    double z,
    [OutAttribute] int% ifail
)
F#
static member s21bb :
        x : float *
        y : float *
        z : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the arguments x, y and z of the function.
Constraint: x, y, z≥0.0 and only one of x, y and z may be zero.
y
Type: System..::..Double
On entry: the arguments x, y and z of the function.
Constraint: x, y, z≥0.0 and only one of x, y and z may be zero.
z
Type: System..::..Double
On entry: the arguments x, y and z of the function.
Constraint: x, y, z≥0.0 and only one of x, y and z may be zero.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s21bb returns a value of the symmetrised elliptic integral of the first kind.

Description

s21bb calculates an approximation to the integral
RF x,y,z=12∫0∞dtt+xt+yt+z
where x, y, z≥0 and at most one is zero.
The basic algorithm, which is due to Carlson (1979) and Carlson (1988), is to reduce the arguments recursively towards their mean by the rule:
  • x 0=min x,y,z,  z 0=max x,y,z,
  • y 0= remaining third intermediate value argument.
(This ordering, which is possible because of the symmetry of the function, is done for technical reasons related to the avoidance of overflow and underflow.)
μn=xn+yn+zn/3Xn=1-xn/μnYn=1-yn/μnZn=1-zn/μnλn=xnyn+ynzn+znxnx n+1=xn+λn/4y n+1=yn+λn/4z n+1=zn+λn/4
εn=max Xn,Yn,Zn and the function may be approximated adequately by a fifth order power series:
RF x,y,z=1 μn 1-E 2 10+E 22 24-3 E 2E 3 44+E 3 14
where E 2=XnYn+YnZn+ZnXn, E 3=XnYnZn.
The truncation error involved in using this approximation is bounded by εn 6/4 1-εn and the recursive process is stopped when this truncation error is negligible compared with the machine precision.
Within the domain of definition, the function value is itself representable for all representable values of its arguments. However, for values of the arguments near the extremes the above algorithm must be modified so as to avoid causing underflows or overflows in intermediate steps. In extreme regions arguments are prescaled away from the extremes and compensating scaling of the result is done before returning to the calling program.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Carlson B C (1979) Computing elliptic integrals by duplication Numerische Mathematik 33 1–16
Carlson B C (1988) A table of elliptic integrals of the third kind Math. Comput. 51 267–280

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, one or more of x, y and z is negative; the function is undefined.
ifail=2
On entry, two or more of x, y and z are zero; the function is undefined. On failure, the method returns zero.
ifail=-9000
An error occured, see message report.

Accuracy

In principle s21bb is capable of producing full machine precision. However round-off errors in internal arithmetic will result in slight loss of accuracy. This loss should never be excessive as the algorithm does not involve any significant amplification of round-off error. It is reasonable to assume that the result is accurate to within a small multiple of the machine precision.

Parallelism and Performance

None.

Further Comments

You should consult (S not in this release) which shows the relationship of this function to the classical definitions of the elliptic integrals.
If two arguments are equal, the function reduces to the elementary integral RC, computed by s21ba.

Example

This example simply generates a small set of nonextreme arguments which are used with the method to produce the table of low accuracy results.

Example program (C#): s21bbe.cs

Example program results: s21bbe.r

See Also

S Class
S Members


s21bc Method

[image]

NAG Library for .NET Release 2
S..::s21bc Method
S Class See Also Send Feedback
s21bc returns a value of the symmetrised elliptic integral of the second kind.

Syntax

C#
public static double s21bc(
    double x,
    double y,
    double z,
    out int ifail
)
Visual Basic
Public Shared Function s21bc ( _
    x As Double, _
    y As Double, _
    z As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s21bc(
    double x,
    double y,
    double z,
    [OutAttribute] int% ifail
)
F#
static member s21bc :
        x : float *
        y : float *
        z : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the arguments x, y and z of the function.
Constraint: x, y≥0.0, z>0.0 and only one of x and y may be zero.
y
Type: System..::..Double
On entry: the arguments x, y and z of the function.
Constraint: x, y≥0.0, z>0.0 and only one of x and y may be zero.
z
Type: System..::..Double
On entry: the arguments x, y and z of the function.
Constraint: x, y≥0.0, z>0.0 and only one of x and y may be zero.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s21bc returns a value of the symmetrised elliptic integral of the second kind.

Description

s21bc calculates an approximate value for the integral
RD x,y,z=32∫0∞dtt+xt+y t+z 3
where x, y≥0, at most one of x and y is zero, and z>0.
The basic algorithm, which is due to Carlson (1979) and Carlson (1988), is to reduce the arguments recursively towards their mean by the rule:
x 0=x,y 0=y,z 0=zμn=xn+yn+3 zn/5Xn=1-xn/μnYn=1-yn/μnZn=1-zn/μnλn=xnyn+ynzn+znxnx n+1=xn+λn/4y n+1=yn+λn/4z n+1=zn+λn/4
For n sufficiently large,
εn=max Xn,Yn,Zn∼14 n
and the function may be approximated adequately by a fifth order power series
RD x,y,z=3∑m=0n-1 4-m zm+λn zm+4-n μn 3 1+37 Sn 2+13 Sn 3+322 Sn 2 2+311 Sn 4+313 Sn 2Sn 3+313 Sn 5
where Sn m=Xnm+Ynm+3 Znm/2 m. The truncation error in this expansion is bounded by 3 εn 61-εn 3 and the recursive process is terminated when this quantity is negligible compared with the machine precision.
The method may fail either because it has been called with arguments outside the domain of definition, or with arguments so extreme that there is an unavoidable danger of setting underflow or overflow.
Note: RD x,x,x=x-3/2, so there exists a region of extreme arguments for which the function value is not representable.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Carlson B C (1979) Computing elliptic integrals by duplication Numerische Mathematik 33 1–16
Carlson B C (1988) A table of elliptic integrals of the third kind Math. Comput. 51 267–280

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, either x or y is negative, or both x and y are zero; the function is undefined.
ifail=2
On entry, z≤0.0; the function is undefined.
ifail=3
On entry, either z is too close to zero or both x and y are too close to zero: there is a danger of setting overflow. See also the Users' Note for your implementation.
ifail=4
On entry, at least one of x, y and z is too large: there is a danger of setting underflow. On failure the method returns zero. See also the Users' Note for your implementation.
ifail=-9000
An error occured, see message report.

Accuracy

In principle the method is capable of producing full machine precision. However round-off errors in internal arithmetic will result in slight loss of accuracy. This loss should never be excessive as the algorithm does not involve any significant amplification of round-off error. It is reasonable to assume that the result is accurate to within a small multiple of the machine precision.

Parallelism and Performance

None.

Further Comments

You should consult (S not in this release) which shows the relationship of this function to the classical definitions of the elliptic integrals.

Example

This example simply generates a small set of nonextreme arguments which are used with the method to produce the table of low accuracy results.

Example program (C#): s21bce.cs

Example program results: s21bce.r

See Also

S Class
S Members


s21bd Method

[image]

NAG Library for .NET Release 2
S..::s21bd Method
S Class See Also Send Feedback
s21bd returns a value of the symmetrised elliptic integral of the third kind.

Syntax

C#
public static double s21bd(
    double x,
    double y,
    double z,
    double r,
    out int ifail
)
Visual Basic
Public Shared Function s21bd ( _
    x As Double, _
    y As Double, _
    z As Double, _
    r As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s21bd(
    double x,
    double y,
    double z,
    double r,
    [OutAttribute] int% ifail
)
F#
static member s21bd :
        x : float *
        y : float *
        z : float *
        r : float *
        ifail : int byref -> float

Parameters

x
Type: System..::..Double
On entry: the arguments x, y, z and ρ of the function.
Constraint: x, y, z≥0.0, r≠0.0 and at most one of x, y and z may be zero.
y
Type: System..::..Double
On entry: the arguments x, y, z and ρ of the function.
Constraint: x, y, z≥0.0, r≠0.0 and at most one of x, y and z may be zero.
z
Type: System..::..Double
On entry: the arguments x, y, z and ρ of the function.
Constraint: x, y, z≥0.0, r≠0.0 and at most one of x, y and z may be zero.
r
Type: System..::..Double
On entry: the arguments x, y, z and ρ of the function.
Constraint: x, y, z≥0.0, r≠0.0 and at most one of x, y and z may be zero.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s21bd returns a value of the symmetrised elliptic integral of the third kind.

Description

s21bd calculates an approximation to the integral
RJ x,y,z,ρ=32∫0∞dtt+ρ t+xt+yt+z
where x, y, z≥0, ρ≠0 and at most one of x, y and z is zero.
If ρ<0, the result computed is the Cauchy principal value of the integral.
The basic algorithm, which is due to Carlson (1979) and Carlson (1988), is to reduce the arguments recursively towards their mean by the rule:
x 0=x,y 0=y,z 0=z,ρ 0=ρμn=xn+yn+zn+2 ρn/5Xn=1-xn/μnYn=1-yn/μnZn=1-zn/μnPn=1-ρn/μnλn=xnyn+ynzn+znxnx n+1=xn+λn/4y n+1=yn+λn/4z n+1=zn+λn/4ρ n+1=ρn+λn/4αn=ρn xn,+yn,+zn+xnynzn 2βn=ρn ρn+λn 2
For n sufficiently large,
εn=max Xn,Yn,Zn,Pn∼1 4 n
and the function may be approximated by a fifth order power series
RJ x,y,z,ρ=3∑m=0n-1 4-m RC αm,βm+4-n μn 3 1+37 Sn 2+13 Sn 3+322 Sn 2 2+311 Sn 4+313 Sn 2Sn 3+313 Sn 5
where Sn m=Xnm+Ynm+Znm+2 Pnm/2 m.
The truncation error in this expansion is bounded by 3 εn 6/1-εn 3 and the recursion process is terminated when this quantity is negligible compared with the machine precision. The method may fail either because it has been called with arguments outside the domain of definition or with arguments so extreme that there is an unavoidable danger of setting underflow or overflow.
Note: RJ x,x,x,x=x-32, so there exists a region of extreme arguments for which the function value is not representable.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Carlson B C (1979) Computing elliptic integrals by duplication Numerische Mathematik 33 1–16
Carlson B C (1988) A table of elliptic integrals of the third kind Math. Comput. 51 267–280

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, at least one of x, y and z is negative, or at least two of them are zero; the function is undefined.
ifail=2
r=0.0; the function is undefined.
ifail=3
On entry, either r is too close to zero, or any two of x, y and z are too close to zero; there is a danger of setting overflow. See also the Users' Note for your implementation.
ifail=4
On entry, at least one of x, y, z and r is too large; there is a danger of setting underflow. See also the Users' Note for your implementation.
ifail=-9000
An error occured, see message report.

Accuracy

In principle the method is capable of producing full machine precision. However round-off errors in internal arithmetic will result in slight loss of accuracy. This loss should never be excessive as the algorithm does not involve any significant amplification of round-off error. It is reasonable to assume that the result is accurate to within a small multiple of the machine precision.

Parallelism and Performance

None.

Further Comments

You should consult (S not in this release) which shows the relationship of this function to the classical definitions of the elliptic integrals.
If the parameter r is equal to any of the other arguments, the function reduces to the integral RD, computed by s21bc.

Example

This example simply generates a small set of nonextreme arguments which are used with the method to produce the table of low accuracy results.

Example program (C#): s21bde.cs

Example program results: s21bde.r

See Also

S Class
S Members


s21be Method

[image]

NAG Library for .NET Release 2
S..::s21be Method
S Class See Also Send Feedback
s21be returns a value of the classical (Legendre) form of the incomplete elliptic integral of the first kind.

Syntax

C#
public static double s21be(
    double phi,
    double dm,
    out int ifail
)
Visual Basic
Public Shared Function s21be ( _
    phi As Double, _
    dm As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s21be(
    double phi,
    double dm,
    [OutAttribute] int% ifail
)
F#
static member s21be :
        phi : float *
        dm : float *
        ifail : int byref -> float

Parameters

phi
Type: System..::..Double
On entry: the arguments ϕ and m of the function.
Constraints:
  • 0.0≤phi≤π 2;
  • dm×sin 2 phi≤1.0;
  • Only one of sin phi and dm may be 1.0.
Note that dm×sin 2 phi=1.0 is allowable, as long as dm≠1.0.
dm
Type: System..::..Double
On entry: the arguments ϕ and m of the function.
Constraints:
  • 0.0≤phi≤π 2;
  • dm×sin 2 phi≤1.0;
  • Only one of sin phi and dm may be 1.0.
Note that dm×sin 2 phi=1.0 is allowable, as long as dm≠1.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s21be returns a value of the classical (Legendre) form of the incomplete elliptic integral of the first kind.

Description

s21be calculates an approximation to the integral
F ϕ∣m=∫0 ϕ 1-m sin 2 θ-12 dθ,
where 0≤ϕ≤π 2, m sin 2 ϕ≤1 and m and sin ϕ may not both equal one.
The integral is computed using the symmetrised elliptic integrals of Carlson (Carlson (1979) and Carlson (1988)). The relevant identity is
F ϕ∣m=RF q,r,1 sin ϕ,
where q=cos 2 ϕ, r=1-m sin 2 ϕ and RF is the Carlson symmetrised incomplete elliptic integral of the first kind (see s21bb).

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Carlson B C (1979) Computing elliptic integrals by duplication Numerische Mathematik 33 1–16
Carlson B C (1988) A table of elliptic integrals of the third kind Math. Comput. 51 267–280

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
phi lies outside the range 0,π 2. On failure, the method returns zero.
ifail=2
On entry, dm×sin 2 phi>1.0; the function is undefined. On failure, the method returns zero.
ifail=3
On entry, sin phi=1.0 and dm=1.0; the function is infinite. On failure, the method returns the largest machine number (see x02al).
ifail=-9000
An error occured, see message report.

Accuracy

In principle s21be is capable of producing full machine precision. However round-off errors in internal arithmetic will result in slight loss of accuracy. This loss should never be excessive as the algorithm does not involve any significant amplification of round-off error. It is reasonable to assume that the result is accurate to within a small multiple of the machine precision.

Parallelism and Performance

None.

Further Comments

You should consult (S not in this release), which shows the relationship between this method and the Carlson definitions of the elliptic integrals. In particular, the relationship between the argument-constraints for both forms becomes clear.
For more information on the algorithm used to compute RF, see the method document for s21bb.
If you wish to input a value of phi outside the range allowed by this method you should refer to Section 17.4 of Abramowitz and Stegun (1972) for useful identities. For example, F-ϕ|m=-F ϕ|m and F sπ±ϕ|m=2 sK m±F ϕ|m where s is an integer and K m is the complete elliptic integral given by s21bh.
A parameter m>1 can be replaced by one less than unity using F ϕ|m=1 m F θ|1 m, sin θ=m sin ϕ.

Example

This example simply generates a small set of nonextreme arguments that are used with the method to produce the table of results.

Example program (C#): s21bee.cs

Example program results: s21bee.r

See Also

S Class
S Members


s21bf Method

[image]

NAG Library for .NET Release 2
S..::s21bf Method
S Class See Also Send Feedback
s21bf returns a value of the classical (Legendre) form of the incomplete elliptic integral of the second kind.

Syntax

C#
public static double s21bf(
    double phi,
    double dm,
    out int ifail
)
Visual Basic
Public Shared Function s21bf ( _
    phi As Double, _
    dm As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s21bf(
    double phi,
    double dm,
    [OutAttribute] int% ifail
)
F#
static member s21bf :
        phi : float *
        dm : float *
        ifail : int byref -> float

Parameters

phi
Type: System..::..Double
On entry: the arguments ϕ and m of the function.
Constraints:
  • 0.0≤phi≤π 2;
  • dm×sin 2 phi≤1.0.
dm
Type: System..::..Double
On entry: the arguments ϕ and m of the function.
Constraints:
  • 0.0≤phi≤π 2;
  • dm×sin 2 phi≤1.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s21bf returns a value of the classical (Legendre) form of the incomplete elliptic integral of the second kind.

Description

s21bf calculates an approximation to the integral
E ϕ∣m=∫0 ϕ 1-m sin 2 θ 12 dθ,
where 0≤ϕ≤π 2 and m sin 2 ϕ≤1.
The integral is computed using the symmetrised elliptic integrals of Carlson (Carlson (1979) and Carlson (1988)). The relevant identity is
E ϕ∣m=sin ϕ RF q,r,1-13 m sin 3 ϕ RD q,r,1,
where q=cos 2 ϕ, r=1-m sin 2 ϕ, RF is the Carlson symmetrised incomplete elliptic integral of the first kind (see s21bb) and RD is the Carlson symmetrised incomplete elliptic integral of the second kind (see s21bc).

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Carlson B C (1979) Computing elliptic integrals by duplication Numerische Mathematik 33 1–16
Carlson B C (1988) A table of elliptic integrals of the third kind Math. Comput. 51 267–280

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
phi lies outside the range 0,π 2. On failure, the method returns zero.
ifail=2
On entry, dm×sin 2 phi>1.0; the function is undefined. On failure, the method returns zero.
ifail=-9000
An error occured, see message report.

Accuracy

In principle s21bf is capable of producing full machine precision. However round-off errors in internal arithmetic will result in slight loss of accuracy. This loss should never be excessive as the algorithm does not involve any significant amplification of round-off error. It is reasonable to assume that the result is accurate to within a small multiple of the machine precision.

Parallelism and Performance

None.

Further Comments

You should consult (S not in this release), which shows the relationship between this method and the Carlson definitions of the elliptic integrals. In particular, the relationship between the argument-constraints for both forms becomes clear.
For more information on the algorithms used to compute RF and RD, see the method documents for s21bb and s21bc, respectively.
If you wish to input a value of phi outside the range allowed by this method you should refer to Section 17.4 of Abramowitz and Stegun (1972) for useful identities. For example, E-ϕ|m=-E ϕ|m. A parameter m>1 can be replaced by one less than unity using E ϕ|m=m E ϕ⁢m|1 m-m-1 ϕ.

Example

This example simply generates a small set of nonextreme arguments that are used with the method to produce the table of results.

Example program (C#): s21bfe.cs

Example program results: s21bfe.r

See Also

S Class
S Members


s21bg Method

[image]

NAG Library for .NET Release 2
S..::s21bg Method
S Class See Also Send Feedback
s21bg returns a value of the classical (Legendre) form of the incomplete elliptic integral of the third kind.

Syntax

C#
public static double s21bg(
    double dn,
    double phi,
    double dm,
    out int ifail
)
Visual Basic
Public Shared Function s21bg ( _
    dn As Double, _
    phi As Double, _
    dm As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s21bg(
    double dn,
    double phi,
    double dm,
    [OutAttribute] int% ifail
)
F#
static member s21bg :
        dn : float *
        phi : float *
        dm : float *
        ifail : int byref -> float

Parameters

dn
Type: System..::..Double
On entry: the arguments n, ϕ and m of the function.
Constraints:
  • 0.0≤phi≤π 2;
  • dm×sin 2 phi≤1.0;
  • Only one of sin phi and dm may be 1.0;
  • dn×sin 2 phi≠1.0.
Note that dm×sin 2 phi=1.0 is allowable, as long as dm≠1.0.
phi
Type: System..::..Double
On entry: the arguments n, ϕ and m of the function.
Constraints:
  • 0.0≤phi≤π 2;
  • dm×sin 2 phi≤1.0;
  • Only one of sin phi and dm may be 1.0;
  • dn×sin 2 phi≠1.0.
Note that dm×sin 2 phi=1.0 is allowable, as long as dm≠1.0.
dm
Type: System..::..Double
On entry: the arguments n, ϕ and m of the function.
Constraints:
  • 0.0≤phi≤π 2;
  • dm×sin 2 phi≤1.0;
  • Only one of sin phi and dm may be 1.0;
  • dn×sin 2 phi≠1.0.
Note that dm×sin 2 phi=1.0 is allowable, as long as dm≠1.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s21bg returns a value of the classical (Legendre) form of the incomplete elliptic integral of the third kind.

Description

s21bg calculates an approximation to the integral
Π n;ϕ∣m=∫0 ϕ 1-n sin 2 θ-11-m sin 2 θ-12 dθ,
where 0≤ϕ≤π 2, m sin 2 ϕ≤1, m and sin ϕ may not both equal one, and n sin 2 ϕ≠1.
The integral is computed using the symmetrised elliptic integrals of Carlson (Carlson (1979) and Carlson (1988)). The relevant identity is
Π n;ϕ∣m=sin ϕ RF q,r,1+13 n sin 3 ϕ RJ q,r,1,s,
where q=cos 2 ϕ, r=1-m sin 2 ϕ, s=1-n sin 2 ϕ, RF is the Carlson symmetrised incomplete elliptic integral of the first kind (see s21bb) and RJ is the Carlson symmetrised incomplete elliptic integral of the third kind (see s21bd).

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Carlson B C (1979) Computing elliptic integrals by duplication Numerische Mathematik 33 1–16
Carlson B C (1988) A table of elliptic integrals of the third kind Math. Comput. 51 267–280

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
phi lies outside the range 0,π 2. On failure, the method returns zero.
ifail=2
On entry, dm×sin 2 phi>1.0; the function is undefined. On failure, the method returns zero.
ifail=3
On entry, sin phi=1.0 and dm=1.0; the function is infinite. On failure, the method returns the largest machine number (see x02al).
ifail=4
On entry, the product dn×sin 2 phi=1.0; the function is infinite. On failure, the method returns the largest machine number (see x02al).
ifail=-9000
An error occured, see message report.

Accuracy

In principle s21bg is capable of producing full machine precision. However round-off errors in internal arithmetic will result in slight loss of accuracy. This loss should never be excessive as the algorithm does not involve any significant amplification of round-off error. It is reasonable to assume that the result is accurate to within a small multiple of the machine precision.

Parallelism and Performance

None.

Further Comments

You should consult (S not in this release), which shows the relationship between this method and the Carlson definitions of the elliptic integrals. In particular, the relationship between the argument-constraints for both forms becomes clear.
For more information on the algorithms used to compute RF and RJ, see the method documents for s21bb and s21bd, respectively.
If you wish to input a value of phi outside the range allowed by this method you should refer to Section 17.4 of Abramowitz and Stegun (1972) for useful identities.

Example

This example simply generates a small set of nonextreme arguments that are used with the method to produce the table of results.

Example program (C#): s21bge.cs

Example program results: s21bge.r

See Also

S Class
S Members


s21bh Method

[image]

NAG Library for .NET Release 2
S..::s21bh Method
S Class See Also Send Feedback
s21bh returns a value of the classical (Legendre) form of the complete elliptic integral of the first kind.

Syntax

C#
public static double s21bh(
    double dm,
    out int ifail
)
Visual Basic
Public Shared Function s21bh ( _
    dm As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s21bh(
    double dm,
    [OutAttribute] int% ifail
)
F#
static member s21bh :
        dm : float *
        ifail : int byref -> float

Parameters

dm
Type: System..::..Double
On entry: the argument m of the function.
Constraint: dm<1.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s21bh returns a value of the classical (Legendre) form of the complete elliptic integral of the first kind.

Description

s21bh calculates an approximation to the integral
K m=∫0 π 2 1-m sin 2 θ-12 dθ,
where m<1.
The integral is computed using the symmetrised elliptic integrals of Carlson (Carlson (1979) and Carlson (1988)). The relevant identity is
K m=RF 0,1-m,1,
where RF is the Carlson symmetrised incomplete elliptic integral of the first kind (see s21bb).

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Carlson B C (1979) Computing elliptic integrals by duplication Numerische Mathematik 33 1–16
Carlson B C (1988) A table of elliptic integrals of the third kind Math. Comput. 51 267–280

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, dm>1.0; the function is undefined. On failure, the method returns zero.
ifail=2
On entry, dm=1.0; the function is infinite. On failure, the method returns the largest machine number (see x02al).
ifail=-9000
An error occured, see message report.

Accuracy

In principle s21bh is capable of producing full machine precision. However round-off errors in internal arithmetic will result in slight loss of accuracy. This loss should never be excessive as the algorithm does not involve any significant amplification of round-off error. It is reasonable to assume that the result is accurate to within a small multiple of the machine precision.

Parallelism and Performance

None.

Further Comments

You should consult (S not in this release), which shows the relationship between this method and the Carlson definitions of the elliptic integrals. In particular, the relationship between the argument-constraints for both forms becomes clear.
For more information on the algorithm used to compute RF, see the method document for s21bb.

Example

This example simply generates a small set of nonextreme arguments that are used with the method to produce the table of results.

Example program (C#): s21bhe.cs

Example program results: s21bhe.r

See Also

S Class
S Members


s21bj Method

[image]

NAG Library for .NET Release 2
S..::s21bj Method
S Class See Also Send Feedback
s21bj returns a value of the classical (Legendre) form of the complete elliptic integral of the second kind.

Syntax

C#
public static double s21bj(
    double dm,
    out int ifail
)
Visual Basic
Public Shared Function s21bj ( _
    dm As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s21bj(
    double dm,
    [OutAttribute] int% ifail
)
F#
static member s21bj :
        dm : float *
        ifail : int byref -> float

Parameters

dm
Type: System..::..Double
On entry: the argument m of the function.
Constraint: dm≤1.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s21bj returns a value of the classical (Legendre) form of the complete elliptic integral of the second kind.

Description

s21bj calculates an approximation to the integral
E m=∫0 π 2 1-m sin 2 θ 12 dθ,
where m≤1.
The integral is computed using the symmetrised elliptic integrals of Carlson (Carlson (1979) and Carlson (1988)). The relevant identity is
E m=RF 0,1-m,1-13 m RD 0,1-m,1,
where RF is the Carlson symmetrised incomplete elliptic integral of the first kind (see s21bb) and RD is the Carlson symmetrised incomplete elliptic integral of the second kind (see s21bc).

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Carlson B C (1979) Computing elliptic integrals by duplication Numerische Mathematik 33 1–16
Carlson B C (1988) A table of elliptic integrals of the third kind Math. Comput. 51 267–280

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, dm>1.0; the function is undefined. On failure, the method returns zero.
ifail=-9000
An error occured, see message report.

Accuracy

In principle s21bj is capable of producing full machine precision. However round-off errors in internal arithmetic will result in slight loss of accuracy. This loss should never be excessive as the algorithm does not involve any significant amplification of round-off error. It is reasonable to assume that the result is accurate to within a small multiple of the machine precision.

Parallelism and Performance

None.

Further Comments

You should consult (S not in this release), which shows the relationship between this method and the Carlson definitions of the elliptic integrals. In particular, the relationship between the argument-constraints for both forms becomes clear.
For more information on the algorithms used to compute RF and RD, see the method documents for s21bb and s21bc, respectively.

Example

This example simply generates a small set of nonextreme arguments that are used with the method to produce the table of results.

Example program (C#): s21bje.cs

Example program results: s21bje.r

See Also

S Class
S Members


s21ca Method

[image]

NAG Library for .NET Release 2
S..::s21ca Method
S Class See Also Send Feedback
s21ca evaluates the Jacobian elliptic functions sn, cn and dn.

Syntax

C#
public static void s21ca(
    double u,
    double m,
    out double sn,
    out double cn,
    out double dn,
    out int ifail
)
Visual Basic
Public Shared Sub s21ca ( _
    u As Double, _
    m As Double, _
    <OutAttribute> ByRef sn As Double, _
    <OutAttribute> ByRef cn As Double, _
    <OutAttribute> ByRef dn As Double, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void s21ca(
    double u,
    double m,
    [OutAttribute] double% sn,
    [OutAttribute] double% cn,
    [OutAttribute] double% dn,
    [OutAttribute] int% ifail
)
F#
static member s21ca :
        u : float *
        m : float *
        sn : float byref *
        cn : float byref *
        dn : float byref *
        ifail : int byref -> unit

Parameters

u
Type: System..::..Double
On entry: the argument u and the parameter m of the functions, respectively.
Constraints:
  • abs u≤λ, where λ=1/x02am;
  • if abs u<1/λ, abs m≤λ.
m
Type: System..::..Double
On entry: the argument u and the parameter m of the functions, respectively.
Constraints:
  • abs u≤λ, where λ=1/x02am;
  • if abs u<1/λ, abs m≤λ.
sn
Type: System..::..Double %
On exit: the values of the functions sn u, cn u and dn u, respectively.
cn
Type: System..::..Double %
On exit: the values of the functions sn u, cn u and dn u, respectively.
dn
Type: System..::..Double %
On exit: the values of the functions sn u, cn u and dn u, respectively.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

s21ca evaluates the Jacobian elliptic functions of argument u and parameter m,
sn u∣m=sin ϕ,cn u∣m=cos ϕ,dn u∣m=1-m sin 2 ϕ,
where ϕ, called the amplitude of u, is defined by the integral
u=∫0 ϕ dθ1-m sin 2 θ.
The elliptic functions are sometimes written simply as sn u, cn u and dn u, avoiding explicit reference to the parameter m.
Another nine elliptic functions may be computed via the formulae
cd u=cn u/dn usd u=sn u/dn und u=1/dn udc u=dn u/cn unc u=1/cn usc u=sn u/cn uns u=1/sn uds u=dn u/sn ucs u=cn u/sn u
(see Abramowitz and Stegun (1972)).
s21ca is based on a procedure given by Bulirsch (1960), and uses the process of the arithmetic-geometric mean (16.9 in Abramowitz and Stegun (1972)). Constraints are placed on the values of u and m in order to avoid the possibility of machine overflow.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Bulirsch R (1960) Numerical calculation of elliptic integrals and elliptic functions Numer. Math. 7 76–90

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, abs u>λ, where λ=1/x02am.
ifail=2
On entry, abs m>λ and abs u<1/λ.
ifail=-9000
An error occured, see message report.

Accuracy

In principle the method is capable of achieving full relative precision in the computed values. However, the accuracy obtainable in practice depends on the accuracy of the standard elementary functions such as SIN and COS.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads values of the argument u and parameter m from a file, evaluates the function and prints the results.

Example program (C#): s21cae.cs

Example program data: s21cae.d

Example program results: s21cae.r

See Also

S Class
S Members


s21cb Method

[image]

NAG Library for .NET Release 2
S..::s21cb Method
S Class See Also Send Feedback
s21cb evaluates the Jacobian elliptic functions sn z, cn z and dn z for a complex argument z.

Syntax

C#
public static void s21cb(
    Complex z,
    double ak2,
    out Complex sn,
    out Complex cn,
    out Complex dn,
    out int ifail
)
Visual Basic
Public Shared Sub s21cb ( _
    z As Complex, _
    ak2 As Double, _
    <OutAttribute> ByRef sn As Complex, _
    <OutAttribute> ByRef cn As Complex, _
    <OutAttribute> ByRef dn As Complex, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void s21cb(
    Complex z,
    double ak2,
    [OutAttribute] Complex% sn,
    [OutAttribute] Complex% cn,
    [OutAttribute] Complex% dn,
    [OutAttribute] int% ifail
)
F#
static member s21cb :
        z : Complex *
        ak2 : float *
        sn : Complex byref *
        cn : Complex byref *
        dn : Complex byref *
        ifail : int byref -> unit

Parameters

z
Type: NagLibrary..::..Complex
On entry: the argument z of the functions.
Constraints:
  • abs Re(z)≤=λ;
  • abs Im(z)≤λ, where λ=1/x02am.
ak2
Type: System..::..Double
On entry: the value of k 2.
Constraint: 0.0≤ak2≤1.0.
sn
Type: NagLibrary..::..Complex %
On exit: the values of the functions sn z, cn z and dn z, respectively.
cn
Type: NagLibrary..::..Complex %
On exit: the values of the functions sn z, cn z and dn z, respectively.
dn
Type: NagLibrary..::..Complex %
On exit: the values of the functions sn z, cn z and dn z, respectively.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

s21cb evaluates the Jacobian elliptic functions sn z∣k, cn z∣k and dn z∣k given by
sn z∣k=sin ϕcn z∣k=cos ϕdn z∣k=1-k 2 sin 2 ϕ,
where z is a complex argument, k is a real parameter (the modulus) with k 2≤1 and ϕ (the amplitude of z) is defined by the integral
z=∫0 ϕ dθ1-k 2 sin 2 θ.
The above definitions can be extended for values of k 2>1 (see Salzer (1962)) by means of the formulae
sn z∣k=k 1 sn kz∣k 1cn z∣k=dn kz∣k 1dn z∣k=cn kz∣k 1,
where k 1=1/k.
Special values include
sn z∣0=sin zcn z∣0=cos zdn z∣0=1sn z∣1=tanh zcn z∣1=sech zdn z∣1=sech z.
These functions are often simply written as sn z, cn z and dn z, thereby avoiding explicit reference to the parameter k. They can also be expressed in terms of Jacobian theta functions (see s21cc).
Another nine elliptic functions may be computed via the formulae
cd z=cn z/dn zsd z=sn z/dn znd z=1/dn zdc z=dn z/cn znc z=1/cn zsc z=sn z/cn zns z=1/sn zds z=dn z/sn zcs z=cn z/sn z
(see Abramowitz and Stegun (1972)).
The values of sn z, cn z and dn z are obtained by calls to s21ca. Further details can be found in [Further Comments].

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Salzer H E (1962) Quick calculation of Jacobian elliptic functions Comm. ACM 5 399

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | ak2<0.0,
or | ak2>1.0,
or | abs Re z>λ,
or | abs Im z>λ, where λ=1/x02am.
ifail=-9000
An error occured, see message report.

Accuracy

In principle the method is capable of achieving full relative precision in the computed values. However, the accuracy obtainable in practice depends on the accuracy of the standard elementary functions such as SIN and COS.

Parallelism and Performance

None.

Further Comments

The values of sn z, cn z and dn z are computed via the formulae
sn z=sn u,kdn v,k′1-dn 2 u,ksn 2 v,k′+i cn u,kdn u,ksn v,k′cn v,k′1-dn 2 u,ksn 2 v,k′cn z=cn u,kcn v,k′1-dn 2 u,ksn 2 v,k′-i sn u,kdn u,ksn v,k′dn v,k′1-dn 2 u,ksn 2 v,k′dn z=dn u,kcn v,k′dn v,k′1-dn 2 u,ksn 2 v,k′-i k 2 sn u,kcn u,ksn v,k′1-dn 2 u,ksn 2 v,k′,
where z=u+iv and k′=1-k 2 (the complementary modulus).

Example

This example evaluates sn z, cn z and dn z at z=-2.0+3.0 i when k=0.5, and prints the results.

Example program (C#): s21cbe.cs

Example program data: s21cbe.d

Example program results: s21cbe.r

See Also

S Class
S Members


s21cc Method

[image]

NAG Library for .NET Release 2
S..::s21cc Method
S Class See Also Send Feedback
s21cc returns the value of one of the Jacobian theta functions θ 0 x,q, θ 1 x,q, θ 2 x,q, θ 3 x,q or θ 4 x,q for a real argument x and non-negative q<1.

Syntax

C#
public static double s21cc(
    int k,
    double x,
    double q,
    out int ifail
)
Visual Basic
Public Shared Function s21cc ( _
    k As Integer, _
    x As Double, _
    q As Double, _
    <OutAttribute> ByRef ifail As Integer _
) As Double
Visual C++
public:
static double s21cc(
    int k,
    double x,
    double q,
    [OutAttribute] int% ifail
)
F#
static member s21cc :
        k : int *
        x : float *
        q : float *
        ifail : int byref -> float

Parameters

k
Type: System..::..Int32
On entry: denotes the function θk x,q to be evaluated. Note that k=4 is equivalent to k=0.
Constraint: 0≤k≤4.
x
Type: System..::..Double
On entry: the argument x of the function.
q
Type: System..::..Double
On entry: the argument q of the function.
Constraint: 0.0≤q<1.0.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Return Value

s21cc returns the value of one of the Jacobian theta functions θ 0 x,q, θ 1 x,q, θ 2 x,q, θ 3 x,q or θ 4 x,q for a real argument x and non-negative q<1.

Description

s21cc evaluates an approximation to the Jacobian theta functions θ 0 x,q, θ 1 x,q, θ 2 x,q, θ 3 x,q and θ 4 x,q given by
θ 0 x,q=1+2∑n=1∞-1 nq n 2 cos 2 nπx,θ 1 x,q=2∑n=0∞-1 nq n+12 2 sin 2 n+1 πx,θ 2 x,q=2∑n=0∞q n+12 2 cos 2 n+1 πx,θ 3 x,q=1+2∑n=1∞q n 2 cos 2 nπx,θ 4 x,q=θ 0 x,q,
where x and q (the nome) are real with 0≤q<1.
These functions are important in practice because every one of the Jacobian elliptic functions (see s21cb) can be expressed as the ratio of two Jacobian theta functions (see Whittaker and Watson (1990)). There is also a bewildering variety of notations used in the literature to define them. Some authors (e.g., Section 16.27 of Abramowitz and Stegun (1972)) define the argument in the trigonometric terms to be x instead of πx. This can often lead to confusion, so great care must therefore be exercised when consulting the literature. Further details (including various relations and identities) can be found in the references.
s21cc is based on a truncated series approach. If t differs from x or -x by an integer when 0≤t≤12, it follows from the periodicity and symmetry properties of the functions that θ 1 x,q=±θ 1 t,q and θ 3 x,q=±θ 3 t,q. In a region for which the approximation is sufficiently accurate, θ 1 is set equal to the first term (n=0) of the transformed series
θ 1 t,q=2 λπ e-λ t 2∑n=0∞-1 ne-λ n+12 2 sinh 2 n+1 λt
and θ 3 is set equal to the first two terms (i.e., n≤1) of
θ 3 t,q=λπ e-λ t 2 1+2∑n=1∞e-λ n 2 cosh 2 nλt,
where λ=π 2/loge q. Otherwise, the trigonometric series for θ 1 t,q and θ 3 t,q are used. For all values of x, θ 0 and θ 2 are computed from the relations θ 0 x,q=θ 3 12-x,q and θ 2 x,q=θ 1 12-x,q.

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications
Byrd P F and Friedman M D (1971) Handbook of Elliptic Integrals for Engineers and Scientists pp. 315–320 (2nd Edition) Springer–Verlag
Magnus W, Oberhettinger F and Soni R P (1966) Formulas and Theorems for the Special Functions of Mathematical Physics 371–377 Springer–Verlag
Tølke F (1966) Praktische Funktionenlehre (Bd. II) 1–38 Springer–Verlag
Whittaker E T and Watson G N (1990) A Course in Modern Analysis (4th Edition) Cambridge University Press

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | k<0,
or | k>4,
or | q<0.0,
or | q≥1.0,
ifail=2
The evaluation has been abandoned because the function value is infinite. The result is returned as the largest machine representable number (see x02al).
ifail=-9000
An error occured, see message report.

Accuracy

In principle the method is capable of achieving full relative precision in the computed values. However, the accuracy obtainable in practice depends on the accuracy of the standard elementary functions such as sin and cos.

Parallelism and Performance

None.

Further Comments

None.

Example

This example evaluates θ 2 x,q at x=0.7 when q=0.4, and prints the results.

Example program (C#): s21cce.cs

Example program data: s21cce.d

Example program results: s21cce.r

See Also

S Class
S Members


s22aa Method

[image]

NAG Library for .NET Release 2
S..::s22aa Method
S Class See Also Send Feedback
s22aa returns a sequence of values for either the unnormalized or normalized Legendre functions of the first kind Pnm x or Pnm¯x for real x of a given order m and degree n=0,1,…,N.

Syntax

C#
public static void s22aa(
    int mode,
    double x,
    int m,
    int nl,
    double[] p,
    out int ifail
)
Visual Basic
Public Shared Sub s22aa ( _
    mode As Integer, _
    x As Double, _
    m As Integer, _
    nl As Integer, _
    p As Double(), _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void s22aa(
    int mode,
    double x,
    int m,
    int nl,
    array<double>^ p,
    [OutAttribute] int% ifail
)
F#
static member s22aa :
        mode : int *
        x : float *
        m : int *
        nl : int *
        p : float[] *
        ifail : int byref -> unit

Parameters

mode
Type: System..::..Int32
On entry: indicates whether the sequence of function values is to be returned unnormalized or normalized.
mode=1
The sequence of function values is returned unnormalized.
mode=2
The sequence of function values is returned normalized.
Constraint: mode=1 or 2.
x
Type: System..::..Double
On entry: the argument x of the function.
Constraint: abs x≤1.0.
m
Type: System..::..Int32
On entry: the order m of the function.
Constraint: abs m≤27.
nl
Type: System..::..Int32
On entry: the degree N of the last function required in the sequence.
Constraints:
  • nl≥0;
  • if m=0, nl≤100;
  • if m≠0, nl≤55-abs m.
p
Type: array< System..::..Double >[]()[][]
An array of size [0:nl]
On exit: the required sequence of function values as follows:
  • if mode=1, p[n] contains Pnm x, for n=0,1,…,N;
  • if mode=2, p[n] contains Pnm¯x, for n=0,1,…,N.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

s22aa evaluates a sequence of values for either the unnormalized or normalized Legendre (m=0) or associated Legendre (m≠0) functions of the first kind Pnm x or Pnm¯x, where x is real with -1≤x≤1, of order m and degree n=0,1,…,N defined by
Pnm x=1-x 2 m/2 dm d xm Pn x  if ​m≥0,Pnm x=n+m!n-m!Pn-m x  if ​m<0  andPnm¯x=2 n+1 2n-m!n+m!Pnm x
respectively; Pn x is the (unassociated) Legendre polynomial of degree n given by
Pn x≡Pn 0 x=1 2 n n!dn d xn x 2-1 n
(the Rodrigues formula). Note that some authors (e.g., Abramowitz and Stegun (1972)) include an additional factor of -1 m (the Condon–Shortley Phase) in the definitions of Pnm x and Pnm¯x. They use the notation P mn x≡-1 m Pnm x in order to distinguish between the two cases.
s22aa is based on a standard recurrence relation described in Section 8.5.3 of Abramowitz and Stegun (1972). Constraints are placed on the values of m and n in order to avoid the possibility of machine overflow. It also sets the appropriate elements of the array p (see [Parameters]) to zero whenever the required function is not defined for certain values of m and n (e.g., m=-5 and n=3).

References

Abramowitz M and Stegun I A (1972) Handbook of Mathematical Functions (3rd Edition) Dover Publications

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, | abs x>1.0,
or | mode≠1 or 2,
or | nl<0,
or | nl>100 when m=0,
or | abs m>27,
or | nl+abs m>55 when m≠0.
ifail=-9000
An error occured, see message report.
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

The computed function values should be accurate to within a small multiple of the machine precision except when underflow (or overflow) occurs, in which case the true function values are within a small multiple of the underflow (or overflow) threshold of the machine.

Parallelism and Performance

None.

Further Comments

None.

Example

This example reads the values of the arguments x, m and N from a file, calculates the sequence of unnormalized associated Legendre function values Pnm x,P n+1 m x,…,P n+N m x, and prints the results.

Example program (C#): s22aae.cs

Example program data: s22aae.d

Example program results: s22aae.r

See Also

S Class
S Members


X01 Class

[image]

NAG Library for .NET Release 2
X01 Class
Members See Also Send Feedback
This chapter is concerned with the provision of mathematical constants required by other methods within the Library.

Syntax

C#
public static class X01
Visual Basic
Public NotInheritable Class X01
Visual C++
public ref class X01 abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type X01 =  class end

Background to the Problems

Some Library methods require mathematical constants. These methods call X01 class and thus lessen the number of changes that have to be made between different implementations of the Library.

Recommendations on Choice and Use of Available Methods

Although these methods are primarily intended for use by other methods they may be accessed directly by you.
Euler's constant, γ x01ab
π x01aa
The parameter X of these methods is a dummy parameter.

Inheritance Hierarchy

System..::..Object
NagLibrary..::..X01

See Also

X01 Members


X01 Members

[image] [image]

NAG Library for .NET Release 2
X01 Members
X01 Class Methods See Also Send Feedback

The X01 type exposes the following members.

Methods

Name | Description
x01aa | x01aa returns the numerical value of π.
x01ab | x01ab returns the numerical value of γ (Euler's constant).

See Also

X01 Class


X01 Methods

[image] [image]

NAG Library for .NET Release 2
X01 Methods
X01 Class See Also Send Feedback

The X01 type exposes the following members.

Methods

Name | Description
x01aa | x01aa returns the numerical value of π.
x01ab | x01ab returns the numerical value of γ (Euler's constant).

See Also

X01 Class


x01aa Method

[image]

NAG Library for .NET Release 2
X01..::x01aa Method
X01 Class See Also Send Feedback
x01aa returns the numerical value of π.

Syntax

C#
public static double x01aa()
Visual Basic
Public Shared Function x01aa As Double
Visual C++
public:
static double x01aa()
F#
static member x01aa : unit -> float

Return Value

x01aa returns the numerical value of π.

Description

None.

References

None.

Error Indicators and Warnings

None.

Accuracy

The result should be correct to machine precision (see X02 class).

Parallelism and Performance

None.

Further Comments

None.

Example

None.

See Also

X01 Class
X01 Members


x01ab Method

[image]

NAG Library for .NET Release 2
X01..::x01ab Method
X01 Class See Also Send Feedback
x01ab returns the numerical value of γ (Euler's constant).

Syntax

C#
public static double x01ab()
Visual Basic
Public Shared Function x01ab As Double
Visual C++
public:
static double x01ab()
F#
static member x01ab : unit -> float

Return Value

x01ab returns the numerical value of γ (Euler's constant).

Description

None.

References

None.

Error Indicators and Warnings

None.

Accuracy

The result should be correct to machine precision (see X02 class).

Parallelism and Performance

None.

Further Comments

None.

Example

None.

See Also

X01 Class
X01 Members


X02 Class

[image]

NAG Library for .NET Release 2
X02 Class
Members See Also Send Feedback
This chapter is concerned with parameters which characterise certain aspects of the computing environment in which the NAG Library is implemented. They relate primarily to floating-point arithmetic, but also to integer arithmetic, the elementary functions and exception handling. The values of the parameters vary from one implementation of the Library to another, but within the context of a single implementation they are constants.
The parameters are intended for use primarily by other methods in the Library, but users of the Library may sometimes need to refer to them directly.

Syntax

C#
public static class X02
Visual Basic
Public NotInheritable Class X02
Visual C++
public ref class X02 abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type X02 =  class end

Background to the Problems

Floating-point Arithmetic

A model of floating-point arithmetic

In order to characterise the important properties of floating-point arithmetic by means of a small number of parameters, NAG uses a simplified model of floating-point arithmetic. The parameters of the model can be chosen to provide a sufficiently close description of the behaviour of actual implementations of floating-point arithmetic, but not, in general, an exact description; actual implementations vary too much in the details of how numbers are represented or arithmetic operations are performed.
The model is based on that developed by Brown (1981), but differs in some respects. The essential features are summarised here.
The model is characterised by four integer parameters. The four integer parameters are:
b: | the base
p: | the precision (i.e., the number of significant base-b digits)
emin: | the minimum exponent
emax: | the maximum exponent
These parameters define a set of numerical values of the form:
f×be
where the exponent e must lie in the range [emin,emax], and the fraction f (also called the mantissa or significand) lies in the range 1/b,1, and may be written
f=0.f 1f 2⋯fp
Thus f is a p-digit fraction to the base b; the fi are the base-b digits of the fraction: they are integers in the range 0 to b-1, and the leading digit f 1 must not be zero.
The set of values so defined (together with zero) are called model numbers. For example, if b=10, p=5, emin=-99 and emax=+99, then a typical model number is 0.12345×1067.
The model numbers must obey certain rules for the computed results of the following basic arithmetic operations: addition, subtraction, multiplication, negation, absolute value, and comparisons: the computed result must be the nearest model number to the exact result (assuming that overflow or underflow does not occur); if the exact result is midway between two model numbers, then it may be rounded either way.
For division and square root, this latter rule is relaxed: the computed result may also be one of the next adjacent model numbers on either side of the permitted values just stated.
On many machines, the full set of representable floating-point numbers conforms to the rules of the model with appropriate values of b, p, emin and emax. For machines supporting IEEE binary double precision arithmetic:
b=2p=53emin=-1021emax=1024.
(Note: the model used here differs from that described in Brown (1981) in the following respect: square-root is treated, like division, as a weakly supported operator.)

Derived parameters of floating-point arithmetic

Most numerical algorithms require access, not to the basic parameters of the model, but to certain derived values, of which the most important are:
the machine precision ε: | =12×b 1-p
the smallest positive model number: | =b emin-1
the largest positive model number: | =1-b-p×b emax
It is important to note that the machine precision defined here differs from that defined by ISO (1997).
Two additional derived values are used in the NAG Library. Their definitions depend not only on the properties of the basic arithmetic operations just considered, but also on properties of some of the elementary functions. We define the safe range parameter to be the smallest positive model number z such that for any x in the range z,1/z the following can be computed without undue loss of accuracy, overflow, underflow or other error:
  • -x
  • 1/x
  • -1/x
  • x
  • log x
  • exp log x
  • y log x/log y for any y
In a similar fashion we define the safe range parameter for complex arithmetic as the smallest positive model number z such that for any x in the range [z,1/z] the following can be computed without any undue loss of accuracy, overflow, underflow or other error:
  • -w
  • 1/w
  • -1/w
  • w
  • log w
  • exp log w
  • y log w/log y for any y
  • w
where w is any of x, ix, x+ix, 1/x, i/x, 1/x+i/x, and i is the square root of -1.
This parameter was introduced to take account of the quality of complex arithmetic on the machine. On machines with well implemented complex arithmetic, its value will differ from that of the real safe range parameter by a small multiplying factor less than 10. For poorly implemented complex arithmetic this factor may be larger by many orders of magnitude.

Other Aspects of the Computing Environment

No attempt has been made to characterise comprehensively any other aspects of the computing environment. The other functions in this chapter provide specific information that is occasionally required by methods in the Library.

Recommendations on Choice and Use of Available Methods

Derived parameters of model of floating-point arithmetic,
largest positive model number x02al
machine precision x02aj
safe range x02am
smallest positive model number x02ak
Largest representable integer x02bb
Maximum number of decimal digits that can be represented x02be
Parameters of model of floating-point arithmetic,
b x02bh

References

Brown W S (1981) A simple but realistic model of floating-point computation ACM Trans. Math. Software 7 445–480
ISO (1997) ISO Fortran 95 programming language (ISO/IEC 1539–1:1997)

Inheritance Hierarchy

System..::..Object
NagLibrary..::..X02

See Also

X02 Members


X02 Members

[image] [image]

NAG Library for .NET Release 2
X02 Members
X02 Class Methods See Also Send Feedback

The X02 type exposes the following members.

Methods

Name | Description
x02aj | x02aj returns ε, the value machine precision.
x02ak | x02ak returns the smallest positive floating-point number.
x02al | x02al returns the largest positive floating-point number.
x02am | x02am returns the safe range of floating-point arithmetic.
x02bb | x02bb returns the largest representable positive integer value.
x02be | x02be returns the maximum number of decimal digits which can be accurately represented over the whole range of floating-point numbers.
x02bh | x02bh returns the base parameter b of the model of floating-point arithmetic as described in the X02 class.

See Also

X02 Class


X02 Methods

[image] [image]

NAG Library for .NET Release 2
X02 Methods
X02 Class See Also Send Feedback

The X02 type exposes the following members.

Methods

Name | Description
x02aj | x02aj returns ε, the value machine precision.
x02ak | x02ak returns the smallest positive floating-point number.
x02al | x02al returns the largest positive floating-point number.
x02am | x02am returns the safe range of floating-point arithmetic.
x02bb | x02bb returns the largest representable positive integer value.
x02be | x02be returns the maximum number of decimal digits which can be accurately represented over the whole range of floating-point numbers.
x02bh | x02bh returns the base parameter b of the model of floating-point arithmetic as described in the X02 class.

See Also

X02 Class


x02aj Method

[image]

NAG Library for .NET Release 2
X02..::x02aj Method
X02 Class See Also Send Feedback
x02aj returns ε, the value machine precision.

Syntax

C#
public static double x02aj()
Visual Basic
Public Shared Function x02aj As Double
Visual C++
public:
static double x02aj()
F#
static member x02aj : unit -> float

Return Value

x02aj returns ε, the value machine precision.

Description

x02aj returns machine precision, computed as ε=12×b 1-p, where b is the arithmetic base (see x02bh) and p is the number of significant base-b digits (see (X02BJF not in this release)).
It is important to note that the definition of ε here differs from that in ISO (1997).

References

ISO (1997) ISO Fortran 95 programming language (ISO/IEC 1539–1:1997)

Error Indicators and Warnings

None.

Accuracy

None.

Parallelism and Performance

None.

Further Comments

None.

Example

This example prints the values of all the functions in X02 class. The results will vary from one implementation of the Library to another.

Example program (C#): x02aje.cs

Example program results: x02aje.r

See Also

X02 Class
X02 Members


x02ak Method

[image]

NAG Library for .NET Release 2
X02..::x02ak Method
X02 Class See Also Send Feedback
x02ak returns the smallest positive floating-point number.

Syntax

C#
public static double x02ak()
Visual Basic
Public Shared Function x02ak As Double
Visual C++
public:
static double x02ak()
F#
static member x02ak : unit -> float

Return Value

x02ak returns the smallest positive floating-point number.

Description

x02ak returns the smallest positive number in the model of floating-point arithmetic described in the X02 class. The returned value is equal to b emin-1, where b is the arithmetic base (see x02bh) and emin is the minimum exponent (see (X02BKF not in this release)) in the model.

References

None.

Error Indicators and Warnings

None.

Accuracy

None.

Parallelism and Performance

None.

Further Comments

None.

Example

See [Example] in x02aj.

See Also

X02 Class
X02 Members


x02al Method

[image]

NAG Library for .NET Release 2
X02..::x02al Method
X02 Class See Also Send Feedback
x02al returns the largest positive floating-point number.

Syntax

C#
public static double x02al()
Visual Basic
Public Shared Function x02al As Double
Visual C++
public:
static double x02al()
F#
static member x02al : unit -> float

Return Value

x02al returns the largest positive floating-point number.

Description

x02al returns the largest positive number in the model of floating-point arithmetic described in the X02 class. The returned value is equal to 1-b-p×b emax, where b is the arithmetic base (see x02bh) and emax is the maximum exponent (see (X02BLF not in this release)) in the model.

References

None.

Error Indicators and Warnings

None.

Accuracy

None.

Parallelism and Performance

None.

Further Comments

None.

Example

See [Example] in x02aj.

See Also

X02 Class
X02 Members


x02am Method

[image]

NAG Library for .NET Release 2
X02..::x02am Method
X02 Class See Also Send Feedback
x02am returns the safe range of floating-point arithmetic.

Syntax

C#
public static double x02am()
Visual Basic
Public Shared Function x02am As Double
Visual C++
public:
static double x02am()
F#
static member x02am : unit -> float

Return Value

x02am returns the safe range of floating-point arithmetic.

Description

x02am is defined to be the smallest positive model number z such that for any x in the range [z,1/z] the following can be computed without undue loss of accuracy, overflow, underflow or other error:
  • -x
  • 1/x
  • -1/x
  • x
  • log x
  • exp log x
  • y log x/log y for any y

References

None.

Error Indicators and Warnings

None.

Accuracy

None.

Parallelism and Performance

None.

Further Comments

None.

Example

See [Example] in x02aj.

See Also

X02 Class
X02 Members


x02bb Method

[image]

NAG Library for .NET Release 2
X02..::x02bb Method
X02 Class See Also Send Feedback
x02bb returns the largest representable positive integer value.

Syntax

C#
public static int x02bb()
Visual Basic
Public Shared Function x02bb As Integer
Visual C++
public:
static int x02bb()
F#
static member x02bb : unit -> int

Return Value

x02bb returns the largest representable positive integer value.

Description

None.

References

None.

Error Indicators and Warnings

None.

Accuracy

None.

Parallelism and Performance

None.

Further Comments

None.

Example

See [Example] in x02aj.

See Also

X02 Class
X02 Members


x02be Method

[image]

NAG Library for .NET Release 2
X02..::x02be Method
X02 Class See Also Send Feedback
x02be returns the maximum number of decimal digits which can be accurately represented over the whole range of floating-point numbers.

Syntax

C#
public static int x02be()
Visual Basic
Public Shared Function x02be As Integer
Visual C++
public:
static int x02be()
F#
static member x02be : unit -> int

Return Value

x02be returns the maximum number of decimal digits which can be accurately represented over the whole range of floating-point numbers.

Description

None.

References

None.

Error Indicators and Warnings

None.

Accuracy

None.

Parallelism and Performance

None.

Further Comments

None.

Example

See [Example] in x02aj.

See Also

X02 Class
X02 Members


x02bh Method

[image]

NAG Library for .NET Release 2
X02..::x02bh Method
X02 Class See Also Send Feedback
x02bh returns the base parameter b of the model of floating-point arithmetic as described in the X02 class.

Syntax

C#
public static int x02bh()
Visual Basic
Public Shared Function x02bh As Integer
Visual C++
public:
static int x02bh()
F#
static member x02bh : unit -> int

Return Value

x02bh returns the base parameter b of the model of floating-point arithmetic as described in the X02 class.

Description

None.

References

None.

Error Indicators and Warnings

None.

Accuracy

None.

Parallelism and Performance

None.

Further Comments

None.

Example

See [Example] in x02aj.

See Also

X02 Class
X02 Members


X04 Class

[image]

NAG Library for .NET Release 2
X04 Class
Members See Also Send Feedback
This chapter contains utility methods concerned with input and output to or from an external file.

Syntax

C#
public static class X04
Visual Basic
Public NotInheritable Class X04
Visual C++
public ref class X04 abstract sealed
F#
[<AbstractClassAttribute>]
[<SealedAttribute>]
type X04 =  class end

Background to the Problems

Output from NAG Library Methods

Output from NAG Library methods to an external file falls into two categories.
(a) | Error messages which are always associated with an error exit from a method, that is, with a nonzero value of ifail as specified in Section 6 of the method document.
(b) | Advisory messages which include output of final results, output of intermediate results to monitor the course of a computation, and various warning or informative messages.
Each category of output is written to its own Fortran output unit – the error message unit or the advisory message unit. In practice these may be the same unit number. Default unit numbers are provided for each implementation of the Library (see the Users' Note for your implementation); they may be changed by users. Output of error messages may be controlled by the setting of ifail (see Library Overview). Output of advisory messages may usually be controlled by the setting of some other parameter (e.g., MSGLVL) (or in some methods also by ifail). An alternative mechanism for completely suppressing output is to set the relevant unit number <0.
At present only formatted records are output from the Library. All formatted output to an external file from within the Library is performed by (X04BAF not in this release). Similarly, all formatted input from an external file is performed by (X04BBF not in this release).

Matrix Printing Methods

Methods are provided to allow formatted output of
(a) | general matrices stored in a two-dimensional array (real, complex and integer data types);
(b) | triangular matrices stored in a packed one-dimensional array (real and complex data types);
(c) | band matrices stored in a packed two-dimensional array (real and complex data types).
Methods in (b) and (c) allow printing of matrices stored in formats used in particular by F06 class F07 class of the Library.
By appropriate choice of arguments you can specify titles, labels, maximum output record length, and the format of individual matrix elements. All output is directed to the advisory messages unit, which may be altered by a call to (X04ABF not in this release).

Inheritance Hierarchy

System..::..Object
NagLibrary..::..X04

See Also

X04 Members


X04 Members

[image] [image]

NAG Library for .NET Release 2
X04 Members
X04 Class Methods See Also Send Feedback

The X04 type exposes the following members.

Methods

Name | Description
x04ca | x04ca is an easy-to-use method to print a real matrix stored in a two-dimensional array.
x04cb | Overloaded.
x04cc | x04cc is an easy-to-use method to print a real triangular matrix stored in a packed one-dimensional array.
x04ce | x04ce is an easy-to-use method to print a real band matrix stored in a packed two-dimensional array.
x04da | x04da is an easy-to-use method to print a complex matrix stored in a two-dimensional array.
x04db | Overloaded.

See Also

X04 Class


X04 Methods

[image] [image]

NAG Library for .NET Release 2
X04 Methods
X04 Class See Also Send Feedback

The X04 type exposes the following members.

Methods

Name | Description
x04ca | x04ca is an easy-to-use method to print a real matrix stored in a two-dimensional array.
x04cb | Overloaded.
x04cc | x04cc is an easy-to-use method to print a real triangular matrix stored in a packed one-dimensional array.
x04ce | x04ce is an easy-to-use method to print a real band matrix stored in a packed two-dimensional array.
x04da | x04da is an easy-to-use method to print a complex matrix stored in a two-dimensional array.
x04db | Overloaded.

See Also

X04 Class


x04ca Method

[image]

NAG Library for .NET Release 2
X04..::x04ca Method
X04 Class See Also Send Feedback
x04ca is an easy-to-use method to print a real matrix stored in a two-dimensional array.

Syntax

C#
public static void x04ca(
    string matrix,
    string diag,
    int m,
    int n,
    double[,] a,
    string title,
    out int ifail
)
Visual Basic
Public Shared Sub x04ca ( _
    matrix As String, _
    diag As String, _
    m As Integer, _
    n As Integer, _
    a As Double(,), _
    title As String, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void x04ca(
    String^ matrix,
    String^ diag,
    int m,
    int n,
    array<double,2>^ a,
    String^ title,
    [OutAttribute] int% ifail
)
F#
static member x04ca :
        matrix : string *
        diag : string *
        m : int *
        n : int *
        a : float[,] *
        title : string *
        ifail : int byref -> unit

Parameters

matrix
Type: System..::..String
On entry: indicates the part of the matrix to be printed.
matrix="G"
The whole of the rectangular matrix.
matrix="L"
The lower triangle of the matrix, or the lower trapezium if the matrix has more rows than columns.
matrix="U"
The upper triangle of the matrix, or the upper trapezium if the matrix has more columns than rows.
Constraint: matrix="G", "L" or "U".
diag
Type: System..::..String
On entry: unless matrix="G", diag must specify whether the diagonal elements of the matrix are to be printed.
diag="B"
The diagonal elements of the matrix are not referenced and not printed.
diag="U"
The diagonal elements of the matrix are not referenced, but are assumed all to be unity, and are printed as such.
diag="N"
The diagonal elements of the matrix are referenced and printed.
If matrix="G", then diag need not be set.
Constraint: if matrix≠"G", diag="B", "U" or "N".
m
Type: System..::..Int32
On entry: the number of rows and columns of the matrix, respectively, to be printed.
If either m or n is less than 1, x04ca will exit immediately after printing title; no row or column labels are printed.
n
Type: System..::..Int32
On entry: the number of rows and columns of the matrix, respectively, to be printed.
If either m or n is less than 1, x04ca will exit immediately after printing title; no row or column labels are printed.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,m
Note: the second dimension of the array a must be at least max 1,n.
On entry: the matrix to be printed. Only the elements that will be referred to, as specified by parameters matrix and diag, need be set.
title
Type: System..::..String
On entry: a title to be printed above the matrix.
If title=' ', no title (and no blank line) will be printed.
If title contains more than 80 characters, the contents of title will be wrapped onto more than one line, with the break after 80 characters.
Any trailing blank characters in title are ignored.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

x04ca prints a real matrix. It is an easy-to-use driver for x04cb. The method uses default values for the format in which numbers are printed, for labelling the rows and columns, and for output record length.
x04ca will choose a format code such that numbers will be printed with an F 8.4, an F 11.4 or a 1 PE 13.4 format. The F 8.4 code is chosen if the sizes of all the matrix elements to be printed lie between 0.001 and 1.0. The F 11.4 code is chosen if the sizes of all the matrix elements to be printed lie between 0.001 and 9999.9999. Otherwise the 1 PE 13.4 code is chosen.
The matrix is printed with integer row and column labels, and with a maximum record length of 80.
The matrix is output to the unit defined by (X04ABF not in this release).

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, matrix≠"G", "L" or "U".
ifail=2
On entry, matrix="L" or "U", but diag≠"N", "U" or "B".
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

A call to x04ca is equivalent to a call to x04cb with the following argument values:

Example

This example program calls x04ca twice, first to print a 3 by 5 rectangular matrix, and then to print a 5 by 5 lower triangular matrix.

Example program (C#): x04cae.cs

Example program results: x04cae.r

See Also

X04 Class
X04 Members


x04cb Method

[image] [image]

NAG Library for .NET Release 2
X04..::x04cb Method
X04 Class See Also Send Feedback

Overload List

Name | Description
x04cb(String, String, Int32, Int32, array<Double,2>[,](,)[,][,], String, String, String, array<String>[]()[][], String, array<String>[]()[][], Int32, Int32, Int32%) | x04cb prints a real matrix stored in a two-dimensional array.
x04cb(String, String, Int32, Int32, array<Double>[]()[][], String, String, String, array<String>[]()[][], String, array<String>[]()[][], Int32, Int32, Int32%) | x04cb prints a real matrix stored in a two-dimensional array.

See Also

X04 Class
X04 Members


x04cb Method (String, String, Int32, Int32, Double[,], String, String, String, String[], String, String[], Int32, Int32, Int32)

[image]

NAG Library for .NET Release 2
X04..::x04cb Method (String, String, Int32, Int32, array<Double,2>[,](,)[,][,], String, String, String, array<String>[]()[][], String, array<String>[]()[][], Int32, Int32, Int32%)
X04 Class See Also Send Feedback
x04cb prints a real matrix stored in a two-dimensional array.

Syntax

C#
public static void x04cb(
    string matrix,
    string diag,
    int m,
    int n,
    double[,] a,
    string form,
    string title,
    string labrow,
    string[] rlabs,
    string labcol,
    string[] clabs,
    int ncols,
    int indent,
    out int ifail
)
Visual Basic
Public Shared Sub x04cb ( _
    matrix As String, _
    diag As String, _
    m As Integer, _
    n As Integer, _
    a As Double(,), _
    form As String, _
    title As String, _
    labrow As String, _
    rlabs As String(), _
    labcol As String, _
    clabs As String(), _
    ncols As Integer, _
    indent As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void x04cb(
    String^ matrix,
    String^ diag,
    int m,
    int n,
    array<double,2>^ a,
    String^ form,
    String^ title,
    String^ labrow,
    array<String^>^ rlabs,
    String^ labcol,
    array<String^>^ clabs,
    int ncols,
    int indent,
    [OutAttribute] int% ifail
)
F#
static member x04cb :
        matrix : string *
        diag : string *
        m : int *
        n : int *
        a : float[,] *
        form : string *
        title : string *
        labrow : string *
        rlabs : string[] *
        labcol : string *
        clabs : string[] *
        ncols : int *
        indent : int *
        ifail : int byref -> unit

Parameters

matrix
Type: System..::..String
On entry: indicates the part of the matrix to be printed.
matrix="G"
The whole of the rectangular matrix.
matrix="L"
The lower triangle of the matrix, or the lower trapezium if the matrix has more rows than columns.
matrix="U"
The upper triangle of the matrix, or the upper trapezium if the matrix has more columns than rows.
Constraint: matrix="G", "L" or "U".
diag
Type: System..::..String
On entry: unless matrix="G", diag must specify whether the diagonal elements of the matrix are to be printed.
diag="B"
The diagonal elements of the matrix are not referenced and not printed.
diag="U"
The diagonal elements of the matrix are not referenced, but are assumed all to be unity, and are printed as such.
diag="N"
The diagonal elements of the matrix are referenced and printed.
If matrix="G", then diag need not be set.
Constraint: if matrix≠"G", diag="B", "U" or "N".
m
Type: System..::..Int32
On entry: the number of rows and columns of the matrix, respectively, to be printed.
If either m or n is less than 1, x04cb will exit immediately after printing title; no row or column labels are printed.
n
Type: System..::..Int32
On entry: the number of rows and columns of the matrix, respectively, to be printed.
If either m or n is less than 1, x04cb will exit immediately after printing title; no row or column labels are printed.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,m
Note: the second dimension of the array a must be at least max 1,n.
On entry: the matrix to be printed. Only the elements that will be referred to, as specified by parameters matrix and diag, need be set.
form
Type: System..::..String
On entry: describes the Fortran format code for printing the elements of the matrix a. The format code may be any allowed on the system, whether it is standard Fortran or not. It may or may not be enclosed in brackets.
In addition, there are the following special codes which force x04cb to choose its own format code:
form=' '
x04cb will choose a format code such that numbers will be printed with an F8.4, an F11.4 or a 1PE13.4 format. The F8.4 code is chosen if the sizes of all the matrix elements to be printed lie between 0.001 and 1.0. The F11.4 code is chosen if the sizes of all the matrix elements to be printed lie between 0.001 and 9999.9999. Otherwise the 1PE13.4 code is chosen.
form='*'
x04cb will choose a format code such that numbers will be printed to as many significant digits as are necessary to distinguish between neighbouring machine numbers. Thus any two numbers that are stored with different internal representations should look different on output. Whether they do in fact look different will depend on the run-time library of the Fortran compiler in use.
By preceding the desired format code by the string ‘MATLAB’, x04cb will print the matrix such that it can be input into MATLAB, and title will be used as the name of the matrix.
Examples of valid values for form are 'F11.4', '1PE13.5', 'G14.5', 'MATLABF11.4', 'MATLAB*'.
Constraint: the character length of the format specifier in form must be ≤80.
title
Type: System..::..String
On entry: a title to be printed above the matrix, or name of the matrix.
If title=' ', no title (and no blank line) will be printed.
If title contains more than ncols characters, the contents of title will be wrapped onto more than one line, with the break after ncols characters.
Any trailing blank characters in title are ignored.
If printing in MATLAB mode, title will be used as the name of the matrix.
labrow
Type: System..::..String
On entry: indicates the type of labelling to be applied to the rows of the matrix, except in MATLAB mode where labrow is ignored.
labrow="N"
Prints no row labels.
labrow="I"
Prints integer row labels.
labrow="C"
Prints character labels, which must be supplied in array rlabs.
Constraint: labrow="N", "I" or "C".
rlabs
Type: array< System..::..String >[]()[][]
An array of size [dim1]
Note: the dimension of the array rlabs must be at least m if labrow="C", and at least 1 otherwise.
On entry: if labrow="C", rlabs must contain labels for the rows of the matrix, except in MATLAB mode where rlabs is ignored.
Labels are right-justified when output, in a field which is as wide as necessary to hold the longest row label. Note that this field width is subtracted from the number of usable columns, ncols.
labcol
Type: System..::..String
On entry: indicates the type of labelling to be applied to the columns of the matrix, except in MATLAB mode where labcol is ignored.
labcol="N"
Prints no column labels.
labcol="I"
Prints integer column labels.
labcol="C"
Prints character labels, which must be supplied in array clabs.
Constraint: labcol="N", "I" or "C".
clabs
Type: array< System..::..String >[]()[][]
An array of size [dim1]
Note: the dimension of the array clabs must be at least n if labcol="C", and at least 1 otherwise.
On entry: if labcol="C", clabs must contain labels for the columns of the matrix, except in MATLAB mode where clabs is ignored.
Labels are right-justified when output. Any label that is too long for the column width, which is determined by form, is truncated.
ncols
Type: System..::..Int32
On entry: the maximum output record length. If the number of columns of the matrix is too large to be accommodated in ncols characters, the matrix will be printed in parts, containing the largest possible number of matrix columns, and each part separated by a blank line.
ncols must be large enough to hold at least one column of the matrix using the format specifier in form. If a value less than 0 or greater than 132 is supplied for ncols, then the value 80 is used instead.
indent
Type: System..::..Int32
On entry: the number of columns by which the matrix (and any title and labels) should be indented. The effective value of ncols is reduced by indent columns. If a value less than 0 or greater than ncols is supplied for indent, the value 0 is used instead.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

x04cb prints a real matrix, or part of it, using a format specifier supplied by you. The matrix is output to the unit defined by (X04ABF not in this release).

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, matrix≠"G", "L" or "U".
ifail=2
On entry, matrix="L" or "U", but diag≠"N", "U" or "B".
ifail=4
On entry, the format specifier in form is more than 80 characters long.
ifail=5
The format specifier in form cannot be used to output a number. The specifier probably has too wide a field width or contains an illegal edit descriptor.
ifail=6
On entry, either labrow or labcol≠"N", "I" or "C".
ifail=7
The quantity ncols-indent-labwid (where labwid is the width needed for the row labels), is not large enough to hold at least one column of the matrix.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

x04cb may be used to print a vector, either as a row or as a column. The following code fragment illustrates possible calls.

Example

This example calls x04cb twice, to print matrices of different orders and bandwidths; various options for labelling and formatting are illustrated.

Example program (C#): x04cbe.cs

Example program results: x04cbe.r

See Also

X04 Class
X04 Members
x04cb Overload


x04cb Method (String, String, Int32, Int32, Double[], String, String, String, String[], String, String[], Int32, Int32, Int32)

[image]

NAG Library for .NET Release 2
X04..::x04cb Method (String, String, Int32, Int32, array<Double>[]()[][], String, String, String, array<String>[]()[][], String, array<String>[]()[][], Int32, Int32, Int32%)
X04 Class See Also Send Feedback
x04cb prints a real matrix stored in a two-dimensional array.

Syntax

C#
public static void x04cb(
    string matrix,
    string diag,
    int m,
    int n,
    double[] a,
    string form,
    string title,
    string labrow,
    string[] rlabs,
    string labcol,
    string[] clabs,
    int ncols,
    int indent,
    out int ifail
)
Visual Basic
Public Shared Sub x04cb ( _
    matrix As String, _
    diag As String, _
    m As Integer, _
    n As Integer, _
    a As Double(), _
    form As String, _
    title As String, _
    labrow As String, _
    rlabs As String(), _
    labcol As String, _
    clabs As String(), _
    ncols As Integer, _
    indent As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void x04cb(
    String^ matrix,
    String^ diag,
    int m,
    int n,
    array<double>^ a,
    String^ form,
    String^ title,
    String^ labrow,
    array<String^>^ rlabs,
    String^ labcol,
    array<String^>^ clabs,
    int ncols,
    int indent,
    [OutAttribute] int% ifail
)
F#
static member x04cb :
        matrix : string *
        diag : string *
        m : int *
        n : int *
        a : float[] *
        form : string *
        title : string *
        labrow : string *
        rlabs : string[] *
        labcol : string *
        clabs : string[] *
        ncols : int *
        indent : int *
        ifail : int byref -> unit

Parameters

matrix
Type: System..::..String
On entry: indicates the part of the matrix to be printed.
matrix="G"
The whole of the rectangular matrix.
matrix="L"
The lower triangle of the matrix, or the lower trapezium if the matrix has more rows than columns.
matrix="U"
The upper triangle of the matrix, or the upper trapezium if the matrix has more columns than rows.
Constraint: matrix="G", "L" or "U".
diag
Type: System..::..String
On entry: unless matrix="G", diag must specify whether the diagonal elements of the matrix are to be printed.
diag="B"
The diagonal elements of the matrix are not referenced and not printed.
diag="U"
The diagonal elements of the matrix are not referenced, but are assumed all to be unity, and are printed as such.
diag="N"
The diagonal elements of the matrix are referenced and printed.
If matrix="G", then diag need not be set.
Constraint: if matrix≠"G", diag="B", "U" or "N".
m
Type: System..::..Int32
On entry: the number of rows and columns of the matrix, respectively, to be printed.
If either m or n is less than 1, x04cb will exit immediately after printing title; no row or column labels are printed.
n
Type: System..::..Int32
On entry: the number of rows and columns of the matrix, respectively, to be printed.
If either m or n is less than 1, x04cb will exit immediately after printing title; no row or column labels are printed.
a
Type: array< System..::..Double >[]()[][]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,m
Note: the second dimension of the array a must be at least max 1,n.
On entry: the matrix to be printed. Only the elements that will be referred to, as specified by parameters matrix and diag, need be set.
form
Type: System..::..String
On entry: describes the Fortran format code for printing the elements of the matrix a. The format code may be any allowed on the system, whether it is standard Fortran or not. It may or may not be enclosed in brackets.
In addition, there are the following special codes which force x04cb to choose its own format code:
form=' '
x04cb will choose a format code such that numbers will be printed with an F8.4, an F11.4 or a 1PE13.4 format. The F8.4 code is chosen if the sizes of all the matrix elements to be printed lie between 0.001 and 1.0. The F11.4 code is chosen if the sizes of all the matrix elements to be printed lie between 0.001 and 9999.9999. Otherwise the 1PE13.4 code is chosen.
form='*'
x04cb will choose a format code such that numbers will be printed to as many significant digits as are necessary to distinguish between neighbouring machine numbers. Thus any two numbers that are stored with different internal representations should look different on output. Whether they do in fact look different will depend on the run-time library of the Fortran compiler in use.
By preceding the desired format code by the string ‘MATLAB’, x04cb will print the matrix such that it can be input into MATLAB, and title will be used as the name of the matrix.
Examples of valid values for form are 'F11.4', '1PE13.5', 'G14.5', 'MATLABF11.4', 'MATLAB*'.
Constraint: the character length of the format specifier in form must be ≤80.
title
Type: System..::..String
On entry: a title to be printed above the matrix, or name of the matrix.
If title=' ', no title (and no blank line) will be printed.
If title contains more than ncols characters, the contents of title will be wrapped onto more than one line, with the break after ncols characters.
Any trailing blank characters in title are ignored.
If printing in MATLAB mode, title will be used as the name of the matrix.
labrow
Type: System..::..String
On entry: indicates the type of labelling to be applied to the rows of the matrix, except in MATLAB mode where labrow is ignored.
labrow="N"
Prints no row labels.
labrow="I"
Prints integer row labels.
labrow="C"
Prints character labels, which must be supplied in array rlabs.
Constraint: labrow="N", "I" or "C".
rlabs
Type: array< System..::..String >[]()[][]
An array of size [dim1]
Note: the dimension of the array rlabs must be at least m if labrow="C", and at least 1 otherwise.
On entry: if labrow="C", rlabs must contain labels for the rows of the matrix, except in MATLAB mode where rlabs is ignored.
Labels are right-justified when output, in a field which is as wide as necessary to hold the longest row label. Note that this field width is subtracted from the number of usable columns, ncols.
labcol
Type: System..::..String
On entry: indicates the type of labelling to be applied to the columns of the matrix, except in MATLAB mode where labcol is ignored.
labcol="N"
Prints no column labels.
labcol="I"
Prints integer column labels.
labcol="C"
Prints character labels, which must be supplied in array clabs.
Constraint: labcol="N", "I" or "C".
clabs
Type: array< System..::..String >[]()[][]
An array of size [dim1]
Note: the dimension of the array clabs must be at least n if labcol="C", and at least 1 otherwise.
On entry: if labcol="C", clabs must contain labels for the columns of the matrix, except in MATLAB mode where clabs is ignored.
Labels are right-justified when output. Any label that is too long for the column width, which is determined by form, is truncated.
ncols
Type: System..::..Int32
On entry: the maximum output record length. If the number of columns of the matrix is too large to be accommodated in ncols characters, the matrix will be printed in parts, containing the largest possible number of matrix columns, and each part separated by a blank line.
ncols must be large enough to hold at least one column of the matrix using the format specifier in form. If a value less than 0 or greater than 132 is supplied for ncols, then the value 80 is used instead.
indent
Type: System..::..Int32
On entry: the number of columns by which the matrix (and any title and labels) should be indented. The effective value of ncols is reduced by indent columns. If a value less than 0 or greater than ncols is supplied for indent, the value 0 is used instead.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

x04cb prints a real matrix, or part of it, using a format specifier supplied by you. The matrix is output to the unit defined by (X04ABF not in this release).

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, matrix≠"G", "L" or "U".
ifail=2
On entry, matrix="L" or "U", but diag≠"N", "U" or "B".
ifail=4
On entry, the format specifier in form is more than 80 characters long.
ifail=5
The format specifier in form cannot be used to output a number. The specifier probably has too wide a field width or contains an illegal edit descriptor.
ifail=6
On entry, either labrow or labcol≠"N", "I" or "C".
ifail=7
The quantity ncols-indent-labwid (where labwid is the width needed for the row labels), is not large enough to hold at least one column of the matrix.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

x04cb may be used to print a vector, either as a row or as a column. The following code fragment illustrates possible calls.

Example

This example calls x04cb twice, to print matrices of different orders and bandwidths; various options for labelling and formatting are illustrated.

Example program (C#): x04cbe.cs

Example program results: x04cbe.r

See Also

X04 Class
X04 Members
x04cb Overload


x04cc Method

[image]

NAG Library for .NET Release 2
X04..::x04cc Method
X04 Class See Also Send Feedback
x04cc is an easy-to-use method to print a real triangular matrix stored in a packed one-dimensional array.

Syntax

C#
public static void x04cc(
    string uplo,
    string diag,
    int n,
    double[] a,
    string title,
    out int ifail
)
Visual Basic
Public Shared Sub x04cc ( _
    uplo As String, _
    diag As String, _
    n As Integer, _
    a As Double(), _
    title As String, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void x04cc(
    String^ uplo,
    String^ diag,
    int n,
    array<double>^ a,
    String^ title,
    [OutAttribute] int% ifail
)
F#
static member x04cc :
        uplo : string *
        diag : string *
        n : int *
        a : float[] *
        title : string *
        ifail : int byref -> unit

Parameters

uplo
Type: System..::..String
On entry: indicates the type of the matrix to be printed
uplo="L"
The matrix is lower triangular. In this case, the packed array a holds the matrix elements in the following order: 1,1,2,1,…,n,1,2,2,3,2,…,n,2, etc.
uplo="U"
The matrix is upper triangular. In this case, the packed array a holds the matrix elements in the following order: 1,1,1,2,2,2,1,3,2,3,3,3,1,4, etc.
Constraint: uplo="L" or "U".
diag
Type: System..::..String
On entry: indicates whether the diagonal elements of the matrix are to be printed.
diag="B"
The diagonal elements of the matrix are not referenced and not printed.
diag="U"
The diagonal elements of the matrix are not referenced, but are assumed all to be unity, and are printed as such.
diag="N"
The diagonal elements of the matrix are referenced and printed.
Constraint: diag="B", "U" or "N".
n
Type: System..::..Int32
On entry: the order of the matrix to be printed.
If n is less than 1, x04cc will exit immediately after printing title; no row or column labels are printed.
a
Type: array< System..::..Double >[]()[][]
An array of size [dim1]
Note: the dimension of the array a must be at least max 1,n×n+1/2.
On entry: the matrix to be printed. Note that a must have space for the diagonal elements of the matrix, even if these are not stored.
More precisely,
  • if uplo="U", the upper triangle of A must be stored with element Aij in a[i+j j-1/2] for i≤j;
  • if uplo="L", the lower triangle of A must be stored with element Aij in a[i+2 n-jj-1/2] for i≥j.
If diag="U", the diagonal elements of A are assumed to be 1, and are not referenced; the same storage scheme is used whether diag="N" or ‘U’.
title
Type: System..::..String
On entry: a title to be printed above the matrix.
If title=' ', no title (and no blank line) will be printed.
If title contains more than 80 characters, the contents of title will be wrapped onto more than one line, with the break after 80 characters.
Any trailing blank characters in title are ignored.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

x04cc prints a real triangular matrix stored in packed form. It is an easy-to-use driver for (X04CDF not in this release). The method uses default values for the format in which numbers are printed, for labelling the rows and columns, and for output record length. The matrix must be packed by column.
x04cc will choose a format code such that numbers will be printed with an F 8.4, an F 11.4 or a 1 PE 13.4 format . The F 8.4 code is chosen if the sizes of all the matrix elements to be printed lie between 0.001 and 1.0. The F 11.4 code is chosen if the sizes of all the matrix elements to be printed lie between 0.001 and 9999.9999. Otherwise the 1 PE 13.4 code is chosen.
The matrix is printed with integer row and column labels, and with a maximum record length of 80.
The matrix is output to the unit defined by (X04ABF not in this release).

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
ifail=1
On entry, uplo≠"L" or "U".
ifail=2
On entry, diag≠"N", "U" or "B".
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

A call to x04cc is equivalent to a call to (X04CDF not in this release) with the following argument values:

Example

The example program calls x04cc twice, first to print a 4 by 4 lower triangular matrix, and then to print a 5 by 5 upper triangular matrix.

Example program (C#): x04cce.cs

Example program results: x04cce.r

See Also

X04 Class
X04 Members


x04ce Method

[image]

NAG Library for .NET Release 2
X04..::x04ce Method
X04 Class See Also Send Feedback
x04ce is an easy-to-use method to print a real band matrix stored in a packed two-dimensional array.

Syntax

C#
public static void x04ce(
    int m,
    int n,
    int kl,
    int ku,
    double[,] a,
    string title,
    out int ifail
)
Visual Basic
Public Shared Sub x04ce ( _
    m As Integer, _
    n As Integer, _
    kl As Integer, _
    ku As Integer, _
    a As Double(,), _
    title As String, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void x04ce(
    int m,
    int n,
    int kl,
    int ku,
    array<double,2>^ a,
    String^ title,
    [OutAttribute] int% ifail
)
F#
static member x04ce :
        m : int *
        n : int *
        kl : int *
        ku : int *
        a : float[,] *
        title : string *
        ifail : int byref -> unit

Parameters

m
Type: System..::..Int32
On entry: the number of rows and columns of the band matrix, respectively, to be printed.
If either m or n is less than 1, x04ce will exit immediately after printing title; no row or column labels are printed.
n
Type: System..::..Int32
On entry: the number of rows and columns of the band matrix, respectively, to be printed.
If either m or n is less than 1, x04ce will exit immediately after printing title; no row or column labels are printed.
kl
Type: System..::..Int32
On entry: the number of subdiagonals of the band matrix A.
Constraint: kl≥0.
ku
Type: System..::..Int32
On entry: the number of superdiagonals of the band matrix A.
Constraint: ku≥0.
a
Type: array< System..::..Double ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥kl+ku+1
Note: the second dimension of the array a must be at least max 1,min m+ku,n.
On entry: the band matrix to be printed.
The matrix is stored in rows 1 to kl+ku+1, more precisely, the element Aij must be stored in
a[ku+1+i-j,j]  for ​max 1,j-ku≤i≤min m,j+kl.
title
Type: System..::..String
On entry: a title to be printed above the matrix.
If title=' ', no title (and no blank line) will be printed.
If title contains more than 80 characters, the contents of title will be wrapped onto more than one line, with the break after 80 characters.
Any trailing blank characters in title are ignored.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

x04ce prints a real band matrix stored in a packed two-dimensional array. It is an easy-to-use driver for (X04CFF not in this release). The method uses default values for the format in which numbers are printed, for labelling the rows and columns, and for output record length.
x04ce will choose a format code such that numbers will be printed with an F 8.4, an F 11.4 or a 1 PE 13.4 format . The F 8.4 code is chosen if the sizes of all the matrix elements to be printed lie between 0.001 and 1.0. The F 11.4 code is chosen if the sizes of all the matrix elements to be printed lie between 0.001 and 9999.9999. Otherwise the 1 PE 13.4 code is chosen.
The matrix is printed with integer row and column labels, and with a maximum record length of 80.
The matrix is output to the unit defined by (X04ABF not in this release).

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, kl<0.
ifail=2
On entry, ku<0.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

A call to x04ce is equivalent to a call to (X04CFF not in this release) with the following argument values:

Example

The example program calls x04ce to print a 5 by 5 band matrix with one subdiagonal and one superdiagonal.

Example program (C#): x04cee.cs

Example program results: x04cee.r

See Also

X04 Class
X04 Members


x04da Method

[image]

NAG Library for .NET Release 2
X04..::x04da Method
X04 Class See Also Send Feedback
x04da is an easy-to-use method to print a complex matrix stored in a two-dimensional array.

Syntax

C#
public static void x04da(
    string matrix,
    string diag,
    int m,
    int n,
    Complex[,] a,
    string title,
    out int ifail
)
Visual Basic
Public Shared Sub x04da ( _
    matrix As String, _
    diag As String, _
    m As Integer, _
    n As Integer, _
    a As Complex(,), _
    title As String, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void x04da(
    String^ matrix,
    String^ diag,
    int m,
    int n,
    array<Complex,2>^ a,
    String^ title,
    [OutAttribute] int% ifail
)
F#
static member x04da :
        matrix : string *
        diag : string *
        m : int *
        n : int *
        a : Complex[,] *
        title : string *
        ifail : int byref -> unit

Parameters

matrix
Type: System..::..String
On entry: indicates the part of the matrix to be printed.
matrix="G"
The whole of the rectangular matrix.
matrix="L"
The lower triangle of the matrix, or the lower trapezium if the matrix has more rows than columns.
matrix="U"
The upper triangle of the matrix, or the upper trapezium if the matrix has more columns than rows.
Constraint: matrix="G", "L" or "U".
diag
Type: System..::..String
On entry: unless matrix="G", diag must specify whether the diagonal elements of the matrix are to be printed.
diag="B"
The diagonal elements of the matrix are not referenced and not printed.
diag="U"
The diagonal elements of the matrix are not referenced, but are assumed all to be unity, and are printed as such.
diag="N"
The diagonal elements of the matrix are referenced and printed.
If matrix="G", then diag need not be set.
Constraint: if matrix≠"G", diag="B", "U" or "N".
m
Type: System..::..Int32
On entry: the number of rows and columns of the matrix, respectively, to be printed.
If either m or n is less than 1, x04da will exit immediately after printing title; no row or column labels are printed.
n
Type: System..::..Int32
On entry: the number of rows and columns of the matrix, respectively, to be printed.
If either m or n is less than 1, x04da will exit immediately after printing title; no row or column labels are printed.
a
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,m
Note: the second dimension of the array a must be at least max 1,n.
On entry: the matrix to be printed. Only the elements that will be referred to, as specified by parameters matrix and diag, need be set.
title
Type: System..::..String
On entry: a title to be printed above the matrix.
If title=' ', no title (and no blank line) will be printed.
If title contains more than 80 characters, the contents of title will be wrapped onto more than one line, with the break after 80 characters.
Any trailing blank characters in title are ignored.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

x04da prints a complex matrix. It is an easy-to-use driver for x04db. The method uses default values for the format in which numbers are printed, for labelling the rows and columns, and for output record length.
x04da will choose a format code such that numbers will be printed with an F 8.4, an F 11.4 or a 1 PE 13.4 format. The F 8.4 code is chosen if the sizes of all the matrix elements to be printed lie between 0.001 and 1.0. The F 11.4 code is chosen if the sizes of all the matrix elements to be printed lie between 0.001 and 9999.9999. Otherwise the 1 PE 13.4 code is chosen. The chosen code is used to print each complex element of the matrix with the real part above the imaginary part.
The matrix is printed with integer row and column labels, and with a maximum record length of 80.
The matrix is output to the unit defined by (X04ABF not in this release).

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, matrix≠"G", "L" or "U".
ifail=2
On entry, matrix="L" or "U", but diag≠"N", "U" or "B".
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Further Comments

A call to x04da is equivalent to a call to x04db with the following argument values:

See Also

X04 Class
X04 Members


x04db Method

[image] [image]

NAG Library for .NET Release 2
X04..::x04db Method
X04 Class See Also Send Feedback

Overload List

Name | Description
x04db(String, String, Int32, Int32, array<Complex,2>[,](,)[,][,], String, String, String, String, array<String>[]()[][], String, array<String>[]()[][], Int32, Int32, Int32%) | x04db prints a complex matrix stored in a two-dimensional array.
x04db(String, String, Int32, Int32, array<Complex>[]()[][], String, String, String, String, array<String>[]()[][], String, array<String>[]()[][], Int32, Int32, Int32%) | x04db prints a complex matrix stored in a two-dimensional array.

See Also

X04 Class
X04 Members


x04db Method (String, String, Int32, Int32, Complex[,], String, String, String, String, String[], String, String[], Int32, Int32, Int32)

[image]

NAG Library for .NET Release 2
X04..::x04db Method (String, String, Int32, Int32, array<Complex,2>[,](,)[,][,], String, String, String, String, array<String>[]()[][], String, array<String>[]()[][], Int32, Int32, Int32%)
X04 Class See Also Send Feedback
x04db prints a complex matrix stored in a two-dimensional array.

Syntax

C#
public static void x04db(
    string matrix,
    string diag,
    int m,
    int n,
    Complex[,] a,
    string usefrm,
    string form,
    string title,
    string labrow,
    string[] rlabs,
    string labcol,
    string[] clabs,
    int ncols,
    int indent,
    out int ifail
)
Visual Basic
Public Shared Sub x04db ( _
    matrix As String, _
    diag As String, _
    m As Integer, _
    n As Integer, _
    a As Complex(,), _
    usefrm As String, _
    form As String, _
    title As String, _
    labrow As String, _
    rlabs As String(), _
    labcol As String, _
    clabs As String(), _
    ncols As Integer, _
    indent As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void x04db(
    String^ matrix,
    String^ diag,
    int m,
    int n,
    array<Complex,2>^ a,
    String^ usefrm,
    String^ form,
    String^ title,
    String^ labrow,
    array<String^>^ rlabs,
    String^ labcol,
    array<String^>^ clabs,
    int ncols,
    int indent,
    [OutAttribute] int% ifail
)
F#
static member x04db :
        matrix : string *
        diag : string *
        m : int *
        n : int *
        a : Complex[,] *
        usefrm : string *
        form : string *
        title : string *
        labrow : string *
        rlabs : string[] *
        labcol : string *
        clabs : string[] *
        ncols : int *
        indent : int *
        ifail : int byref -> unit

Parameters

matrix
Type: System..::..String
On entry: indicates the part of the matrix to be printed.
matrix="G"
The whole of the rectangular matrix.
matrix="L"
The lower triangle of the matrix, or the lower trapezium if the matrix has more rows than columns.
matrix="U"
The upper triangle of the matrix, or the upper trapezium if the matrix has more columns than rows.
Constraint: matrix="G", "L" or "U".
diag
Type: System..::..String
On entry: unless matrix="G", diag must specify whether the diagonal elements of the matrix are to be printed.
diag="B"
The diagonal elements of the matrix are not referenced and not printed.
diag="U"
The diagonal elements of the matrix are not referenced, but are assumed all to be unity, and are printed as such.
diag="N"
The diagonal elements of the matrix are referenced and printed.
If matrix="G", then diag need not be set.
Constraint: if matrix≠"G", diag="B", "U" or "N".
m
Type: System..::..Int32
On entry: the number of rows and columns of the matrix, respectively, to be printed.
If either m or n is less than 1, x04db will exit immediately after printing title; no row or column labels are printed.
n
Type: System..::..Int32
On entry: the number of rows and columns of the matrix, respectively, to be printed.
If either m or n is less than 1, x04db will exit immediately after printing title; no row or column labels are printed.
a
Type: array< NagLibrary..::..Complex ,2>[,](,)[,][,]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,m
Note: the second dimension of the array a must be at least max 1,n.
On entry: the matrix to be printed. Only the elements that will be referred to, as specified by parameters matrix and diag, need be set.
usefrm
Type: System..::..String
On entry: indicates how the value of form is to be used to print matrix elements, except in MATLAB mode where usefrm is ignored.
usefrm="A"
The format code in form is assumed to contain a single real edit-descriptor which is to be used to print the real and imaginary parts of each complex number one above the other. Each row of the matrix is separated by a blank line, and any row labels are attached only to the real parts. This option means that about twice as many columns can be fitted into ncols characters than if any other usefrm option is used. A typical value of form for this usefrm option might be 'E13.4', '*' or ' '.
usefrm="B"
The format code in form is assumed to contain a single edit-descriptor such as 'E13.4', '*' or ' ' which is used to print the real and imaginary parts of each complex number separated by a comma, and surrounded by brackets. Thus a matrix element printed with this usefrm option might look like this: 12.345,-11.323.
usefrm="D"
The format code in form is used unaltered to print a complex number. This usefrm option allows you flexibility to specify exactly how the number is printed. With this option for usefrm and a suitable value for form it is possible, for example, to print a complex number in the form 0.123+3.214 i or 0.123E−02,0.234E−01. See [Example] for an example illustrating this option.
Constraint: usefrm="A", "B" or "D".
form
Type: System..::..String
On entry: describes the Fortran format code that is used in conjunction with usefrm for printing the elements of the matrix a. The format code may be any allowed on the system, whether it is standard Fortran or not. It may or may not be enclosed in brackets.
In addition, there are the following special codes which force x04db to choose its own format code:
form=' '
x04db will choose a format code such that numbers will be printed with an F8.4, an F11.4 or a 1PE13.4 format. The F8.4 code is chosen if the sizes of the real and imaginary parts of all the matrix elements to be printed lie between 0.001 and 1.0. The F11.4 code is chosen if the sizes of all the numbers to be printed lie between 0.001 and 9999.9999. Otherwise the 1PE13.4 code is chosen.
form='*'
x04db will choose a format code such that numbers will be printed to as many significant digits as are necessary to distinguish between neighbouring machine numbers. Thus any two numbers that are stored with different internal representations should look different on output. Whether they do in fact look different will depend on the run-time library of the Fortran compiler in use.
By preceding the desired format code by the string ‘MATLAB’, x04db will print the matrix such that it can be input into MATLAB, and title will be used as the name of the matrix.
More complicated values of form, to print a complex number in a desired form, may be used. See the description of parameter usefrm for more details.
Examples of valid values for form are '(F11.4)', '1P,2E13.5', 'MATLABF11.4', 'MATLAB*'.
Constraint: the character length of the format specifier in form must be ≤80.
title
Type: System..::..String
On entry: a title to be printed above the matrix, or name of the matrix.
If title=' ', no title (and no blank line) will be printed.
If title contains more than ncols characters, the contents of title will be wrapped onto more than one line, with the break after ncols characters.
Any trailing blank characters in title are ignored.
If printing in MATLAB mode, title will be used as the name of the matrix.
labrow
Type: System..::..String
On entry: indicates the type of labelling to be applied to the rows of the matrix, except in MATLAB mode where labrow is ignored.
labrow="N"
Prints no row labels.
labrow="I"
Prints integer row labels.
labrow="C"
Prints character labels, which must be supplied in array rlabs.
Constraint: labrow="N", "I" or "C".
rlabs
Type: array< System..::..String >[]()[][]
An array of size [dim1]
Note: the dimension of the array rlabs must be at least m if labrow="C", and at least 1 otherwise.
On entry: if labrow="C", rlabs must contain labels for the rows of the matrix, except in MATLAB mode where rlabs is ignored.
Labels are right-justified when output, in a field which is as wide as necessary to hold the longest row label. Note that this field width is subtracted from the number of usable columns, ncols.
labcol
Type: System..::..String
On entry: indicates the type of labelling to be applied to the columns of the matrix, except in MATLAB mode where labcol is ignored.
labcol="N"
Prints no column labels.
labcol="I"
Prints integer column labels.
labcol="C"
Prints character labels, which must be supplied in array clabs.
Constraint: labcol="N", "I" or "C".
clabs
Type: array< System..::..String >[]()[][]
An array of size [dim1]
Note: the dimension of the array clabs must be at least n if labcol="C", and at least 1 otherwise.
On entry: if labcol="C", clabs must contain labels for the columns of the matrix, except in MATLAB mode where clabs is ignored.
Labels are right-justified when output. Any label that is too long for the column width, which is determined by form, is truncated.
ncols
Type: System..::..Int32
On entry: the maximum output record length. If the number of columns of the matrix is too large to be accommodated in ncols characters, the matrix will be printed in parts, containing the largest possible number of matrix columns, and each part separated by a blank line.
ncols must be large enough to hold at least one column of the matrix using the format specifier in form. If a value less than 0 or greater than 132 is supplied for ncols, then the value 80 is used instead.
indent
Type: System..::..Int32
On entry: the number of columns by which the matrix (and any title and labels) should be indented. The effective value of ncols is reduced by indent columns. If a value less than 0 or greater than ncols is supplied for indent, the value 0 is used instead.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

x04db prints a complex matrix, or part of it, using a format specifier supplied by you. The matrix is output to the unit defined by (X04ABF not in this release).

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, matrix≠"G", "L" or "U".
ifail=2
On entry, matrix="L" or "U", but diag≠"N", "U" or "B".
ifail=4
On entry, usefrm≠"A", "B" or "D".
ifail=5
On entry, the format specifier in form is more than 80 characters long.
ifail=6
The format specifier in form cannot be used to output a number. The specifier probably has too wide a field width or contains an illegal edit descriptor.
ifail=7
On entry, either labrow or labcol≠"N", "I" or "C".
ifail=8
The quantity ncols-indent-labwid (where labwid is the width needed for the row labels) is not large enough to hold at least one column of the matrix.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Example

The example program calls x04db three times, first to print a 3 by 4 rectangular matrix, next to print a 4 by 4 upper triangular matrix, and then to print a 3 by 4 lower triangular matrix; various options for labelling and formatting are illustrated.

Example program (C#): x04dbe.cs

Example program results: x04dbe.r

See Also

X04 Class
X04 Members
x04db Overload


x04db Method (String, String, Int32, Int32, Complex[], String, String, String, String, String[], String, String[], Int32, Int32, Int32)

[image]

NAG Library for .NET Release 2
X04..::x04db Method (String, String, Int32, Int32, array<Complex>[]()[][], String, String, String, String, array<String>[]()[][], String, array<String>[]()[][], Int32, Int32, Int32%)
X04 Class See Also Send Feedback
x04db prints a complex matrix stored in a two-dimensional array.

Syntax

C#
public static void x04db(
    string matrix,
    string diag,
    int m,
    int n,
    Complex[] a,
    string usefrm,
    string form,
    string title,
    string labrow,
    string[] rlabs,
    string labcol,
    string[] clabs,
    int ncols,
    int indent,
    out int ifail
)
Visual Basic
Public Shared Sub x04db ( _
    matrix As String, _
    diag As String, _
    m As Integer, _
    n As Integer, _
    a As Complex(), _
    usefrm As String, _
    form As String, _
    title As String, _
    labrow As String, _
    rlabs As String(), _
    labcol As String, _
    clabs As String(), _
    ncols As Integer, _
    indent As Integer, _
    <OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void x04db(
    String^ matrix,
    String^ diag,
    int m,
    int n,
    array<Complex>^ a,
    String^ usefrm,
    String^ form,
    String^ title,
    String^ labrow,
    array<String^>^ rlabs,
    String^ labcol,
    array<String^>^ clabs,
    int ncols,
    int indent,
    [OutAttribute] int% ifail
)
F#
static member x04db :
        matrix : string *
        diag : string *
        m : int *
        n : int *
        a : Complex[] *
        usefrm : string *
        form : string *
        title : string *
        labrow : string *
        rlabs : string[] *
        labcol : string *
        clabs : string[] *
        ncols : int *
        indent : int *
        ifail : int byref -> unit

Parameters

matrix
Type: System..::..String
On entry: indicates the part of the matrix to be printed.
matrix="G"
The whole of the rectangular matrix.
matrix="L"
The lower triangle of the matrix, or the lower trapezium if the matrix has more rows than columns.
matrix="U"
The upper triangle of the matrix, or the upper trapezium if the matrix has more columns than rows.
Constraint: matrix="G", "L" or "U".
diag
Type: System..::..String
On entry: unless matrix="G", diag must specify whether the diagonal elements of the matrix are to be printed.
diag="B"
The diagonal elements of the matrix are not referenced and not printed.
diag="U"
The diagonal elements of the matrix are not referenced, but are assumed all to be unity, and are printed as such.
diag="N"
The diagonal elements of the matrix are referenced and printed.
If matrix="G", then diag need not be set.
Constraint: if matrix≠"G", diag="B", "U" or "N".
m
Type: System..::..Int32
On entry: the number of rows and columns of the matrix, respectively, to be printed.
If either m or n is less than 1, x04db will exit immediately after printing title; no row or column labels are printed.
n
Type: System..::..Int32
On entry: the number of rows and columns of the matrix, respectively, to be printed.
If either m or n is less than 1, x04db will exit immediately after printing title; no row or column labels are printed.
a
Type: array< NagLibrary..::..Complex >[]()[][]
An array of size [dim1, dim2]
Note: dim1 must satisfy the constraint: dim1≥max 1,m
Note: the second dimension of the array a must be at least max 1,n.
On entry: the matrix to be printed. Only the elements that will be referred to, as specified by parameters matrix and diag, need be set.
usefrm
Type: System..::..String
On entry: indicates how the value of form is to be used to print matrix elements, except in MATLAB mode where usefrm is ignored.
usefrm="A"
The format code in form is assumed to contain a single real edit-descriptor which is to be used to print the real and imaginary parts of each complex number one above the other. Each row of the matrix is separated by a blank line, and any row labels are attached only to the real parts. This option means that about twice as many columns can be fitted into ncols characters than if any other usefrm option is used. A typical value of form for this usefrm option might be 'E13.4', '*' or ' '.
usefrm="B"
The format code in form is assumed to contain a single edit-descriptor such as 'E13.4', '*' or ' ' which is used to print the real and imaginary parts of each complex number separated by a comma, and surrounded by brackets. Thus a matrix element printed with this usefrm option might look like this: 12.345,-11.323.
usefrm="D"
The format code in form is used unaltered to print a complex number. This usefrm option allows you flexibility to specify exactly how the number is printed. With this option for usefrm and a suitable value for form it is possible, for example, to print a complex number in the form 0.123+3.214 i or 0.123E−02,0.234E−01. See [Example] for an example illustrating this option.
Constraint: usefrm="A", "B" or "D".
form
Type: System..::..String
On entry: describes the Fortran format code that is used in conjunction with usefrm for printing the elements of the matrix a. The format code may be any allowed on the system, whether it is standard Fortran or not. It may or may not be enclosed in brackets.
In addition, there are the following special codes which force x04db to choose its own format code:
form=' '
x04db will choose a format code such that numbers will be printed with an F8.4, an F11.4 or a 1PE13.4 format. The F8.4 code is chosen if the sizes of the real and imaginary parts of all the matrix elements to be printed lie between 0.001 and 1.0. The F11.4 code is chosen if the sizes of all the numbers to be printed lie between 0.001 and 9999.9999. Otherwise the 1PE13.4 code is chosen.
form='*'
x04db will choose a format code such that numbers will be printed to as many significant digits as are necessary to distinguish between neighbouring machine numbers. Thus any two numbers that are stored with different internal representations should look different on output. Whether they do in fact look different will depend on the run-time library of the Fortran compiler in use.
By preceding the desired format code by the string ‘MATLAB’, x04db will print the matrix such that it can be input into MATLAB, and title will be used as the name of the matrix.
More complicated values of form, to print a complex number in a desired form, may be used. See the description of parameter usefrm for more details.
Examples of valid values for form are '(F11.4)', '1P,2E13.5', 'MATLABF11.4', 'MATLAB*'.
Constraint: the character length of the format specifier in form must be ≤80.
title
Type: System..::..String
On entry: a title to be printed above the matrix, or name of the matrix.
If title=' ', no title (and no blank line) will be printed.
If title contains more than ncols characters, the contents of title will be wrapped onto more than one line, with the break after ncols characters.
Any trailing blank characters in title are ignored.
If printing in MATLAB mode, title will be used as the name of the matrix.
labrow
Type: System..::..String
On entry: indicates the type of labelling to be applied to the rows of the matrix, except in MATLAB mode where labrow is ignored.
labrow="N"
Prints no row labels.
labrow="I"
Prints integer row labels.
labrow="C"
Prints character labels, which must be supplied in array rlabs.
Constraint: labrow="N", "I" or "C".
rlabs
Type: array< System..::..String >[]()[][]
An array of size [dim1]
Note: the dimension of the array rlabs must be at least m if labrow="C", and at least 1 otherwise.
On entry: if labrow="C", rlabs must contain labels for the rows of the matrix, except in MATLAB mode where rlabs is ignored.
Labels are right-justified when output, in a field which is as wide as necessary to hold the longest row label. Note that this field width is subtracted from the number of usable columns, ncols.
labcol
Type: System..::..String
On entry: indicates the type of labelling to be applied to the columns of the matrix, except in MATLAB mode where labcol is ignored.
labcol="N"
Prints no column labels.
labcol="I"
Prints integer column labels.
labcol="C"
Prints character labels, which must be supplied in array clabs.
Constraint: labcol="N", "I" or "C".
clabs
Type: array< System..::..String >[]()[][]
An array of size [dim1]
Note: the dimension of the array clabs must be at least n if labcol="C", and at least 1 otherwise.
On entry: if labcol="C", clabs must contain labels for the columns of the matrix, except in MATLAB mode where clabs is ignored.
Labels are right-justified when output. Any label that is too long for the column width, which is determined by form, is truncated.
ncols
Type: System..::..Int32
On entry: the maximum output record length. If the number of columns of the matrix is too large to be accommodated in ncols characters, the matrix will be printed in parts, containing the largest possible number of matrix columns, and each part separated by a blank line.
ncols must be large enough to hold at least one column of the matrix using the format specifier in form. If a value less than 0 or greater than 132 is supplied for ncols, then the value 80 is used instead.
indent
Type: System..::..Int32
On entry: the number of columns by which the matrix (and any title and labels) should be indented. The effective value of ncols is reduced by indent columns. If a value less than 0 or greater than ncols is supplied for indent, the value 0 is used instead.
ifail
Type: System..::..Int32 %
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

x04db prints a complex matrix, or part of it, using a format specifier supplied by you. The matrix is output to the unit defined by (X04ABF not in this release).

References

None.

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDA) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry, matrix≠"G", "L" or "U".
ifail=2
On entry, matrix="L" or "U", but diag≠"N", "U" or "B".
ifail=4
On entry, usefrm≠"A", "B" or "D".
ifail=5
On entry, the format specifier in form is more than 80 characters long.
ifail=6
The format specifier in form cannot be used to output a number. The specifier probably has too wide a field width or contains an illegal edit descriptor.
ifail=7
On entry, either labrow or labcol≠"N", "I" or "C".
ifail=8
The quantity ncols-indent-labwid (where labwid is the width needed for the row labels) is not large enough to hold at least one column of the matrix.
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

Not applicable.

Parallelism and Performance

None.

Example

The example program calls x04db three times, first to print a 3 by 4 rectangular matrix, next to print a 4 by 4 upper triangular matrix, and then to print a 3 by 4 lower triangular matrix; various options for labelling and formatting are illustrated.

Example program (C#): x04dbe.cs

Example program results: x04dbe.r

See Also

X04 Class
X04 Members
x04db Overload


//      a00aa Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class A00AAE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {

        A00.a00aa();
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      Console.WriteLine("");
    }
    //
    //
  }
}


 **** NAG Library for .NET Release 2 platform x86 ****

Underlying Library Details

Product Code: DTW3A02DAL
Library Mark: 24
Microsoft Windows 32-bit editions


//      a00ac Example Program Text
//      Mark 21 Release.  NAG Copyright 2004.
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class a00ace
  {
    public static int Main (string[] args)
    {
      bool lmok=false;
      int ifail;
      Console.WriteLine("a00ac Example Program Results");
      lmok = A00.a00ac();
      if (lmok)
      {
        Console.WriteLine(" {0}","A valid licence key is available");
      }
      else
      {
        Console.WriteLine(" {0}","No valid licence key was found");
      }
      //
      return 0;
    }
  }
}


//      c05au Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class C05AUE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        //   C05.C05AG_F fC05AG = new C05.C05AG_F(f);
        C05.C05AU_F fC05AU = new C05.C05AU_F(f);
        double a,  b,  eps,  eta,  h,  x; int ifail;
        Console.WriteLine("c05au Example Program Results");
        x = 1.00e0;
        h = 0.10e0;
        eps = 1.00e-5;
        eta = 0.00e0;
        //
      //    C05.c05ag(ref x, h, eps, eta, fC05AG, out a, out b, out ifail);
        C05.c05au(ref x, h, eps, eta, fC05AU, out a, out b, out ifail);
        //
        Console.WriteLine("");
        if (ifail == 0)
        {
          Console.WriteLine("  {0}{1,13:f5}", "Root is ", x);
          Console.WriteLine("  {0}{1,8:f5}{2}{3,8:f5}{4}", "Interval searched is [", a, ",", b, "]");
        }
        else
        {
          Console.WriteLine("** c05au failed with ifail = {0,5}", ifail);
          if ((ifail == 3) || (ifail == 4))
          {
            Console.WriteLine("  {0}{1,13:f5}", "Final value = ", x);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      Console.WriteLine("");
    }
    //
    public static double f(double x)
    {
      double fValue;
      fValue = x - Math.Exp(-x);
      return fValue;
    }
  }
}


c05au Example Program Results

  Root is       0.56714
  Interval searched is [ 0.50000, 0.90000]


//      c05av Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class C05AVE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        double boundl,  boundu,  fx,  h,  x,  y; int ind;
        double[] c = new double[11];
        int ifail;
        Console.WriteLine("c05av Example Program Results");
        Console.WriteLine("");
        x = 3.00e0;
        h = 0.10e0;
        boundl = 0.00e0;
        boundu = 4.00e0;
        fx = 0.0;
        y = 0.0;
        ind = 1;
        //
        do
        {
          C05.c05av(ref x, fx, ref h, boundl, boundu, ref y, c, ref ind, out ifail);
          //
          fx = x * x - 3.00e0 * x + 2.00e0;
          } while (ind != 0);
          if (ifail == 0)
          {
            Console.WriteLine(" {0}","Interval containing root is [X,Y], where");
            Console.WriteLine("  {0}{1,12:f4}{2}{3,12:f4}","x =",x,"   y =",y);
            Console.WriteLine(" {0}","Values of f at x and y are");
            Console.WriteLine("  {0}{1,12:f2}{2}{3,12:f2}","f(x) =",fx,"   f(y) =",c[0]);
          }
          else
          {
            Console.WriteLine("");
            Console.WriteLine("** c05av failed with ifail = {0,5}", ifail);
          }
          //
        }
        catch (Exception e)
        {
          Console.WriteLine(e.Message);
          Console.WriteLine("Exception Raised");
        }
        Console.WriteLine("");
      }
    }
  }


c05av Example Program Results

 Interval containing root is [X,Y], where
  x =      1.7000   y =      2.5000
 Values of f at x and y are
  f(x) =       -0.21   f(y) =        0.75


//      c05aw Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class C05AWE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {

    //C05.C05AJ_F fC05AJ = new C05.C05AJ_F(f);
        C05.C05AW_F fC05AW = new C05.C05AW_F(f);
        double eps,  eta,  x; int k;
        int nfmax;
        int ifail;
        Console.WriteLine("c05aw Example Program Results");
        for (k = 3; k <= 4; k++)
        {
          eps = Math.Pow(10.00e0, (-k));
          x = 1.00e0;
          eta = 0.00e0;
          nfmax = 200;
          //
      //C05.c05aj(ref x, eps, eta, fC05AJ, nfmax, out ifail);
          C05.c05aw(ref x, eps, eta, fC05AW, nfmax, out ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine("  {0}{1,10:e2}{2}{3,14:f5}", "With eps = ", eps, "   root = ", x);
          }
          else if (ifail < 0)
          {
            Console.WriteLine("");
            Console.WriteLine("** c05aw failed with ifail = {0,5}", ifail);
            goto L40;
          }
          else
          {
            Console.WriteLine("** c05aw failed with ifail = {0,5}", ifail);
            if ((ifail == 3) || (ifail == 4))
            {
              Console.WriteLine("  {0}{1,10:e2}{2}{3,14:f5}", "With eps = ", eps, " final value = ", x);
            }
          }
        }
        L40: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      Console.WriteLine("");
    }
    //
    //
    public static double f(double x)
    {
      double fValue;
      fValue = Math.Exp(-x) - x;
      return fValue;
    }
  }
}


c05aw Example Program Results
  With eps =  1.00e-003   root =        0.56715
  With eps =  1.00e-004   root =        0.56715


//      c05ax Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class C05AXE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        double fx=0.0,  scal=0.0,  tol=0.0,  x=0.0; int i,  ind,  ir;
        double[] c = new double[26];
        int ifail;
        Console.WriteLine("c05ax Example Program Results");
        scal = Math.Sqrt(X02.x02aj());
        ir = 0;
        for (i = 3 ; i <= 4 ; i++)
        {
          tol = Math.Pow(10.00e0 ,( -i));
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,10:e4}","tol = ",tol);
          Console.WriteLine("");
          x = 1.00e0;
          ind = 1;
          //
          do
          {
            C05.c05ax(ref x, fx, tol, ir, scal, c, ref ind, out ifail);
            //
            fx = x - Math.Exp( -x);
            }while (ind != 0);
            if (ifail < 0)
            {
              Console.WriteLine("");
              Console.WriteLine("** c05ax failed with ifail = {0,5}", ifail);
            }
            else if (ifail > 0)
            {
              Console.WriteLine("  {0}{1,5}","Error exit, ifail =",ifail);
              if ((ifail == 4) || (ifail == 6))
              {
                Console.WriteLine("  {0}{1,14:f5}{2}{3,10:f2}{4}{5,10:f2}","Final value = ",x," theta = ",c[4]," lambda = ",c[6]);
              }
            }
            else
            {
              Console.WriteLine("  {0}{1,14:f5}","Root is ",x);
            }
          }
          //
        }
        catch (Exception e)
        {
          Console.WriteLine(e.Message);
          Console.WriteLine("Exception Raised");
        }
        Console.WriteLine("");
      }
    }
  }


c05ax Example Program Results

  tol = 1.0000e-003

  Root is        0.56715

  tol = 1.0000e-004

  Root is        0.56715


//      c05ay Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class C05AYE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
       //C05.C05AD_F fC05AD = new C05.C05AD_F(f);
          C05.C05AY_F fC05AY = new C05.C05AY_F(f);
        double a,   b,   eps,    eta,   x; int ifail; Console.WriteLine("c05ay Example Program Results");
        a = 0.00e0;
        b = 1.00e0;
        eps = 1.00e-5;
        eta = 0.00e0;
        //
          // C05.c05ad(a, b, eps, eta, fC05AD, out x, out ifail);
        C05.c05ay(a, b, eps, eta, fC05AY, out x, out ifail);
        //
        Console.WriteLine("");
        if (ifail == 0)
        {
          Console.WriteLine("  {0}{1,12:f5}","Zero at x =",x);
        }
        else
        {
          Console.WriteLine("  {0}{1,5}"," ** c05ay returned with ifail = ",ifail);
          if ((ifail == 2) || (ifail == 3))
          {
            Console.WriteLine("  {0}{1,12:f5}","Final point = ",x);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      Console.WriteLine("");
    }
    //
    //
    public static double f (double x)
    {
      double fValue;
      fValue = Math.Exp( -x) - x;
      return fValue;
    }
  }
}


c05ay Example Program Results

  Zero at x =     0.56714


//      c05az Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class C05AZE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        double fx=0.0,  tolx,  x,  y;
        int ind;
        int ir = 0;
        double[] c = new double[17];
        int ifail;
        Console.WriteLine("c05az Example Program Results");
        Console.WriteLine("");
        Console.WriteLine(" {0}", " Iterations");
        Console.WriteLine("");
        tolx = 1.00e-5;
        x = 0.00e0;
        y = 1.00e0;
        ind = 1;
        //
        do
        {
          C05.c05az(ref x, ref y,   fx, tolx, ir, c, ref ind, out ifail);
          //
          fx = f(ref x);
          Console.WriteLine("  {0}{1,8:f5}{2}{3,12:e4}{4}{5,2}", " x =", x, "   fx =", fx, "   ind =", ind);
          } while (ind != 0 );
          if (ifail == 0)
          {
            Console.WriteLine("");
            Console.WriteLine(" {0}", " Solution");
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,8:f5}{2}{3,8:f5}", " x =", x, "   y =", y);
          }
          else
          {
            if (ifail < 0)
            {
              Console.WriteLine("");
            }
            Console.WriteLine("** c05az failed with ifail = {0,5}", ifail);
            if ((ifail == 4) || (ifail == 5))
            {
              Console.WriteLine("  {0}{1,8:f5}{2}{3,8:f5}", "x =", x, "  y =", y);
            }
          }
          //
        }
        catch (Exception e)
        {
          Console.WriteLine(e.Message);
          Console.WriteLine("Exception Raised");
        }
        Console.WriteLine("");
      }
      //
      public static double f(ref double x)
      {
        double fValue;
        fValue = Math.Exp(-x) - x;
        return fValue;
      }
    }
  }


//      c05qb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class C05QBE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        int n = 9;
          // C05.C05NB_FCN fcnC05NB = new C05.C05NB_FCN(fcn);
        C05.C05QB_FCN fcnC05QB = new C05.C05QB_FCN(fcn);
        double fnorm,   xtol; int i,  j;
        double[] fvec = new double[n];
        double[] x = new double[n];
        int ifail;
        Console.WriteLine("c05qb Example Program Results");
        Console.WriteLine("");
        //      The following starting values provide a rough solution.
        for (j = 1; j <= n; j++)
        {
          x[j - 1] = -1.00e0;
        }
        xtol = Math.Sqrt(X02.x02aj());
        //
    //C05.c05nb(fcnC05NB, n, x, fvec, xtol, out ifail);
        C05.c05qb(fcnC05QB, n, x, fvec, xtol, out ifail);
        //
        if (ifail == 0)
        {
          fnorm = F06.f06ej(n, fvec, 1, out ifail);
          Console.WriteLine("  {0}{1,12:e4}", "Final 2-norm of the residuals =", fnorm);
          Console.WriteLine("");
          Console.WriteLine(" {0}", "Final approximate solution");
          Console.WriteLine("");
          for (j = 1; j <= n; j++)
          {
            Console.Write(" {0,10:f4}{1}", x[j - 1], j % 3 == 0 ? "\n" : "");
          }
          Console.WriteLine("");
        }
        else if (ifail < 0)
        {
          Console.WriteLine("");
          Console.WriteLine("** c05qb failed with ifail = {0,5}", ifail);
        }
        else
        {
          Console.WriteLine("  {0}{1,5}", "ifail = ", ifail);
          if (ifail > 1)
          {
            Console.WriteLine("");
            Console.WriteLine(" {0}", "Approximate solution");
            Console.WriteLine("");
            for (i = 1; i <= n; i++)
            {
              Console.Write(" {0}", x[i - 1]);
            }
            Console.WriteLine("");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      Console.WriteLine("");
    }
    //
    public static void fcn(int n, double[] x, double[] fvec, ref int iflag)
    {
      const double one = 1.00e0;
      const double two = 2.00e0;
      const double three = 3.00e0;
      for (int k = 1; k <= n; k++)
      {
        fvec[k - 1] = (three - two * x[k - 1]) * x[k - 1] + one;
        if (k > 1)
        {
          fvec[k - 1] = fvec[k - 1] - x[k - 2];
        }
        if (k < n)
        {
          fvec[k - 1] = fvec[k - 1] - two * x[k];
        }
      }
    }
  }
}


//      c05qc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class C05QCE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int n=9;
          //C05.C05NC_FCN fcnC05NC = new C05.C05NC_FCN(fcn);
        C05.C05QC_FCN fcnC05QC = new C05.C05QC_FCN(fcn);
        double epsfcn,   factor,   fnorm,   xtol; int j,  maxfev,  ml,  mode,  mu,  nfev,  nprint;
        double[] diag = new double[n];
        double[,] fjac = new double[n, n];
        double[] fvec = new double[n];
        double[] qtf = new double[n];
        double[] r = new double[n*(n+1)/2];
        double[] x = new double[n];
        int ifail;
        Console.WriteLine("c05qc Example Program Results");
        Console.WriteLine("");
        //      The following starting values provide a rough solution.
        for (j = 1 ; j <= n ; j++)
        {
          x[j - 1] =  -1.00e0;
        }
        xtol = Math.Sqrt(X02.x02aj());
        for (j = 1 ; j <= n ; j++)
        {
          diag[j - 1] = 1.00e0;
        }
        maxfev = 2000;
        ml = 1;
        mu = 1;
        epsfcn = 0.00e0;
        mode = 2;
        factor = 100.00e0;
        nprint = 0;
        //
    /*  C05.c05nc(fcnC05NC, n, x, fvec, xtol, maxfev, ml, mu, epsfcn,diag, mode, factor, nprint,
        out nfev, fjac, r, qtf, out ifail);*/
        C05.c05qc(fcnC05QC, n, x, fvec, xtol, maxfev, ml, mu, epsfcn, mode, diag, factor, nprint,
        out nfev, fjac, r, qtf, out ifail);
        //
        if (ifail == 0)
        {
          fnorm = F06.f06ej(n, fvec, 1, out ifail);
          Console.WriteLine("  {0}{1,12:e4}","Final 2-norm of the residuals =",fnorm);
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,10}","Number of function evaluations =",nfev);
          Console.WriteLine("");
          Console.WriteLine(" {0}","Final approximate solution");
          Console.WriteLine("");
          for (j = 1 ; j <= n ; j++)
          {
            Console.Write(" {0,10:f4}{1}", x[j - 1], j % 3 == 0 ? "\n" : "");
          }
          Console.WriteLine("");
        }
        else if (ifail < 0)
        {
          Console.WriteLine("");
          Console.WriteLine("** c05qc failed with ifail = {0,5}", ifail);
        }
        else
        {
          Console.WriteLine("  {0}{1,5}","ifail = ",ifail);
          if (ifail >= (2))
          {
            Console.WriteLine("");
            Console.WriteLine(" {0}","Approximate solution");
            Console.WriteLine("");
            for (j = 1 ; j <= n ; j++)
            {
              Console.Write(" {0, 10:f4}", x[j - 1]);
            }
            Console.WriteLine("");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      Console.WriteLine("");
    }
    //
    //
    public static void fcn (int n, double[] x, double[] fvec, ref int iflag)
    {
      const double one=1.00e0;
      const double two=2.00e0;
      const double three=3.00e0;
      int k=0;
      if (iflag == 0)
      {
        //
        //         Insert print statements here when nprint is positive.
        //
      }
      else
      {
        for (k = 1 ; k <= n ; k++)
        {
          fvec[k - 1] = (three - two * x[k - 1]) * x[k - 1] + one;
          if (k > 1)
          {
            fvec[k - 1] = fvec[k - 1] - x[k - 2];
          }
          if (k < n)
          {
            fvec[k - 1] = fvec[k - 1] - two * x[k];
          }
        }
      }
    }
  }
}


c05qc Example Program Results

  Final 2-norm of the residuals = 1.1926e-008

  Number of function evaluations =        14

 Final approximate solution

    -0.5707    -0.6816    -0.7017
    -0.7042    -0.7014    -0.6919
    -0.6658    -0.5960    -0.4164


//      c05qd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class C05QDE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int n=9;
        const double one=1.00e0;
        const double two=2.00e0;
        const double three=3.00e0;
        double epsfcn,  factor=0.0,  fnorm=0.0,  xtol=0.0; int icount,  irevcm, j=0,  k=0, ml=0, mode=0, mu=0;
        double[] diag = new double[n];
        double[,] fjac = new double[n, n];
        double[] fvec = new double[n];
        double[] qtf = new double[n];
        double[] r = new double[n*(n+1)/2];
        double[] x = new double[n];
        int ifail;
        Console.WriteLine("c05qd Example Program Results");
        //      The following starting values provide a rough solution.
        for (j = 1 ; j <= n ; j++)
        {
          x[j - 1] =  -1.00e0;
        }
        xtol = Math.Sqrt(X02.x02aj());
        for (j = 1 ; j <= n ; j++)
        {
          diag[j - 1] = 1.00e0;
        }
        ml = 1;
        mu = 1;
        epsfcn = 0.00e0;
        mode = 2;
        factor = 100.00e0;
        icount = 0;
        irevcm = 0;
        //
    //C05.c05ndCommunications communications  = new C05.c05ndCommunications(n);
        C05.c05qdCommunications communications  = new C05.c05qdCommunications(n);
        do
        {
        /*     C05.c05nd(ref irevcm, n, x, fvec, xtol, ml, mu, epsfcn, diag, mode , factor, fjac, r, qtf,
          communications, out ifail );*/
          C05.c05qd(ref irevcm, n, x, fvec, xtol, ml, mu, epsfcn, mode, diag, factor, fjac, r, qtf,
          communications, out ifail );
          //
          if (irevcm == 1)
          {
            icount = icount + 1;
            //         Insert print statements here to monitor progess if desired.
          }
          else if (irevcm == 2)
          {
            //         Evaluate functions at given point
            for (k = 1 ; k <= n ; k++)
            {
              fvec[k - 1] = (three - two * x[k - 1]) * x[k - 1] + one;
              if (k > 1)
              {
                fvec[k - 1] = fvec[k - 1] - x[k - 2];
              }
              if (k < n)
              {
                fvec[k - 1] = fvec[k - 1] - two * x[k];
              }
            }
          }
          } while (irevcm != 0);
          //
          Console.WriteLine("");
          if (ifail == 0)
          {
            fnorm = F06.f06ej(n, fvec, 1, out ifail);
            Console.WriteLine("  {0}{1,4}{2}{3,12:e4}","Final 2-norm of the residuals after",icount," iterations is ",fnorm);
            Console.WriteLine("");
            Console.WriteLine(" {0}","Final approximate solution");
            for (j = 1 ; j <= n ; j++)
            {
              Console.Write(" {0, 10:f4}{1}", x[j - 1], j%3==0?"\n":"");
            }
            Console.WriteLine("");
          }
          else if (ifail == 1)
          {
            Console.WriteLine("");
            Console.WriteLine("** c05qd failed with ifail = {0,5}", ifail);
          }
          else
          {
            Console.WriteLine("  {0}{1,4}","ifail =",ifail);
            if (ifail >= (2))
            {
              Console.WriteLine(" {0}","Approximate solution");
              for (j = 1 ; j <= n ; j++)
              {
                Console.Write(" {0, 10:f4}{1}", x[j - 1], x[j - 1], j%3==0?"\n":"");
              }
              Console.WriteLine("");
            }
          }
          //
        }
        catch (Exception e)
        {
          Console.WriteLine(e.Message);
          Console.WriteLine("Exception Raised");
        }
        Console.WriteLine("");
      }
    }
  }


c05qd Example Program Results

  Final 2-norm of the residuals after  11 iterations is  1.1926e-008

 Final approximate solution
    -0.5707    -0.6816    -0.7017
    -0.7042    -0.7014    -0.6919
    -0.6658    -0.5960    -0.4164


//      c05rb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class C05RBE
  {
    static double[] ruser = new double[5];
    //
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int n = 9;
          //C05.C05PB_FCN fcnC05PB = new C05.C05PB_FCN(fcn);
        C05.C05RB_FCN fcnC05RB = new C05.C05RB_FCN(fcn);
        double fnorm,  tol;
        int j = 0;
        double[,] fjac = new double[n, n];
        double[] fvec = new double[n];
        double[] x = new double[n];
        int ifail;
        Console.WriteLine("c05rb Example Program Results");
        Console.WriteLine("");
        //      The following starting values provide a rough solution.
        for (j = 1; j <= n; j++)
        {
          x[j - 1] = -1.00e0;
        }
        //      Store the coefficients describing the system
        ruser[0] = -1.00e0;
        ruser[1] = 3.00e0;
        ruser[2] = -2.00e0;
        ruser[3] = -2.00e0;
        ruser[4] = -1.00e0;
        //
        tol = Math.Sqrt(X02.x02aj());
        //
    // C05.c05pb(fcnC05PB, n, x, fvec, fjac, tol, out ifail);
        C05.c05rb(fcnC05RB, n, x, fvec, fjac, tol, out ifail);
        //
        if (ifail == 0)
        {
          fnorm = F06.f06ej(n, fvec, 1, out ifail);
          Console.WriteLine("  {0}{1,12:e4}", "Final 2-norm of the residuals =", fnorm);
          Console.WriteLine("");
          Console.WriteLine(" {0}", "Final approximate solution");
          Console.WriteLine("");
          for (j = 1; j <= n; j++)
          {
            Console.Write(" {0, 10:f4}{1}", x[j - 1], j%3==0?"\n":"");
          }
          Console.WriteLine("");
        }
        else if (ifail < 0)
        {
          Console.WriteLine("");
          Console.WriteLine("** c05rb failed with ifail = {0,5}", ifail);
        }
        else
        {
          Console.WriteLine("  {0}{1,5}", "ifail = ", ifail);
          if (ifail >= (2))
          {
            Console.WriteLine("");
            Console.WriteLine(" {0}", "Approximate solution");
            Console.WriteLine("");
            for (j = 1; j <= n; j++)
            {
              Console.Write(" {0, 10:f4}", x[j - 1], j%3==0?"\n":"");
            }
            Console.WriteLine("");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      Console.WriteLine("");
    }
    //
    //
    public static void fcn(int n, double[] x, double[] fvec, double[,] fjac,
    ref int iflag)
    {
      const double zero = 0.00e0;
      int j,  k;
      if (iflag != 2)
      {
        for (k = 1; k <= n; k++)
        {
          fvec[k - 1] = (ruser[1] + ruser[2] * x[k - 1]) * x[k - 1] - ruser[4];
          if (k > 1)
          {
            fvec[k - 1] = fvec[k - 1] + ruser[0] * x[k - 2];
          }
          if (k < n)
          {
            fvec[k - 1] = fvec[k - 1] + ruser[3] * x[k];
          }
        }
      }
      else
      {
        for (k = 1; k <= n; k++)
        {
          for (j = 1; j <= n; j++)
          {
            fjac[k - 1, j - 1] = zero;
          }
          fjac[k - 1, k - 1] = ruser[1] + 2.00e0 * ruser[2] * x[k - 1];
          if (k > 1)
          {
            fjac[k - 1, k - 2] = ruser[0];
          }
          if (k < n)
          {
            fjac[k - 1, k] = ruser[3];
          }
        }
      }
    }
  }
}


//      c05rc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class C05RCE
  {
    static double[] ruser = new double[5];
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int n = 9;
          // C05.C05PC_FCN fcnC05PC = new C05.C05PC_FCN(fcn);
        C05.C05RC_FCN fcnC05RC = new C05.C05RC_FCN(fcn);
        double factor,  fnorm,  xtol = 0.0; int j, maxfev,  mode, nfev = 0, njev = 0, nprint = 0;
        double[] diag = new double[n];
        double[,] fjac = new double[n, n];
        double[] fvec = new double[n];
        double[] qtf = new double[n];
        double[] r = new double[n*(n+1)/2];
        double[] x = new double[n];
        int ifail;
        Console.WriteLine("c05rc Example Program Results");
        Console.WriteLine("");
        //      Store the coefficients describing the system
        ruser[0] = -1.00e0;
        ruser[1] = 3.00e0;
        ruser[2] = -2.00e0;
        ruser[3] = -2.00e0;
        ruser[4] = -1.00e0;
        //
        //      The following starting values provide a rough solution.
        for (j = 1; j <= n; j++)
        {
          x[j - 1] = -1.00e0;
        }
        xtol = Math.Sqrt(X02.x02aj());
        for (j = 1; j <= n; j++)
        {
          diag[j - 1] = 1.00e0;
        }
        maxfev = 1000;
        mode = 2;
        factor = 100.00e0;
        //
    /*C05.c05pc(fcnC05PC, n, x, fvec, fjac, xtol, maxfev, diag, mode, factor, nprint, out nfev,
        out njev, r, qtf, out ifail);*/
        C05.c05rc(fcnC05RC, n, x, fvec, fjac, xtol, maxfev, mode, diag, factor, nprint, out nfev,
        out njev, r, qtf, out ifail);
        //
        if (ifail == 0)
        {
          fnorm = F06.f06ej(n, fvec, 1, out ifail);
          Console.WriteLine("  {0}{1,12:e4}", "Final 2-norm of the residuals =", fnorm);
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,10}", "Number of function evaluations =", nfev);
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,10}", "Number of Jacobian evaluations =", njev);
          Console.WriteLine("");
          Console.WriteLine(" {0}", "Final approximate solution");
          Console.WriteLine("");
          for (j = 1; j <= n; j++)
          {
            Console.Write(" {0, 10:f4}{1}", x[j - 1], j%3==0?"\n":"");
          }
          Console.WriteLine("");
        }
        else if (ifail < 0)
        {
          Console.WriteLine("");
          Console.WriteLine("** c05rc failed with ifail = {0,5}", ifail);
        }
        else
        {
          Console.WriteLine("  {0}{1,5}", "ifail = ", ifail);
          if (ifail > 2)
          {
            Console.WriteLine("");
            Console.WriteLine(" {0}", "Approximate solution:");
            Console.WriteLine("");
            for (j = 1; j <= n; j++)
            {
              Console.Write(" {0, 10:f4}{1}", x[j - 1], j%3==0?"\n":"");
            }
            Console.WriteLine("");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      Console.WriteLine("");
    }
    //
    public static void fcn(int n, double[] x, double[] fvec, double[,] fjac,
    ref int iflag)
    {
      const double zero = 0.00e0;
      if (iflag == 0)
      {
        //
        //         Insert print statements here when nprint is positive.
        //
      }
      else if (iflag != 2)
      {
        for (int k = 1; k <= n; k++)
        {
          fvec[k - 1] = (ruser[1] + ruser[2] * x[k - 1]) * x[k - 1] - ruser[4];
          if (k > 1)
          {
            fvec[k - 1] = fvec[k - 1] + ruser[0] * x[k - 2];
          }
          if (k < n)
          {
            fvec[k - 1] = fvec[k - 1] + ruser[3] * x[k];
          }
        }
      }
      else
      {
        for (int k = 1; k <= n; k++)
        {
          for (int j = 1; j <= n; j++)
          {
            fjac[k - 1, j - 1] = zero;
          }
          fjac[k - 1, k - 1] = ruser[1] + 2.00e0 * ruser[2] * x[k - 1];
          if (k > 1)
          {
            fjac[k - 1, k - 2] = ruser[0];
          }
          if (k < n)
          {
            fjac[k - 1, k] = ruser[3];
          }
        }
      }
    }
  }
}


c05rc Example Program Results

  Final 2-norm of the residuals = 1.1926e-008

  Number of function evaluations =        11

  Number of Jacobian evaluations =         1

 Final approximate solution

    -0.5707    -0.6816    -0.7017
    -0.7042    -0.7014    -0.6919
    -0.6658    -0.5960    -0.4164


//      c05rd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class C05RDE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int n=9;
        const double zero=0.00e0;
        const double one=1.00e0;
        const double two=2.00e0;
        const double three=3.00e0;
        const double four=4.00e0;
        double factor,  fnorm,  xtol=0.0; int icount=0, irevcm=0, j=0, k=0, mode;
        double[] diag = new double[n];
        double[,] fjac = new double[n, n];
        double[] fvec = new double[n];
        double[] qtf = new double[n];
        double[] r = new double[n*(n + 1)/2];
        double[] x = new double[n];
        int ifail;
        Console.WriteLine("c05rd Example Program Results");
        //      The following starting values provide a rough solution.
        for (j = 1 ; j <= n ; j++)
        {
          x[j - 1] =  -1.00e0;
        }
        xtol = Math.Sqrt(X02.x02aj());
        for (j = 1 ; j <= n ; j++)
        {
          diag[j - 1] = 1.00e0;
        }
        mode = 2;
        factor = 100.00e0;
        //
    // C05.c05pdCommunications communications  = new C05.c05pdCommunications(n);
        C05.c05rdCommunications communications  = new C05.c05rdCommunications(n);
        do
        {
        /*C05.c05pd(ref irevcm, n, x, fvec, fjac, xtol, diag, mode, factor, r, qtf,
          communications, out ifail );*/
          C05.c05rd(ref irevcm, n, x, fvec, fjac, xtol, mode, diag, factor, r, qtf,
          communications, out ifail );
          //
          if (irevcm == 1)
          {
            icount = icount + 1;
            //         Insert print statements here to monitor progess if desired
          }
          else if (irevcm == 2)
          {
            //         Evaluate functions at current point
            for (k = 1 ; k <= n ; k++)
            {
              fvec[k - 1] = (three - two * x[k - 1]) * x[k - 1] + one;
              if (k > 1)
              {
                fvec[k - 1] = fvec[k - 1] - x[k - 2];
              }
              if (k < n)
              {
                fvec[k - 1] = fvec[k - 1] - two * x[k];
              }
            }
          }
          else if (irevcm == 3)
          {
            //         Evaluate Jacobian at current point
            for (k = 1 ; k <= n ; k++)
            {
              for (j = 1 ; j <= n ; j++)
              {
                fjac[k - 1 , j - 1] = zero;
              }
              fjac[k - 1 , k - 1] = three - four * x[k - 1];
              if (k != 1)
              {
                fjac[k - 1 , k - 2] =  -one;
              }
              if (k != n)
              {
                fjac[k - 1 , k] =  -two;
              }
            }
          }
          } while (irevcm != 0);
          //
          Console.WriteLine("");
          if (ifail == 0)
          {
            fnorm = F06.f06ej(n, fvec, 1, out ifail);
            Console.WriteLine("  {0}{1,4}{2}{3,12:e4}","Final 2 norm of the residuals after",icount," iterations is ",fnorm);
            Console.WriteLine("");
            Console.WriteLine(" {0}","Final approximate solution");
            for (j = 1 ; j <= n ; j++)
            {
              Console.Write(" {0, 10:f4}{1}", x[j - 1], j%3==0?"\n":"");
            }
            Console.WriteLine("");
          }
          else if (ifail == 1)
          {
            Console.WriteLine("");
            Console.WriteLine("** c05rd failed with ifail = {0,5}", ifail);
          }
          else
          {
            Console.WriteLine("  {0}{1,4}","ifail =",ifail);
            if (ifail >= 2)
            {
              Console.WriteLine(" {0}","Approximate solution");
              for (j = 1 ; j <= n ; j++)
              {
                Console.Write(" {0, 10:f4}{1}", x[j - 1], j%3==0?"\n":"");
              }
              Console.WriteLine("");
            }
          }
          //
        }
        catch (Exception e)
        {
          Console.WriteLine(e.Message);
          Console.WriteLine("Exception Raised");
        }
        Console.WriteLine("");
      }
    }
  }


c05rd Example Program Results

  Final 2 norm of the residuals after  11 iterations is  1.1926e-008

 Final approximate solution
    -0.5707    -0.6816    -0.7017
    -0.7042    -0.7014    -0.6919
    -0.6658    -0.5960    -0.4164


//      c05zd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class C05ZDE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int m = 15;
        const int n = 3;
        int i,  mode; double[] err = new double[m];
        double[,] fjac = new double[m, n];
        double[] fvec = new double[m];
        double[] fvecp = new double[m];
        double[] x = new double[n];
        double[] xp = new double[n];
        int ifail;
        Console.WriteLine("c05zd Example Program Results");
        //
        x[0] = 9.20e-1;
        x[1] = 1.30e-1;
        x[2] = 5.40e-1;
        mode = 1;
        //
          // C05.c05za(m, n, x, fvec, fjac, xp, fvecp, mode, err, out ifail);
        C05.c05zd(mode, m, n, x, fvec, fjac, xp, fvecp,  err, out ifail);
        //
        fcn(m, n, x, fvec, fjac, m, 1);
        fcn(m, n, x, fvec, fjac, m, 2);
        fcn(m, n, xp, fvecp, fjac, m, 1);
        //
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     fvec at x = ");
        for (i = 1; i <= n; i++)
        {
          Console.Write(" {0, 10:f4}{1}", x[i - 1], i%3==0?"\n":"");
        }
        Console.WriteLine("");
        Console.WriteLine("");
        for (i = 1; i <= m; i++)
        {
          Console.Write(" {0,10:f4}{1}", fvec[i - 1],i%3==0?"\n":"");
        }
        Console.WriteLine("");
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     fvecp at xp = ");
        for (i = 1; i <= n; i++)
        {
          Console.Write(" {0,10:f4}", xp[i - 1]);
        }
        Console.WriteLine("");
        Console.WriteLine("");
        for (i = 1; i <= m; i++)
        {
          Console.Write(" {0,10:f4}{1}", fvecp[i - 1], i % 3 == 0 ? "\n" : "");
        }
        Console.WriteLine("");
        //
        mode = 2;
        //
        C05.c05zd( mode,m, n, x, fvec, fjac, xp, fvecp, err,out ifail);
        //
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     err");
        Console.WriteLine("");
        for (i = 1; i <= m; i++)
        {
          Console.Write(" {0,10:f4}{1}", err[i - 1], i % 3 == 0 ? "\n" : "");
        }
        Console.WriteLine("");
        //
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      Console.WriteLine("");
    }
    //
    public static void fcn(int m, int n, double[] x, double[] fvec, double[,] fjac,
    int ldfjac,  int iflag) { double tmp1,  tmp2,  tmp3,  tmp4;
    int i = 0;
    double[] y = new double[15] { 1.40e-1, 1.80e-1, 2.20e-1, 2.50e-1, 2.90e-1, 3.20e-1, 3.50e-1, 3.90e-1, 3.70e-1, 5.80e-1, 7.30e-1, 9.60e-1, 1.340e0, 2.10e0, 4.390e0 };
    if (iflag != 2)
    {
      for (i = 1; i <= m; i++)
      {
        tmp1 = (double)i;
        tmp2 = m + 1 - i;
        tmp3 = (double)tmp1;
        if (i > (m + 1) / 2)
        {
          tmp3 = (double)tmp2;
        }
        fvec[i - 1] = y[i - 1] - (x[0] + tmp1 / (x[1] * tmp2 + x[2] * tmp3));
      }
    }
    else
    {
      for (i = 1; i <= m; i++)
      {
        tmp1 = (double)i;
        tmp2 = m + 1 - i;
        //
        //            Error introduced into next statement for illustration.
        //            Corrected statement should read    tmp3 = tmp1.
        //
        tmp3 = (double)tmp2;
        if (i > (m + 1) / 2)
        {
          tmp3 = (double)tmp2;
        }
        tmp4 = ((x[1] * tmp2 + x[2] * tmp3)) * ((x[1] * tmp2 + x[2] * tmp3));
        fjac[i - 1, 0] = -1.00e0;
        fjac[i - 1, 1] = tmp1 * tmp2 / tmp4;
        fjac[i - 1, 2] = tmp1 * tmp3 / tmp4;
      }
    }
  }
}
}


//      c06ea Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class C06EAE
  {
    static string datafile = "ExampleData/c06eae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int j,  n,  n2,  nj;
        int ifail;
        Console.WriteLine("c06ea Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        try
        {
          while (true)
          {
            sr.Reset();
            n = int.Parse(sr.Next());
            if (n >= 1)
            {
              double[] a = new double[n];
              double[] b = new double[n];
              double[] x = new double[n];
              double[] xx = new double[n];
              for (j = 0 ; j <= n - 1 ; j++)
              {
                sr.Reset();
                x[j - 0] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                xx[j - 0] = x[j - 0];
              }
              //
              C06.c06ea(x, n, out ifail);
              //
              if (ifail == 0)
              {
                Console.WriteLine("");
                Console.WriteLine(" {0}","Components of discrete Fourier transform");
                Console.WriteLine("");
                Console.WriteLine(" {0}","          Real      Imag");
                Console.WriteLine("");
                a[0] = x[0];
                b[0] = 0.00e0;
                n2 = (n - 1) / 2;
                for (j = 1 ; j <= n2 ; j++)
                {
                  nj = n - j;
                  a[j - 0] = x[j - 0];
                  a[nj - 0] = x[j - 0];
                  b[j - 0] = x[nj - 0];
                  b[nj - 0] =  -x[nj - 0];
                }
                if (( n % 2 ) == 0)
                {
                  a[n2 + 1 - 0] = x[n2 + 1 - 0];
                  b[n2 + 1 - 0] = 0.00e0;
                }
                for (j = 0 ; j <= n - 1 ; j++)
                {
                  Console.WriteLine("  {0,5}{1,10:f5}{2,10:f5}",j,a[j - 0],b[j - 0]);
                }
                //
                C06.c06gb(x, n, out ifail);
                C06.c06eb(x, n, out ifail);
                //
                Console.WriteLine("");
                Console.WriteLine(" {0}","Original sequence as restored by inverse transform");
                Console.WriteLine("");
                Console.WriteLine(" {0}","        Original  Restored");
                Console.WriteLine("");
                for (j = 0 ; j <= n - 1 ; j++)
                {
                  Console.WriteLine("  {0,5}{1,10:f5}{2,10:f5}",j,xx[j - 0],x[j - 0]);
                }
              }
              else
              {
                Console.WriteLine("");
                Console.WriteLine(" ** c06ea returned with ifail = {0, 3}", ifail);
              }
            }
            else
            {
              Console.WriteLine(" {0}","Invalid value of N");
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      c06eb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class C06EBE
  {
    static string datafile = "ExampleData/c06ebe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int j,  n,  n2,  nj;
        int ifail;
        Console.WriteLine("c06eb Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        try
        {
          while (true)
          {
            sr.Reset();
            n = int.Parse(sr.Next());
            if (n >= 1)
            {
              double[] u = new double[n];
              double[] v = new double[n];
              double[] x = new double[n];
              double[] xx = new double[n];
              for (j = 0 ; j <= n - 1 ; j++)
              {
                sr.Reset();
                x[j - 0] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                xx[j - 0] = x[j - 0];
              }
              u[0] = x[0];
              v[0] = 0.00e0;
              n2 = (n - 1) / 2;
              for (j = 1 ; j <= n2 ; j++)
              {
                nj = n - j;
                u[j - 0] = x[j - 0];
                u[nj - 0] = x[j - 0];
                v[j - 0] = x[nj - 0];
                v[nj - 0] =  -x[nj - 0];
              }
              if (( n % 2 ) == 0)
              {
                u[n2 + 1 - 0] = x[n2 + 1 - 0];
                v[n2 + 1 - 0] = 0.00e0;
              }
              //
              C06.c06eb(x, n, out ifail);
              //
              if (ifail == 0)
              {
                Console.WriteLine("");
                Console.WriteLine(" {0}","Original sequence and corresponding complex sequence");
                Console.WriteLine("");
                Console.WriteLine(" {0}","         Data           Real      Imag");
                Console.WriteLine("");
                for (j = 0 ; j <= n - 1 ; j++)
                {
                  Console.WriteLine("  {0,5}{1,10:f5}{2}{3,10:f5}{4,10:f5}",j,xx[j - 0],"",u[j - 0],v[j - 0]);
                }
                Console.WriteLine("");
                Console.WriteLine(" {0}","Components of discrete Fourier transform");
                Console.WriteLine("");
                for (j = 0 ; j <= n - 1 ; j++)
                {
                  Console.WriteLine("  {0,5}{1,10:f5}",j,x[j - 0]);
                }
                //
                C06.c06ea(x, n, out ifail);
                C06.c06gb(x, n, out ifail);
                //
                Console.WriteLine("");
                Console.WriteLine(" {0}","Original sequence as restored by inverse transform");
                Console.WriteLine("");
                Console.WriteLine(" {0}","        Original  Restored");
                Console.WriteLine("");
                for (j = 0 ; j <= n - 1 ; j++)
                {
                  Console.WriteLine("  {0,5}{1,10:f5}{2,10:f5}",j,xx[j - 0],x[j - 0]);
                }
              }
              else
              {
                Console.WriteLine("");
                Console.WriteLine(" ** c06eb returned with ifail = {0, 3}", ifail);
              }
            }
            else
            {
              Console.WriteLine(" {0}","Invalid value of N");
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      c06fp Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class C06FPE
  {
    static string datafile = "ExampleData/c06fpe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   j,   m,   n; int ifail;
        Console.WriteLine("c06fp Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        try
        {
          while (true)
          {
            sr.Reset();
            m = int.Parse(sr.Next());
            n = int.Parse(sr.Next());
            if (m >= 1 && n >= 1)
            {
              double[] trig = new double[2*n];
              double[] u = new double[m*n];
              double[] v = new double[m*n];
              double[] x = new double[m*n];
              for (j = 1 ; j <= m ; j++)
              {
                sr.Reset();
                for (i = 0 ; i <= n - 1 ; i++)
                {
                  x[i * m + j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }
              }
              Console.WriteLine("");
              Console.WriteLine(" {0}","Original data values");
              Console.WriteLine("");
              for (j = 1 ; j <= m ; j++)
              {
                Console.Write(" {0}",  "");
                for (i = 0 ; i <= n - 1 ; i++)
                {
                  Console.Write(" {0, 10:f4}", x[i * m + j - 1]);
                }
                Console.WriteLine();
              }
              //
              C06.c06fp(m, n, x, "Initial", trig, out ifail);
              //
              if (ifail == 0)
              {
                Console.WriteLine("");
                Console.WriteLine(" {0}","Discrete Fourier transforms in Hermitian format");
                Console.WriteLine("");
                for (j = 1 ; j <= m ; j++)
                {
                  Console.Write(" {0}",  "");
                  for (i = 0 ; i <= n - 1 ; i++)
                  {
                    Console.Write(" {0, 10:f4}", x[i * m + j - 1]);
                  }
                  Console.WriteLine();
                }
                Console.WriteLine("");
                Console.WriteLine(" {0}","Fourier transforms in full complex form");
                //
                C06.c06gs(m, n, x, u, v, out ifail);
                //
                for (j = 1 ; j <= m ; j++)
                {
                  Console.WriteLine("");
                  Console.Write(" {0}",  "Real ");
                  for (i = 0 ; i <= n - 1 ; i++)
                  {
                    Console.Write(" {0, 10:f4}", u[i * m + j - 1]);
                  }
                  Console.WriteLine();
                  Console.Write(" {0}",  "Imag ");
                  for (i = 0 ; i <= n - 1 ; i++)
                  {
                    Console.Write(" {0, 10:f4}", v[i * m + j - 1]);
                  }
                  Console.WriteLine();
                }
                //
                C06.c06gq(m, n, x, out ifail);
                C06.c06fq(m, n, x, "Subsequent", trig, out ifail);
                //
                Console.WriteLine("");
                Console.WriteLine(" {0}","Original data as restored by inverse transform");
                Console.WriteLine("");
                for (j = 1 ; j <= m ; j++)
                {
                  Console.Write(" {0}",  "");
                  for (i = 0 ; i <= n - 1 ; i++)
                  {
                    Console.Write(" {0, 10:f4}", x[i * m + j - 1]);
                  }
                  Console.WriteLine();
                }
              }
              else
              {
                Console.WriteLine("");
                Console.WriteLine(" ** c06fp returned with ifail = {0, 3}", ifail);
              }
            }
            else
            {
              Console.WriteLine(" {0}","Invalid value of M or N");
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      c06fq Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class C06FQE
  {
    static string datafile = "ExampleData/c06fqe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   j,   m,   n; int ifail;
        Console.WriteLine("c06fq Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        try
        {
          while (true)
          {
            sr.Reset();
            m = int.Parse(sr.Next());
            n = int.Parse(sr.Next());
            if (m >= 1 && n >= 1)
            {
              double[] trig = new double[2*n];
              double[] u = new double[m*n];
              double[] v = new double[m*n];
              double[] x = new double[m*n];
              for (j = 1 ; j <= m ; j++)
              {
                sr.Reset();
                for (i = 0 ; i <= n - 1 ; i++)
                {
                  x[i * m + j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }
              }
              Console.WriteLine("");
              Console.WriteLine(" {0}","Original data values");
              Console.WriteLine("");
              for (j = 1 ; j <= m ; j++)
              {
                Console.Write(" {0}",  "");
                for (i = 0 ; i <= n - 1 ; i++)
                {
                  Console.Write(" {0, 10:f4}", x[i * m + j - 1]);
                }
                Console.WriteLine();
              }
              Console.WriteLine("");
              Console.WriteLine(" {0}","Original data written in full complex form");
              //
              C06.c06gs(m, n, x, u, v, out ifail);
              //
              if (ifail != 0)
              {
                Console.WriteLine("");
                Console.WriteLine(" ** c06gs returned with ifail = {0, 3}", ifail);
              }
              for (j = 1 ; j <= m ; j++)
              {
                Console.WriteLine("");
                Console.Write(" {0}",  "Real ");
                for (i = 0 ; i <= n - 1 ; i++)
                {
                  Console.Write(" {0, 10:f4}", u[i * m + j - 1]);
                }
                Console.WriteLine();
                Console.Write(" {0}",  "Imag ");
                for (i = 0 ; i <= n - 1 ; i++)
                {
                  Console.Write(" {0, 10:f4}", v[i * m + j - 1]);
                }
                Console.WriteLine();
              }
              //
              C06.c06fq(m, n, x, "Initial", trig, out ifail);
              //
              if (ifail == 0)
              {
                Console.WriteLine("");
                Console.WriteLine(" {0}","Discrete Fourier transforms (real values)");
                Console.WriteLine("");
                for (j = 1 ; j <= m ; j++)
                {
                  Console.Write(" {0}",  "");
                  for (i = 0 ; i <= n - 1 ; i++)
                  {
                    Console.Write(" {0, 10:f4}", x[i * m + j - 1]);
                  }
                  Console.WriteLine();
                }
                //
                C06.c06fp(m, n, x, "Subsequent", trig, out ifail);
                C06.c06gq(m, n, x, out ifail);
                //
                Console.WriteLine("");
                Console.WriteLine(" {0}","Original data as restored by inverse transform");
                Console.WriteLine("");
                for (j = 1 ; j <= m ; j++)
                {
                  Console.Write(" {0}",  "");
                  for (i = 0 ; i <= n - 1 ; i++)
                  {
                    Console.Write(" {0, 10:f4}", x[i * m + j - 1]);
                  }
                  Console.WriteLine();
                }
              }
              else
              {
                Console.WriteLine("");
                Console.WriteLine(" ** c06fq returned with ifail = {0, 3}", ifail);
              }
            }
            else
            {
              Console.WriteLine(" {0}","Invalid value of M or N");
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      c06gb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class C06GBE
  {
    static string datafile = "ExampleData/c06gbe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int j,  n,  n2,  nj;
        int ifail;
        Console.WriteLine("c06gb Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        try
        {
          while (true)
          {
            sr.Reset();
            n = int.Parse(sr.Next());
            if (n >= 1)
            {
              double[] a = new double[n];
              double[] b = new double[n];
              double[] x = new double[n];
              for (j = 0 ; j <= n - 1 ; j++)
              {
                sr.Reset();
                x[j - 0] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              //
              C06.c06ea(x, n, out ifail);
              if (ifail == 0)
              {
                C06.c06gb(x, n, out ifail);
                //
                Console.WriteLine("");
                Console.WriteLine(" {0}","Components of inverse discrete Fourier transform");
                Console.WriteLine("");
                Console.WriteLine(" {0}","           Real      Imag");
                Console.WriteLine("");
                a[0] = x[0];
                b[0] = 0.00e0;
                n2 = (n - 1) / 2;
                for (j = 1 ; j <= n2 ; j++)
                {
                  nj = n - j;
                  a[j - 0] = x[j - 0];
                  a[nj - 0] = x[j - 0];
                  b[j - 0] = x[nj - 0];
                  b[nj - 0] =  -x[nj - 0];
                }
                if (( n % 2 ) == 0)
                {
                  a[n2 + 1 - 0] = x[n2 + 1 - 0];
                  b[n2 + 1 - 0] = 0.00e0;
                }
                for (j = 0 ; j <= n - 1 ; j++)
                {
                  Console.WriteLine("  {0,6}{1,10:f5}{2,10:f5}",j,a[j - 0],b[j - 0]);
                }
              }
              else
              {
                Console.WriteLine("");
                Console.WriteLine(" ** c06ea returned with ifail = {0, 3}", ifail);
              }
            }
            else
            {
              Console.WriteLine(" {0}","Invalid value of N");
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      c06gq Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class C06GQE
  {
    static string datafile = "ExampleData/c06gqe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   j,   m,   n; int ifail;
        Console.WriteLine("c06gq Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        try
        {
          while (true)
          {
            sr.Reset();
            m = int.Parse(sr.Next());
            n = int.Parse(sr.Next());
            if (m >= 1 && n >=1)
            {
              double[] u = new double[m*n];
              double[] v = new double[m*n];
              double[] x = new double[m*n];
              for (j = 1 ; j <= m ; j++)
              {
                sr.Reset();
                for (i = 0 ; i <= n - 1 ; i++)
                {
                  x[i * m + j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }
              }
              Console.WriteLine("");
              Console.WriteLine(" {0}","Original data values");
              Console.WriteLine("");
              for (j = 1 ; j <= m ; j++)
              {
                Console.Write(" {0}",  "");
                for (i = 0 ; i <= n - 1 ; i++)
                {
                  Console.Write(" {0, 10:f4}", x[i * m + j - 1]);
                }
                Console.WriteLine();
              }
              Console.WriteLine("");
              Console.WriteLine(" {0}","Original data written in full complex form");
              //
              C06.c06gs(m, n, x, u, v, out ifail);
              //
              if (ifail == 0)
              {
                for (j = 1 ; j <= m ; j++)
                {
                  Console.WriteLine("");
                  Console.Write(" {0}",  "Real ");
                  for (i = 0 ; i <= n - 1 ; i++)
                  {
                    Console.Write(" {0, 10:f4}", u[i * m + j - 1]);
                  }
                  Console.WriteLine();
                  Console.Write(" {0}",  "Imag ");
                  for (i = 0 ; i <= n - 1 ; i++)
                  {
                    Console.Write(" {0, 10:f4}", v[i * m + j - 1]);
                  }
                  Console.WriteLine();
                }
                //
                C06.c06gq(m, n, x, out ifail);
                //
                Console.WriteLine("");
                Console.WriteLine(" {0}","Conjugated data values");
                Console.WriteLine("");
                for (j = 1 ; j <= m ; j++)
                {
                  Console.Write(" {0}",  "");
                  for (i = 0 ; i <= n - 1 ; i++)
                  {
                    Console.Write(" {0, 10:f4}", x[i * m + j - 1]);
                  }
                  Console.WriteLine();
                }
                //
                C06.c06gs(m, n, x, u, v, out ifail);
                //
                Console.WriteLine("");
                Console.WriteLine(" {0}","Conjugated data written in full complex form");
                //
                C06.c06gs(m, n, x, u, v, out ifail);
                //
                for (j = 1 ; j <= m ; j++)
                {
                  Console.WriteLine("");
                  Console.Write(" {0}",  "Real ");
                  for (i = 0 ; i <= n - 1 ; i++)
                  {
                    Console.Write(" {0, 10:f4}", u[i * m + j - 1]);
                  }
                  Console.WriteLine();
                  Console.Write(" {0}",  "Imag ");
                  for (i = 0 ; i <= n - 1 ; i++)
                  {
                    Console.Write(" {0, 10:f4}", v[i * m + j - 1]);
                  }
                  Console.WriteLine();
                }
              }
              else
              {
                Console.WriteLine("");
                Console.WriteLine(" ** c06gs returned with ifail = {0, 3}", ifail);
              }
            }
            else
            {
              Console.WriteLine(" {0}","Invalid value of M or N");
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      c06gs Example Program Text
//      Mark 14 Revised. NAG Copyright 1989.
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class C06gsfe
  {
    const int mmax=5;
    const int nmax=20;
    const int nin=5;
    public static int Main (string[] args)
    {
      DataReader sr = new DataReader("ExampleData/c06gsfe.d");
      int i=0,
      j=0,
      m=0,
      n=0;
      double[] u = new double[100];
      double[] v = new double[100];
      double[] x = new double[100];
      int ifail;
      Console.WriteLine("c06gs Example Program Results");
      //      Skip heading in data file
      sr.Reset();
      L20: ;
      try
      {
        sr.Reset();
        m = int.Parse(sr.Next());
        n = int.Parse(sr.Next());
      }
      catch
      {
        goto L100;
      }
      if ((m <= mmax) && (n <= nmax))
      {
        for (j = 1 ; j <= m ; j++)
        {
          sr.Reset();
          for (i = 0 ; i <= n - 1 ; i++)
          {
            x[i * m + j - 1] = double.Parse(sr.Next(), CultureInfo.CurrentCulture);
          }
        }
        Console.WriteLine("");
        Console.WriteLine(" {0}","Original data values");
        Console.WriteLine("");
        for (j = 1 ; j <= m ; j++)
        {
          Console.Write(" {0}",  "");
          for (i = 0 ; i <= n - 1 ; i++)
          {
            // nested do in write
            Console.Write(" {0}", x[i * m + j - 1]);
          }
          Console.WriteLine();
        }
        Console.WriteLine("");
        Console.WriteLine(" {0}","Original data written in full complex form");
        //
        C06.c06gs(m, n, x, u, v, ref ifail);
        //
        if (ifail == 0)
        {
          for (j = 1 ; j <= m ; j++)
          {
            Console.WriteLine("");
            Console.Write(" {0}",  "Real ");
            for (i = 0 ; i <= n - 1 ; i++)
            {
              // nested do in write
              Console.Write(" {0}", u[i * m + j - 1]);
            }
            Console.WriteLine();
            Console.Write(" {0}",  "Imag ");
            for (i = 0 ; i <= n - 1 ; i++)
            {
              // nested do in write
              Console.Write(" {0}", v[i * m + j - 1]);
            }
            Console.WriteLine();
          }
          goto L20;
        }
        else
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,5}"," ** c06gs returned with ifail = ",ifail);
        }
      }
      else
      {
        Console.WriteLine(" {0}","Invalid value of M or N");
      }
      L100: ;
      //
      return 0;
    }
  }
}


//      c09ca Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class C09CAE
  {
    static string datafile = "ExampleData/c09cae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   n,   nwc,   ny; string wtrans="";
        int ifail;
        Console.WriteLine("c09ca Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        //      Read N
        sr.Reset();
        n = int.Parse(sr.Next());
        //      Read wavnam, mode
        sr.Reset();
        string wavnam = sr.Next();
        string mode = sr.Next();
        //
        double[] x = new double[n];
        double[] y = new double[n];
        if (n >= 2)
        {
          Console.WriteLine(" {0} {1,5} {2} {3,5}","DWT :: Wavelet: ",wavnam,", End mode: ",mode);
          //         Read array
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          Console.WriteLine(" {0}","Input Data      x :");
          for (i = 1 ; i <= n ; i++)
          {
            Console.Write(" {0, 8:f4}", x[i - 1]);
          }
          Console.WriteLine();
          //         Query wavelet filter dimensions
          wtrans = "S";
          //
          C09.C09Communications c09comm = new C09.C09Communications(wavnam, wtrans, mode, n,
          out ifail);
          nwc = c09comm.ApproximateCoeffCount;
          //
          if (ifail != 0)
          {
            Console.WriteLine(" ** C09Communications constructor with ifail = {0, 3}", ifail);
            return;
          }
          //
          double[] ca = new double[nwc];
          double[] cd = new double[nwc];
          C09.c09ca(n, x, ca, cd, c09comm, out ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine("   Approximation coefficients CA : ");
            for (i = 1 ; i <= nwc ; i++)
            {
              Console.Write(" {0, 8:f4}", ca[i - 1]);
            }
            Console.WriteLine();
            Console.WriteLine("   Detail coefficients        CD : ");
            for (i = 1 ; i <= nwc ; i++)
            {
              Console.Write(" {0, 8:f4}", cd[i - 1]);
            }
            Console.WriteLine();
          }
          else
          {
            Console.WriteLine("");
            Console.WriteLine(" ** c09ca returned with ifail = {0, 3}", ifail);
          }
          if (mode == "PE")
          {
            ny = 2 * nwc;
          }
          else
          {
            ny = (int)n;
          }
          //
          //
          C09.c09cb(ca, cd, ny, y, c09comm, out ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine("   Reconstruction              Y : ");
            for (i = 1 ; i <= ny ; i++)
            {
              Console.Write(" {0, 8:f4}", y[i - 1]);
            }
            Console.WriteLine();
          }
          else
          {
            Console.WriteLine(" {0} {1}","Error in c09cb: ifail = ",ifail);
          }
          //
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      c09cc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class C09CCE
  {
    static string datafile = "ExampleData/c09cce.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,    n,    nf,    nnz,    nwc,    nwl,    ny; string wtrans=""; int ifail;
        Console.WriteLine("c09cc Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        //      Read N - length of input data sequence
        sr.Reset();
        n = int.Parse(sr.Next());
        //      Read Wavelet name (wavnam) and end mode (mode)
        sr.Reset();
        string wavnam = sr.Next();
        string mode = sr.Next();
        //
        double[] x = new double[n];
        double[] y = new double[n];
        if (n >= 2)
        {
          Console.WriteLine("   MLDWT :: Wavelet : {0,10}, End mode : {1,10} N = {2,10}",wavnam,mode,n);
          //
          //         Read data array and write it out
          //
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //
          Console.WriteLine(" {0}"," Input Data      x :");
          for (i = 1 ; i <= n ; i++)
          {
            Console.Write(" {0, 8:f4}{1}", x[i - 1], i%8==0?"\n":"");
          }
          Console.WriteLine();
          //
          //         Query wavelet filter dimensions
          //         For Multi-Resolution Analysis, decomposition, wtrans = 'M'
          //
          wtrans = "M";
          C09.C09Communications c09comm = new C09.C09Communications(wavnam, wtrans, mode, n,
          out ifail);
          nwl = c09comm.ResolutionLevelCount;
          nf = c09comm.FilterLength;
          nwc = c09comm.ApproximateCoeffCount;
          //
          if (ifail != 0)
          {
            Console.WriteLine(" ** C09Communications constructor returned with ifail = {0, 3}", ifail);
            return;
          }
          double[] c = new double[nwc];
          int[] dwtlev = new int[nwl+1];
          //
          //         Perform Discrete Wavelet transform
          //
          C09.c09cc(n, x, c, dwtlev, c09comm, out ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine("   Number of Levels : {0,10}",nwl);
            Console.WriteLine("   Number of coefficients in each level : ");
            for (i = 1 ; i <= nwl + 1 ; i++)
            {
              Console.Write(" {0, 8}", dwtlev[i - 1]);
            }
            Console.WriteLine();
            nnz = 0;
            for (i = 1 ; i <= nwl + 1 ; i++)
            {
              nnz = nnz + dwtlev[i - 1];
            }
            Console.WriteLine("   Wavelet coefficients C : ");
            for (i = 1 ; i <= nnz ; i++)
            {
              Console.Write(" {0, 8:f4}{1}", c[i - 1], i%8==0?"\n":"");
            }
            Console.WriteLine();
            //
            //            Reconstruct original data
            //
            ny = (int)n;
            C09.c09cd(nwl, c, ny, y, c09comm, out ifail);
            //
            if (ifail != 0)
            {
              Console.WriteLine(" ** c09cd returned with ifail = {0, 3}", ifail);
            }
            else
            {
              Console.WriteLine("   Reconstruction              Y : ");
              for (i = 1 ; i <= ny ; i++)
              {
                Console.Write(" {0, 8:f4}{1}", y[i - 1], i%8==0?"\n":"");
              }
              Console.WriteLine();
            }
          }
          else
          {
            Console.WriteLine(" ** c09cc returned with ifail = {0, 3}", ifail);
          }
          //
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      d01ah Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class D01AHE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        D01.D01AH_F fD01AH = new D01.D01AH_F(f);
        double a,  ans,  b,  epsr,  relerr; int nlimit, npts;
        int ifail;
        Console.WriteLine("d01ah Example Program Results");
        a = 0.00e0;
        b = 1.00e0;
        nlimit = 0;
        epsr = 1.00e-5;
        ans = D01.d01ah(a, b, epsr, out npts, out relerr, fD01AH, nlimit, out ifail);
        Console.WriteLine("");
        if ((ifail >= 0) && (ifail <= 2))
        {
          Console.WriteLine("  {0}{1,8:f5}", "Integral = ", ans);
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,10:e2}", "Estimated relative error = ", relerr);
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,5}", "Number of function evaluations = ", npts);
        }
        else
        {
          Console.WriteLine("** d01ah failed with ifail = {0,5}", ifail);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      ;
    }
    //
    public static double f(double x)
    {
      double fValue;
      fValue = 4.00e0 / (1.00e0 + x * x);
      return fValue;
    }
  }
}


d01ah Example Program Data
   0.0    1.0        : a, b
   0                 : nlimit
   0.00001           : epsr


d01ah Example Program Results

  Integral =  3.14159

  Estimated relative error =  5.85e-009

  Number of function evaluations =    15


//      d01aj Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class D01AJE
  {
    public static double pi;
    public static int kount = 0;
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int lw = 800;
        D01.D01AJ_F fD01AJ = new D01.D01AJ_F(f);
        double a,   abserr,   b,   epsabs,   epsrel,   result;
        double[] w = new double[lw];
        int subintvls;
        int ifail;
        Console.WriteLine("d01aj Example Program Results");
        pi = Math.PI;
        epsabs = 0.00e0;
        epsrel = 1.00e-04;
        a = 0.00e0;
        b = 2.00e0 * pi;
        kount = 0;
        //
        D01.d01aj(fD01AJ, a, b, epsabs, epsrel, out result, out abserr, w, out subintvls,
                  out ifail);
        //
        if (ifail >= 0)
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,10:f4}", "a      - lower limit of integration = ", a);
          Console.WriteLine("  {0}{1,10:f4}", "b      - upper limit of integration = ", b);
          Console.WriteLine("  {0}{1,9:e2}", "epsabs - absolute accuracy requested = ", epsabs);
          Console.WriteLine("  {0}{1,9:e2}", "epsrel - relative accuracy requested = ", epsrel);
          Console.WriteLine("");
          if (ifail != 0)
          {
            Console.WriteLine("  {0}{1,4}", "ifail = ", ifail);
          }
          if (ifail <= 5)
          {
            Console.WriteLine("  {0}{1,9:f5}", "result - approximation to the integral = ", result);
            Console.WriteLine("  {0}{1,9:e2}", "abserr - estimate of the absolute error = ", abserr);
            Console.WriteLine("  {0}{1,4}", "kount  - number of function evaluations = ", kount);
            Console.WriteLine("  {0}{1,4}", "subintvls  - number of subintervals used = ", subintvls);
          }
        }
        else
        {
          Console.WriteLine("");
          Console.WriteLine("** d01aj failed with ifail = {0,5}", ifail);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      ;
    }
    //
    public static double f(double x)
    {
      double fValue;
      kount = kount + 1;
      fValue = x * Math.Sin(30.00e0 * x) / Math.Sqrt(1.00e0 - (x) * (x) / (4.00e0 * (pi) * (pi)));
      return fValue;
    }
  }
}


d01aj Example Program Results

  a      - lower limit of integration =     0.0000
  b      - upper limit of integration =     6.2832
  epsabs - absolute accuracy requested = 0.00e+000
  epsrel - relative accuracy requested = 1.00e-004

  result - approximation to the integral =  -2.54326
  abserr - estimate of the absolute error = 1.28e-005
  kount  - number of function evaluations =  777
  subintvls  - number of subintervals used =   19


//      d01ak Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class D01AKE
  {
    public static int kount = 0;
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int lw = 800;
        D01.D01AK_F fD01AK = new D01.D01AK_F(f);
        double a,  abserr,  b,  epsabs,  epsrel,  pi,  result; double[] w = new double[lw];
        int subintvls;
        int ifail;
        Console.WriteLine("d01ak Example Program Results");
        pi = Math.PI;
        epsabs = 0.00e0;
        epsrel = 1.00e-03;
        a = 0.00e0;
        b = 2.00e0 * pi;
        kount = 0;
        //
        D01.d01ak(fD01AK, a, b, epsabs, epsrel, out result, out abserr, w, out subintvls,
                  out ifail);
        //
        if (ifail >= 0)
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,10:f4}", "a      - lower limit of integration = ", a);
          Console.WriteLine("  {0}{1,10:f4}", "b      - upper limit of integration = ", b);
          Console.WriteLine("  {0}{1,9:e2}", "epsabs - absolute accuracy requested = ", epsabs);
          Console.WriteLine("  {0}{1,9:e2}", "epsrel - relative accuracy requested = ", epsrel);
          Console.WriteLine("");
          if (ifail != 0)
          {
            Console.WriteLine("  {0}{1,4}", "ifail = ", ifail);
          }
          if (ifail <= 3)
          {
            Console.WriteLine("  {0}{1,9:f5}", "result - approximation to the integral = ", result);
            Console.WriteLine("  {0}{1,9:e2}", "abserr - estimate of the absolute error = ", abserr);
            Console.WriteLine("  {0}{1,4}", "kount  - number of function evaluations = ", kount);
            Console.WriteLine("  {0}{1,4}", "subintvls  - number of subintervals used = ", subintvls);
          }
        }
        else
        {
          Console.WriteLine("");
          Console.WriteLine("** d01ak failed with ifail = {0,5}", ifail);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      ;
    }
    //
    public static double f(double x)
    {
      double fValue;
      kount = kount + 1;
      fValue = x * (Math.Sin(30.00e0 * x)) * Math.Cos(x);
      return fValue;
    }
  }
}


d01ak Example Program Results

  a      - lower limit of integration =     0.0000
  b      - upper limit of integration =     6.2832
  epsabs - absolute accuracy requested = 0.00e+000
  epsrel - relative accuracy requested = 1.00e-003

  result - approximation to the integral =  -0.20967
  abserr - estimate of the absolute error = 4.45e-014
  kount  - number of function evaluations =  427
  subintvls  - number of subintervals used =    4


//      d01al Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class D01ALE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static int kount = 0;
    public static void StartExample()
    {
      try
      {
        const int npts = 1;
        const int lw = 800;
        D01.D01AL_F fD01AL = new D01.D01AL_F(f);
        double a,  abserr,  b,  epsabs,  epsrel,  result; double[] points = new double[1];
        double[] w = new double[lw];
        int subintvls;
        int ifail;
        Console.WriteLine("d01al Example Program Results");
        epsabs = 0.00e0;
        epsrel = 1.00e-03;
        a = 0.00e0;
        b = 1.00e0;
        points[0] = 1.00e0 / 7.00e0;
        kount = 0;
        //
        D01.d01al(fD01AL, a, b, npts, points, epsabs, epsrel, out result, out abserr, w,
                  out subintvls, out ifail);
        //
        if (ifail >= 0)
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,10:f4}", "a      - lower limit of integration = ", a);
          Console.WriteLine("  {0}{1,10:f4}", "b      - upper limit of integration = ", b);
          Console.WriteLine("  {0}{1,9:e2}", "epsabs - absolute accuracy requested = ", epsabs);
          Console.WriteLine("  {0}{1,9:e2}", "epsrel - relative accuracy requested = ", epsrel);
          Console.WriteLine("  {0}{1,10:f4}", "points[0] - given break-point = ",
          points[0]);
          Console.WriteLine("");
          if (ifail != 0)
          {
            Console.WriteLine("  {0}{1,4}", "ifail = ", ifail);
          }
          if (ifail <= 5)
          {
            Console.WriteLine("  {0}{1,9:f5}", "  result - approximation to the integral = ", result);
            Console.WriteLine("  {0}{1,9:e2}", "  abserr - estimate of the absolute error = ", abserr);
            Console.WriteLine("  {0}{1,4}", "  kount  - number of function evaluations = ", kount);
            Console.WriteLine("  {0}{1,4}", "  subintvls  - number of subintervals used = ", subintvls);
          }
        }
        else
        {
          Console.WriteLine("");
          Console.WriteLine("** d01al failed with ifail = {0,5}", ifail);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      ;
    }
    //
    public static double f(double x)
    {
      double fValue;
      double a;
      kount = kount + 1;
      a = Math.Abs(x - 1.00e0 / 7.00e0);
      fValue = 0.00e0;
      if (a != 0.00e0)
      {
        fValue = Math.Pow(a, (-0.50e0));
      }
      return fValue;
    }
  }
}


d01al Example Program Results

  a      - lower limit of integration =     0.0000
  b      - upper limit of integration =     1.0000
  epsabs - absolute accuracy requested = 0.00e+000
  epsrel - relative accuracy requested = 1.00e-003
  points[0] - given break-point =     0.1429

    result - approximation to the integral =   2.60757
    abserr - estimate of the absolute error = 5.51e-014
    kount  - number of function evaluations =  462
    subintvls  - number of subintervals used =   12


//      d01am Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class D01AME
  {
    public static int kount = 0;
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int lw = 800;
        D01.D01AM_F fD01AM = new D01.D01AM_F(f);
        double abserr,   bound,   epsabs,   epsrel,   result;
        int inf;
        double[] w = new double[lw];
        int subintvls;
        int ifail;
        Console.WriteLine("d01am Example Program Results");
        epsabs = 0.00e0;
        epsrel = 1.00e-04;
        bound = 0.00e0;
        inf = 1;
        kount = 0;
        //
        D01.d01am(fD01AM, bound, inf, epsabs, epsrel, out result, out abserr, w, out subintvls,
        out ifail);
        //
        if (ifail >= 0)
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,10:f4}", "a      - lower limit of integration = ", bound);
          Console.WriteLine("  {0}", "b      - upper limit of integration = infinity");
          Console.WriteLine("  {0}{1,9:e2}", "epsabs - absolute accuracy requested = ", epsabs);
          Console.WriteLine("  {0}{1,9:e2}", "epsrel - relative accuracy requested = ", epsrel);
          Console.WriteLine("");
          if (ifail != 0)
          {
            Console.WriteLine("  {0}{1,4}", "ifail = ", ifail);
          }
          if (ifail <= 5)
          {
            Console.WriteLine("  {0}{1,9:f5}", "result - approximation to the integral = ", result);
            Console.WriteLine("  {0}{1,9:e2}", "abserr - estimate of the absolute error = ", abserr);
            Console.WriteLine("  {0}{1,4}", "kount  - number of function evaluations = ", kount);
            Console.WriteLine("  {0}{1,4}", "subintvls  - number of subintervals used = ", subintvls);
          }
        }
        else
        {
          Console.WriteLine("");
          Console.WriteLine("** d01am failed with ifail = {0,5}", ifail);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      ;
    }
    //
    public static double f(double x)
    {
      double fValue;
      kount = kount + 1;
      fValue = 1.00e0 / ((x + 1.00e0) * Math.Sqrt(x));
      return fValue;
    }
  }
}


d01am Example Program Results

  a      - lower limit of integration =     0.0000
  b      - upper limit of integration = infinity
  epsabs - absolute accuracy requested = 0.00e+000
  epsrel - relative accuracy requested = 1.00e-004

  result - approximation to the integral =   3.14159
  abserr - estimate of the absolute error = 2.65e-005
  kount  - number of function evaluations =  285
  subintvls  - number of subintervals used =   10


//      d01an Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class D01ANE
  {
    public static int kount = 0;
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int lw = 800;
        D01.D01AN_G gD01AN = new D01.D01AN_G(g);
        double a,  abserr,  b,  epsabs,  epsrel,  omega, result;
        int key = 0;
        double[] w = new double[lw];
        int subintvls;
        int ifail;
        Console.WriteLine("d01an Example Program Results");
        epsrel = 1.00e-04;
        epsabs = 0.00e+00;
        a = 0.00e0;
        b = 1.00e0;
        omega = 10.00e0 *  Math.PI;
        key = 2;
        kount = 0;
        //
        D01.d01an(gD01AN, a, b, omega, key, epsabs, epsrel, out result, out abserr, w,
                  out subintvls, out ifail);
        //
        if (ifail >= 0)
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,10:f4}", "a      - lower limit of integration = ", a);
          Console.WriteLine("  {0}{1,10:f4}", "b      - upper limit of integration = ", b);
          Console.WriteLine("  {0}{1,9:e2}", "epsabs - absolute accuracy requested = ", epsabs);
          Console.WriteLine("  {0}{1,9:e2}", "epsrel - relative accuracy requested = ", epsrel);
          Console.WriteLine("");
          if (ifail != 0)
          {
            Console.WriteLine("  {0}{1,4}", "ifail = ", ifail);
          }
          if (ifail <= 5)
          {
            Console.WriteLine("  {0}{1,9:f5}", "result - approximation to the integral = ", result);
            Console.WriteLine("  {0}{1,9:e2}", "abserr - estimate of the absolute error = ", abserr);
            Console.WriteLine("  {0}{1,4}", "kount  - number of function evaluations = ", kount);
            Console.WriteLine("  {0}{1,4}", "subintvls   - number of subintervals used = ", subintvls);
          }
        }
        else
        {
          Console.WriteLine("");
          Console.WriteLine("** d01an failed with ifail = {0,5}", ifail);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      ;
    }
    //
    public static double g(double x)
    {
      double gValue = 0.0;
      kount = kount + 1;
      gValue = 0.00e0;
      if (x > 0.00e0)
      {
        gValue = Math.Log(x);
      }
      return gValue;
    }
  }
}


d01an Example Program Results

  a      - lower limit of integration =     0.0000
  b      - upper limit of integration =     1.0000
  epsabs - absolute accuracy requested = 0.00e+000
  epsrel - relative accuracy requested = 1.00e-004

  result - approximation to the integral =  -0.12814
  abserr - estimate of the absolute error = 3.58e-006
  kount  - number of function evaluations =  275
  subintvls   - number of subintervals used =    8


//      d01ap Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class D01APE
  {
    public static int kount = 0,
    nof = 0;
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int lw = 800;
        D01.D01AP_G gD01AP = new D01.D01AP_G(g);
        double a,  abserr,  b,  epsabs,  epsrel,  result;
        double[] alfa = new double[2] { 0.00e0, -0.50e0 };
        double[] beta = new double[2] { 0.00e0, -0.50e0 };
        double[] w = new double[lw];
        int[] key = new int[2] { 2, 1 };
        int subintvls;
        int ifail;
        Console.WriteLine("d01ap Example Program Results");
        epsabs = 0.00e0;
        epsrel = 1.00e-04;
        a = 0.00e0;
        b = 1.00e0;
        for (nof = 1; nof <= 2; nof++)
        {
          kount = 0;
          //
          D01.d01ap(gD01AP, a, b, alfa[nof - 1], beta[nof - 1], key[nof - 1], epsabs, epsrel,
          out result, out abserr, w, out subintvls, out ifail);
          //
          if (ifail < 0)
          {
            Console.WriteLine("");
            Console.WriteLine("** d01ap failed with ifail = {0,5}", ifail);
            goto L40;
          }
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,10:f4}", "a      - lower limit of integration = ", a);
          Console.WriteLine("  {0}{1,10:f4}", "b     - upper limit of integration = ", b);
          Console.WriteLine("  {0}{1,9:e2}", "epsabs - absolute accuracy requested = ", epsabs);
          Console.WriteLine("  {0}{1,9:e2}", "epsrel - relative accuracy requested = ", epsrel);
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,9:e2}", "ALFa   - parameter in the weight function = ", alfa[nof - 1]);
          Console.WriteLine("  {0}{1,9:e2}", "BETa   - parameter in the weight function = ", beta[nof - 1]);
          Console.WriteLine("  {0}{1,4}", "key    - denotes which weight function is to be used = ", key[nof - 1]);
          Console.WriteLine("");
          if (ifail != 0)
          {
            Console.WriteLine("  {0}{1,4}", "ifail = ", ifail);
          }
          if (ifail <= 3)
          {
            Console.WriteLine("  {0}{1,9:f5}", "result - approximation to the integral = ", result);
            Console.WriteLine("  {0}{1,9:e2}", "abserr - estimate of the absolute error = ", abserr);
            Console.WriteLine("  {0}{1,4}", "kount  - number of function evaluations = ", kount);
            Console.WriteLine("  {0}{1,4}", "subintvls  - number of subintervals used = ", subintvls);
          }
        }
        L40: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      ;
    }
    //
    public static double g(double x)
    {
      double gValue = 0.0;
      double a,  omega,  pi;
      pi = Math.PI;
      kount = kount + 1;
      if (nof == 1)
      {
        a = 10.00e0 * pi;
        gValue = Math.Cos(a * x);
      }
      else
      {
        omega = 10.00e0;
        gValue = Math.Sin(omega * x);
      }
      return gValue;
    }
  }
}


d01ap Example Program Results

  a      - lower limit of integration =     0.0000
  b     - upper limit of integration =     1.0000
  epsabs - absolute accuracy requested = 0.00e+000
  epsrel - relative accuracy requested = 1.00e-004

  ALFa   - parameter in the weight function = 0.00e+000
  BETa   - parameter in the weight function = 0.00e+000
  key    - denotes which weight function is to be used =    2

  result - approximation to the integral =  -0.04899
  abserr - estimate of the absolute error = 1.14e-007
  kount  - number of function evaluations =  110
  subintvls  - number of subintervals used =    4

  a      - lower limit of integration =     0.0000
  b     - upper limit of integration =     1.0000
  epsabs - absolute accuracy requested = 0.00e+000
  epsrel - relative accuracy requested = 1.00e-004

  ALFa   - parameter in the weight function = -5.00e-001
  BETa   - parameter in the weight function = -5.00e-001
  key    - denotes which weight function is to be used =    1

  result - approximation to the integral =   0.53502
  abserr - estimate of the absolute error = 1.94e-012
  kount  - number of function evaluations =   50
  subintvls  - number of subintervals used =    2


//      d01aq Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class D01AQE
  {
    public static int kount = 0;
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int lw = 800;
        D01.D01AQ_G gD01AQ = new D01.D01AQ_G(g);
        double a,  abserr,  b,  c,  epsabs,  epsrel,  result;
        double[] w = new double[lw];
        int subintvls;
        int ifail;
        Console.WriteLine("d01aq Example Program Results");
        epsabs = 0.00e0;
        epsrel = 1.00e-04;
        a = -1.00e0;
        b = 1.00e0;
        c = 0.50e0;
        kount = 0;
        //
        D01.d01aq(gD01AQ, a, b, c, epsabs, epsrel, out result, out abserr, w, out subintvls,
                  out ifail);
        //
        if (ifail >= 0)
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,10:f4}", "a      - lower limit of integration = ", a);
          Console.WriteLine("  {0}{1,10:f4}", "b     - upper limit of integration = ", b);
          Console.WriteLine("  {0}{1,9:e2}", "epsabs - absolute accuracy requested = ", epsabs);
          Console.WriteLine("  {0}{1,9:e2}", "epsrel - relative accuracy requested = ", epsrel);
          Console.WriteLine("  {0}{1,9:e2}", "C      - parameter in the weight function = ", c);
          Console.WriteLine("");
          if (ifail != 0)
          {
            Console.WriteLine("  {0}{1,4}", "ifail = ", ifail);
          }
          if (ifail <= 3)
          {
            Console.WriteLine("  {0}{1,9:f2}", "result - approximation to the integral = ", result);
            Console.WriteLine("  {0}{1,9:e2}", "abserr - estimate of the absolute error = ", abserr);
            Console.WriteLine("  {0}{1,4}", "kount  - number of function evaluations = ", kount);
            Console.WriteLine("  {0}{1,4}", "subintvls  - number of subintervals used = ", subintvls);
          }
        }
        else
        {
          Console.WriteLine("");
          Console.WriteLine("** d01aq failed with ifail = {0,5}", ifail);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      ;
    }
    //
    public static double g(double x)
    {
      double gValue = 0.0;
      double aa = 0.0;
      kount = kount + 1;
      aa = 0.010e0;
      gValue = 1.00e0 / ((x) * (x) + (aa) * (aa));
      return gValue;
    }
  }
}


d01aq Example Program Results

  a      - lower limit of integration =    -1.0000
  b     - upper limit of integration =     1.0000
  epsabs - absolute accuracy requested = 0.00e+000
  epsrel - relative accuracy requested = 1.00e-004
  C      - parameter in the weight function = 5.00e-001

  result - approximation to the integral =   -628.46
  abserr - estimate of the absolute error = 1.32e-002
  kount  - number of function evaluations =  255
  subintvls  - number of subintervals used =    8


//      d01ar Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class D01ARE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int maxrul = 0;
        D01.D01AR_FUN f1D01AR = new D01.D01AR_FUN(f1);
        D01.D01AR_FUN f2D01AR = new D01.D01AR_FUN(f2);
        double a,  absacc,  acc,  ans,  b,  relacc; int iparm,  n;
        double[] alpha = new double[390];
        int ifail;
        Console.WriteLine("d01ar Example Program Results");
        relacc = 0.00e0;
        absacc = 1.00e-5;
        //      Definite integral of f1(x) - no expansion
        iparm = 0;
        a = 0.00e0;
        b = 1.00e0;
        Console.WriteLine("");
        Console.WriteLine(" {0}", "Definite integral of 4/(1+x*x) over (0,1)");
        //
        D01.d01ar(a, b, f1D01AR, relacc, absacc, maxrul, iparm, out acc, out ans, out n, alpha,
        out ifail);
        //
        if (ifail != 0)
        {
          Console.WriteLine("** d01ar failed with ifail = {0,5}", ifail);
          if (ifail < 0)
          {
            goto L20;
          }
        }
        if (ifail <= 1)
        {
          Console.WriteLine("  {0}{1,9:f5}", "Estimated value of the integral =", ans);
          Console.WriteLine("  {0}{1,10:e2}", "Estimated absolute error =", acc);
          Console.WriteLine("  {0}{1,4}", "Number of points used =", n);
        }
        //      Definite integral of f2(x) - with expansion
        iparm = 1;
        a = 1.00e0;
        b = 2.00e0;
        Console.WriteLine("");
        Console.WriteLine(" {0}", "Definite integral of x**(1/8) over (1,2)");
        //
        D01.d01ar(a, b, f2D01AR, relacc, absacc, maxrul, iparm, out acc, out ans, out n, alpha,
        out ifail);
        //
        if (ifail != 0)
        {
          Console.WriteLine("** d01ar failed with ifail = {0,5}", ifail);
          if (ifail < 0)
          {
            goto L20;
          }
        }
        if (ifail <= 1)
        {
          Console.WriteLine("  {0}{1,9:f5}", "Estimated value of the integral =", ans);
          Console.WriteLine("  {0}{1,10:e2}", "Estimated absolute error =", acc);
          Console.WriteLine("  {0}{1,4}", "Number of points used =", n);
        }
        //      Indefinite integral of f2(x)
        iparm = 2;
        a = 1.20e0;
        b = 1.80e0;
        Console.WriteLine("");
        Console.WriteLine(" {0}", "Indefinite integral of x**(1/8) over (1.2,1.8)");
        //
        D01.d01ar(a, b, f2D01AR, relacc, absacc, maxrul, iparm, out acc, out ans, out n, alpha,
        out ifail);
        //
        Console.WriteLine("  {0}{1,9:f5}", "Estimated value of the integral =", ans);
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      ;
    }
    //
    public static double f1(double x)
    {
      double f1Value = 0.0;
      f1Value = 4.00e0 / (1.00e0 + x * x);
      return f1Value;
    }
    public static double f2(double x)
    {
      double f2Value = 0.0;
      f2Value = Math.Pow(x, 0.1250e0);
      return f2Value;
    }
  }
}


d01ar Example Program Results

 Definite integral of 4/(1+x*x) over (0,1)
  Estimated value of the integral =  3.14159
  Estimated absolute error = 1.84e-008
  Number of points used =  15

 Definite integral of x**(1/8) over (1,2)
  Estimated value of the integral =  1.04979
  Estimated absolute error = 5.88e-007
  Number of points used =   7

 Indefinite integral of x**(1/8) over (1.2,1.8)
  Estimated value of the integral =  0.63073


//      d01as Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class D01ASE
  {
    public static int kount = 0;
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
         const int limlst = 50;
        D01.D01AS_G gD01AS = new D01.D01AS_G(g);
        double a,  abserr,  epsabs,  omega,  result; int key,  lst;
        double[] erlst = new double[limlst];
        double[] rslst = new double[limlst];
        int[] ierlst = new int[limlst];
        int subintvls;
        int ifail;
        Console.WriteLine("d01as Example Program Results");
        epsabs = 1.00e-03;
        a = 0.00e0;
        kount = 0;
        omega = 0.50e0 * Math.PI;
        key = 1;
        //
        D01.d01as(gD01AS, a, omega, key, epsabs, out result, out abserr, limlst, out lst, erlst,
        rslst, ierlst, out subintvls, out ifail);
        //
        if (ifail >= 0)
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,10:f4}", "a      - lower limit of integration = ", a);
          Console.WriteLine(" {0}", "b     - upper limit of integration =  infinity");
          Console.WriteLine("  {0}{1,9:e2}", "epsabs - absolute accuracy requested = ", epsabs);
          Console.WriteLine("");
          if (ifail != 0)
          {
            Console.WriteLine("  {0}{1,4}", "ifail = ", ifail);
          }
          if ((ifail != 6) && (ifail != 10))
          {
            Console.WriteLine("  {0}{1,9:f5}", "result - approximation to the integral = ", result);
            Console.WriteLine("  {0}{1,9:e2}", "abserr - estimate of the absolute error = ", abserr);
            Console.WriteLine("  {0}{1,4}", "kount  - number of function evaluations = ", kount);
            Console.WriteLine("  {0}{1,4}", "lst    - number of intervals used = ", lst);
            Console.WriteLine("  {0}{1,4}",
            "subintvls - max. no. of subintervals used in any one interval = ", subintvls);
          }
        }
        else
        {
          Console.WriteLine("");
          Console.WriteLine("** d01as failed with ifail = {0,5}", ifail);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      ;
    }
    //
    public static double g(double x)
    {
      double gValue;
      kount = kount + 1;
      gValue = 0.00e0;
      if (x > 0.00e0)
      {
        gValue = 1.00e0 / Math.Sqrt(x);
      }
      return gValue;
    }
  }
}


d01as Example Program Results

  a      - lower limit of integration =     0.0000
 b     - upper limit of integration =  infinity
  epsabs - absolute accuracy requested = 1.00e-003

  result - approximation to the integral =   1.00000
  abserr - estimate of the absolute error = 5.92e-004
  kount  - number of function evaluations =  380
  lst    - number of intervals used =    6
  subintvls - max. no. of subintervals used in any one interval =    8


//      d01bc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class D01BCE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int n = 7;
        double a,  b,  c,  d; int itype;
        double[] abscis = new double[n];
        double[] weight = new double[n];
        int ifail;
        Console.WriteLine("d01bc Example Program Results");
        a = 0.00e0;
        b = 1.00e0;
        c = 0.00e0;
        d = 0.00e0;
        itype = -3;
        //
        D01.d01bc(itype, a, b, c, d, n, weight, abscis, out ifail);
        //
        if (ifail == 0)
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,3}{2}", "Laguerre formula,", n, " points");
          Console.WriteLine("");
          Console.WriteLine(" {0}", "      Abscissae             Weights");
          Console.WriteLine("");
          for (int j = 1; j <= n; j++)
          {
            Console.Write("\t{0,10:e5}\t\t{1,10:e5}", abscis[j - 1], weight[j - 1]);
            Console.WriteLine("");
          }
        }
        else
        {
          Console.WriteLine("");
          Console.WriteLine("** d01bc failed with ifail = {0,5}", ifail);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      ;
    }
  }
}


//      d01bd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class D01BDE
  {
    public static double pi = 0.0;
    public static int kount = 0;
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        D01.D01BD_F fD01BD = new D01.D01BD_F(f);
        double a,  abserr,  b,  epsabs,  epsrel,  result;
        int ifail;
        Console.WriteLine("d01bd Example Program Results");
        //
        pi = Math.PI;
        epsabs = 0.00e0;
        epsrel = 1.00e-04;
        a = 0.00e0;
        b = 1.00e0;
        kount = 0;
        //
        D01.d01bd(fD01BD, a, b, epsabs, epsrel, out result, out abserr, out ifail);
        //
        Console.WriteLine("");
        Console.WriteLine("  {0}{1,10:f4}", "a      - lower limit of integration = ", a);
        Console.WriteLine("  {0}{1,10:f4}", "b     - upper limit of integration = ", b);
        Console.WriteLine("  {0}{1,9:e2}", "epsabs - absolute accuracy requested = ", epsabs);
        Console.WriteLine("  {0}{1,9:e2}", "epsrel - relative accuracy requested = ", epsrel);
        Console.WriteLine("");
        Console.WriteLine("  {0}{1,9:f5}", "result - approximation to the integral = ", result);
        Console.WriteLine("  {0}{1,9:e2}", "abserr - estimate to the absolute error = ", abserr);
        Console.WriteLine("  {0}{1,4}", "kount  - number of function evaluations = ", kount);
        Console.WriteLine("");
        if ((kount > 87) || (abserr > Math.Max(epsabs, epsrel * Math.Abs(result))))
        {
          Console.WriteLine(" {0}", "Warning - requested accuracy may not have been achieved");
        }
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      ;
    }
    //
    //
    public static double f(double x)
    {
      double fValue;
      kount = kount + 1;
      fValue = ((x) * (x)) * Math.Sin(10.00e0 * pi * x);
      return fValue;
    }
  }
}


d01bd Example Program Results

  a      - lower limit of integration =     0.0000
  b     - upper limit of integration =     1.0000
  epsabs - absolute accuracy requested = 0.00e+000
  epsrel - relative accuracy requested = 1.00e-004

  result - approximation to the integral =  -0.03183
  abserr - estimate to the absolute error = 1.34e-011
  kount  - number of function evaluations =   43


//      d01da Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class D01DAE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        D01.D01DA_PHI1 phi1D01DA = new D01.D01DA_PHI1(phi1);
        D01.D01DA_PHI2 phi2aD01DA = new D01.D01DA_PHI2(phi2a);
        D01.D01DA_F faD01DA = new D01.D01DA_F(fa);
        D01.D01DA_PHI2 phi2bD01DA = new D01.D01DA_PHI2(phi2b);
        D01.D01DA_F fbD01DA = new D01.D01DA_F(fb);
        double absacc,  ans,  ya,  yb;
        int npts = 0;
        int ifail;
        Console.WriteLine("d01da Example Program Results");
        ya = 0.00e0;
        yb = 1.00e0;
        absacc = 1.00e-6;
        Console.WriteLine("");
        //
        D01.d01da(ya, yb, phi1D01DA, phi2aD01DA, faD01DA, absacc, out ans, out npts,
        out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine("** d01da failed with ifail = {0,5}", ifail);
        }
        else
        {
          //
          Console.WriteLine(" {0}", "First formulation");
          Console.WriteLine("  {0}{1,9:f4}", "Integral =", ans);
          Console.WriteLine("  {0}{1,5}", "Number of function evaluations =", npts);
          if (ifail > 0)
          {
            Console.WriteLine("  {0}{1,5}", "ifail = ", ifail);
          }
          Console.WriteLine("");
          Console.WriteLine(" {0}", "Second formulation");
          //
          D01.d01da(ya, yb, phi1D01DA, phi2bD01DA, fbD01DA, absacc, out ans, out npts,
          out ifail);
          //
          Console.WriteLine("  {0}{1,9:f4}", "Integral =", ans);
          Console.WriteLine("  {0}{1,5}", "Number of function evaluations =", npts);
          if (ifail > 0)
          {
            Console.WriteLine("  {0}{1,5}", "ifail = ", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      ;
    }
    //
    public static double phi1(double y)
    {
      double phi1Value = 0.0;
      phi1Value = 0.00e0;
      return phi1Value;
    }
    //
    public static double phi2a(double y)
    {
      double phi2aValue = 0.0;
      phi2aValue = Math.Sqrt(1.00e0 - y * y);
      return phi2aValue;
    }
    public static double fa(double x, double y)
    {
      double faValue = 0.0;
      faValue = x + y;
      return faValue;
    }
    public static double phi2b(double y)
    {
      double phi2bValue = 0.0;
      phi2bValue = 0.50e0 * Math.PI;
      return phi2bValue;
    }
    public static double fb(double x, double y)
    {
      double fbValue = 0.0;
      fbValue = y * y * (Math.Cos(x) + Math.Sin(x));
      return fbValue;
    }
  }
}


d01da Example Program Results

 First formulation
  Integral =   0.6667
  Number of function evaluations =  189

 Second formulation
  Integral =   0.6667
  Number of function evaluations =   89


//      d01fc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class D01FCE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int ndim = 4;
        const int maxpts = 1000 * ndim;
        D01.D01FC_FUNCTN functnD01FC = new D01.D01FC_FUNCTN(functn);
        double acc,   eps,   finval; int minpts; double[] a = new double[ndim];
        double[] b = new double[ndim];
        int ifail;
        Console.WriteLine("d01fc Example Program Results");
        for (int k = 1; k <= ndim; k++)
        {
          a[k - 1] = 0.00e0;
          b[k - 1] = 1.00e0;
        }
        eps = 0.00010e0;
        minpts = 0;
        //
        D01.d01fc(ndim, a, b, ref minpts, maxpts, functnD01FC, eps, out acc, out finval,
        out ifail);
        //
        Console.WriteLine("");
        if (ifail >= 0)
        {
          if (ifail > 0)
          {
            Console.WriteLine("  {0}{1,5}", "ifail =", ifail);
            Console.WriteLine("");
          }
          if ((ifail == 0) || (ifail >= (2)))
          {
            Console.WriteLine("  {0}{1,12:e2}", "Requested accuracy = ", eps);
            Console.WriteLine("  {0}{1,12:f4}", "Estimated value    = ", finval);
            Console.WriteLine("  {0}{1,12:e2}", "Estimated accuracy = ", acc);
          }
        }
        else
        {
          Console.WriteLine("** d01fc failed with ifail = {0,5}", ifail);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      ;
    }
    //
    public static double functn(int ndim, double[] z)
    {
      double functnValue = 0.0;
      functnValue = 4.00e0 * z[0] * z[2] * z[2] * Math.Exp(2.00e0 * z[0] * z[2]) /
      ((1.00e0 + z[1] + z[3]) * (1.00e0 + z[1] + z[3]));
      return functnValue;
    }
  }
}


d01fc Example Program Results

  Requested accuracy =    1.00e-004
  Estimated value    =       0.5754
  Estimated accuracy =    9.89e-005


//      d01gd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class D01GDE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        D01.D01GD_VECFUN vecfunD01GD = new D01.D01GD_VECFUN(vecfun);
        D01.D01GD_VECREG vecregD01GD = new D01.D01GD_VECREG(vecreg);
        const int ndim = 4;
        double err,  res; int itrans, npts, nrand;
        double[] vk = new double[ndim];
        int ifail;
        Console.WriteLine("d01gd Example Program Results");
        Console.WriteLine("");
        npts = 2;
        itrans = 0;
        nrand = 4;
        //
        D01.d01gd(ndim, vecfunD01GD, vecregD01GD, npts, vk, nrand, itrans, out res, out err,
        out ifail);
        //
        if (ifail == 0)
        {
          Console.WriteLine("  {0}{1,13:f5}{2}{3,10:e2}", "Result = ", res, ", standard error = ", err);
        }
        else
        {
          Console.WriteLine("** d01gd failed with ifail = {0,5}", ifail);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      ;
    }
    //
    public static void vecfun(int ndim, double[,] x, double[] fv, int m)
    {
      int i,  j;
      for (i = 1; i <= m; i++)
      {
        fv[i - 1] = 0.00e0;
      }
      for (j = 1; j <= ndim; j++)
      {
        for (i = 1; i <= m; i++)
        {
          fv[i - 1] = fv[i - 1] + x[i - 1, j - 1];
        }
      }
      for (i = 1; i <= m; i++)
      {
        fv[i - 1] = Math.Cos(0.50e0 + 2.00e0 * fv[i - 1] - (double)ndim);
      }
    }
    public static void vecreg(int ndim, double[,] x, int j, double[] c, double[] d,
    int m)
    {
      int i = 0;
      for (i = 1; i <= m; i++)
      {
        c[i - 1] = 0.00e0;
        d[i - 1] = 1.00e0;
      }
    }
  }
}


d01gd Example Program Results

  Result =       0.43999, standard error =  1.89e-006


//      d01gy Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class D01GYE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int ndim=4;
        int i,  npts; double[] vk = new double[20];
        int ifail;
        Console.WriteLine("d01gy Example Program Results");
        npts = 631;
        Console.WriteLine("");
        //
        D01.d01gy(ndim, npts, vk, out ifail);
        //
        if (ifail == 0)
        {
          Console.WriteLine("  {0}{1,3}{2}{3,6}","NDIM =",ndim," NPTS =",npts);
          Console.WriteLine("");
          Console.Write(" {0}",  "Coefficients =");
          for (i = 1 ; i <= ndim ; i++)
          {
            Console.Write(" {0, 10:f2}", vk[i - 1]);
          }
          Console.WriteLine("");
        }
        else
        {
          Console.WriteLine("** d01gy failed with ifail = {0,5}", ifail);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      ;
    }
  }
}


d01gy Example Program Results

  NDIM =  4 NPTS =   631

 Coefficients =       1.00     198.00      82.00     461.00


//      d01gz Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class D01GZE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int ndim = 4;
        int i,  np1,  np2; double[] vk = new double[ndim];
        int ifail;
        Console.WriteLine("d01gz Example Program Results");
        np1 = 89;
        np2 = 11;
        Console.WriteLine("");
        //
        D01.d01gz(ndim, np1, np2, vk, out ifail);
        //
        if (ifail == 0)
        {
          Console.WriteLine("  {0}{1,3}{2}{3,6}{4}{5,6}","NDIM =",ndim," NP1 =",np1," NP2 =",np2);
          Console.WriteLine("");
          Console.Write(" {0}",  "Coefficients =");
          for (i = 1 ; i <= ndim ; i++)
          {
            Console.Write(" {0, 10:f2}", vk[i - 1]);
          }
          Console.WriteLine("");
        }
        else
        {
          Console.WriteLine("** d01gz failed with ifail = {0,5}", ifail);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


d01gz Example Program Results

  NDIM =  4 NP1 =    89 NP2 =    11

 Coefficients =       1.00     102.00     614.00     951.00


//      d01ja Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class D01JAE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        D01.D01JA_F fD01JA = new D01.D01JA_F(f);
        double epsa,  epsr,  esterr,  radius,  relest,  result; int icoord,  itest,  method,  ndim,  nevals; int[] nd = new int[2] { 2, 4 };
        int ifail;
        Console.WriteLine("d01ja Example Program Results");
        radius = 1.00e0;
        method = 0;
        icoord = 1;
        epsa = 0.00e0;
        epsr = 0.50e-4;
        for (itest = 1; itest <= 2; itest++)
        {
          ndim = nd[itest - 1];
          //
          D01.d01ja(fD01JA, ndim, radius, epsa, epsr, method, icoord, out result, out esterr,
          out nevals, out ifail);
          //
          Console.WriteLine("");
          if (ifail != 0)
          {
            if (ifail > 0)
            {
              Console.WriteLine("  {0}{1,5}", "ifail =", ifail);
              Console.WriteLine("");
            }
            else
            {
              Console.WriteLine("** d01ja failed with ifail = {0,5}", ifail);
              goto L40;
            }
          }
          if (ifail <= 3)
          {
            relest = esterr / result;
            Console.WriteLine("  {0}{1,5}", "Dimension of the sphere       =", ndim);
            Console.WriteLine("  {0}{1,9:e2}", "Requested relative tolerance  =", epsr);
            Console.WriteLine("  {0}{1,9:f5}", "Approximation to the integral =", result);
            Console.WriteLine("  {0}{1,5}", "No. of function evaluations   =", nevals);
            Console.WriteLine("  {0}{1,9:e2}", "Estimated relative error      =", relest);
          }
        }
        L40: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      ;
    }
    //
    public static double f(int ndim, double[] x)
    {
      double fValue;
      double a,  rho = x[0];
      fValue = 0.00e0;
      a = (1.00e0 - rho) * (1.00e0 + rho);
      if (a != 0.00e0)
      {
        fValue = 1.00e0 / Math.Sqrt(a);
      }
      return fValue;
    }
  }
}


d01ja Example Program Results

  Dimension of the sphere       =    2
  Requested relative tolerance  =5.00e-005
  Approximation to the integral =  6.28319
  No. of function evaluations   =  193
  Estimated relative error      =3.15e-005

  Dimension of the sphere       =    4
  Requested relative tolerance  =5.00e-005
  Approximation to the integral = 13.16004
  No. of function evaluations   = 2873
  Estimated relative error      =4.03e-005


//      d01pa Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class D01PAE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int ndim = 3;
        const int ldvert = ndim + 1;
        const int sdvert = 2 * (ndim + 1);
        const int mxord = 5;
        D01.D01PA_FUNCTN functnD01PA = new D01.D01PA_FUNCTN(functn);
        double esterr;
        int maxord,  minord,  nevals; double[] finvls = new double[mxord];
        double[,] vert = new double[ldvert, sdvert];
        int ifail;
        Console.WriteLine("d01pa Example Program Results");
        for (int j = 1; j <= ldvert; j++)
        {
          for (int k = 1; k <= ndim; k++)
          {
            vert[j - 1, k - 1] = 0.00e0;
          }
          if (j > 1)
          {
            vert[j - 1, j - 1 - 1] = 1.00e0;
          }
        }
        minord = 0;
        nevals = 1;
        Console.WriteLine("");
        Console.WriteLine(" {0}", "MAXORD   Estimated      Estimated         Integrand");
        Console.WriteLine(" {0}", "           value         accuracy        evaluations");
        for (maxord = 1; maxord <= mxord; maxord++)
        {
          //
          D01.d01pa(ndim, vert, functnD01PA, ref minord, maxord, finvls, out esterr,
          out ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine("  {0,4}{1,13:f5}{2,16:e3}{3,15}", maxord, finvls[maxord - 1], esterr, nevals);
            nevals = (nevals * (maxord + ndim + 1)) / maxord;
          }
          else
          {
            Console.WriteLine("");
            Console.WriteLine("** d01pa failed with ifail = {0,5}", ifail);
            goto L80;
          }
        }
        L80: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
      ;
    }
    //
    public static double functn(int ndim, double[] x)
    {
      double functnValue;
      functnValue = Math.Exp(x[0] + x[1] + x[2]) * Math.Cos(x[0] + x[1] + x[2]);
      return functnValue;
    }
  }
}


//      e01ba Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class E01BAE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        int m=7;
        int lck=m + 4;
        double fit,   xarg; int i,  j,  r;
        double[] c = new double[lck];
        double[] lamda = new double[lck];
        double[] x = new double[] {0.00e0, 0.20e0, 0.40e0, 0.60e0, 0.750e0, 0.90e0, 1.00e0};
        double[] y = new double[m];
        int ifail;
        Console.WriteLine("e01ba Example Program Results");
        for (i = 1 ; i <= m ; i++)
        {
          y[i - 1] = Math.Exp(x[i - 1]);
        }
        //
        E01.e01ba(m, x, y, lamda, c, out ifail);
        //
        if (ifail == 0)
        {
          Console.WriteLine("");
          Console.WriteLine(" {0}","   J    Knot LAMDA(J+2)   B-spline coeff C(J)");
          Console.WriteLine("");
          j = 1;
          Console.WriteLine("  {0,4}{1,35:f4}",j,c[0]);
          for (j = 2 ; j <= m - 1 ; j++)
          {
            Console.WriteLine("  {0,4}{1,15:f4}{2,20:f4}",j,lamda[j + 2 - 1],c[j - 1]);
          }
          Console.WriteLine("  {0,4}{1,35:f4}",m,c[m - 1]);
          Console.WriteLine("");
          Console.WriteLine(" {0}","   R        Abscissa            Ordinate             Spline");
          Console.WriteLine("");
          for (r = 1 ; r <= m ; r++)
          {
            //
            E02.e02bb(m + 4, lamda, c, x[r - 1], out fit, out ifail);
            //
            Console.WriteLine("  {0,4}{1,15:f4}{2,20:f4}{3,20:f4}",r,x[r - 1],y[r - 1],fit);
            if (r < m)
            {
              xarg = 0.50e0 * (x[r - 1] + x[r + 1 - 1]);
              //
              E02.e02bb(m + 4, lamda, c, xarg, out fit, out ifail);
              //
              Console.WriteLine("  {0,19:f4}{1,40:f4}",xarg,fit);
            }
          }
        }
        else
        {
          Console.WriteLine(" ** e01ba returned with ifail = {0, 3}", ifail);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      e01be Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class E01BEE
  {
    static string datafile = "ExampleData/e01bee.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double step=0.0;
        int i,   m,   n,   r; int ifail;
        Console.WriteLine("e01be Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        if (n > 0)
        {
          double[] d = new double[n];
          double[] f = new double[n];
          double[] x = new double[n];
          for (r = 1 ; r <= n ; r++)
          {
            sr.Reset();
            x[r - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            f[r - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //
          E01.e01be(n, x, f, d, out ifail);
          //
          sr.Reset();
          m = int.Parse(sr.Next());
          if (ifail == 0 && m > 0)
          {
            double[] pf = new double[m];
            double[] px = new double[m];
            //            Compute M equally spaced points from X(1) to X(N).
            step = (x[n - 1] - x[0]) / (m - 1);
            for (i = 1 ; i <= m ; i++)
            {
              px[i - 1] = Math.Min(x[0] + (i - 1) * step, x[n - 1]);
            }
            //
            E01.e01bf(n, x, f, d, m, px, pf, out ifail);
            //
            Console.WriteLine("");
            Console.WriteLine(" {0}","                Interpolated");
            Console.WriteLine(" {0}","     Abscissa          Value");
            for (i = 1 ; i <= m ; i++)
            {
              Console.WriteLine("  {0,13:f4}    {1,13:f4}",px[i - 1],pf[i - 1]);
            }
          }
          else
          {
            Console.WriteLine(" ** e01be returned with ifail = {0, 3}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      e01bf Example Program Text
//      Mark 14 Revised. NAG Copyright 1989.
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class E01bffe
  {
    const int nin=5;
    const int mmax=21;
    const int nmax=50;
    public static int Main (string[] args)
    {
      DataReader sr = new DataReader("ExampleData/e01bffe.d");
      double step=0.0;
      int i=0,
      m=0,
      n=0,
      r=0;
      double[] d = new double[50];
      double[] f = new double[50];
      double[] pf = new double[21];
      double[] px = new double[21];
      double[] x = new double[50];
      int ifail;
      Console.WriteLine("e01bf Example Program Results");
      //      Skip heading in data file
      sr.Reset();
      sr.Reset();
      n = int.Parse(sr.Next());
      if ((n > 0) && (n <= nmax))
      {
        for (r = 1 ; r <= n ; r++)
        {
          sr.Reset();
          x[r - 1] = double.Parse(sr.Next(), CultureInfo.CurrentCulture);
          f[r - 1] = double.Parse(sr.Next(), CultureInfo.CurrentCulture);
          d[r - 1] = double.Parse(sr.Next(), CultureInfo.CurrentCulture);
        }
        sr.Reset();
        m = int.Parse(sr.Next());
        if ((m > 0) && (m <= mmax))
        {
          //            Compute M equally spaced points from X(1) to X(N).
          step = (x[n - 1] - x[0]) / (m - 1);
          for (i = 1 ; i <= m ; i++)
          {
            px[i - 1] = Math.Min(x[0] + (i - 1) * step, x[n - 1]);
          }
          //
          E01.e01bf(n, x, f, d, m, px, pf, ref ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine("");
            Console.WriteLine(" {0}","                  Interpolated");
            Console.WriteLine(" {0}","       Abscissa          Value");
            for (i = 1 ; i <= m ; i++)
            {
              Console.WriteLine("  {0,15:f4}{1,15:f4}",px[i - 1],pf[i - 1]);
            }
          }
          else
          {
            Console.WriteLine("   ** e01bf returned with ifail = {0,5}",ifail);
          }
        }
      }
      //
      return 0;
    }
  }
}


//      e01da Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class E01DAE
  {
    static string datafile = "ExampleData/e01dae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double step,   xhi,   xlo,   yhi,   ylo; int i,  j,  mx,  my,  nx,  ny,  px,  py;
        int ifail;
        Console.WriteLine("e01da Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        //      Read the number of x points, mx, and the values of the
        //      x co-ordinates.
        sr.Reset();
        mx = int.Parse(sr.Next());
        double[] x = new double[mx];
        double[] lamda = new double[mx+4];
        sr.Reset();
        for (i = 1 ; i <= mx ; i++)
        {
          x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        //      Read the number of Y points, my, and the values of the
        //      Y co-ordinates.
        sr.Reset();
        my = int.Parse(sr.Next());
        double[] c = new double[mx*my];
        double[] f = new double[mx*my];
        double[] mu = new double[my+4];
        double[] y = new double[my];
        sr.Reset();
        for (i = 1 ; i <= my ; i++)
        {
          y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        //      Read the function values at the grid points.
        for (j = 1 ; j <= my ; j++)
        {
          sr.Reset();
          for (i = 1 ; i <= mx ; i++)
          {
            f[my * (i - 1) + j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        //
        //      Generate the (X,Y,F) interpolating bicubic B-spline.
        E01.e01da(mx, my, x, y, f, out px, out py, lamda, mu, c, out ifail);
        //
        if (ifail == 0)
        {
          //
          //         Print the knot sets, lamda and mu.
          Console.WriteLine("");
          Console.WriteLine(" {0}","               I   Knot LAMDA(I)      J     Knot MU(J)");
          for (j = 4 ; j <= Math.Max(px, py) - 3 ; j++)
          {
            if ((j <= px - 3) && (j <= py - 3))
            {
              Console.WriteLine("  {0,16}{1,12:f4}{2,11}{3,12:f4}",j,lamda[j - 1],j,mu[j - 1]);
            }
            else if (j <= px - 3)
            {
              Console.WriteLine("  {0,16}{1,12:f4}",j,lamda[j - 1]);
            }
            else if (j <= py - 3)
            {
              Console.WriteLine("  {0,39}{1,12:f4}",j,mu[j - 1]);
            }
          }
          //         Print the spline coefficients.
          Console.WriteLine("");
          Console.WriteLine(" {0}","The B-Spline coefficients:");
          for (i = 1 ; i <= mx * my ; i++)
          {
            Console.Write(" {0, 9:f4}{1}", c[i - 1], i%8==0?"\n":"");
          }
          Console.WriteLine();
          Console.WriteLine("");
          //         Evaluate the spline on a regular rectangular grid at nx*ny
          //         points over the domain (xlo to xhi) x (ylo to yhi).
          sr.Reset();
          nx = int.Parse(sr.Next());
          xlo = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          xhi = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          sr.Reset();
          ny = int.Parse(sr.Next());
          ylo = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          yhi = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          double[] fg = new double[nx*ny];
          double[] tx = new double[nx];
          double[] ty = new double[ny];
          if (nx >= 1 && ny >= 1)
          {
            step = (xhi - xlo) / (nx - 1);
            for (i = 1 ; i <= nx ; i++)
            {
              //               Generate nx equispaced x co-ordinates.
              tx[i - 1] = Math.Min(xlo + (i - 1) * step, xhi);
              //               Generate x axis labels for printing results.
            }
            step = (yhi - ylo) / (ny - 1);
            for (i = 1 ; i <= ny ; i++)
            {
              ty[i - 1] = Math.Min(ylo + (i - 1) * step, yhi);
            }
            //
            //            Evaluate the spline.
            E02.e02df(nx, ny, px, py, tx, ty, lamda, mu, c, fg, out ifail);
            //
            //            Print the results.
            // In fg the data is row ordered. Store it as column ordered data in the 2d fg_print
            // array.
            double [, ] fg_print = new double [nx,  ny];
            for (i=1; i<=nx; i++)
            for (j=1; j<=ny; j++)
            fg_print[i-1,j-1]=fg[(j-1)*nx+i-1];
            //
            Console.WriteLine("Spline evaluated on a regular mesh (X across, Y down):");
            for (i=0; i<nx; i++)
            {
              if (i==0)
              Console.Write("{0,5}", "");
              Console.Write("{0, 8:f2}", tx[i]);
            }
            Console.WriteLine();
            for (i=1; i<=nx; i++)
            {
              Console.Write("{0, 5:f2}", ty[i-1]);
              for (j=1; j<=ny; j++)
              {
                Console.Write("{0, 8:f3}", fg_print[i-1,j-1]);
              }
              Console.WriteLine();
            }
            //
          }
        }
        else
        {
          Console.WriteLine(" ** e01da returned with ifail = {0, 3}", ifail);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      e02bb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class E02BBE
  {
    static string datafile = "ExampleData/e02bbe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double a,   b,   s,   x; int j, m, ncap, r;
        int ifail;
        Console.WriteLine("e02bb Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        try
        {
          while (true)
          {
            sr.Reset();
            m = int.Parse(sr.Next());
            if (m > 0)
            {
              sr.Reset();
              ncap = int.Parse(sr.Next());
              if (ncap + 7 >= 8)
              {
                double[] c = new double[ncap+7];
                double[] lamda = new double[ncap+7];
                sr.Reset();
                for (j = 1 ; j <= ncap + 7 ; j++)
                {
                  lamda[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }
                sr.Reset();
                for (j = 1 ; j <= ncap + 3 ; j++)
                {
                  c[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }
                a = lamda[3];
                b = lamda[ncap + 4 - 1];
                Console.WriteLine("");
                for (r = 1 ; r <= m ; r++)
                {
                  x = ((double)(m - r) * a + (double)(r - 1) * b) / (double)(m - 1);
                  //
                  E02.e02bb(ncap + 7, lamda, c, x, out s, out ifail);
                  //
                  if (ifail == 0)
                  {
                    if (r == 1)
                    {
                      Console.WriteLine(" {0}","  J       LAMDA(J)    B-spline coefficient (J-2)");
                      Console.WriteLine("");
                      for (j = 1 ; j <= ncap + 7 ; j++)
                      {
                        if ((j < 3) || (j > ncap + 5))
                        {
                          Console.WriteLine("  {0,3}{1,14:f4}",j,lamda[j - 1]);
                        }
                        else
                        {
                          Console.WriteLine("  {0,3}{1,14:f4}{2,21:f4}",j,lamda[j - 1],c[j - 2 - 1]);
                        }
                      }
                      Console.WriteLine("");
                      Console.WriteLine(" {0}","  R       Argument      Value of cubic spline");
                      Console.WriteLine("");
                    }
                    Console.WriteLine("  {0,3}{1,14:f4}{2,21:f4}",r,x,s);
                  }
                  else
                  {
                    Console.WriteLine(" ** e02bb returned with ifail = {0, 3}", ifail);
                  }
                }
              }
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      e02de Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class E02DEE
  {
    static string datafile = "ExampleData/e02dee.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   m,   px,   py; int ifail;
        Console.WriteLine("e02de Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        //      Read px and py, the number of knots in the x and Y directions.
        sr.Reset();
        px = int.Parse(sr.Next());
        py = int.Parse(sr.Next());
        if (px >= 8 && py >= 8)
        {
          double[] lamda = new double[px];
          double[] mu = new double[py];
          double[] c = new double[(px-4)*(py-4)];
          sr.Reset();
          for (i = 1 ; i <= px ; i++)
          {
            lamda[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          sr.Reset();
          for (i = 1 ; i <= py ; i++)
          {
            mu[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //         Read C, the bicubic spline coefficients.
          sr.Reset();
          for (i = 1 ; i <= (px - 4) * (py - 4) ; i++)
          {
            c[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //         Read M, the number of spline evaluation points.
          sr.Reset();
          m = int.Parse(sr.Next());
          if (m >= 1)
          {
            double[] x = new double[m];
            double[] y = new double[m];
            double[] ff = new double[m];
            //            Read the x and Y co-ordinates of the evaluation points.
            for (i = 1 ; i <= m ; i++)
            {
              sr.Reset();
              x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            //
            //            Evaluate the spline at the M points.
            E02.e02de(m, px, py, x, y, lamda, mu, c, ff, out ifail);
            //
            Console.WriteLine("");
            if (ifail == 0)
            {
              //               Print the results.
              Console.WriteLine(" {0}","      I       X(I)       Y(I)      FF(I)");
              for (i = 1 ; i <= m ; i++)
              {
                Console.WriteLine(" {0, 7}{1, 11:f3}{2,11:f3}{3,11:f3}", i, x[i - 1], y[i - 1], ff[i - 1]);
              }
              Console.WriteLine();
            }
            else
            {
              Console.WriteLine(" ** e02de returned with ifail = {0, 3}", ifail);
            }
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      e02df Example Program Text
//      Mark 14 Release. NAG Copyright 1989.
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
    public class E02DFE
    {
        static string datafile = "exampledata/e02dfe.d";
        // as a command line argument. It defaults to the named file specified below otherwise.
        //
        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
        {
            try
            {
                const int mxmax = 20;
                const int mymax = mxmax;
                const int pxmax = mxmax;
                const int pymax = pxmax;

                DataReader sr = new DataReader(datafile);
                int i = 0,
                mx = 0,
                my = 0,
                px = 0,
                py = 0;
                double[] c = new double[(pxmax - 4) * (pymax - 4)];
                double[] ff = new double[400];
                double[] lamda = new double[20];
                double[] mu = new double[20];
                double[] wrk = new double[108];
                double[] x = new double[20];
                double[] y = new double[20];
                string[] clabs = new string[20];
                string[] rlabs = new string[20];
                int ifail;
                Console.WriteLine("e02df Example Program Results");
                //      Skip heading in data file
                sr.Reset();
                Console.WriteLine("");
                //      Read PX and PY, the number of knots in the X and Y directions.
                sr.Reset();
                px = int.Parse(sr.Next());
                py = int.Parse(sr.Next());
                if ((px <= pxmax) && (py <= pymax))
                {
                    sr.Reset();
                    for (i = 1; i <= px; i++)
                    {
                        lamda[i - 1] = double.Parse(sr.Next(), CultureInfo.CurrentCulture);
                    }
                    sr.Reset();
                    for (i = 1; i <= py; i++)
                    {
                        mu[i - 1] = double.Parse(sr.Next(), CultureInfo.CurrentCulture);
                    }
                    //         Read C, the bicubic spline coefficients.
                    sr.Reset();
                    for (i = 1; i <= (px - 4) * (py - 4); i++)
                    {
                        c[i - 1] = double.Parse(sr.Next(), CultureInfo.CurrentCulture);
                    }
                    //         Read MX and MY, the number of grid points in the X and Y
                    //         directions respectively.
                    sr.Reset();
                    mx = int.Parse(sr.Next());
                    my = int.Parse(sr.Next());
                    if ((mx <= mxmax) && (my <= mymax))
                    {
                        //            Read the X and Y co-ordinates defining the evaluation grid.
                        sr.Reset();
                        for (i = 1; i <= mx; i++)
                        {
                            x[i - 1] = double.Parse(sr.Next(), CultureInfo.CurrentCulture);
                        }
                        sr.Reset();
                        for (i = 1; i <= my; i++)
                        {
                            y[i - 1] = double.Parse(sr.Next(), CultureInfo.CurrentCulture);
                        }
                        //
                        //            Evaluate the spline at the MX by MY points.
                        E02.e02df(mx, my, px, py, x, y, lamda, mu, c, ff, out ifail);
                        //
                        if (ifail == 0)
                        {
                            //               Generate column and row labels to print the results with.
                            for (i = 1; i <= mx; i++)
                            {
                                clabs[i-1]= x[i-1].ToString("F1");
                            }
                            for (i = 1; i <= my; i++)
                            {
                                rlabs[i - 1] = y[i - 1].ToString("F1");
                            }
                            //
                            //               Print the result array.
                            X04.x04cb("G", "X", my, mx, ff, "F8.3", "Spline evaluated on X-Y grid (X across, Y down):", "Character", rlabs, "Character", clabs, 80, 0, out ifail);
                            //
                        }
                        else
                        {
                            Console.WriteLine("  {0}{1,5}", " ** e02df returned with ifail = ", ifail);
                        }
                    }
                }

            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
                Console.WriteLine("Exception Raised");
            }
        }

    }
}


//      e04ab Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04ABE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04AB_FUNCT functE04AB = new E04.E04AB_FUNCT(funct);
      double a,  b,  e1,  e2,  f,  x;
      int ifail,  maxcal;
      Console.WriteLine("e04ab Example Program Results");
      //      e1 and e2 are set to zero so that E04.e04ab will reset them to
      //      their default values
      e1 = 0.00e0;
      e2 = 0.00e0;
      //      The minimum is known to lie in the range (3.5, 5.0)
      a = 3.50e0;
      b = 5.00e0;
      //      Allow 30 calls of funct
      maxcal = 30;
      //
      try
      {
        E04.e04ab(functE04AB, ref e1, ref e2, ref a, ref b, ref maxcal, out x, out f,
        out ifail);
        //
        Console.WriteLine("");
        if (ifail < 0)
        {
          Console.WriteLine(" ** e04ab returned with ifail = {0, 3}", ifail);
        }
        else if (ifail == 1)
        {
          Console.WriteLine(" {0}", "Parameter outside expected range");
        }
        else
        {
          if (ifail == 2)
          {
            Console.WriteLine(" {0}", "Results after MAXCAL function evaluations are");
            Console.WriteLine("");
          }
          Console.WriteLine("  {0}{1,10:f8}{2}{3,10:f8}", "The minimum lies in the interval ", a, " to ", b);
          Console.WriteLine("  {0}{1,10:f8}{2}", "Its estimated position is ", x, ",");
          Console.WriteLine("  {0}{1,7:f4}", "where the function value is ", f);
          Console.WriteLine("  {0,2}  {1}", maxcal, " function evaluations were required");
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
    //
    public static void funct(double xc, out double fc)
    {
      //      Routine to evaluate F(x) at any point in (A, B)
      fc = Math.Sin(xc) / xc;
    }
  }
}


e04ab Example Program Results

  The minimum lies in the interval 4.49340940 to 4.49340951
  Its estimated position is 4.49340945,
  where the function value is -0.2172
  10   function evaluations were required


//      e04bb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04BBE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04BB_FUNCT functE04BB = new E04.E04BB_FUNCT(funct);
      double a,  b,  e1,  e2,  f,  g,  x;
      int ifail,  maxcal;
      Console.WriteLine("e04bb Example Program Results");
      // e1 and e2 are set to zero so that E04.e04bb will reset them to
      // their default values
      e1 = 0.00e0;
      e2 = 0.00e0;
      // The minimum is known to lie in the range (3.5, 5.0)
      a = 3.50e0;
      b = 5.00e0;
      //      Allow 30 calls of funct
      maxcal = 30;
      //
      try
      {
        E04.e04bb(functE04BB, ref e1, ref e2, ref a, ref b, ref maxcal, out x, out f, out g,
        out ifail);
        //
        Console.WriteLine("");
        if (ifail < 0)
        {
          Console.WriteLine(" ** e04bb returned with ifail = {0, 3}", ifail);
        }
        else if (ifail == 1)
        {
          Console.WriteLine(" {0}", "Parameter outside expected range");
        }
        else
        {
          if (ifail == 2)
          {
            Console.WriteLine(" {0}", "Results after MAXCAL calls of FUNCT are");
            Console.WriteLine("");
          }
          Console.WriteLine("  {0}{1,10:f8}{2}{3,10:f8}", "The minimum lies in the interval ", a, " to ", b);
          Console.WriteLine("  {0}{1,10:f8}{2}", " Its estimated position is ", x, ",");
          Console.WriteLine("  {0}{1,7:f4}", "where the function value is ", f);
          Console.WriteLine("  {0}{1,8:e1}{2}", "and the gradient is ", g, " (machine dependent)");
          Console.WriteLine("  {0,2}{1}", maxcal, " calls of FUNCT were required");
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
    //
    public static void funct(double xc, out double fc, out double gc)
    {
      //      Routine to evaluate F(x) and dF/dx at any point in (A, B)
      fc = Math.Sin(xc) / xc;
      gc = (Math.Cos(xc) - fc) / xc;
    }
  }
}


e04bb Example Program Results

  The minimum lies in the interval 4.49340940 to 4.49340946
   Its estimated position is 4.49340946,
  where the function value is -0.2172
  and the gradient is 3.9e-016 (machine dependent)
   6 calls of FUNCT were required


//      e04cb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04CBE
  {
    static int[] iuser = new int[1];
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04CB_FUNCT functE04CB = new E04.E04CB_FUNCT(funct);
      E04.E04CB_MONIT monitE04CB = new E04.E04CB_MONIT(monit);
      double f,  tolf = 0.0,  tolx = 0.0; int i, ifail, maxcal = 0;
      int n = 2;
      double[] x = new double[n];
      Console.WriteLine("e04cb Example Program Results");
      // set iuser[0] to 1 to obtain monitoring information **
      iuser[0] = 0;
      x[0] = -1.00e0;
      x[1] = 1.00e0;
      tolf = Math.Sqrt(X02.x02aj());
      tolx = Math.Sqrt(tolf);
      maxcal = 100;
      //
      try
      {
        E04.e04cb(n, x, out f, tolf, tolx, functE04CB, monitE04CB, maxcal, out ifail);
        //
        Console.WriteLine("");
        if (ifail >= 0)
        {
          Console.WriteLine("  On exit from e04cb, ifail = {0,4}", ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine("  The final function value is{0,12:f4}", f);
            Console.Write("  at the point  ");
            for (i = 1; i <= n; i++)
            {
              Console.Write(" " + " {0, 12:f4}", x[i - 1]);
            }
            Console.WriteLine(" ");
          }
        }
        else
        {
          Console.WriteLine("  {0}{1,5}", ifail);
        }
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    //
    public static void funct(int n, double[] xc, out double fc)
    {
      //
      fc = Math.Exp(xc[0]) * (4.00e0 * xc[0] * (xc[0] + xc[1]) + 2.00e0 * xc[1] * (xc[1] + 1.00e0) + 1.00e0);
      //
    }
    //
    public static void monit(double fmin, double fmax, double[,] sim, int n, int ncall,
    double serror,  double vratio) { if (iuser[0] != 0) { int i,  j;
    Console.WriteLine("");
    Console.WriteLine("  There have been{0,5} function calls", ncall);
    Console.WriteLine("  The smallest function value is{0,10:f4}", fmin);
    Console.WriteLine("  The simplex is");
    for (i = 1; i <= n + 1; i++)
    {
      for (j = 1; j <= n; j++)
      {
        Console.Write(" {0}", sim[i - 1, j - 1]);
      }
      Console.WriteLine(" ");
    }
    Console.WriteLine(" ");
    Console.WriteLine("  The standard deviation in function values at the vertices of the simplex is{0,10:f4}", serror);
    Console.WriteLine("  The linearized volume ratio of the current simplex to the starting one is{0,10:f4}", vratio);
  }
}
}
}


e04cb Example Program Results

  On exit from e04cb, ifail =    0
  The final function value is      0.0000
  at the point          0.5000       -0.9999


//      e04dg Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04DGE
  {
    static string datafile = "ExampleData/e04dge.d";
    // as a command line argument. It defaults to the named file specified below otherwise.
    //
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04DG_OBJFUN objfunE04DG = new E04.E04DG_OBJFUN(objfun);
      try
      {
        DataReader sr = new DataReader(datafile);
      double objf;
      int i,  ifail,  iter,  n; Console.WriteLine("e04dg Example Program Results");
      //      Skip heading in data file
      sr.Reset();
      sr.Reset();
      n = int.Parse(sr.Next());
      double[] objgrd = new double[n];
      double[] x = new double[n];
      //
      //         Read x from data file
      //
      sr.Reset();
      for (i = 1; i <= n; i++)
      {
        x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
      }
      //
      //         Initialise E04.e04dg
      //
      E04.e04dgOptions options = new E04.e04dgOptions();
      //
      //            Solve the problem
      //
      options.Set("List");
      options.Set("Print level = 10");
      E04.e04dg(n, objfunE04DG, out iter, out objf, objgrd, x, options, out ifail);
      //
      //            Check for error exits
      //
      Console.WriteLine("");
      if ((ifail >= 0) && (ifail < 9))
      {
        Console.WriteLine(" ** e04dg returned with ifail = {0, 3}", ifail);
        Console.WriteLine("");
        Console.WriteLine("  Variable                    Value                Gradient value");
        Console.WriteLine("");
        for (i = 1; i <= n; i++)
        {
          Console.WriteLine("  Varbl  {0,3}        {1,15:g7}        {2,9:g1}", i, x[i - 1], objgrd[i - 1]);
        }
        Console.WriteLine("");
        Console.WriteLine("");
        Console.WriteLine("  Final objective value = {0,15:g7}", objf);
      }
      else
      {
        if (ifail >= (9))
        {
          Console.WriteLine("   ** An input parameter is invalid");
        }
        else if (ifail == -399)
        {
          Console.WriteLine(" ** e04dg returned with ifail = {0, 3}", ifail);
        }
        else
        {
          Console.WriteLine("  MODE < 0 on exit from OBJFUN. Problem abandoned.");
        }
      }
      //
      //
    }
    catch (Exception e)
    {
      Console.WriteLine(e.Message);
      Console.WriteLine( "Exception Raised");
    }
  }
  //
  public static void objfun(ref int mode, int n, double[] x, out double objf,
  double[] objgrd, int nstate)
  {
    //      Routine to evaluate F(x) and its 1st derivatives.
    double one = 1.00e0;
    double two = 2.00e0;
    double four = 4.00e0;
    double expx1,  x1,  x2;
    x1 = x[0];
    x2 = x[1];
    expx1 = Math.Exp(x1);
    objf = expx1 * (four * (x1) * (x1) + two * (x2) * (x2) + four * x1 * x2 + two * x2 + one);
    //
    if (mode == 2)
    {
      objgrd[0] = four * expx1 * (two * x1 + x2) + objf;
      objgrd[1] = two * expx1 * (two * x2 + two * x1 + one);
    }
    //
  }
}
}


e04dg Example Program Data
  2                          :Value of N
 -1.0  1.0                   :End of X


//      e04fc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04FCE
  {
    static int m = 15;
    static int nt = 3;
    public static double[,] t = new double[m, nt];
    public static double[] y = new double[m];
    static string datafile = "ExampleData/e04fce.d";
    // as a command line argument. It defaults to the named file specified below otherwise.
    //
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04FC_LSQFUN lsqfunE04FC = new E04.E04FC_LSQFUN(lsqfun);
      E04.E04FC_LSQMON lsqmonE04FC = new E04.E04FC_LSQMON(lsqmon);
      try
      {
        DataReader sr = new DataReader(datafile);
      double eta,  fsumsq,  stepmx,  xtol;
      int i,  ifail,  iprint,  j,  maxcal,  nf,  niter;
      int n = 3;
      double[,] fjac = new double[m, n];
      double[] fvec = new double[m];
      double[] g = new double[n];
      double[] s = new double[n];
      double[,] v = new double[n, n];
      double[] x = new double[n];
      int[] iw = new int[1];
      Console.WriteLine("e04fc Example Program Results");
      //      Skip heading in data file
      sr.Reset();
      //      Observations of tj(j = 1, 2, 3) are held in t[i-1, j-1]
      //      (i = 1, 2, . . . , 15)
      for (i = 1; i <= m; i++)
      {
        sr.Reset();
        y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        for (j = 1; j <= nt; j++)
        {
          t[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
      }
      //      * Set iprint to 1 to obtain output from lsqmon at each iteration *
      iprint = -1;
      maxcal = 400 * n;
      eta = 0.50e0;
      xtol = 10.00e0 * Math.Sqrt(X02.x02aj());
      // We estimate that the minimum will be within 10 units of the
      // starting point
      stepmx = 10.00e0;
      //      Set up the starting point
      x[0] = 0.50e0;
      x[1] = 1.00e0;
      x[2] = 1.50e0;
      //
      E04.e04fc(m, n, lsqfunE04FC, lsqmonE04FC, iprint, maxcal, eta, xtol, stepmx, x,
      out fsumsq, fvec, fjac, s, v,
      out niter, out nf, out ifail);
      //
      if (ifail < 0)
      {
        Console.WriteLine("");
        Console.WriteLine(" ** e04fc returned with ifail = {0, 3}", ifail);
      }
      else
      {
        if (ifail != 0)
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,3}{2}", "Error exit type", ifail, " - see method document");
        }
        if (ifail != 1)
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,12:f4}", "On exit, the sum of squares is", fsumsq);
          Console.Write(" " + " {0}", "at the point");
          for (j = 1; j <= n; j++)
          {
            Console.Write(" " + " {0}", x[j - 1]);
          }
          Console.WriteLine(" ");
          lsqgrd(m, n, fvec, fjac, g);
          Console.Write(" " + " {0}", "The estimated gradient is");
          for (j = 1; j <= n; j++)
          {
            Console.WriteLine(" " + " {0}", g[j - 1]);
          }
          Console.WriteLine(" ");
          Console.WriteLine(" {0}", "                           (machine dependent)");
          Console.WriteLine(" {0}\n", "and the residuals are");
          for (i = 1; i <= m; i++)
          {
            Console.WriteLine(" " + " {0, 9:e1}", fvec[i - 1]);
          }
          Console.WriteLine(" ");
        }
      }
      //
    }
    catch (Exception e)
    {
      Console.WriteLine(e.Message);
      Console.WriteLine( "Exception Raised");
      // Console.WriteLine(e.Message);
    }
  }
  //
  public static void lsqfun(ref int iflag, int m, int n, double[] xc,
  double[] fvec)
  {
    //      Routine to evaluate the residuals
    int i = 0;
    for (i = 1; i <= m; i++)
    {
      fvec[i - 1] = xc[0] + t[i - 1, 0] / (xc[1] * t[i - 1, 1] + xc[2] * t[i - 1, 2]) - y[i - 1];
    }
  }
  //
  public static void lsqmon(int m, int n, double[] xc, double[] fvec, double[,] fjac,
  double[] s, int igrade, int niter, int nf)
  {
    //      Monitoring method
    double fsumsq,  gtg;
    int j = 0;
    int ifail;
    double[] g = new double[3];
    fsumsq = F06.f06ea(m, fvec, 1, fvec, 1, out ifail);
    lsqgrd(m, n, fvec, fjac, g);
    gtg = F06.f06ea(n, g, 1, g, 1, out ifail);
    Console.WriteLine("");
    Console.WriteLine(" {0}", "  Itn      F evals        SUMSQ             GTG        Grade");
    Console.WriteLine("  {0,4}            {1,5}            {2,13:e5}            {3,9:e1}            {4,3}", niter, nf, fsumsq, gtg, igrade);
    Console.WriteLine("");
    Console.WriteLine(" {0}", "       x                    g           Singular values");
    for (j = 1; j <= n; j++)
    {
      Console.WriteLine("  {0,13:e5}                    {1,9:e1}                    {2,9:e1}", xc[j - 1], g[j - 1], s[j - 1]);
    }
    //
  }
  //
  public static void lsqgrd(int m, int n, double[] fvec, double[,] fjac, double[] g)
  {
    //      Routine to evaluate gradient of the sum of squares
    double sum = 0.0;
    int i,  j;
    for (j = 1; j <= n; j++)
    {
      sum = 0.00e0;
      for (i = 1; i <= m; i++)
      {
        sum = sum + fjac[i - 1, j - 1] * fvec[i - 1];
      }
      g[j - 1] = sum + sum;
    }
  }
}
}


//      e04fy Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04FYE
  {
    static int m = 15;
    static int nt = 3;
    static double[] ruser = new double[m + m * nt];
    static int[] iuser = new int[1];
    static string datafile = "ExampleData/e04fye.d";
    // as a command line argument. It defaults to the named file specified below otherwise.
    //
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04FY_LSFUN1 lsfun1E04FY = new E04.E04FY_LSFUN1(lsfun1);
      try
      {
        DataReader sr = new DataReader(datafile);
      double fsumsq = 0.0;
      int i,  ifail,  j,  k;
      int n = 3;
      double[,] t = new double[m, nt];
      double[] x = new double[n];
      double[] y = new double[m];
      Console.WriteLine("e04fy Example Program Results");
      //      Skip heading in data file
      sr.Reset();
      //
      //      Observations of tj (j = 1, 2, 3) are held in t[i-1, j-1]
      //      (i = 1, 2, . . . , 15)
      //
      iuser[0] = nt;
      k = m;
      for (i = 1; i <= m; i++)
      {
        sr.Reset();
        y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        for (j = 1; j <= nt; j++)
        {
          t[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        ruser[i - 1] = y[i - 1];
        for (j = 1; j <= nt; j++)
        {
          ruser[k + j - 1] = t[i - 1, j - 1];
        }
        k = k + nt;
      }
      //
      x[0] = 0.50e0;
      x[1] = 1.00e0;
      x[2] = 1.50e0;
      //
      E04.e04fy(m, n, lsfun1E04FY, x, out fsumsq, out ifail);
      //
      if (ifail < 0)
      {
        Console.WriteLine("");
        Console.WriteLine(" ** e04fy returned with ifail = {0, 3}", ifail);
      }
      else
      {
        if (ifail != 0)
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,3}{2}", "Error exit type", ifail, " - see method document");
        }
        //
        if (ifail != 1)
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,12:f4}", "On exit, the sum of squares is", fsumsq);
          Console.Write(" {0}", "at the point");
          for (j = 1; j <= n; j++)
          {
            Console.Write(" {0, 12:f4}", x[j - 1]);
          }
          Console.WriteLine();
        }
      }
      //
    }
    catch (Exception e)
    {
      Console.WriteLine(e.Message);
      Console.WriteLine( "Exception Raised");
    }
  }
  //
  public static void lsfun1(int m, int n, double[] xc, double[] fvec)
  {
    int i,  k;
    k = m;
    for (i = 1; i <= m; i++)
    {
      fvec[i - 1] = xc[0] + ruser[k + 1 - 1] / (xc[1] * ruser[k + 2 - 1] + xc[2] * ruser[k + 3 - 1]) - ruser[i - 1];
      k = k + iuser[0];
    }
  }
}
}


e04fy Example Program Results

  On exit, the sum of squares is      0.0082
 at the point       0.0824       1.1330       2.3437


//      e04gd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04GDE
  {
    static int m = 15;
    static int nt = 3;
    static int ldfjac = m;
    public static double[,] t = new double[m, nt];
    public static double[] y = new double[m];
    static string datafile = "ExampleData/e04gde.d";
    // as a command line argument. It defaults to the named file specified below otherwise.
    //
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04YA_LSQFUN lsqfunE04YA = new E04.E04YA_LSQFUN(lsqfun);
      E04.E04GD_LSQFUN lsqfunE04GD = new E04.E04GD_LSQFUN(lsqfun);
      E04.E04GD_LSQMON lsqmonE04GD = new E04.E04GD_LSQMON(lsqmon);
      try
      {
        DataReader sr = new DataReader(datafile);
      double eta,  fsumsq,  stepmx,  xtol;
      int i,  ifail,  iprint,  j,  maxcal,  nf,  niter;
      int n = 3;
      int ldv = n;
      double[,] fjac = new double[ldfjac, n];
      double[] fvec = new double[m];
      double[] g = new double[n];
      double[] s = new double[n];
      double[,] v = new double[ldv, n];
      double[] x = new double[n];
      int[] iw = new int[1];
      Console.WriteLine("e04gd Example Program Results");
      //      Skip heading in data file
      sr.Reset();
      //      Observations of tj (j = 1, 2, 3) are held in t[i-1, j-1]
      //      (i = 1, 2, . . . , 15)
      for (i = 1; i <= m; i++)
      {
        sr.Reset();
        y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        for (j = 1; j <= nt; j++)
        {
          t[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
      }
      //      Check lsqfunE04YA by calling e04ya at an arbitrary point.
      x[0] = 0.190e0;
      x[1] = -1.340e0;
      x[2] = 0.880e0;
      E04.e04ya(m, n, lsqfunE04YA, x, fvec, fjac, out ifail);
      //
      if (ifail != 0)
      {
        Console.WriteLine("");
        Console.WriteLine(" ** e04ya returned with ifail = {0, 3}", ifail);
        goto L40;
      }
      //      Continue setting parameters for e04gd
      //      Set iprint to 1 to obtain output from lsqfunE04YA at each iteration *
      iprint = -1;
      maxcal = 50 * n;
      eta = 0.90e0;
      xtol = 10.00e0 * Math.Sqrt(X02.x02aj());
      //      We estimate that the minimum will be within 10 units of the
      //      starting point
      stepmx = 10.00e0;
      //      Set up the starting point
      x[0] = 0.50e0;
      x[1] = 1.00e0;
      x[2] = 1.50e0;
      //
      E04.e04gd(m, n, lsqfunE04GD, lsqmonE04GD, iprint, maxcal, eta, xtol, stepmx, x,
      out fsumsq, fvec, fjac, s, v, out niter, out nf, out ifail);
      //
      if (ifail != 0)
      {
        Console.WriteLine("");
        Console.WriteLine(" ** e04gd returned with ifail = {0, 3}", ifail);
        if ((ifail < 0) || (ifail == 1))
        {
          goto L40;
        }
      }
      //
      Console.WriteLine("");
      Console.WriteLine("  {0}{1,12:f4}", "On exit, the sum of squares is", fsumsq);
      Console.Write(" " + " {0}", "at the point");
      for (j = 1; j <= n; j++)
      {
        Console.Write(" " + " {0, 12:f4}", x[j - 1]);
      }
      Console.WriteLine(" ");
      lsqgrd(m, n, fvec, fjac, ldfjac, g);
      Console.Write(" " + " {0}", "The corresponding gradient is");
      for (j = 1; j <= n; j++)
      {
        Console.Write(" " + " {0, 12:e3}", g[j - 1]);
      }
      Console.WriteLine(" ");
      Console.WriteLine(" {0}", "                           (machine dependent)");
      Console.WriteLine(" {0}\n", "and the residuals are");
      for (i = 1; i <= m; i++)
      {
        Console.WriteLine(" " + " {0, 12:e1}", fvec[i - 1]);
      }
      Console.WriteLine(" ");
      //
      L40: ;
      //
    }
    catch (Exception e) {
    Console.WriteLine(e.Message);
    Console.WriteLine( "Exception Raised");
  }
}
//
public static void lsqfun(ref int iflag, int m, int n, double[] xc, double[] fvec,
double[,] fjac)
{
  //      Routine to evaluate the residuals and their 1st derivatives.
  //      An static variable could be updated here to count the
  //      number of calls of lsqfun with iflag set to 1 (since nf
  //      in lsqmon only counts calls with iflag set to 2)
  double denom,  dummy;
  int i = 0;
  for (i = 1; i <= m; i++)
  {
    denom = xc[1] * t[i - 1, 1] + xc[2] * t[i - 1, 2];
    if (iflag == 2)
    {
      fvec[i - 1] = xc[0] + t[i - 1, 0] / denom - y[i - 1];
    }
    fjac[i - 1, 0] = 1.00e0;
    dummy = -1.00e0 / (denom * denom);
    fjac[i - 1, 1] = t[i - 1, 0] * t[i - 1, 1] * dummy;
    fjac[i - 1, 2] = t[i - 1, 0] * t[i - 1, 2] * dummy;
  }
}
//
public static void lsqmon(int m, int n, double[] xc, double[] fvec, double[,] fjac,
double[] s, int igrade, int niter, int nf)
{
  //      Monitoring method
  double fsumsq,  gtg;
  int j = 0;
  double[] g = new double[3];
  int ifail;
  fsumsq = F06.f06ea(m, fvec, 1, fvec, 1, out ifail);
  lsqgrd(m, n, fvec, fjac, ldfjac, g);
  gtg = F06.f06ea(n, g, 1, g, 1, out ifail);
  //      A static variable giving the number of calls of
  //      lsqfun with iflag set to 1 could be printed here
  Console.WriteLine("");
  Console.WriteLine(" {0}", " Itns    F evals          SUMSQ             GTG        grade");
  Console.WriteLine("  {0,4}            {1,5}            {2,13:e5}            {3,9:e1}            {4,3}", niter, nf, fsumsq, gtg, igrade);
  Console.WriteLine("");
  Console.WriteLine(" {0}", "       x                    g           Singular values");
  for (j = 1; j <= n; j++)
  {
    Console.WriteLine("  {0,13:e5}                    {1,9:e1}                    {2,9:e1}", xc[j - 1], g[j - 1], s[j - 1]);
  }
  //
}
//
public static void lsqgrd(int m, int n, double[] fvec, double[,] fjac, int ldfjac,
double[] g)
{
  //      Routine to evaluate gradient of the sum of squares
  double sum = 0.0;
  int i,  j;
  for (j = 1; j <= n; j++)
  {
    sum = 0.00e0;
    for (i = 1; i <= m; i++)
    {
      sum = sum + fjac[i - 1, j - 1] * fvec[i - 1];
    }
    g[j - 1] = sum + sum;
  }
}
}
}


//      e04gy Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04GYE
  {
    static int m = 15;
    static int nt = 3;
    static double[] ruser = new double[m + m * nt];
    static int[] iuser = new int[1];
    static string datafile = "ExampleData/e04gye.d";
    // as a command line argument. It defaults to the named file specified below otherwise.
    //
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04GY_LSFUN2 lsfun2E04GY = new E04.E04GY_LSFUN2(lsfun2);
      try
      {
        DataReader sr = new DataReader(datafile);
      double fsumsq = 0.0;
      int i,  ifail,  j,  k;
      int n = 3;
      double[,] t = new double[m, nt];
      double[] x = new double[n];
      double[] y = new double[m];
      Console.WriteLine("e04gy Example Program Results");
      //      Skip heading in data file
      sr.Reset();
      //
      //      Observations of tj (j = 1, 2, 3) are held in t[i-1, j-1]
      //      (i = 1, 2, . . . , 15)
      //
      iuser[0] = nt;
      k = m;
      for (i = 1; i <= m; i++)
      {
        sr.Reset();
        y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        for (j = 1; j <= nt; j++)
        {
          t[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        ruser[i - 1] = y[i - 1];
        for (j = 1; j <= nt; j++)
        {
          ruser[k + j - 1] = t[i - 1, j - 1];
        }
        k = k + nt;
      }
      //
      x[0] = 0.50e0;
      x[1] = 1.00e0;
      x[2] = 1.50e0;
      //
      //
      E04.e04gy(m, n, lsfun2E04GY, x, out fsumsq, out ifail);
      //
      if (ifail < 0)
      {
        Console.WriteLine("");
        Console.WriteLine(" ** e04gy returned with ifail = {0, 3}", ifail);
      }
      else
      {
        if (ifail != 0)
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,3}{2}", "Error exit type", ifail, " - see method document");
        }
        if ((ifail != 1) && (ifail != 9))
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,12:f4}", "On exit, the sum of squares is", fsumsq);
          Console.Write(" " + " {0}", "at the point");
          for (j = 1; j <= n; j++)
          {
            Console.Write(" " + " {0, 12:f4}", x[j - 1]);
          }
          Console.WriteLine(" ");
        }
      }
      //
    }
    catch (Exception e)
    {
      Console.WriteLine(e.Message);
      Console.WriteLine( "Exception Raised");
    }
  }
  //
  public static void lsfun2(int m, int n, double[] xc, double[] fvec, double[,
  ] fjac)
  {
    //      Routine to evaluate the residuals and their 1st derivatives.
    double denom,  dummy;
    int i,  k;
    k = m;
    for (i = 1; i <= m; i++)
    {
      denom = xc[1] * ruser[k + 2 - 1] + xc[2] * ruser[k + 3 - 1];
      fvec[i - 1] = xc[0] + ruser[k + 1 - 1] / denom - ruser[i - 1];
      fjac[i - 1, 0] = 1.00e0;
      dummy = -1.00e0 / (denom * denom);
      fjac[i - 1, 1] = ruser[k + 1 - 1] * ruser[k + 2 - 1] * dummy;
      fjac[i - 1, 2] = ruser[k + 1 - 1] * ruser[k + 3 - 1] * dummy;
      k = k + iuser[0];
    }
  }
}
}


e04gy Example Program Results

  On exit, the sum of squares is      0.0082
  at the point        0.0824        1.1330        2.3437


//      e04gz Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04GZE
  {
    static int m = 15;
    static int nt = 3;
    static double[] ruser = new double[m + m * nt];
    static int[] iuser = new int[1];
    static string datafile = "ExampleData/e04gze.d";
    // as a command line argument. It defaults to the named file specified below otherwise.
    //
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04GZ_LSFUN2 lsfun3E04GZ = new E04.E04GZ_LSFUN2(lsfun3);
      try
      {
        DataReader sr = new DataReader(datafile);
      double fsumsq = 0.0;
      int i,  ifail,  j,  k;
      int n = 3;
      double[,] t = new double[m, nt];
      double[] x = new double[n];
      double[] y = new double[m];
      // int[] iuser = new int[1];
      Console.WriteLine("e04gz Example Program Results");
      //      Skip heading in data file
      sr.Reset();
      //
      //      Observations of tj (j = 1, 2, 3) are held in t[i-1, j-1]
      //      (i = 1, 2, . . . , 15)
      //
      iuser[0] = nt;
      k = m;
      for (i = 1; i <= m; i++)
      {
        sr.Reset();
        y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        for (j = 1; j <= nt; j++)
        {
          t[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        ruser[i - 1] = y[i - 1];
        for (j = 1; j <= nt; j++)
        {
          ruser[k + j - 1] = t[i - 1, j - 1];
        }
        k = k + nt;
      }
      //
      x[0] = 0.50e0;
      x[1] = 1.00e0;
      x[2] = 1.50e0;
      //
      E04.e04gz(m, n, lsfun3E04GZ, x, out fsumsq, out ifail);
      //
      if (ifail < 0)
      {
        Console.WriteLine("");
        Console.WriteLine(" ** e04gz returned with ifail = {0, 3}", ifail);
      }
      else
      {
        if (ifail != 0)
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,3}{2}", "Error exit type", ifail, " - see method document");
        }
        if ((ifail != 1) && (ifail != 9))
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,12:f4}", "On exit, the sum of squares is", fsumsq);
          Console.Write(" " + " {0}", "at the point");
          for (j = 1; j <= n; j++)
          {
            Console.Write(" " + " {0, 12:f4}", x[j - 1]);
          }
          Console.WriteLine(" ");
        }
      }
      //
    }
    catch (Exception e)
    {
      Console.WriteLine(e.Message);
      Console.WriteLine( "Exception Raised");
    }
  }
  //
  public static void lsfun3(int m, int n, double[] xc, double[] fvec, double[,
  ] fjac)
  {
    //      Method to evaluate the residuals and their 1st derivatives.
    double denom,  dummy;
    int i,  k;
    k = m;
    for (i = 1; i <= m; i++)
    {
      denom = xc[1] * ruser[k + 2 - 1] + xc[2] * ruser[k + 3 - 1];
      fvec[i - 1] = xc[0] + ruser[k + 1 - 1] / denom - ruser[i - 1];
      fjac[i - 1, 0] = 1.00e0;
      dummy = -1.00e0 / (denom * denom);
      fjac[i - 1, 1] = ruser[k + 1 - 1] * ruser[k + 2 - 1] * dummy;
      fjac[i - 1, 2] = ruser[k + 1 - 1] * ruser[k + 3 - 1] * dummy;
      k = k + iuser[0];
    }
  }
}
}


e04gz Example Program Results

  On exit, the sum of squares is      0.0082
  at the point        0.0824        1.1330        2.3437


//      e04hc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04HCE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04HC_FUNCT functE04HC = new E04.E04HC_FUNCT(funct);
      try
      {
        double f = 0.0;
        int ifail,  j;
        int n = 4;
        int lw = 3 * n;
        double[] g = new double[n];
        double[] w = new double[lw];
        double[] x = new double[n];
        int[] iw = new int[1];
        Console.WriteLine("e04hc Example Program Results");
        //      Set up an arbitrary point at which to check the 1st derivatives
        x[0] = 1.460e0;
        x[1] = -0.820e0;
        x[2] = 0.570e0;
        x[3] = 1.210e0;
        Console.WriteLine("");
        Console.Write(" {0}", "The test point is");
        for (j = 1; j <= n; j++)
        {
          Console.WriteLine(" " + " {0, 10:f4}", x[j - 1]);
        }
        Console.WriteLine(" ");
        //
        E04.e04hc(n, functE04HC, x, out f, g, out ifail);
        //
        Console.WriteLine("");
        if (ifail == 1)
        {
          Console.WriteLine(" {0}", "A parameter is outside its expected range");
        }
        else if (ifail >= 0)
        {
          if (ifail == 0)
          {
            Console.WriteLine(" {0}", "1st derivatives are consistent with function values");
          }
          else
          {
            Console.WriteLine(" {0}", "Probable error in calculation of 1st derivatives");
          }
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,12:e4}", "At the test point, FUNCT gives the function value", f);
          Console.WriteLine(" {0}", "and the 1st derivatives");
          for (j = 1; j <= n; j++)
          {
            Console.Write(" " + " {0, 12:e3}", g[j - 1]);
          }
          Console.WriteLine(" ");
        }
        else
        {
          if (ifail < 0)
          {
            Console.WriteLine("  {0}{1,3}{2}", "IFLAG was set to ", ifail, "in FUNCT");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
    //
    public static void funct(ref int iflag, int n, double[] xc, ref double fc,
    double[] gc)
    {
      //      Routine to evaluate objective function and its 1st derivatives.
      fc = 0.0;
      if (iflag != 1)
      {
        fc = ((xc[0] + 10.00e0 * xc[1])) * ((xc[0] + 10.00e0 * xc[1])) + 5.00e0 * ((xc[2] - xc[3])) * ((xc[2] - xc[3])) + Math.Pow((xc[1] - 2.00e0 * xc[2]), 4) + 10.00e0 * Math.Pow((xc[0] - xc[3]), 4);
      }
      if (iflag != 0)
      {
        gc[0] = 2.00e0 * (xc[0] + 10.00e0 * xc[1]) + 40.00e0 * Math.Pow((xc[0] - xc[3]), 3);
        gc[1] = 20.00e0 * (xc[0] + 10.00e0 * xc[1]) + 4.00e0 * Math.Pow((xc[1] - 2.00e0 * xc[2]), 3);
        gc[2] = 10.00e0 * (xc[2] - xc[3]) - 8.00e0 * Math.Pow((xc[1] - 2.00e0 * xc[2]), 3);
        gc[3] = 10.00e0 * (xc[3] - xc[2]) - 40.00e0 * Math.Pow((xc[0] - xc[3]), 3);
      }
    }
  }
}


e04hc Example Program Results

 The test point is      1.4600
     -0.8200
      0.5700
      1.2100

 1st derivatives are consistent with function values

  At the test point, FUNCT gives the function value 6.2273e+001
 and the 1st derivatives
   -1.286e+001   -1.649e+002    5.384e+001    5.775e+000


//      e04hd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04HDE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04HC_FUNCT functE04HC = new E04.E04HC_FUNCT(funct);
      E04.E04HD_FUNCT functE04HD = new E04.E04HD_FUNCT(funct);
      E04.E04HD_H hE04HD = new E04.E04HD_H(h);
      try
      {
        double f = 0.0;
        int i,  ifail,  j,  k;
        int n = 4;
        int lh = n * (n - 1) / 2;
        int lw = 5 * n;
        double[] g = new double[n];
        double[] hesd = new double[n];
        double[] hesl = new double[lh];
        double[] w = new double[lw];
        double[] x = new double[n];
        int[] iw = new int[1];
        Console.WriteLine("e04hd Example Program Results");
        //      Set up an arbitrary point at which to check the derivatives
        x[0] = 1.460e0;
        x[1] = -0.820e0;
        x[2] = 0.570e0;
        x[3] = 1.210e0;
        Console.WriteLine("");
        Console.WriteLine(" {0}", "The test point is");
        for (j = 1; j <= n; j++)
        {
          Console.Write(" " + " {0, 9:f4}", x[j - 1]);
        }
        Console.WriteLine(" ");
        //      Check the 1st derivatives
        //
        E04.e04hc(n, functE04HC, x, out f, g, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("");
          Console.WriteLine(" ** e04hc returned with ifail = {0, 3}", ifail);
          goto L40;
        }
        //
        //      Check the 2nd derivatives
        E04.e04hd(n, functE04HD, hE04HD, x, g, hesl, hesd, out ifail);
        //
        Console.WriteLine("");
        if (ifail == 1)
        {
          Console.WriteLine(" {0}", "A parameter is outside its expected range");
        }
        else if (ifail >= 0)
        {
          if (ifail == 0)
          {
            Console.WriteLine(" {0}", "2nd derivatives are consistent with 1st derivatives");
          }
          else if (ifail == 2)
          {
            Console.WriteLine(" {0}", "Probable error in calculation of 2nd derivatives");
          }
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,12:e4}", "At the test point, FUNCT gives the function value", f);
          Console.WriteLine(" {0}", "and the 1st derivatives");
          for (j = 1; j <= n; j++)
          {
            Console.Write(" " + " {0, 12:e3}", g[j - 1]);
          }
          Console.WriteLine(" ");
          Console.WriteLine("");
          Console.WriteLine(" {0}", "H gives the lower triangle of the Hessian matrix");
          Console.WriteLine("  {0,12:e3}", hesd[0]);
          k = 1;
          for (i = 2; i <= n; i++)
          {
            for (j = k; j <= k + i - 2; j++)
            {
              Console.Write(" " + " {0, 12:e3}", hesl[j - 1]);
            }
            Console.Write(" " + " {0, 12:e3}", hesd[i - 1]);
            Console.WriteLine(" ");
            k = k + i - 1;
          }
        }
        else
        {
          if (ifail < 0)
          {
            Console.WriteLine("  IFLAG was set to {0,5}in FUNCT or H", ifail);
          }
        }
        //
        L40: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
    //
    public static void funct(ref int iflag, int n, double[] xc, ref double fc,
    double[] gc)
    {
      //      Routine to evaluate objective function and its 1st derivatives.
      fc = ((xc[0] + 10.00e0 * xc[1])) * ((xc[0] + 10.00e0 * xc[1])) + 5.00e0 * ((xc[2] - xc[3])) * ((xc[2] - xc[3])) + Math.Pow((xc[1] - 2.00e0 * xc[2]), 4) + 10.00e0 * Math.Pow((xc[0] - xc[3]), 4);
      gc[0] = 2.00e0 * (xc[0] + 10.00e0 * xc[1]) + 40.00e0 * Math.Pow((xc[0] - xc[3]), 3);
      gc[1] = 20.00e0 * (xc[0] + 10.00e0 * xc[1]) + 4.00e0 * Math.Pow((xc[1] - 2.00e0 * xc[2]), 3);
      gc[2] = 10.00e0 * (xc[2] - xc[3]) - 8.00e0 * Math.Pow((xc[1] - 2.00e0 * xc[2]), 3);
      gc[3] = 10.00e0 * (xc[3] - xc[2]) - 40.00e0 * Math.Pow((xc[0] - xc[3]), 3);
    }
    //
    public static void h(ref int iflag, int n, double[] xc, double[] fhesl,
    double[] fhesd)
    {
      //      Routine to evaluate 2nd derivatives
      fhesd[0] = 2.00e0 + 120.00e0 * ((xc[0] - xc[3])) * ((xc[0] - xc[3]));
      fhesd[1] = 200.00e0 + 12.00e0 * ((xc[1] - 2.00e0 * xc[2])) * ((xc[1] - 2.00e0 * xc[2]));
      fhesd[2] = 10.00e0 + 48.00e0 * ((xc[1] - 2.00e0 * xc[2])) * ((xc[1] - 2.00e0 * xc[2]));
      fhesd[3] = 10.00e0 + 120.00e0 * ((xc[0] - xc[3])) * ((xc[0] - xc[3]));
      fhesl[0] = 20.00e0;
      fhesl[1] = 0.00e0;
      fhesl[2] = -24.00e0 * ((xc[1] - 2.00e0 * xc[2])) * ((xc[1] - 2.00e0 * xc[2]));
      fhesl[3] = -120.00e0 * ((xc[0] - xc[3])) * ((xc[0] - xc[3]));
      fhesl[4] = 0.00e0;
      fhesl[5] = -10.00e0;
    }
  }
}


e04hd Example Program Results

 The test point is
     1.4600    -0.8200     0.5700     1.2100

 2nd derivatives are consistent with 1st derivatives

  At the test point, FUNCT gives the function value 6.2273e+001
 and the 1st derivatives
   -1.286e+001   -1.649e+002    5.384e+001    5.775e+000

 H gives the lower triangle of the Hessian matrix
    9.500e+000
    2.000e+001    2.461e+002
    0.000e+000   -9.220e+001    1.944e+002
   -7.500e+000    0.000e+000   -1.000e+001    1.750e+001


//      e04he Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04HEE
  {
    static int m = 15;
    static int nt = 3;
    static double[,] t = new double[m, nt];
    static double[] y = new double[m];
    static string datafile = "ExampleData/e04hee.d";
    // as a command line argument. It defaults to the named file specified below otherwise.
    //
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04YA_LSQFUN lsqfunE04YA = new E04.E04YA_LSQFUN(lsqfun);
      E04.E04YB_LSQFUN lsqfunE04YB = new E04.E04YB_LSQFUN(lsqfun);
      E04.E04YB_LSQHES lsqhesE04YB = new E04.E04YB_LSQHES(lsqhes);
      E04.E04HE_LSQFUN lsqfunE04HE = new E04.E04HE_LSQFUN(lsqfun);
      E04.E04HE_LSQHES lsqhesE04HE = new E04.E04HE_LSQHES(lsqhes);
      E04.E04HE_LSQMON lsqmonE04HE = new E04.E04HE_LSQMON(lsqmon);
      try
      {
        DataReader sr = new DataReader(datafile);
      double eta,  fsumsq,  stepmx,  xtol;
      int i,  ifail,  iprint,  j,  maxcal,  nf,  niter;
      int n = 3;
      int ldfjac = m;
      int ldv = n;
      int lb = n * (n + 1) / 2;
      double[] b = new double[lb];
      double[,] fjac = new double[ldfjac, n];
      double[] fvec = new double[m];
      double[] g = new double[n];
      double[] s = new double[n];
      double[,] v = new double[ldv, n];
      double[] x = new double[n];
      Console.WriteLine("e04he Example Program Results");
      //      Skip heading in data file
      sr.Reset();
      //      Observations of tj (j = 1, 2, 3) are held in t[i-1, j-1]
      //      (i = 1, 2, . . . , 15)
      for (i = 1; i <= m; i++)
      {
        sr.Reset();
        y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        for (j = 1; j <= nt; j++)
        {
          t[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
      }
      //      Set up an arbitrary point at which to check the derivatives
      x[0] = 0.190e0;
      x[1] = -1.340e0;
      x[2] = 0.880e0;
      //      Check the 1st derivatives
      //
      E04.e04ya(m, n, lsqfunE04YA, x, fvec, fjac, out ifail);
      //
      if (ifail == 0)
      {
        //
        //         Check the evaluation of B
        E04.e04yb(m, n, lsqfunE04YB, lsqhesE04YB, x, fvec, fjac, b, out ifail);
        //
      }
      if (ifail != 0)
      {
        Console.WriteLine("");
        Console.WriteLine(" ** e04ya returned with ifail = {0, 3}", ifail);
        goto L40;
      }
      //
      //      Continue setting parameters for e04he
      //      Set iprint to 1 to obtain output from lsqmonE04HE at each iteration *
      iprint = -1;
      maxcal = 50 * n;
      eta = 0.90e0;
      xtol = 10.00e0 * Math.Sqrt(X02.x02aj());
      //      We estimate that the minimum will be within 10 units of the
      //      starting point
      stepmx = 10.00e0;
      //      Set up the starting point
      x[0] = 0.50e0;
      x[1] = 1.00e0;
      x[2] = 1.50e0;
      //
      E04.e04he(m, n, lsqfunE04HE, lsqhesE04HE, lsqmonE04HE, iprint, maxcal, eta, xtol,
      stepmx, x, out fsumsq, fvec, fjac, s, v, out niter, out nf, out ifail);
      //
      if (ifail >= 0)
      {
        if (ifail != 0)
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,3}{2}", "Error exit type", ifail, " - see method document");
        }
        if (ifail != 1)
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,12:f4}", "On exit, the sum of squares is", fsumsq);
          Console.Write(" " + " {0}", "at the point");
          for (j = 1; j <= n; j++)
          {
            Console.Write(" " + " {0, 12:f4}", x[j - 1]);
          }
          Console.WriteLine(" ");
          lsqgrd(m, n, fvec, fjac, g);
          Console.Write(" " + " {0}", "The corresponding gradient is");
          for (j = 1; j <= n; j++)
          {
            Console.Write(" " + " {0, 12:e3}", g[j - 1]);
          }
          Console.WriteLine(" ");
          Console.WriteLine(" {0}", "                           (machine dependent)");
          Console.WriteLine(" {0}\n", "and the residuals are");
          for (i = 1; i <= m; i++)
          {
            Console.WriteLine(" " + " {0, 9:e1}", fvec[i - 1]);
          }
          Console.WriteLine(" ");
        }
      }
      else
      {
        Console.WriteLine("");
        Console.WriteLine(" ** e04he returned with ifail = {0, 3}", ifail);
      }
      L40: ;
      //
    }
    catch (Exception e)
    {
      Console.WriteLine(e.Message);
      Console.WriteLine( "Exception Raised");
    }
  }
  //
  public static void lsqfun(ref int iflag, int m, int n, double[] xc, double[] fvec,
  double[,] fjac)
  {
    //      Routine to evaluate the residuals and their 1st derivatives
    double denom,  dummy;
    int i = 0;
    for (i = 1; i <= m; i++)
    {
      denom = xc[1] * t[i - 1, 1] + xc[2] * t[i - 1, 2];
      fvec[i - 1] = xc[0] + t[i - 1, 0] / denom - y[i - 1];
      fjac[i - 1, 0] = 1.00e0;
      dummy = -1.00e0 / (denom * denom);
      fjac[i - 1, 1] = t[i - 1, 0] * t[i - 1, 1] * dummy;
      fjac[i - 1, 2] = t[i - 1, 0] * t[i - 1, 2] * dummy;
    }
  }
  //
  public static void lsqhes(ref int iflag, int m, int n, double[] fvec, double[] xc,
  double[] b)
  {
    //      Routine to compute the lower triangle of the matrix B
    //      (stored by rows in the array B)
    double dummy,  sum22,  sum32,  sum33;
    int i = 0;
    b[0] = 0.00e0;
    b[1] = 0.00e0;
    sum22 = 0.00e0;
    sum32 = 0.00e0;
    sum33 = 0.00e0;
    for (i = 1; i <= m; i++)
    {
      dummy = 2.00e0 * t[i - 1, 0] / Math.Pow((xc[1] * t[i - 1, 1] + xc[2] * t[i - 1, 2]), 3);
      sum22 = sum22 + fvec[i - 1] * dummy * (t[i - 1, 1]) * (t[i - 1, 1]);
      sum32 = sum32 + fvec[i - 1] * dummy * t[i - 1, 1] * t[i - 1, 2];
      sum33 = sum33 + fvec[i - 1] * dummy * (t[i - 1, 2]) * (t[i - 1, 2]);
    }
    b[2] = sum22;
    b[3] = 0.00e0;
    b[4] = sum32;
    b[5] = sum33;
  }
  //
  public static void lsqmon(int m, int n, double[] xc, double[] fvec, double[,] fjac,
  double[] s, int igrade, int niter, int nf)
  {
    //      Monitoring method
    double fsumsq,  gtg;
    int j = 0;
    int ifail;
    double[] g = new double[3];
    fsumsq = F06.f06ea(m, fvec, 1, fvec, 1, out ifail);
    lsqgrd(m, n, fvec, fjac, g);
    gtg = F06.f06ea(n, g, 1, g, 1, out ifail);
    Console.WriteLine("");
    Console.WriteLine(" {0}", " Itns    F evals          SUMSQ             GTG        grade");
    Console.WriteLine("  {0,4}            {1,5}            {2,13:e5}            {3,9:e1}            {4,3}", niter, nf, fsumsq, gtg, igrade);
    Console.WriteLine("");
    Console.WriteLine(" {0}", "       x                    g           Singular values");
    for (j = 1; j <= n; j++)
    {
      Console.WriteLine("  {0,13:e5}                    {1,9:e1}                    {2,9:e1}", xc[j - 1], g[j - 1], s[j - 1]);
    }
    //
  }
  //
  public static void lsqgrd(int m, int n, double[] fvec, double[,] fjac, double[] g)
  {
    //      Routine to evaluate gradient of the sum of squares
    double sum = 0.0;
    int i,  j;
    for (j = 1; j <= n; j++)
    {
      sum = 0.00e0;
      for (i = 1; i <= m; i++)
      {
        sum = sum + fjac[i - 1, j - 1] * fvec[i - 1];
      }
      g[j - 1] = sum + sum;
    }
  }
}
}


//      e04hy Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04HYE
  {
    static int m = 15;
    static int nt = 3;
    static double[] ruser = new double[m + m * nt];
    static int[] iuser = new int[1];
    static string datafile = "ExampleData/e04hye.d";
    // as a command line argument. It defaults to the named file specified below otherwise.
    //
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04HY_LSFUN2 lsfun3E04HY = new E04.E04HY_LSFUN2(lsfun3);
      E04.E04HY_LSHES2 lshes3E04HY = new E04.E04HY_LSHES2(lshes3);
      try
      {
        DataReader sr = new DataReader(datafile);
      double fsumsq = 0.0;
      int i,  ifail,  j,  k;
      int n = 3;
      int lw = 8 * n + 2 * n * n + 2 * m * n + 3 * m;
      double[,] t = new double[m, nt];
      double[] w = new double[lw];
      double[] x = new double[n];
      double[] y = new double[m];
      Console.WriteLine("e04hy Example Program Results");
      //      Skip heading in data file
      sr.Reset();
      //
      //      Observations of tj (j = 1, 2, 3) are held in t(i-1, j-1]
      //      (i = 1, 2, . . . , 15)
      //
      iuser[0] = nt;
      k = m;
      for (i = 1; i <= m; i++)
      {
        sr.Reset();
        y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        for (j = 1; j <= nt; j++)
        {
          t[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        ruser[i - 1] = y[i - 1];
        for (j = 1; j <= nt; j++)
        {
          ruser[k + j - 1] = t[i - 1, j - 1];
        }
        k = k + nt;
      }
      //
      x[0] = 0.50e0;
      x[1] = 1.00e0;
      x[2] = 1.50e0;
      //
      E04.e04hy(m, n, lsfun3E04HY, lshes3E04HY, x, out fsumsq, out ifail);
      //
      if (ifail < 0)
      {
        Console.WriteLine("");
        Console.WriteLine(" ** e04hy returned with ifail = {0, 3}", ifail);
      }
      else
      {
        if (ifail != 0)
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,3}{2}", "Error exit type", ifail, " - see method document");
        }
        if ((ifail != 1) && (ifail != 9))
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,12:f4}", "On exit, the sum of squares is", fsumsq);
          Console.Write(" " + " {0}", "at the point");
          for (j = 1; j <= n; j++)
          {
            Console.Write(" " + " {0, 12:f4}", x[j - 1]);
          }
          Console.WriteLine(" ");
        }
      }
      //
    }
    catch (Exception e)
    {
      Console.WriteLine(e.Message);
      Console.WriteLine( "Exception Raised");
    }
  }
  //
  public static void lsfun3(int m, int n, double[] xc, double[] fvec, double[,
  ] fjac)
  {
    //      Routine to evaluate the residuals and their 1st derivatives.
    double denom,  dummy;
    int i,  k;
    k = m;
    for (i = 1; i <= m; i++)
    {
      denom = xc[1] * ruser[k + 2 - 1] + xc[2] * ruser[k + 3 - 1];
      fvec[i - 1] = xc[0] + ruser[k + 1 - 1] / denom - ruser[i - 1];
      fjac[i - 1, 0] = 1.00e0;
      dummy = -1.00e0 / (denom * denom);
      fjac[i - 1, 1] = ruser[k + 1 - 1] * ruser[k + 2 - 1] * dummy;
      fjac[i - 1, 2] = ruser[k + 1 - 1] * ruser[k + 3 - 1] * dummy;
      k = k + iuser[0];
    }
  }
  //
  public static void lshes3(int m, int n, double[] fvec, double[] xc, double[] b)
  {
    //      Routine to compute the lower triangle of the matrix B
    //      (stored by rows in the array B).
    double dummy,  sum22,  sum32,  sum33;
    int i,  k;
    b[0] = 0.00e0;
    b[1] = 0.00e0;
    sum22 = 0.00e0;
    sum32 = 0.00e0;
    sum33 = 0.00e0;
    k = m;
    for (i = 1; i <= m; i++)
    {
      dummy = 2.00e0 * ruser[k + 1 - 1] / Math.Pow((xc[1] * ruser[k + 2 - 1] + xc[2] * ruser[k + 3 - 1]), 3);
      sum22 = sum22 + fvec[i - 1] * dummy * (ruser[k + 2 - 1]) * (ruser[k + 2 - 1]);
      sum32 = sum32 + fvec[i - 1] * dummy * ruser[k + 2 - 1] * ruser[k + 3 - 1];
      sum33 = sum33 + fvec[i - 1] * dummy * (ruser[k + 3 - 1]) * (ruser[k + 3 - 1]);
      k = k + iuser[0];
    }
    b[2] = sum22;
    b[3] = 0.00e0;
    b[4] = sum32;
    b[5] = sum33;
  }
}
}


e04hy Example Program Results

  On exit, the sum of squares is      0.0082
  at the point        0.0824        1.1330        2.3437


//      e04jc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{

    public class E04JCE
    {

        public static int Main(string[] args)
        {
            StartExample();
            return 0;
        }

        public static void StartExample()
        {

            E04.E04JC_OBJFUN objfunE04JC = new E04.E04JC_OBJFUN(objfun);
            E04.E04JC_MONFUN e04jcpE04JC = new E04.E04JC_MONFUN(E04.e04jcp);
            try
            {

                double f,
                infbnd,
                rhobeg,
                rhoend;
                int ifail = 0,
                maxcal = 0,
                n = 0,
                nf = 0,
                npt = 0;

                Console.WriteLine(" {0}", "E04JC Example Program Results");
                maxcal = 500;
                rhobeg = 1.0e-1;
                rhoend = 1.0E-6;
                n = 4;
                npt = 2 * n + 1;
                infbnd = Math.Pow(X02.x02al(), 0.25);

                /*
                      x[2] is unconstrained, so we're going to set bl[2]) to a large
                      negative number and bu[2] to a large positive number.
                */

                double[] bl = { 1.0, -2.0, -infbnd, 1.0 };
                double[] bu = { 3.0, 0.0, infbnd, 3.0 };
                double[] x = { 3.0, -1.0, 0.0, 1.0 };

                /*
                      use monfun  and pass this to e04jc instead
                      of e04jcp to enable monitoring output
                */

                E04.e04jc(objfunE04JC, n, npt, x, bl, bu, rhobeg, rhoend, e04jcpE04JC, maxcal, out f, out nf, out ifail);

                if (ifail == 0)
                {
                    Console.WriteLine("Successful exit from e04jc.\nFunction value at lowest point found = {0}", f);
                }
                else
                {
                    Console.WriteLine("On exit from  e04jc, function value at lowest point found = {0}", f);
                }
                Console.WriteLine("The corresponding X is:");
                for (int i = 0 ; i < x.Length; i++)
                {
                    Console.WriteLine(x[i]);
                }
                return ;
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
                Console.WriteLine("Exception Raised");
            }
        }

        public static void objfun(int n, double[] x, out double f, out int inform)
        {
            inform = 0;

            f = Math.Pow((x[0] + 10.0 * x[1]), 2) +
                5.0 * Math.Pow(x[2] - x[3], 2) +
                Math.Pow(x[1] - 2.0 * x[2], 4) +
                10.0 * Math.Pow(x[0] - x[3], 4);

        }

        public static void monfun(int n, int nf, double[] x, double f, double rho, out int inform)
        {
            inform = 0;
            Console.WriteLine("");
            Console.WriteLine("New rho: {0}, number of evaluations: {1}", rho, nf);
            Console.WriteLine("Current function value = {0}", f);
            Console.WriteLine("The corresponding x is");
            foreach (int i in x)
            {
                Console.WriteLine(x[i]);
            }

        }
    }
}


 E04JC Example Program Results
Successful exit from e04jc.
Function value at lowest point found = 2.43378751212073
The corresponding X is:
1
-0.0852325910072734
0.409303585899442
1


//      e04jy Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04JYE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04JY_FUNCT1 funct1E04JY = new E04.E04JY_FUNCT1(funct1);
      try
      {
        double f = 0.0;
        double phm;
        int ibound,  ifail,  j;
        int n = 4;
        double[] bl = new double[n];
        double[] bu = new double[n];
        double[] fdiff = new double[n];
        double[] x = new double[n];
        int[] bndinfo = new int[n];
        int freevar;
        Console.WriteLine("e04jy Example Program Results");
        x[0] = 3.00e0;
        x[1] = -1.00e0;
        x[2] = 0.00e0;
        x[3] = 1.00e0;
        ibound = 0;
        bl[0] = 1.00e0;
        bu[0] = 3.00e0;
        bl[1] = -2.00e0;
        bu[1] = 0.00e0;
        //
        //      x[2] is unconstrained, so we set bl[2] to a large negative
        //      number and bu[2] to a large positive number.
        //
        bl[2] = -1.00e6;
        bu[2] = 1.00e6;
        bl[3] = 1.00e0;
        bu[3] = 3.00e0;
        int nftotl;
        //
        E04.e04jy(n, ibound, funct1E04JY, bl, bu, x, out f, out nftotl, bndinfo, out freevar,
                  fdiff, out phm, out ifail);
        //
        if (ifail == 0 || ifail == 3 || ifail >= 5 )
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,8:f4}", "Function value on exit is ", f);
          Console.Write(" " + " {0}", "at the point");
          for (j = 1; j <= n; j++)
          {
            Console.Write(" " + " {0, 9:f4}", x[j - 1]);
          }
          Console.WriteLine(" ");
        }
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
    //
    public static void funct1(int n, double[] xc, out double fc)
    {
      //      Routine to evaluate objective function.
      double x1,  x2,  x3,  x4;
      x1 = xc[0];
      x2 = xc[1];
      x3 = xc[2];
      x4 = xc[3];
      fc = ((x1 + 10.00e0 * x2)) * ((x1 + 10.00e0 * x2)) + 5.00e0 * ((x3 - x4)) * ((x3 - x4)) + Math.Pow((x2 - 2.00e0 * x3), 4) + 10.00e0 * Math.Pow((x1 - x4), 4);
    }
  }
}


e04jy Example Program Results

  Message
It is probable that a local minimum has been found,
but it cannot be guaranteed.
    Call to    e04jy returned with ifail = 5

  Function value on exit is   2.4338
  at the point     1.0000    -0.0852     0.4093     1.0000


//      e04kd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04KDE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04HC_FUNCT functE04HC = new E04.E04HC_FUNCT(funct);
      E04.E04KD_FUNCT functE04KD = new E04.E04KD_FUNCT(funct);
      E04.E04KD_MONIT monitE04KD = new E04.E04KD_MONIT(monit);
      try
      {
        double delta,  eta,  f,  stepmx,  xtol;
        int ibound,  ifail,  iprint,  j,  maxcal;
        int n = 4;
        int lh = n * (n - 1) / 2;
        int lw = 7 * n + n * (n - 1) / 2;
        int liw = 2;
        double[] bl = new double[n];
        double[] bu = new double[n];
        double[] g = new double[n];
        double[] hesd = new double[n];
        double[] hesl = new double[lh];
        double[] w = new double[lw];
        double[] x = new double[n];
        int[] istate = new int[n];
        int[] iw = new int[liw];
        Console.Out.Flush();
        Console.WriteLine("e04kd Example Program Results");
        //      Check functE04HC by calling e04hc at an arbitrary point. Since e04hc
        //      only checks the derivatives calculated when iflag = 2, a separate
        //      program should be run before using e04hc or e04kd to check that
        //      functE04HC gives the same values for the gc[j-1] when iflag is set to 1
        //      as when iflag is set to 2.
        x[0] = 1.460e0;
        x[1] = -0.820e0;
        x[2] = 0.570e0;
        x[3] = 1.210e0;
        //
        E04.e04hc(n, functE04HC, x, out f, g, out ifail);
        //
        if (ifail != 0)
        {
          Console.WriteLine("");
          Console.WriteLine(" ** e04hc returned with ifail = {0, 3}", ifail);
          return;
        }
        //
        //      Continue setting parameters for e04kd
        //      Set iprint to 1 to obtain output from monitE04KD at each iteration *
        iprint = -1;
        maxcal = 50 * n;
        eta = 0.50e0;
        //      Set xtol and delta to zero so that e04kd  will use the default
        //      values
        xtol = 0.00e0;
        delta = 0.00e0;
        //      We estimate that the minimum will be within 4 units of the
        //      starting point
        stepmx = 4.00e0;
        ibound = 0;
        bl[0] = 1.00e0;
        bu[0] = 3.00e0;
        bl[1] = -2.00e0;
        bu[1] = 0.00e0;
        //      x[2] is not bounded, so we set bl[2] to a large negative
        //      number and bu[2] to a large positive number
        bl[2] = -1.00e6;
        bu[2] = 1.00e6;
        bl[3] = 1.00e0;
        bu[3] = 3.00e0;
        //      Set up starting point
        x[0] = 3.00e0;
        x[1] = -1.00e0;
        x[2] = 0.00e0;
        x[3] = 1.00e0;
        //
        E04.e04kd(n, functE04KD, monitE04KD, iprint, maxcal, eta, xtol, delta, stepmx, ibound,
        bl, bu, x, hesl, hesd, istate, out f, g, out ifail);
        Console.Out.Flush();
        //
             if (ifail == 0 || ifail == 3 || ifail == 5)
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,12:f4}", "Function value on exit is ", f);
          Console.Write(" " + " {0}", "at the point");
          for (j = 1; j <= n; j++)
          {
            Console.Write(" " + " {0, 12:f4}", x[j - 1]);
          }
          Console.WriteLine(" ");
          Console.WriteLine(" {0}", "The corresponding (machine dependent) gradient is");
          for (j = 1; j <= n; j++)
          {
            Console.Write(" " + " {0, 12:e3}", g[j - 1]);
          }
          Console.WriteLine(" ");
          Console.Write(" " + " {0}", "istate contains");
          for (j = 1; j <= n; j++)
          {
            Console.Write(" " + " {0, 5}", istate[j - 1]);
          }
          Console.WriteLine(" ");
          Console.Write(" " + " {0}", "and hesd contains");
          for (j = 1; j <= n; j++)
          {
            Console.Write(" " + " {0, 12:e4}", hesd[j - 1]);
          }
          Console.WriteLine(" ");
        }
      }
      //
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    //
    public static void funct(ref int iflag, int n, double[] xc, ref double fc,
    double[] gc)
    {
      //      Routine to evaluate objective function and its 1st derivatives.
      if (iflag != 1)
      {
        fc = ((xc[0] + 10.00e0 * xc[1])) * ((xc[0] + 10.00e0 * xc[1]))
        + 5.00e0 * ((xc[2] - xc[3])) * ((xc[2] - xc[3])) +
        Math.Pow((xc[1] - 2.00e0 * xc[2]), 4) + 10.00e0 * Math.Pow((xc[0] - xc[3]), 4);
      }
      gc[0] = 2.00e0 * (xc[0] + 10.00e0 * xc[1]) + 40.00e0 * Math.Pow((xc[0] - xc[3]), 3);
      gc[1] = 20.00e0 * (xc[0] + 10.00e0 * xc[1]) + 4.00e0 * Math.Pow((xc[1] - 2.00e0 * xc[2]), 3);
      gc[2] = 10.00e0 * (xc[2] - xc[3]) - 8.00e0 * Math.Pow((xc[1] - 2.00e0 * xc[2]), 3);
      gc[3] = 10.00e0 * (xc[3] - xc[2]) - 40.00e0 * Math.Pow((xc[0] - xc[3]), 3);
    }
    //
    public static void monit(int n, double[] xc, double fc, double[] gc, int[] istate,
    double gpjnrm,  double cond,  bool posdef,  int niter,  int nf)
    {
      //  Monitoring method
      int isj,  j;
      Console.WriteLine("");
      Console.WriteLine(" {0}", " Itn     Fn evals              Fn value            Norm of proj gradient");
      Console.WriteLine("  {0,3}            {1,5}            {2,20:e4}            {3,20:e4}", niter, nf, fc, gpjnrm);
      Console.WriteLine("");
      Console.WriteLine(" {0}", " J           x[J-1]                g[J-1]           Status");
      for (j = 1; j <= n; j++)
      {
        isj = istate[j - 1];
        if (isj > 0)
        {
          Console.WriteLine("  {0,2}  {1,20:e4}{2,20:e4}{3}", j, xc[j - 1], gc[j - 1], "    Free");
        }
        else if (isj == -1)
        {
          Console.WriteLine("  {0,2}  {1,20:e4}{2,20:e4}{3}", j, xc[j - 1], gc[j - 1], "    Upper Bound");
        }
        else if (isj == -2)
        {
          Console.WriteLine("  {0,2}  {1,20:e4}{2,20:e4}{3}", j, xc[j - 1], gc[j - 1], "    Lower Bound");
        }
        else if (isj == -3)
        {
          Console.WriteLine("  {0,2}  {1,20:e4}{2,20:e4}{3}", j, xc[j - 1], gc[j - 1], "    ant");
        }
      }
      if (cond != 0.00e0)
      {
        if (cond > 1.00e6)
        {
          Console.WriteLine("");
          Console.WriteLine(" {0}", "Estimated condition number of projected Hessian is more than 1.0E+6");
        }
        else
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,10:e2}", "Estimated condition number of projected Hessian = ", cond);
        }
        if (!(posdef))
        {
          //            The following statement is included so that this monit
          //            can be used in conjunction with either of the method
          //            E04.e04kd or  E04.e04lb
          Console.WriteLine("");
          Console.WriteLine(" {0}", "Projected Hessian matrix is not positive definite");
        }
      }
      //
    }
  }
}


e04kd Example Program Results

  Message
The conditions for a minimum have not all been satisfied,
but a lower point could not be found.
    Call to    e04kd returned with ifail = 3

  Function value on exit is       2.4338
  at the point        1.0000       -0.0852        0.4093        1.0000
 The corresponding (machine dependent) gradient is
    2.953e-001   -5.868e-010    1.177e-009    5.907e+000
  istate contains     -2      1      2     -2
  and hesd contains   2.0980e+002   4.7380e+001   4.5518e+001   0.0000e+000


//      e04ky Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04KYE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04KY_FUNCT2 funct2E04KY = new E04.E04KY_FUNCT2(funct2);
      try
      {
        double f = 0.0;
        int ibound,  ifail,  j;
        int n = 4;
        int liw = n + 2;
        int lw = 10 * n + n * (n - 1) / 2;
        double[] bl = new double[n];
        double[] bu = new double[n];
        double[] g = new double[n];
        double[] ruser = new double[1];
        double[] w = new double[lw];
        double[] x = new double[n];
        int[] iuser = new int[1];
        int[] iw = new int[liw];
        Console.WriteLine("e04ky Example Program Results");
        x[0] = 3.00e0;
        x[1] = -1.00e0;
        x[2] = 0.00e0;
        x[3] = 1.00e0;
        ibound = 0;
        bl[0] = 1.00e0;
        bu[0] = 3.00e0;
        bl[1] = -2.00e0;
        bu[1] = 0.00e0;
        //
        //      x[2] is unconstrained, so we set bl[2] to a large negative
        //      number and bu[2] to a large positive number.
        //
        bl[2] = -1.00e6;
        bu[2] = 1.00e6;
        bl[3] = 1.00e0;
        bu[3] = 3.00e0;
        //
        E04.e04ky(n, ibound, funct2E04KY, bl, bu, x, out f, g, iw, w, out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine("");
          Console.WriteLine(" ** e04ky returned with ifail = {0, 3}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,3}{2}", "Error exit type", ifail, " - see method document");
          }
          if (ifail != 1)
          {
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,9:f4}", "Function value on exit is ", f);
            Console.Write(" " + " {0}", "at the point");
            for (j = 1; j <= n; j++)
            {
              Console.Write(" " + " {0, 9:f4}", x[j - 1]);
            }
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "The corresponding (machine dependent) gradient is");
            for (j = 1; j <= n; j++)
            {
              Console.Write(" " + " {0, 12:e4}", g[j - 1]);
            }
            Console.WriteLine(" ");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
    //
    public static void funct2(int n, double[] xc, out double fc, double[] gc)
    {
      //      Routine to evaluate objective function and its 1st derivatives.
      double x1,  x2,  x3,  x4;
      x1 = xc[0];
      x2 = xc[1];
      x3 = xc[2];
      x4 = xc[3];
      fc = ((x1 + 10.00e0 * x2)) * ((x1 + 10.00e0 * x2)) + 5.00e0 * ((x3 - x4)) * ((x3 - x4)) + Math.Pow((x2 - 2.00e0 * x3), 4) + 10.00e0 * Math.Pow((x1 - x4), 4);
      gc[0] = 2.00e0 * (x1 + 10.00e0 * x2) + 40.00e0 * Math.Pow((x1 - x4), 3);
      gc[1] = 20.00e0 * (x1 + 10.00e0 * x2) + 4.00e0 * Math.Pow((x2 - 2.00e0 * x3), 3);
      gc[2] = 10.00e0 * (x3 - x4) - 8.00e0 * Math.Pow((x2 - 2.00e0 * x3), 3);
      gc[3] = -10.00e0 * (x3 - x4) - 40.00e0 * Math.Pow((x1 - x4), 3);
    }
  }
}


e04ky Example Program Results

  Function value on exit is    2.4338
  at the point     1.0000    -0.0852     0.4093     1.0000
 The corresponding (machine dependent) gradient is
   2.9535e-001   3.0225e-009  -1.2365e-008   5.9070e+000


//      e04kz Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04KZE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04KZ_FUNCT2 funct2E04KZ = new E04.E04KZ_FUNCT2(funct2);
      try
      {
        double f = 0.0;
        int ibound,  ifail,  j;
        int n = 4;
        int liw = n + 2;
        int lw = n * (n + 7);
        double[] bl = new double[n];
        double[] bu = new double[n];
        double[] g = new double[n];
        double[] ruser = new double[1];
        double[] w = new double[lw];
        double[] x = new double[n];
        int[] iuser = new int[1];
        int[] iw = new int[liw];
        Console.WriteLine("e04kz Example Program Results");
        x[0] = 3.00e0;
        x[1] = -1.00e0;
        x[2] = 0.00e0;
        x[3] = 1.00e0;
        ibound = 0;
        bl[0] = 1.00e0;
        bu[0] = 3.00e0;
        bl[1] = -2.00e0;
        bu[1] = 0.00e0;
        //
        //      x[2] is unconstrained, so we set bl[2] to a large negative
        //      number and bu[2] to a large positive number.
        //
        bl[2] = -1.00e6;
        bu[2] = 1.00e6;
        bl[3] = 1.00e0;
        bu[3] = 3.00e0;
        //
        E04.e04kz(n, ibound, funct2E04KZ, bl, bu, x, out f, g, out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine("");
          Console.WriteLine(" ** e04kz returned with ifail = {0, 3}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,3}{2}", "Error exit type", ifail, " - see method document");
          }
          if (ifail != 1)
          {
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,12:f4}", "Function value on exit is ", f);
            Console.Write(" " + " {0}", "at the point");
            for (j = 1; j <= n; j++)
            {
              Console.Write(" " + " {0, 12:f4}", x[j - 1]);
            }
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "the corresponding (machine dependent) gradient is");
            for (j = 1; j <= n; j++)
            {
              Console.Write(" " + " {0, 12:e4}", g[j - 1]);
            }
            Console.WriteLine(" ");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
    //
    public static void funct2(int n, double[] xc, out double fc, double[] gc)
    {
      //      Routine to evaluate objective function and its 1st derivatives.
      double x1,  x2,  x3,  x4;
      x1 = xc[0];
      x2 = xc[1];
      x3 = xc[2];
      x4 = xc[3];
      fc = ((x1 + 10.00e0 * x2)) * ((x1 + 10.00e0 * x2)) + 5.00e0 * ((x3 - x4)) * ((x3 - x4)) + Math.Pow((x2 - 2.00e0 * x3), 4) + 10.00e0 * Math.Pow((x1 - x4), 4);
      gc[0] = 2.00e0 * (x1 + 10.00e0 * x2) + 40.00e0 * Math.Pow((x1 - x4), 3);
      gc[1] = 20.00e0 * (x1 + 10.00e0 * x2) + 4.00e0 * Math.Pow((x2 - 2.00e0 * x3), 3);
      gc[2] = 10.00e0 * (x3 - x4) - 8.00e0 * Math.Pow((x2 - 2.00e0 * x3), 3);
      gc[3] = -10.00e0 * (x3 - x4) - 40.00e0 * Math.Pow((x1 - x4), 3);
    }
  }
}


e04kz Example Program Results

  Message
It is probable that a local minimum has been found,
but it cannot be guaranteed.
    Call to    e04kz returned with ifail = 5

  Error exit type  5 - see method document

  Function value on exit is       2.4338
  at the point        1.0000       -0.0852        0.4093        1.0000
 the corresponding (machine dependent) gradient is
   2.9535e-001  -5.8684e-010   1.1769e-009   5.9070e+000


//      e04lb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04LBE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04HC_FUNCT functE04HC = new E04.E04HC_FUNCT(funct);
      E04.E04HD_FUNCT functE04HD = new E04.E04HD_FUNCT(funct);
      E04.E04HD_H hE04HD = new E04.E04HD_H(h);
      E04.E04LB_FUNCT functE04LB = new E04.E04LB_FUNCT(funct);
      E04.E04LB_H hE04LB = new E04.E04LB_H(h);
      E04.E04LB_MONIT monitE04LB = new E04.E04LB_MONIT(monit);
      try
      {
        double eta,  f,  stepmx,  xtol;
        int ibound,  ifail,  iprint,  j,  maxcal,  nz;
        int n = 4;
        int lh = n * (n - 1) / 2;
        int liw = 2;
        int lw = 7 * n + n * (n - 1) / 2;
        double[] bl = new double[n];
        double[] bu = new double[n];
        double[] g = new double[n];
        double[] hesd = new double[n];
        double[] hesl = new double[lh];
        double[] w = new double[lw];
        double[] x = new double[n];
        int[] istate = new int[n];
        int[] iw = new int[liw];
        Console.WriteLine("e04lb Example Program Results");
        //      Set up an arbitrary point at which to check the derivatives
        x[0] = 1.460e0;
        x[1] = -0.820e0;
        x[2] = 0.570e0;
        x[3] = 1.210e0;
        //      Check the 1st derivatives
        E04.e04hc(n, functE04HC, x, out f, g, out ifail);
        //
        if (ifail == 0)
        {
          //
          //         Check the 2nd derivatives
          E04.e04hd(n, functE04HD, hE04HD, x, g, hesl, hesd, out ifail);
        }
        if (ifail != 0)
        {
          Console.WriteLine("");
          Console.WriteLine(" ** e04hc returned with ifail = {0, 3}", ifail);
          goto L40;
        }
        //
        //      Continue setting parameters for e04lb
        //      set iprint to 1 to obtain output from monit at each iteration *
        iprint = -1;
        maxcal = 50 * n;
        eta = 0.90e0;
        //      Set xtol to zero so that e04lb will use the default tolerance
        xtol = 0.00e0;
        //      We estimate that the minimum will be within 4 units of the
        //      starting point
        stepmx = 4.00e0;
        ibound = 0;
        bl[0] = 1.00e0;
        bu[0] = 3.00e0;
        bl[1] = -2.00e0;
        bu[1] = 0.00e0;
        //      x[2] is not bounded, so we set bl[2] to a large negative
        //      number and bu[2] to a large positive number
        bl[2] = -1.00e6;
        bu[2] = 1.00e6;
        bl[3] = 1.00e0;
        bu[3] = 3.00e0;
        //      Set up starting point
        x[0] = 3.00e0;
        x[1] = -1.00e0;
        x[2] = 0.00e0;
        x[3] = 1.00e0;
        //
        E04.e04lb(n, functE04LB, hE04LB, monitE04LB, iprint, maxcal, eta, xtol, stepmx,
        ibound, bl, bu, x, hesl, hesd, istate, out f, g, out ifail);
        //
        if (ifail >= 0)
        {
          if (ifail != 0)
          {
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,3}{2}", "Error exit type", ifail, " - see method document");
          }
          if (ifail != 1)
          {
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,9:f4}", "Function value on exit is ", f);
            Console.Write(" " + " {0}", "at the point");
            for (j = 1; j <= n; j++)
            {
              Console.Write(" " + " {0, 9:f4}", x[j - 1]);
            }
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "The corresponding (machine dependent) gradient is");
            for (j = 1; j <= n; j++)
            {
              Console.Write(" " + " {0, 12:e3}", g[j - 1]);
            }
            Console.WriteLine(" ");
            Console.Write(" " + " {0}", "ISTATE contains");
            for (j = 1; j <= n; j++)
            {
              Console.Write(" " + " {0, 5}", istate[j - 1]);
            }
            Console.WriteLine(" ");
            nz = 0;
            for (j = 1; j <= n; j++)
            {
              if (istate[j - 1] > 0)
              {
                nz = nz + 1;
              }
            }
            Console.Write(" " + " {0}", "and HESD contains");
            for (j = 1; j <= nz; j++)
            {
              Console.Write(" " + " {0, 12:e4}", hesd[j - 1]);
            }
            Console.WriteLine(" ");
          }
        }
        else
        {
          Console.WriteLine("");
          Console.WriteLine(" ** e04lb returned with ifail = {0, 3}", ifail);
        }
        L40: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
    //
    public static void funct(ref int iflag, int n, double[] xc, ref double fc,
    double[] gc)
    {
      //      Routine to evaluate objective function and its 1st derivatives.
      fc = ((xc[0] + 10.00e0 * xc[1])) * ((xc[0] + 10.00e0 * xc[1])) + 5.00e0 * ((xc[2] - xc[3])) * ((xc[2] - xc[3])) + Math.Pow((xc[1] - 2.00e0 * xc[2]), 4) + 10.00e0 * Math.Pow((xc[0] - xc[3]), 4);
      gc[0] = 2.00e0 * (xc[0] + 10.00e0 * xc[1]) + 40.00e0 * Math.Pow((xc[0] - xc[3]), 3);
      gc[1] = 20.00e0 * (xc[0] + 10.00e0 * xc[1]) + 4.00e0 * Math.Pow((xc[1] - 2.00e0 * xc[2]), 3);
      gc[2] = 10.00e0 * (xc[2] - xc[3]) - 8.00e0 * Math.Pow((xc[1] - 2.00e0 * xc[2]), 3);
      gc[3] = 10.00e0 * (xc[3] - xc[2]) - 40.00e0 * Math.Pow((xc[0] - xc[3]), 3);
    }
    //
    public static void h(ref int iflag, int n, double[] xc, double[] fhesl,
    double[] fhesd)
    {
      //      Routine to evaluate 2nd derivatives
      fhesd[0] = 2.00e0 + 120.00e0 * ((xc[0] - xc[3])) * ((xc[0] - xc[3]));
      fhesd[1] = 200.00e0 + 12.00e0 * ((xc[1] - 2.00e0 * xc[2])) * ((xc[1] - 2.00e0 * xc[2]));
      fhesd[2] = 10.00e0 + 48.00e0 * ((xc[1] - 2.00e0 * xc[2])) * ((xc[1] - 2.00e0 * xc[2]));
      fhesd[3] = 10.00e0 + 120.00e0 * ((xc[0] - xc[3])) * ((xc[0] - xc[3]));
      fhesl[0] = 20.00e0;
      fhesl[1] = 0.00e0;
      fhesl[2] = -24.00e0 * ((xc[1] - 2.00e0 * xc[2])) * ((xc[1] - 2.00e0 * xc[2]));
      fhesl[3] = -120.00e0 * ((xc[0] - xc[3])) * ((xc[0] - xc[3]));
      fhesl[4] = 0.00e0;
      fhesl[5] = -10.00e0;
    }
    //
    public static void monit(int n, double[] xc, double fc, double[] gc, int[] istate,
    double gpjnrm,  double cond,  bool posdef,  int niter,  int nf)
    {
      //      Monitoring method
      int isj,  j;
      Console.WriteLine("");
      Console.WriteLine(" {0}", " Itn     Fn evals              Fn value            Norm of proj gradient");
      Console.WriteLine("  {0,3}            {1,5}            {2,20:e4}            {3,20:e4}", niter, nf, fc, gpjnrm);
      Console.WriteLine("");
      Console.WriteLine(" {0}", " J           X(J)                G(J)           Status");
      Console.WriteLine("");
      Console.WriteLine(" {0}", " Itn     Fn evals              Fn value            Norm of proj gradient");
      Console.WriteLine("  {0,3}            {1,5}            {2,20:e4}            {3,20:e4}", niter, nf, fc, gpjnrm);
      Console.WriteLine("");
      Console.WriteLine(" {0}", " J           X(J)                G(J)           Status");
      for (j = 1; j <= n; j++)
      {
        isj = istate[j - 1];
        if (isj > 0)
        {
          Console.WriteLine("  {0,2}  {1,20:e4}{2,20:e4}{3}", j, xc[j - 1], gc[j - 1], "    Free");
          Console.WriteLine("  {0,2}  {1,20:e4}{2,20:e4}{3}", j, xc[j - 1], gc[j - 1], "    Free");
        }
        else if (isj == -1)
        {
          Console.WriteLine("  {0,2}  {1,20:e4}{2,20:e4}{3}", j, xc[j - 1], gc[j - 1], "    Upper Bound");
          Console.WriteLine("  {0,2}  {1,20:e4}{2,20:e4}{3}", j, xc[j - 1], gc[j - 1], "    Upper Bound");
        }
        else if (isj == -2)
        {
          Console.WriteLine("  {0,2}  {1,20:e4}{2,20:e4}{3}", j, xc[j - 1], gc[j - 1], "    Lower Bound");
          Console.WriteLine("  {0,2}  {1,20:e4}{2,20:e4}{3}", j, xc[j - 1], gc[j - 1], "    Lower Bound");
        }
        else if (isj == -3)
        {
          Console.WriteLine("  {0,2}  {1,20:e4}{2,20:e4}{3}", j, xc[j - 1], gc[j - 1], "    ant");
        }
      }
      if (cond != 0.00e0)
      {
        if (cond > 1.00e6)
        {
          Console.WriteLine("");
          Console.WriteLine(" {0}", "Estimated condition number of projected Hessian is more than 1.0E+6");
        }
        else
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,10:e2}", "Estimated condition number of projected Hessian = ", cond);
        }
        if (!(posdef))
        {
          //            The following statement is included so that this monit
          //            can also be used in conjunction with e04kd
          Console.WriteLine("");
          Console.WriteLine(" {0}", "Projected Hessian matrix is not positive definite");
        }
      }
      //
    }
  }
}


e04lb Example Program Results

  Message
The conditions for a minimum have not all been satisfied,
but a lower point could not be found.
    Call to    e04lb returned with ifail = 3

  Error exit type  3 - see method document

  Function value on exit is    2.4338
  at the point     1.0000    -0.0852     0.4093     1.0000
 The corresponding (machine dependent) gradient is
    2.953e-001   -5.867e-010    1.173e-009    5.907e+000
  ISTATE contains     -2      1      2     -2
  and HESD contains   2.0980e+002   4.7380e+001


//      e04ly Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04LYE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04LY_FUNCT2 funct2E04LY = new E04.E04LY_FUNCT2(funct2);
      E04.E04LY_HESS2 hess2E04LY = new E04.E04LY_HESS2(hess2);
      try
      {
        double f = 0.0;
        int ibound,  ifail,  j;
        int n = 4;
        int liw = n + 2;
        int lw = n * (n + 7);
        double[] bl = new double[n];
        double[] bu = new double[n];
        double[] g = new double[n];
        double[] ruser = new double[1];
        double[] w = new double[lw];
        double[] x = new double[n];
        int[] iuser = new int[1];
        int[] iw = new int[liw];
        Console.WriteLine("e04ly Example Program Results");
        x[0] = 3.00e0;
        x[1] = -1.00e0;
        x[2] = 0.00e0;
        x[3] = 1.00e0;
        ibound = 0;
        bl[0] = 1.00e0;
        bu[0] = 3.00e0;
        bl[1] = -2.00e0;
        bu[1] = 0.00e0;
        //
        //      x[2] is unconstrained, so we set bl[2] to a large negative
        //      number and bu[2] to a large positive number.
        //
        bl[2] = -1.00e6;
        bu[2] = 1.00e6;
        bl[3] = 1.00e0;
        bu[3] = 3.00e0;
        //
        E04.e04ly(n, ibound, funct2E04LY, hess2E04LY, bl, bu, x, out f, g, out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine("");
          Console.WriteLine(" ** e04ly returned with ifail = {0, 3}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,3}{2}", "Error exit type", ifail, " - see method document");
          }
          if (ifail != 1)
          {
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,9:f4}", "Function value on exit is ", f);
            Console.Write(" " + " {0}", "at the point");
            for (j = 1; j <= n; j++)
            {
              Console.Write(" " + " {0, 8:f4}", x[j - 1]);
            }
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "The corresponding (machine dependent) gradient is");
            for (j = 1; j <= n; j++)
            {
              Console.Write(" " + " {0, 12:e4}", g[j - 1]);
            }
            Console.WriteLine(" ");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
    //
    public static void funct2(int n, double[] xc, ref double fc, double[] gc)
    {
      //      Routine to evaluate objective function and its 1st derivatives.
      double x1,  x2,  x3,  x4;
      x1 = xc[0];
      x2 = xc[1];
      x3 = xc[2];
      x4 = xc[3];
      fc = ((x1 + 10.00e0 * x2)) * ((x1 + 10.00e0 * x2)) + 5.00e0 * ((x3 - x4)) * ((x3 - x4)) + Math.Pow((x2 - 2.00e0 * x3), 4) + 10.00e0 * Math.Pow((x1 - x4), 4);
      gc[0] = 2.00e0 * (x1 + 10.00e0 * x2) + 40.00e0 * Math.Pow((x1 - x4), 3);
      gc[1] = 20.00e0 * (x1 + 10.00e0 * x2) + 4.00e0 * Math.Pow((x2 - 2.00e0 * x3), 3);
      gc[2] = 10.00e0 * (x3 - x4) - 8.00e0 * Math.Pow((x2 - 2.00e0 * x3), 3);
      gc[3] = -10.00e0 * (x3 - x4) - 40.00e0 * Math.Pow((x1 - x4), 3);
    }
    //
    public static void hess2(int n, double[] xc, double[] heslc, double[] hesdc)
    {
      //      Routine to evaluate 2nd derivatives.
      double x1,  x2,  x3,  x4;
      x1 = xc[0];
      x2 = xc[1];
      x3 = xc[2];
      x4 = xc[3];
      hesdc[0] = 2.00e0 + 120.00e0 * ((x1 - x4)) * ((x1 - x4));
      hesdc[1] = 200.00e0 + 12.00e0 * ((x2 - 2.00e0 * x3)) * ((x2 - 2.00e0 * x3));
      hesdc[2] = 10.00e0 + 48.00e0 * ((x2 - 2.00e0 * x3)) * ((x2 - 2.00e0 * x3));
      hesdc[3] = 10.00e0 + 120.00e0 * ((x1 - x4)) * ((x1 - x4));
      heslc[0] = 20.00e0;
      heslc[1] = 0.00e0;
      heslc[2] = -24.00e0 * ((x2 - 2.00e0 * x3)) * ((x2 - 2.00e0 * x3));
      heslc[3] = -120.00e0 * ((x1 - x4)) * ((x1 - x4));
      heslc[4] = 0.00e0;
      heslc[5] = -10.00e0;
    }
  }
}


e04ly Example Program Results

  Message
It is probable that a local minimum has been found,
but it cannot be guaranteed.
    Call to    e04ly returned with ifail = 5

  Error exit type  5 - see method document

  Function value on exit is    2.4338
  at the point    1.0000   -0.0852    0.4093    1.0000
 The corresponding (machine dependent) gradient is
   2.9535e-001  -5.8675e-010   1.1735e-009   5.9070e+000


//      e04mf Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04MFE
  {
    static string datafile = "ExampleData/e04mfe.d";
    // as a command line argument. It defaults to the named file specified below otherwise.
    //
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
      double obj = 0.0;
      int i,  ifail,  iter,  j,  n,  nclin;
      Console.WriteLine("e04mf Example Program Results");
      //      Skip heading in data file
      sr.Reset();
      sr.Reset();
      n = int.Parse(sr.Next());
      nclin = int.Parse(sr.Next());
      double[,] a = new double[nclin, n];
      double[] ax = new double[nclin];
      double[] bl = new double[n + nclin];
      double[] bu = new double[n + nclin];
      double[] clamda = new double[n + nclin];
      double[] cvec = new double[n];
      double[] x = new double[n];
      int[] istate = new int[n + nclin];
      //
      //         Read cvec, a, bl, bu and x from data file
      //
      sr.Reset();
      for (i = 1; i <= n; i++)
      {
        cvec[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
      }
      sr.Reset();
      for (i = 1; i <= nclin; i++)
      {
        for (j = 1; j <= n; j++)
        {
          a[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
      }
      sr.Reset();
      for (i = 1; i <= n + nclin; i++)
      {
        bl[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
      }
      sr.Reset();
      for (i = 1; i <= n + nclin; i++)
      {
        bu[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
      }
      sr.Reset();
      for (i = 1; i <= n; i++)
      {
        x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
      }
      //
      //         Initialise E04.e04mf and check for error exits
      //
      //
      E04.e04mfOptions options = new E04.e04mfOptions();
      //
      //            Solve the problem
      //
      options.Set("List");
      options.Set("Print level = 10");
      //
      E04.e04mf(n, nclin, a, bl, bu, cvec, istate, x, out iter, out obj, ax, clamda, options,
      out ifail);
      //
      Console.WriteLine("");
      if (ifail == 6)
      {
        Console.WriteLine("   ** An input parameter is invalid");
      }
      else if (ifail >= 0)
      {
        Console.WriteLine(" ** e04mf returned with ifail = {0, 3}", ifail);
        Console.WriteLine("");
        Console.WriteLine("  Varbl    Istate      Value                Lagr Mult");
        Console.WriteLine("");
        for (i = 1; i <= n; i++)
        {
          Console.WriteLine("  V  {0,3}  {1,3}    {2,14:g6}    {3,12:g4}", i, istate[i - 1], x[i - 1], clamda[i - 1]);
        }
        if (nclin > 0)
        {
          Console.WriteLine("");
          Console.WriteLine("");
          Console.WriteLine("  L Con    Istate      Value                Lagr Mult");
          Console.WriteLine("");
          for (i = n + 1; i <= n + nclin; i++)
          {
            j = i - n;
            Console.WriteLine("  L  {0,3}  {1,3}    {2,14:g6}    {3,12:g4}", j, istate[i - 1], ax[j - 1], clamda[i - 1]);
          }
        }
        Console.WriteLine("");
        Console.WriteLine("");
        Console.WriteLine("  Final objective value = {0,15:g7}", obj);
        Console.WriteLine("");
        Console.WriteLine("");
        Console.WriteLine("  Exit from problem after  {0,6}  iterations.", iter);
      }
      else
      {
        Console.WriteLine(" ** e04mf returned with ifail = {0, 3}", ifail);
      }
      //
    }
    catch (Exception e)
    {
      Console.WriteLine(e.Message);
      Console.WriteLine( "Exception Raised");
    }
  }
}
}


//      e04nc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04NCE
  {
    static string datafile = "ExampleData/e04nce.d";
    // as a command line argument. It defaults to the named file specified below otherwise.
    //
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double obj = 0.0;
        int i,  ifail,  iter,  j,  m,  n,  nclin;
        Console.WriteLine("e04nc Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        m = int.Parse(sr.Next());
        n = int.Parse(sr.Next());
        nclin = int.Parse(sr.Next());
        //
        //         Read a, b, c, bl, bu and x from data file
        //
        double[,] a = new double[Math.Max(1,m), n];
        double[] b = new double[m];
        double[] bl = new double[n + nclin];
        double[] bu = new double[n + nclin];
        double[,] c = new double[nclin, n];
        double[] clamda = new double[n + nclin];
        double[] cvec = new double[n];
        double[] work = new double[nclin];
        double[] x = new double[n];
        int[] istate = new int[n + nclin];
        int[] kx = new int[n];
        sr.Reset();
        for (i = 1; i <= m; i++)
        {
          for (j = 1; j <= n; j++)
          {
            a[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        sr.Reset();
        for (i = 1; i <= m; i++)
        {
          b[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        sr.Reset();
        for (i = 1; i <= nclin; i++)
        {
          for (j = 1; j <= n; j++)
          {
            c[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        sr.Reset();
        for (i = 1; i <= n + nclin; i++)
        {
          bl[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        sr.Reset();
        for (i = 1; i <= n + nclin; i++)
        {
          bu[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        //
        //         Initialise E04.e04nc and check for error exits
        //
        E04.e04ncOptions options = new E04.e04ncOptions();
        //
        //            Solve the problem
        //
        options.Set("Defaults");
        options.Set("List");
        options.Set("Print level = 10");
        //
        E04.e04nc(m, n, nclin, c, bl, bu, cvec, istate, kx, x, a, b, out iter, out obj, clamda,
        options, out ifail);
        //
        //            A valid licence was found: continue.
        //            Check for error exits
        //
        Console.WriteLine("");
        if (ifail == 6)
        {
          Console.WriteLine("   ** An input parameter is invalid");
        }
        else if (ifail >= 0)
        {
          Console.WriteLine(" ** e04nc returned with ifail = {0, 3}", ifail);
          Console.WriteLine("");
          Console.WriteLine("  Varbl    Istate      Value                  Lagr Mult");
          Console.WriteLine("");
          for (i = 1; i <= n; i++)
          {
            Console.WriteLine("  V  {0,3}  {1,3}        {2,14:g6}    {3,12:g4}", i, istate[i - 1], x[i - 1], clamda[i - 1]);
          }
          if (nclin > 0)
          {
            //
            //  This performs the matrix vector multiplication C*X
            // (linear constraint values) and puts the result in
            // the first nclin locations of work.
            //
            F06.f06pa("N", nclin, n, 1.00e0, c, x, 1, 0.00e0, work, 1, out ifail);
            Console.WriteLine("");
            Console.WriteLine("");
            Console.WriteLine("  L Con    Istate      Value                  Lagr Mult");
            Console.WriteLine("");
            for (i = n + 1; i <= n + nclin; i++)
            {
              j = i - n;
              Console.WriteLine("  L  {0,3}  {1,3}        {2,14:g6}    {3,12:g4}", j, istate[i - 1], work[j - 1], clamda[i - 1]);
            }
          }
          Console.WriteLine("");
          Console.WriteLine("");
          Console.WriteLine("  Final objective value = {0,15:g7}", obj);
        }
        else
        {
          Console.WriteLine(" ** e04nc returned with ifail = {0, 3}", ifail);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      e04nf Example Program Text
//      Mark 20 Release. NAG Copyright 2001.
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class E04NFE
  {

     static string datafile = "ExampleData/e04nfe.d";
     static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }

       public static void StartExample()
     {
         try
         {
             E04.E04NF_QPHESS e04nfuE04NF = new E04.E04NF_QPHESS(E04.e04nfu);
             DataReader sr = new DataReader(datafile);
             double obj = 0.0;
             int i = 0,
             lda = 1,
             iter = 0,
             j = 0,
             n = 0,
             nclin = 0,
             nmax = 10,
             ldh = 1,
             ncmax = 10;

             Console.WriteLine("e04nf Example Program Results");
             //      Skip heading in data file
             sr.Reset();
             sr.Reset();
             n = int.Parse(sr.Next());
             nclin = int.Parse(sr.Next());
             lda = Math.Max(nclin, 1);
             ldh = n;

             double[,] a = new double[lda, nmax];
             double[] ax = new double[10];
             double[] bl = new double[20];
             double[] bu = new double[20];
             double[] clamda = new double[20];
             double[] cvec = new double[10];
             double[,] h = new double[ldh, nmax];
             double[] ruser = new double[1];
             double[] rwsav = new double[475];
             double[] work = new double[10000];
             double[] x = new double[10];
             int[] istate = new int[20];
             int[] iwork = new int[1000];
             int[] iwsav = new int[610];
             bool[] lwsav = new bool[120];
             string[] cwsav = new string[1];
             int ifail = 0;

             if ((n <= nmax) && (nclin <= ncmax))
             {
                 //
                 //         Read CVEC, A, BL, BU, X and H from data file
                 //
                 sr.Reset();
                 for (i = 1; i <= n; i++)
                 {
                     cvec[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                 }
                 sr.Reset();
                 for (i = 1; i <= nclin; i++)
                 {
                     for (j = 1; j <= n; j++)
                     {
                         a[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                     }
                 }
                 sr.Reset();
                 for (i = 1; i <= n + nclin; i++)
                 {
                     bl[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                 }
                 sr.Reset();
                 for (i = 1; i <= n + nclin; i++)
                 {
                     bu[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                 }
                 sr.Reset();
                 for (i = 1; i <= n; i++)
                 {
                     x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                 }
                 sr.Reset();
                 for (i = 1; i <= n; i++)
                 {
                     for (j = 1; j <= n; j++)
                     {
                         h[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                     }
                 }

                 //
                 //         Initialise E04NF and check for error exits
                 //
                 E04.e04nfOptions options = new E04.e04nfOptions();
                     //
                     //            Solve the problem
                     //
                     //
                     E04.e04nf(n, nclin, a, bl, bu, cvec, h, e04nfuE04NF, istate, x, out iter, out obj, ax,
                               clamda, options, out ifail);
                     //
                     //            A valid licence was found: continue.
                     //            Check for error exits
                     //
                     Console.WriteLine("");
                     if (ifail == 6)
                     {
                         Console.WriteLine("  An input parameter is invalid");
                     }
                     else if ((ifail) >= (0))
                     {
                         Console.WriteLine("  e04nf returned with ifail = {0,4}", ifail);
                         Console.WriteLine("");
                         Console.WriteLine("  Varbl    Istate      Value                  Lagr Mult");
                         Console.WriteLine("");
                         for (i = 1; i <= n; i++)
                         {
                             Console.WriteLine("  V  {0,3}  {1,3}        {2,14:g6}    {3,12:g4}", i, istate[i - 1], x[i - 1], clamda[i - 1]);
                         }
                         if (nclin > 0)
                         {
                             Console.WriteLine("");
                             Console.WriteLine("");
                             Console.WriteLine("  L Con    Istate      Value                  Lagr Mult");
                             Console.WriteLine("");
                             for (i = n + 1; i <= n + nclin; i++)
                             {
                                 j = i - n;
                                 Console.WriteLine("  L  {0,3}  {1,3}        {2,14:g6}    {3,12:g4}", j, istate[i - 1], ax[j - 1], clamda[i - 1]);
                             }
                         }
                         Console.WriteLine("");
                         Console.WriteLine("");
                         Console.WriteLine("  Final objective value = {0,15:g7}", obj);
                         Console.WriteLine("");
                         Console.WriteLine("");
                         Console.WriteLine("  Exit from problem after  {0,6}  iterations.", iter);
                     }
                     else
                     {
                         Console.WriteLine("   ** e04nf returned with ifail = {0,5}", ifail);
                     }
             }
             //
         }
         catch (Exception e)
         {
             Console.WriteLine(e.Message);
             Console.WriteLine("Exception Raised");
         }
    }
  }
}


//      e04nk Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04NKE
  {
    static string datafile = "ExampleData/e04nke.d";
    // as a command line argument. It defaults to the named file specified below otherwise.
    //
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04NK_QPHX qphxE04NK = new E04.E04NK_QPHX(qphx);
      try
      {
        DataReader sr = new DataReader(datafile);
      double obj,  sinf;
      int i,  icol=0,  ifail,  iobj,  j,  jcol,  m,  miniz,  minz,  n,  ncolh,  ninf,  nname,  nnz,  ns=0;
      string start = "";
      int idummy = -11111;
      string[] names = new string[5];
      Console.WriteLine("e04nk Example Program Results");
      //      Skip heading in data file.
      sr.Reset();
      sr.Reset();
      n = int.Parse(sr.Next());
      m = int.Parse(sr.Next());
      //
      //         Read nnz, iobj, ncolh, start and nname from data file.
      //
      sr.Reset();
      nnz = int.Parse(sr.Next());
      iobj = int.Parse(sr.Next());
      ncolh = int.Parse(sr.Next());
      start = sr.Next();
      nname = int.Parse(sr.Next());
      //
      //         Read names and crname from data file.
      //
      double[] a = new double[nnz];
      double[] bl = new double[n + m];
      double[] bu = new double[n + m];
      double[] clamda = new double[n + m];
      double[] xs = new double[n + m];
      int[] ha = new int[nnz];
      int[] istate = new int[n + m];
      int[] ka = new int[n + 1];
      string[] crname = new string[n + m];
      sr.Reset();
      for (i = 1; i <= 5; i++)
      {
        names[i - 1] = sr.Next();
      }
      sr.Reset();
      for (i = 1; i <= nname; i++)
      {
        crname[i - 1] = sr.Next();
      }
      //
      //         read the matrix a from data file. Set up ka.
      //
      jcol = 1;
      ka[jcol - 1] = 1;
      for (i = 1; i <= nnz; i++)
      {
        //
        //            Element ( ha( i-1 ), icol ) is stored in a[ i-1].
        //
        sr.Reset();
        a[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        ha[i - 1] = int.Parse(sr.Next());
        icol = int.Parse(sr.Next());
        //
        if (icol < jcol)
        {
          //
          //               Elements not ordered by increasing column index.
          //
          Console.WriteLine("\n  {0}{1,5}{2}{3,5}{4}{5}", "Element in column", icol, " found after element in column", jcol, ". Problem", " abandoned.");
          goto L120;
        }
        else if (icol == jcol + 1)
        {
          //
          //               Index in a of the start of the icol-th column equals I.
          //
          ka[icol - 1] = i;
          jcol = (int)icol;
        }
        else if (icol > jcol + 1)
        {
          //
          //               Index in a of the start of the icol-th column equals i,
          //               but columns jcol+1,jcol+2,...,icol-1 are empty. Set the
          //               corresponding elements of ka to i.
          //
          for (j = jcol + 1; j <= icol - 1; j++)
          {
            ka[j - 1] = i;
          }
          ka[icol - 1] = i;
          jcol = (int)icol;
        }
      }
      //
      ka[n + 1 - 1] = nnz + 1;
      //
      if (n > icol)
      {
        //
        //            Columns n,n-1,...,icol+1 are empty. Set the corresponding
        //            elements of ka accordingly.
        //
        for (i = n; i <= icol + 1; i += -1)
        {
          if (ka[i - 1] == idummy)
          {
            ka[i - 1] = ka[i + 1 - 1];
          }
        }
      }
      //
      //         Read bl, bu, istate and xs from data file.
      //
      sr.Reset();
      for (i = 1; i <= n + m; i++)
      {
        bl[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
      }
      sr.Reset();
      for (i = 1; i <= n + m; i++)
      {
        bu[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
      }
      if (start == "C")
      {
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          istate[i - 1] = int.Parse(sr.Next());
        }
      }
      else if (start == "W")
      {
        sr.Reset();
        for (i = 1; i <= n + m; i++)
        {
          istate[i - 1] = int.Parse(sr.Next());
        }
      }
      sr.Reset();
      for (i = 1; i <= n; i++)
      {
        xs[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
      }
      //
      //         Initialise E04.e04nk
      //
      // Switch off all output.
      PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
      PrintManager.Message = new PrintManager.MessageLogger(discardmessage);
      E04.e04nkOptions options = new E04.e04nkOptions();
      //
      //            Solve the QP problem.
      //
      //
      start = "C";
      // First get appropriate minimum lengths of arrays, z and iz
      int lenz = 1;
      int leniz = 1;
      double[] z = new double[lenz];
      int[] iz = new int[leniz];
      E04.e04nk(n, m, nnz, iobj, ncolh, qphxE04NK, a, ha, ka, bl, bu,
      start, names, nname, crname, ref ns, xs, istate, out miniz,
      out minz, out ninf, out sinf, out obj, clamda, iz, z, options, out ifail);
      Console.WriteLine("Computed values of the size of z and iz are {0}, {1} respectively.", minz, miniz);
      lenz = 358;
      leniz = 428;
      z = new double[lenz];
      iz = new int[leniz];
      //         Initialise E04.e04nk again and check for error exits
      PrintManager.Warning = new PrintManager.MessageLogger(printmessage);
      PrintManager.Message = new PrintManager.MessageLogger(printmessage);
      options = new E04.e04nkOptions();
      options.Set("List");
      options.Set("Print level = 10");
      E04.e04nk(n, m, nnz, iobj, ncolh, qphxE04NK, a, ha, ka, bl, bu,
      start, names, nname, crname, ref ns, xs, istate, out miniz,
      out minz, out ninf, out sinf, out obj, clamda, iz, z, options, out ifail);
      //
      //            Check for error exits
      //
      Console.WriteLine("");
      if (ifail == 7)
      {
        Console.WriteLine("   ** An input parameter is invalid");
      }
      else if (ifail >= 0)
      {
        Console.WriteLine(" ** e04nk returned with ifail = {0, 3}", ifail);
        Console.WriteLine("");
        Console.WriteLine("  Variable    Istate          Value                  Lagr Mult");
        Console.WriteLine("");
        for (i = 1; i <= n; i++)
        {
          Console.WriteLine("    {0}  {1,3}        {2,14:g6}    {3,12:g4}", crname[i - 1], istate[i - 1], xs[i - 1], clamda[i - 1]);
        }
        if (m > 0)
        {
          //
          Console.WriteLine("");
          Console.WriteLine("");
          Console.WriteLine("  Constrnt    Istate          Value                  Lagr Mult");
          Console.WriteLine("");
          for (i = n + 1; i <= n + m; i++)
          {
            j = i - n;
            Console.WriteLine("    {0}  {1,3}        {2,14:g6}    {3,12:g4}", crname[i - 1], istate[i - 1], xs[i - 1], clamda[i - 1]);
          }
        }
        Console.WriteLine("");
        Console.WriteLine("");
        Console.WriteLine("  Final objective value = {0,15:g7}", obj);
      }
      else
      {
        Console.WriteLine(" ** e04nk returned with ifail = {0, 3}", ifail);
      }
      L120: ;
      //
    }
    catch (Exception e)
    {
      Console.WriteLine(e.Message);
      Console.WriteLine( "Exception Raised");
    }
  }
  //
  public static void qphx(int nstate, int ncolh, double[] x, double[] hx)
  {
    //
    //      Routine to compute H*x. (In this version of QPHX, the Hessian
    //      matrix h is not referenced explicitly.)
    //
    double two = 2.00e+0;
    hx[0] = two * x[0];
    hx[1] = two * x[1];
    hx[2] = two * (x[2] + x[3]);
    hx[3] = hx[2];
    hx[4] = two * x[4];
    hx[5] = two * (x[5] + x[6]);
    hx[6] = hx[5];
    //
  }
  static void discardmessage(String message)
  {
  }
  static void printmessage(String message)
  {
    Console.WriteLine(message);
  }
}
}


//      e04nq Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04NQE
  {
    static string datafile = "ExampleData/e04nqe.d";
    // as a command line argument. It defaults to the named file specified below otherwise.
    //
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04NQ_QPHX qphxE04NQ = new E04.E04NQ_QPHX(qphx);
      try
      {
        DataReader sr = new DataReader(datafile);
      double obj,  objadd,  sinf;
      int i,  icol=0,  ifail,  iobj,  j,  jcol,  lenc,  m,  n,  ncolh,  ne,  ninf,  nname,  ns=0;
      string start = "";
      string prob = "";
      int lenrw = 600;
      Console.WriteLine("e04nq Example Program Results");
      //      Skip heading in data file.
      sr.Reset();
      sr.Reset();
      n = int.Parse(sr.Next());
      m = int.Parse(sr.Next());
      double[] acol = new double[n*m];
      double[] bl = new double[n + m];
      double[] bu = new double[n + m];
      double[] c = new double[1];
      double[] pi = new double[m];
      double[] rc = new double[n + m];
      double[] ruser = new double[1];
      double[] rw = new double[lenrw];
      double[] x = new double[n + m];
      int[] helast = new int[n + m];
      int[] hs = new int[n + m];
      int[] inda = new int[n*m];
      int[] loca = new int[n + 1];
      string[] names = new string[n + m];
      //
      //         Read ne, iobj, ncolh, start and nname from data file.
      sr.Reset();
      ne = int.Parse(sr.Next());
      iobj = int.Parse(sr.Next());
      ncolh = int.Parse(sr.Next());
      start = sr.Next();
      nname = int.Parse(sr.Next());
      //
      //         Read names from data file.
      sr.Reset();
      for (i = 1; i <= nname; i++)
      {
        names[i - 1] = sr.Next();
      }
      //
      //         Read the matrix acol from data file. Set up loca.
      jcol = 1;
      loca[jcol - 1] = 1;
      for (i = 1; i <= ne; i++)
      {
        //
        //            Element ( inda[i-1], icol-1 ) is stored in acol[ i-1 ].
        sr.Reset();
        acol[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        inda[i - 1] = int.Parse(sr.Next());
        icol = int.Parse(sr.Next());
        //
        if (icol < jcol)
        {
          //               Elements not ordered by increasing column index.
          Console.WriteLine("  {0}{1,5}{2}{3,5}{4}{5}", "Element in column", icol, " found after element in column", jcol, ". Problem", " abandoned.");
          goto L100;
        }
        else if (icol == jcol + 1)
        {
          //               Index in acol of the start of the icol-th column equals i.
          loca[icol - 1] = i;
          jcol = (int)icol;
        }
        else if (icol > jcol + 1)
        {
          //               Index in acol of the start of the icol-th column equals i,
          //               but columns jcol+1,jcol+2,...,icol-1 are empty. Set the
          //               corresponding elements of loca to i.
          for (j = jcol + 1; j <= icol - 1; j++)
          {
            loca[j - 1] = i;
          }
          loca[icol - 1] = i;
          jcol = (int)icol;
        }
      }
      //
      loca[n + 1 - 1] = ne + 1;
      //
      if (n > icol)
      {
        //            Columns n,n-1,...,icol+1 are empty. Set the corresponding
        //            elements of loca accordingly.
        for (i = n; i <= icol + 1; i += -1)
        {
          loca[i - 1] = loca[i + 1 - 1];
        }
      }
      //
      //         Read bl, bu, hs and x from data file.
      sr.Reset();
      for (i = 1; i <= n + m; i++)
      {
        bl[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
      }
      sr.Reset();
      for (i = 1; i <= n + m; i++)
      {
        bu[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
      }
      if (start == "C")
      {
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          hs[i - 1] = int.Parse(sr.Next());
        }
      }
      else if (start == "W")
      {
        sr.Reset();
        for (i = 1; i <= n + m; i++)
        {
          hs[i - 1] = int.Parse(sr.Next());
        }
      }
      sr.Reset();
      for (i = 1; i <= n; i++)
      {
        x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
      }
      //
      //         Initialise e04nq.
      E04.e04nqOptions options = new E04.e04nqOptions();
      //
      options.Set("Print file = 6");
      //
      //         We have no explicit objective vector so set lenc = 0; the
      //         objective vector is stored in row iobj of acol.
      lenc = 0;
      objadd = 0.00e0;
      prob = "";
      //
      //         Do not allow any elastic variables (i.e. they cannot be
      //         infeasible). If we'd set optional argument "Elastic mode" to 0,
      //         we wouldn't need to set the individual elements of array helast.
      for (i = 1; i <= n + m; i++)
      {
        helast[i - 1] = 0;
      }
      //
      //         Solve the QP problem.
      start = "C";
      E04.e04nq(start, qphxE04NQ, m, n, ne, nname, lenc, ncolh, iobj, objadd, prob, acol, inda,
      loca, bl, bu, c, names, helast, hs, x, pi, rc, ref ns, out ninf, out sinf, out obj, options,
      out ifail);
      //
      Console.WriteLine("");
      if (ifail >= 0)
      {
        Console.WriteLine("  On exit from e04nq, ifail = {0,5}", ifail);
        if (ifail == 0)
        {
          Console.WriteLine("  Final objective value = {0,11:e3}\n", obj);
          Console.Write("  Optimal x = ");
          for (i = 1; i <= n; i++)
          {
            Console.Write(" " + " {0, 9:f2}", x[i - 1]);
          }
          Console.WriteLine(" ");
        }
      }
      else
      {
        Console.WriteLine(" ** e04nq returned with ifail = {0, 3}", ifail);
      }
      //
      L100: ;
      //
    }
    catch (Exception e)
    {
      Console.WriteLine(e.Message);
      Console.WriteLine( "Exception Raised");
    }
  }
  //
  public static void qphx(int ncolh, double[] x, double[] hx, int nstate)
  {
    //      Routine to compute H*x. (In this version of qphx, the Hessian
    //      matrix h is not referenced explicitly.)
    double two = 2.00e+0;
    hx[0] = two * x[0];
    hx[1] = two * x[1];
    hx[2] = two * (x[2] + x[3]);
    hx[3] = hx[2];
    hx[4] = two * x[4];
    hx[5] = two * (x[5] + x[6]);
    hx[6] = hx[5];
  }
}
}


e04nq Example Program Results

 Parameters
 ==========

 Files
 -----
 Solution file..........         0       Old basis file ........         0       (Print file)...........         6
 Insert file............         0       New basis file ........         0       (Summary file).........         0
 Punch file.............         0       Backup basis file......         0
 Load file..............         0       Dump file..............         0

 Frequencies
 -----------
 Print frequency........       100       Check frequency........        60       Save new basis map.....       100
 Summary frequency......       100       Factorization frequency        50       Expand frequency.......     10000

 LP/QP Parameters
 ----------------
 Minimize...............                 QPsolver Cholesky......                 Cold start.............
 Scale tolerance........     0.900       Feasibility tolerance..  1.00E-06       Iteration limit........     10000
 Scale option...........         2       Optimality tolerance...  1.00E-06       Print level............         1
 Crash tolerance........     0.100       Pivot tolerance........  2.04E-11       Partial price..........         1
 Crash option...........         3       Elastic weight.........  1.00E+00       Prtl price section ( A)         7
 Elastic mode...........         1       Elastic objective......         1       Prtl price section (-I)         8

 QP objective
 ------------
 Objective variables....         7       Hessian columns........         7       Superbasics limit......         7
 Nonlin Objective vars..         7       Unbounded step size....  1.00E+20
 Linear Objective vars..         0

 Miscellaneous
 -------------
 LU factor tolerance....      3.99       LU singularity tol.....  2.04E-11       Timing level...........         0
 LU update tolerance....      3.99       LU swap tolerance......  1.03E-04       Debug level............         0
 LU partial  pivoting...                 eps (machine precision)  1.11E-16       System information.....        No

 Matrix statistics
 -----------------
               Total      Normal        Free       Fixed     Bounded
 Rows              8           5           1           1           1
 Columns           7           2           0           0           5

 No. of matrix elements                   48     Density      85.714
 Biggest                          1.0000E+00  (excluding fixed columns,
 Smallest                         1.0000E-02   free rows, and RHS)

 No. of objective coefficients             7
 Biggest                          2.0000E+03  (excluding fixed columns)
 Smallest                         2.0000E+02

 Nonlinear constraints       0     Linear constraints       8
 Nonlinear variables         7     Linear variables         0
 Jacobian  variables         0     Objective variables      7
 Total constraints           8     Total variables          7

 Itn      1: Feasible linear constraints

 E04NQT EXIT   0 -- finished successfully
 E04NQT INFO   1 -- optimality conditions satisfied

 Problem name
 No. of iterations                   9   Objective value     -1.8477846771E+06
 No. of Hessian products            16   Objective row       -2.9886903537E+06
                                         Quadratic objective  1.1409056766E+06
 No. of superbasics                  2   No. of basic nonlinears             4
 No. of degenerate steps             0   Percentage                       0.00
 Max x       (scaled)        3 2.4E-01   Max pi      (scaled)        6 4.7E+07
 Max x                       3 6.5E+02   Max pi                      7 1.5E+04
 Max Prim inf(scaled)        0 0.0E+00   Max Dual inf(scaled)        6 1.3E-08
 Max Primal infeas           0 0.0E+00   Max Dual infeas             9 3.8E-11

 Name                                    Objective Value     -1.8477846771E+06

 Status         Optimal Soln             Iteration      9    Superbasics     2

 Section 1 - Rows

  Number  ...Row.. State  ...Activity...  Slack Activity  ..Lower Limit.  ..Upper Limit.  .Dual Activity    ..i

       8  ..ROW1..    EQ      2000.00000          .           2000.00000      2000.00000    -12900.76766      1
       9  ..ROW2..    BS        49.23160       -10.76840           None         60.00000         0.00000      2
      10  ..ROW3..    UL       100.00000          .                None        100.00000     -2324.86620      3
      11  ..ROW4..    BS        32.07187        -7.92813           None         40.00000          .           4
      12  ..ROW5..    BS        14.55719       -15.44281           None         30.00000          .           5
      13  ..ROW6..    LL      1500.00000          .           1500.00000           None      14454.60290      6
      14  ..ROW7..    LL       250.00000          .            250.00000       300.00000     14580.95432      7
      15  ..COST..    BS  -2988690.35370  -2988690.35370           None            None         -1.0          8

 Section 2 - Columns

  Number  .Column. State  ...Activity...  .Obj Gradient.  ..Lower Limit.  ..Upper Limit.  Reduced Gradnt    m+j

       1  ...X1...    LL          .           -200.00000          .            200.00000      2360.67253      9
       2  ...X2...    BS       349.39923     -1301.20153          .           2500.00000        -0.00000     10
       3  ...X3...   SBS       648.85342      -356.59829       400.00000       800.00000        -0.00000     11
       4  ...X4...   SBS       172.84743      -356.59829       100.00000       700.00000         0.00000     12
       5  ...X5...    BS       407.52089     -1184.95822          .           1500.00000         0.00000     13
       6  ...X6...    BS       271.35624      1242.75804          .                None          0.00000     14
       7  ...X7...    BS       150.02278      1242.75804          .                None          0.00000     15

  On exit from e04nq, ifail =     0
  Final objective value = -1.848e+006

  Optimal x =        0.00     349.40     648.85     172.85     407.52     271.36     150.02


//      e04pc Example Program Text
//      Mark 24 Release. NAG Copyright 2012.
//      C# version, NAG Copyright 2012

using System;
using NagLibrary;
using System.Globalization;
using System.IO;

namespace NagDotNetExamples
{

    public class E04PCE
    {
        static string datafile = "ExampleData/e04pce.d";
        // as a command line argument. It defaults to the named file specified below otherwise.
        //
        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
        {

            try
            {
                DataReader sr = new DataReader(datafile);
                double tol = 0.0;
                int itype = 1;
                double rnorm;
                int i = 0,
                    ifail = 0,
                    lda = 0,
                    lwork = 0,
                    m = 0,
                    n = 0,
                    nfree = 0;
                double[,] a;
                double[] b;
                double[] lbnd;
                double[] ubnd;
                double[] w;
                double[] x;
                int[] indx;

                Console.WriteLine(" {0}", "E04PCF Example Program Results");
                Console.WriteLine("");

                //      Skip heading in data file
                sr.Reset();

                sr.Reset();
                m = int.Parse(sr.Next());
                n = int.Parse(sr.Next());

                int j = 0;
                lda = (int)m;

                lwork = 4 * n;

                // allocate
                a = new double[lda, n];
                b = new double[m];
                w = new double[lwork];
                lbnd = new double[n];
                ubnd = new double[n];
                x = new double[n];
                indx = new int[n];

                // allocate

                sr.Reset();

                for (i = 1; i <= m; i++)
                {
                    for (j = 1; j <= n; j++)
                    {
                        a[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                    }
                }

                sr.Reset();
                for (j = 1; j <= m; j++)
                {
                    b[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }

                sr.Reset();
                for (j = 1; j <= n; j++)
                {
                    lbnd[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }

                sr.Reset();
                for (j = 1; j <= n; j++)
                {
                    ubnd[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }

                ifail = 0;
                E04.e04pc(itype, m, n, a, b, lbnd, ubnd, tol, x, out rnorm, out nfree, w, indx,out  ifail);

                Console.WriteLine("Solution vector\n");
                for (j = 1; j <= n; j++)
                {
                    Console.WriteLine("  {0}" , x[j - 1]);
                }

                Console.WriteLine("");
                Console.WriteLine("Dual Solution\n");

                for (j = 1; j <= n; j++)
                {
                    Console.WriteLine("  {0} ",  w[j - 1]);
                }

                Console.WriteLine("  \n{0} {1} ", "Residual ", rnorm);
                Console.WriteLine("");

            }

            catch (Exception e)
            {
                Console.WriteLine(e.Message);
                Console.WriteLine("Exception Raised");
            }
        }
    }
}


//      e04uc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04UCE
  {
    // Specify data file as a command line argument.
    // It defaults to the named file specified below otherwise.
    static string datafile = "ExampleData/e04uce.d";

    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04UC_CONFUN confunE04UC = new E04.E04UC_CONFUN(confun);
      E04.E04UC_OBJFUN objfunE04UC = new E04.E04UC_OBJFUN(objfun);
      try
      {
        DataReader sr = new DataReader(datafile);
        double objf = 0.0;
        int i,  ifail,  iter,  j,  n,  nclin,  ncnln;
        Console.WriteLine("e04uc Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        nclin = int.Parse(sr.Next());
        ncnln = int.Parse(sr.Next());
        double[,] a = new double[nclin, n];
        double[] bl = new double[n + nclin + ncnln];
        double[] bu = new double[n + nclin + ncnln];
        double[] c = new double[ncnln];
        double[,] cjac = new double[ncnln, n];
        double[] clamda = new double[n + nclin + ncnln];
        double[] objgrd = new double[n];
        double[,] r = new double[n, n];
        double[] x = new double[n];
        double[] work = new double[nclin];
        int[] istate = new int[n + nclin + ncnln];
        //
        //         Read a, bl, bu and x from data file
        //
        if (nclin > 0)
        {
          sr.Reset();
          for (i = 1; i <= nclin; i++)
          {
            for (j = 1; j <= n; j++)
            {
              a[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
        }
        sr.Reset();
        for (i = 1; i <= n + nclin + ncnln; i++)
        {
          bl[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        sr.Reset();
        for (i = 1; i <= n + nclin + ncnln; i++)
        {
          bu[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        //
        //         Initialise E04.E04UC and check for error exits
        //
        E04.e04ucOptions options = new E04.e04ucOptions();
        options.Set("List");
        options.Set("Print level = 10");
        //
        //            Solve the problem
        //
        //
        E04.e04uc(n, nclin, ncnln, a, bl, bu, confunE04UC, objfunE04UC, out iter, istate, c,
        cjac,
        clamda, out objf, objgrd, r, x, options, out ifail);
        //
        //            Check for error exits
        //
        Console.WriteLine("");
        if (ifail >= (9))
        {
          Console.WriteLine("   ** An input parameter is invalid");
        }
        else if (ifail == 7)
        {
          Console.WriteLine("  User supplied derivatives are incorrect");
        }
        else if (ifail == -399)
        {
          Console.WriteLine(" ** e04uc returned with ifail = {0, 3}", ifail);
        }
        else if (ifail < 0)
        {
          Console.WriteLine("  MODE < 0 on exit from OBJFUN or CONFUN.\n\n Problem abandoned.");
        }
        else
        {
          Console.WriteLine(" ** e04uc returned with ifail = {0, 3}", ifail);
          Console.WriteLine("");
          Console.WriteLine("  Varbl    Istate            Value         Lagr Mult");
          Console.WriteLine("");
          for (i = 1; i <= n; i++)
          {
            Console.WriteLine("  V  {0,3}  {1,3}        {2,14:g6}    {3,12:g4}", i, istate[i - 1], x[i - 1], clamda[i - 1]);
          }
          if (nclin > 0)
          {
            //
            // This performs the matrix vector multiplication A*X
            // (linear constraint values) and puts the result in
            // the first nclin locations of work.
            //
            F06.f06pa("N", nclin, n, 1.00e0, a, x, 1, 0.00e0, work, 1, out ifail);
            Console.WriteLine("");
            Console.WriteLine("");
            Console.WriteLine("  L Con    Istate      Value                  Lagr Mult");
            Console.WriteLine("");
            for (i = n + 1; i <= n + nclin; i++)
            {
              j = i - n;
              Console.WriteLine("  L  {0,3}  {1,3}        {2,14:g6}    {3,12:g4}", j, istate[i - 1], work[j - 1], clamda[i - 1]);
            }
          }
          if (ncnln > 0)
          {
            Console.WriteLine("");
            Console.WriteLine("");
            Console.WriteLine("  N Con    Istate             Value           Lagr Mult");
            Console.WriteLine("");
            for (i = n + nclin + 1; i <= n + nclin + ncnln; i++)
            {
              j = i - n - nclin;
              Console.WriteLine("  N  {0,3}  {1,3}        {2,14:g6}    {3,12:g4}", j, istate[i - 1], c[j - 1], clamda[i - 1]);
            }
          }
          Console.WriteLine("");
          Console.WriteLine("");
          Console.WriteLine("  Final objective value = {0,15:g7}", objf);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
    //
    public static void objfun(ref int mode, int n, double[] x, ref double objf,
    double[] objgrd, int nstate)
    {
      //      Routine to evaluate objective function and its 1st derivatives.
      double one = 1.00e0;
      double two = 2.00e0;
      if ((mode == 0) || (mode == 2))
      {
        objf = x[0] * x[3] * (x[0] + x[1] + x[2]) + x[2];
      }
      //
      if ((mode == 1) || (mode == 2))
      {
        objgrd[0] = x[3] * (two * x[0] + x[1] + x[2]);
        objgrd[1] = x[0] * x[3];
        objgrd[2] = x[0] * x[3] + one;
        objgrd[3] = x[0] * (x[0] + x[1] + x[2]);
      }
      //
    }
    //
    public static void confun(ref int mode, int ncnln, int n, int[] needc, double[] x,
    double[] c, double[,] cjac, int nstate)
    {
      //      Routine to evaluate the nonlinear constraints and their 1st
      //      derivatives.
      double zero = 0.00e0;
      double two = 2.00e0;
      int i,  j;
      if (nstate == 1)
      {
        //         First call to confun.  Set all Jacobian elements to zero.
        //         Note that this will only work when 'Derivative Level = 3'
        //         (the default; see Section 11.2).
        for (j = 1; j <= n; j++)
        {
          for (i = 1; i <= ncnln; i++)
          {
            cjac[i - 1, j - 1] = zero;
          }
        }
      }
      //
      if (needc[0] > 0)
      {
        if ((mode == 0) || (mode == 2))
        {
          c[0] = (x[0]) * (x[0]) + (x[1]) * (x[1]) + (x[2]) * (x[2]) + (x[3]) * (x[3]);
        }
        if ((mode == 1) || (mode == 2))
        {
          cjac[0, 0] = two * x[0];
          cjac[0, 1] = two * x[1];
          cjac[0, 2] = two * x[2];
          cjac[0, 3] = two * x[3];
        }
      }
      //
      if (needc[1] > 0)
      {
        if ((mode == 0) || (mode == 2))
        {
          c[1] = x[0] * x[1] * x[2] * x[3];
        }
        if ((mode == 1) || (mode == 2))
        {
          cjac[1, 0] = x[1] * x[2] * x[3];
          cjac[1, 1] = x[0] * x[2] * x[3];
          cjac[1, 2] = x[0] * x[1] * x[3];
          cjac[1, 3] = x[0] * x[1] * x[2];
        }
      }
      //
    }
  }
}


e04uc Example Program Results

 Calls to E04UCF
 ---------------

      List
      Print level = 10

 *** E04UCF

 Parameters
 ----------

 Linear constraints.....         1       Variables..............         4
 Nonlinear constraints..         2

 Infinite bound size....  1.00E+20       COLD start.............
 Infinite step size.....  1.00E+20       EPS (machine precision)  1.11E-16
 Step limit.............  2.00E+00       Hessian................        NO

 Linear feasibility.....  1.05E-08       Crash tolerance........  1.00E-02
 Nonlinear feasibility..  1.05E-08       Optimality tolerance...  3.26E-12
 Line search tolerance..  9.00E-01       Function precision.....  4.37E-15

 Derivative level.......         3       Monitoring file........        -1
 Verify level...........         0

 Major iterations limit.        50       Major print level......        10
 Minor iterations limit.        50       Minor print level......         0

 Start point
    1.000000E+00   5.000000E+00   5.000000E+00   1.000000E+00

 Workspace provided is     IWORK(      17),  WORK(     185).
 To solve problem we need  IWORK(      17),  WORK(     185).

 Verification of the constraint gradients.
 -----------------------------------------

 The constraint Jacobian seems to be ok.

 The largest relative error was    2.29E-07  in constraint    2

 Verification of the objective gradients.
 ----------------------------------------

 The objective gradients seem to be ok.

 Directional derivative of the objective    8.15250000E-01
 Difference approximation                   8.15249734E-01

  Maj  Mnr    Step Merit Function Norm Gz  Violtn Cond Hz
    0    4 0.0E+00   1.738281E+01 7.1E-01 1.2E+01 1.0E+00
    1    1 1.0E+00   1.703169E+01 4.6E-02 1.9E+00 1.0E+00
    2    1 1.0E+00   1.701442E+01 2.1E-02 8.8E-02 1.0E+00
    3    1 1.0E+00   1.701402E+01 3.1E-04 5.4E-04 1.0E+00
    4    1 1.0E+00   1.701402E+01 7.0E-06 9.9E-08 1.0E+00
    5    1 1.0E+00   1.701402E+01 1.1E-08 4.6E-11 1.0E+00

 Exit from NP problem after     5 major iterations,
                                9 minor iterations.

 Varbl State     Value       Lower Bound   Upper Bound    Lagr Mult   Slack

 V   1    LL   1.000000      1.000000       5.00000       1.088         .
 V   2    FR    4.74300      1.000000       5.00000           .      0.2570
 V   3    FR    3.82115      1.000000       5.00000           .       1.179
 V   4    FR    1.37941      1.000000       5.00000           .      0.3794

 L Con State     Value       Lower Bound   Upper Bound    Lagr Mult   Slack

 L   1    FR    10.9436          None       20.0000           .       9.056

 N Con State     Value       Lower Bound   Upper Bound    Lagr Mult   Slack

 N   1    UL    40.0000          None       40.0000     -0.1615     -3.5264E-11
 N   2    LL    25.0000       25.0000          None      0.5523     -2.8791E-11

 Exit E04UCF - Optimal solution found.

 Final objective value =    17.01402

 ** e04uc returned with ifail =   0

  Varbl    Istate            Value         Lagr Mult

  V    1    1                     1           1.088
  V    2    0                 4.743               0
  V    3    0               3.82115               0
  V    4    0               1.37941               0

  L Con    Istate      Value                  Lagr Mult

  L    1    0               10.9436               0

  N Con    Istate             Value           Lagr Mult

  N    1    2                    40         -0.1615
  N    2    1                    25          0.5523

  Final objective value =        17.01402


//      e04uf Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04UFE
  {
    static string datafile = "ExampleData/e04ufe.d";
    // as a command line argument. It defaults to the named file specified below otherwise.
    //
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {            try
    {
      DataReader sr = new DataReader(datafile);
      double objf = 0.0;
      int i,  irevcm,  iter=0,  j,  n,  nclin,  ncnln;
      double zero = 0.00e+0;
      double one = 1.00e+0;
      double two = 2.00e+0;
      int ifail;
      Console.WriteLine("e04uf Example Program Results");
      //      Skip heading in data file.
      sr.Reset();
      sr.Reset();
      n = int.Parse(sr.Next());
      nclin = int.Parse(sr.Next());
      ncnln = int.Parse(sr.Next());
      double[,] a = new double[nclin, n];
      double[] bl = new double[n + nclin + ncnln];
      double[] bu = new double[n + nclin + ncnln];
      double[] c = new double[ncnln];
      double[,] cjac = new double[ncnln, n];
      double[] clamda = new double[n + nclin + ncnln];
      double[] objgrd = new double[n];
      double[,] r = new double[n, n];
      double[] work = new double[1000];
      double[] x = new double[n];
      int[] istate = new int[n + nclin + ncnln];
      int[] iwork = new int[100];
      int[] needc = new int[10];
      //
      // Read a, bl, bu and x from data file.
      //
      if (nclin > 0)
      {
        sr.Reset();
        for (i = 1; i <= nclin; i++)
        {
          for (j = 1; j <= n; j++)
          {
            a[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
      }
      sr.Reset();
      for (i = 1; i <= n + nclin + ncnln; i++)
      {
        bl[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
      }
      sr.Reset();
      for (i = 1; i <= n + nclin + ncnln; i++)
      {
        bu[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
      }
      sr.Reset();
      for (i = 1; i <= n; i++)
      {
        x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
      }
      //
      //         Set all constraint Jacobian elements to zero.
      //         Note that this will only work when 'Derivative Level = 3'
      //         (the default; see Section 11.2).
      //
      for (j = 1; j <= n; j++)
      {
        for (i = 1; i <= ncnln; i++)
        {
          cjac[i - 1, j - 1] = zero;
        }
      }
      //
      //         Initialise E04.e04uf and check for error exits
      //
      E04.e04ufOptions options = new E04.e04ufOptions();
      options.Set("List");
      options.Set("Print level = 10");
      //
      //            Solve the problem.
      //
      irevcm = 0;
      //
      L60: ;
      //
      E04.e04uf(ref irevcm, n, nclin, ncnln, a, bl, bu, ref iter, istate, c, cjac, clamda,
      ref objf, objgrd, r, x, needc, iwork, work, options, out ifail);
      //
      //            On intermediate exit ifail should not have been changed
      //            and irevcm should be > 0.
      //
      if (irevcm > 0)
      {
        if ((irevcm == 1) || (irevcm == 3))
        {
          //                  Evaluate the objective function.
          objf = x[0] * x[3] * (x[0] + x[1] + x[2]) + x[2];
        }
        if ((irevcm == 2) || (irevcm == 3))
        {
          //                  Evaluate the objective gradient.
          objgrd[0] = x[3] * (two * x[0] + x[1] + x[2]);
          objgrd[1] = x[0] * x[3];
          objgrd[2] = x[0] * x[3] + one;
          objgrd[3] = x[0] * (x[0] + x[1] + x[2]);
        }
        //
        if ((irevcm == 4) || (irevcm == 6))
        {
          //                  Evaluate the nonlinear constraint functions.
          if (needc[0] > 0)
          {
            c[0] = (x[0]) * (x[0]) + (x[1]) * (x[1]) + (x[2]) * (x[2]) + (x[3]) * (x[3]);
          }
          if (needc[1] > 0)
          {
            c[1] = x[0] * x[1] * x[2] * x[3];
          }
        }
        if ((irevcm == 5) || (irevcm == 6))
        {
          //                  Evaluate the constraint Jacobian.
          if (needc[0] > 0)
          {
            cjac[0, 0] = two * x[0];
            cjac[0, 1] = two * x[1];
            cjac[0, 2] = two * x[2];
            cjac[0, 3] = two * x[3];
          }
          if (needc[1] > 0)
          {
            cjac[1, 0] = x[1] * x[2] * x[3];
            cjac[1, 1] = x[0] * x[2] * x[3];
            cjac[1, 2] = x[0] * x[1] * x[3];
            cjac[1, 3] = x[0] * x[1] * x[2];
          }
        }
        goto L60;
      }
      else if (ifail >= (9))
      {
        Console.WriteLine("   ** An input parameter is invalid");
      }
      else if (ifail == 7)
      {
        Console.WriteLine("   ** User supplied derivatives are incorrect");
      }
      else if (ifail >= 0)
      {
        Console.WriteLine(" ** e04uf returned with ifail = {0, 3}", ifail);
        Console.WriteLine("");
        Console.WriteLine("  Varbl    Istate      Value                  Lagr Mult");
        Console.WriteLine("");
        for (i = 1; i <= n; i++)
        {
          Console.WriteLine("  V  {0,3}  {1,3}        {2,14:g6}    {3,12:g4}", i, istate[i - 1], x[i - 1], clamda[i - 1]);
        }
        if (nclin > 0)
        {
          //
          //                  This performs the matrix vector multiplication A*X
          //                  (linear constraint values) and puts the result in
          //                  the first nclin locations of work.
          //
          F06.f06pa("N", nclin, n, 1.00e0, a, x, 1, 0.00e0, work, 1, out ifail);
          Console.WriteLine("");
          Console.WriteLine("");
          Console.WriteLine("  L Con    Istate      Value                  Lagr Mult");
          Console.WriteLine("");
          for (i = n + 1; i <= n + nclin; i++)
          {
            j = i - n;
            Console.WriteLine("  L  {0,3}  {1,3}        {2,14:g6}    {3,12:g4}", j, istate[i - 1], work[j - 1], clamda[i - 1]);
          }
        }
        if (ncnln > 0)
        {
          Console.WriteLine("");
          Console.WriteLine("");
          Console.WriteLine("  N Con    Istate      Value                  Lagr Mult");
          Console.WriteLine("");
          for (i = n + nclin + 1; i <= n + nclin + ncnln; i++)
          {
            j = i - n - nclin;
            Console.WriteLine("  N  {0,3}  {1,3}        {2,14:g6}    {3,12:g4}", j, istate[i - 1], c[j - 1], clamda[i - 1]);
          }
        }
        Console.WriteLine("");
        Console.WriteLine("");
        Console.WriteLine("  Final objective value = {0,15:g7}", objf);
      }
      else
      {
        Console.WriteLine(" ** e04uf returned with ifail = {0, 3}", ifail);
      }
    }
    catch (Exception e)
    {
      Console.WriteLine(e.Message);
      Console.WriteLine("Exception Raised");
    }
  }
}
}


e04uf Example Program Results

 Calls to E04UFF
 ---------------

      List
      Print level = 10

 *** E04UFF

 Parameters
 ----------

 Linear constraints.....         1       Variables..............         4
 Nonlinear constraints..         2

 Infinite bound size....  1.00E+20       COLD start.............
 Infinite step size.....  1.00E+20       EPS (machine precision)  1.11E-16
 Step limit.............  2.00E+00       Hessian................        NO

 Linear feasibility.....  1.05E-08       Crash tolerance........  1.00E-02
 Nonlinear feasibility..  1.05E-08       Optimality tolerance...  3.26E-12
 Line search tolerance..  9.00E-01       Function precision.....  4.37E-15

 Derivative level.......         3       Monitoring file........        -1
 Verify level...........         0

 Major iterations limit.        50       Major print level......        10
 Minor iterations limit.        50       Minor print level......         0

 Workspace provided is     IWORK(     100),  WORK(    1000).
 To solve problem we need  IWORK(      17),  WORK(     192).

 Verification of the constraint gradients.
 -----------------------------------------

 The constraint Jacobian seems to be ok.

 The largest relative error was    2.29E-07  in constraint    2

 Verification of the objective gradients.
 ----------------------------------------

 The objective gradients seem to be ok.

 Directional derivative of the objective    8.15250000E-01
 Difference approximation                   8.15249734E-01

  Maj  Mnr    Step Merit Function Norm Gz  Violtn Cond Hz
    0    4 0.0E+00   1.738281E+01 7.1E-01 1.2E+01 1.0E+00
    1    1 1.0E+00   1.703169E+01 4.6E-02 1.9E+00 1.0E+00
    2    1 1.0E+00   1.701442E+01 2.1E-02 8.8E-02 1.0E+00
    3    1 1.0E+00   1.701402E+01 3.1E-04 5.4E-04 1.0E+00
    4    1 1.0E+00   1.701402E+01 7.0E-06 9.9E-08 1.0E+00
    5    1 1.0E+00   1.701402E+01 1.1E-08 4.6E-11 1.0E+00

 Exit from NP problem after     5 major iterations,
                                9 minor iterations.

 Varbl State     Value       Lower Bound   Upper Bound    Lagr Mult   Slack

 V   1    LL   1.000000      1.000000       5.00000       1.088         .
 V   2    FR    4.74300      1.000000       5.00000           .      0.2570
 V   3    FR    3.82115      1.000000       5.00000           .       1.179
 V   4    FR    1.37941      1.000000       5.00000           .      0.3794

 L Con State     Value       Lower Bound   Upper Bound    Lagr Mult   Slack

 L   1    FR    10.9436          None       20.0000           .       9.056

 N Con State     Value       Lower Bound   Upper Bound    Lagr Mult   Slack

 N   1    UL    40.0000          None       40.0000     -0.1615     -3.5264E-11
 N   2    LL    25.0000       25.0000          None      0.5523     -2.8791E-11

 Exit E04UFF - Optimal solution found.

 Final objective value =    17.01402
 ** e04uf returned with ifail =   0

  Varbl    Istate      Value                  Lagr Mult

  V    1    1                     1           1.088
  V    2    0                 4.743               0
  V    3    0               3.82115               0
  V    4    0               1.37941               0

  L Con    Istate      Value                  Lagr Mult

  L    1    0               10.9436               0

  N Con    Istate      Value                  Lagr Mult

  N    1    2                    40         -0.1615
  N    2    1                    25          0.5523

  Final objective value =        17.01402


//      e04ug Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04UGE
  {
    static string datafile = "ExampleData/e04uge.d";
    // as a command line argument. It defaults to the named file specified below otherwise.
    //
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04UG_CONFUN confunE04UG = new E04.E04UG_CONFUN(confun);
      E04.E04UG_OBJFUN objfunE04UG = new E04.E04UG_OBJFUN(objfun);
      try
      {
        DataReader sr = new DataReader(datafile);
      double obj,   sinf; int i,  icol=0,  iobj,  j,  jcol,  m,  miniz,  minz,  n,  ncnln,  ninf,  njnln,  nname,  nnz,  nonln,  ns=0;
      string start="";
      int idummy = -11111;
      string[] names = new string[200];
      int ifail;
      Console.WriteLine("e04ug Example Program Results");
      //      Skip heading in data file.
      sr.Reset();
      sr.Reset();
      n = int.Parse(sr.Next());
      m = int.Parse(sr.Next());
      //
      //         Read ncnln, nonln and njnln from data file.
      //
      sr.Reset();
      ncnln = int.Parse(sr.Next());
      nonln = int.Parse(sr.Next());
      njnln = int.Parse(sr.Next());
      //
      //         Read nnz, iobj, start, nname and names from data file.
      //
      sr.Reset();
      nnz = int.Parse(sr.Next());
      iobj = int.Parse(sr.Next());
      start = sr.Next();
      nname = int.Parse(sr.Next());
      double[] a = new double[nnz];
      double[] bl = new double[n+m];
      double[] bu = new double[n+m];
      double[] clamda = new double[n+m];
      double[] user = new double[1];
      double[] xs = new double[n+m];
      int[] ha = new int[300];
      int[] istate = new int[n+m];
      int[] iuser = new int[1];
      int[] ka = new int[n+1];
      if (nname == n + m)
      {
        sr.Reset();
        for (i = 1 ; i <= n + m ; i++)
        {
          names[i - 1] = sr.Next();
        }
      }
      //
      //         Initialize ka.
      //
      for (i = 1 ; i <= n + 1 ; i++)
      {
        ka[i - 1] = idummy;
      }
      //
      //         Read the matrix a from data file. Set up ka.
      //
      jcol = 1;
      ka[jcol - 1] = 1;
      for (i = 1 ; i <= nnz ; i++)
      {
        //
        //            Element ( ha( i-1 ), icol-1 ) is stored in a[ i-1].
        //
        sr.Reset();
        a[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        ha[i - 1] = int.Parse(sr.Next());
        icol = int.Parse(sr.Next());
        //
        if (icol < jcol)
        {
          //
          //               Elements not ordered by increasing column index.
          //
          Console.WriteLine("\n  {0}{1,5}{2}{3,5}{4}{5}","Element in column",icol," found after element in column",jcol,". Problem"," abandoned.");
          goto L160;
        }
        else if (icol == jcol + 1)
        {
          //
          //               Index in a of the start of the icol-th column equals i.
          //
          ka[icol - 1] = i;
          jcol = (int)icol;
        }
        else if (icol > jcol + 1)
        {
          //
          //               Index in a of the start of the icol-th column equals i,
          //               but columns jcol+1,jcol+2,...,icol-1 are empty. Set the
          //               corresponding elements of ka to i.
          //
          for (j = jcol + 1 ; j <= icol - 1 ; j++)
          {
            ka[j - 1] = i;
          }
          ka[icol - 1] = i;
          jcol = (int)icol;
        }
      }
      //
      ka[n + 1 - 1] = nnz + 1;
      //
      if (n > icol)
      {
        //
        //            Columns n,n-1,...,icol+1 are empty. Set the corresponding
        //            elements of ka accordingly.
        //
        for (i = n ; i <= icol + 1 ; i +=  -1)
        {
          if (ka[i - 1] == idummy)
          {
            ka[i - 1] = ka[i + 1 - 1];
          }
        }
      }
      //
      //         Read bl, bu, istate, xs and clamda from data file.
      //
      sr.Reset();
      for (i = 1 ; i <= n + m ; i++)
      {
        bl[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
      }
      sr.Reset();
      for (i = 1 ; i <= n + m ; i++)
      {
        bu[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
      }
      if (start == "C")
      {
        sr.Reset();
        for (i = 1 ; i <= n ; i++)
        {
          istate[i - 1] = int.Parse(sr.Next());
        }
      }
      else if (start == "W")
      {
        sr.Reset();
        for (i = 1 ; i <= n + m ; i++)
        {
          istate[i - 1] = int.Parse(sr.Next());
        }
      }
      sr.Reset();
      for (i = 1 ; i <= n ; i++)
      {
        xs[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
      }
      if (ncnln > 0)
      {
        sr.Reset();
        for (i = n + 1 ; i <= n + ncnln ; i++)
        {
          clamda[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
      }
      // Switch off all output.
      PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
      PrintManager.Message = new PrintManager.MessageLogger(discardmessage);
      //
      //         Initialise E04.e04ug
      //
      E04.e04ugOptions options = new E04.e04ugOptions();
      //
      //            Solve the problem.
      //
      start="C";
      // First get appropriate minimum lengths of arrays, z and iz
      int leniz = 500;
      int lenz = 500;
      double[] z = new double[lenz];
      int[] iz = new int[leniz];
      E04.e04ug(confunE04UG, objfunE04UG, n, m, ncnln, nonln, njnln, iobj, nnz, a, ha, ka, bl,
      bu, start, nname, names, ref ns, xs, istate, clamda, out miniz, out minz, out ninf, out sinf,
      out obj, iz, z, options, out ifail);
      Console.WriteLine("Computed values of the size of z and iz are {0}, {1} respectively.", minz, miniz);
      //         Initialise E04.e04ug again and check for error exits
      PrintManager.Warning = new PrintManager.MessageLogger(printmessage);
      PrintManager.Message = new PrintManager.MessageLogger(printmessage);
      options = new E04.e04ugOptions();
      options.Set("List");
      options.Set("Print level = 10");
      //
      //            Solve the problem.
      //
      start="C";
      // The minimum values of lenz and leniz found above are only a preliminary estimate.
      // In practice, larger values need to be chosen frequently, we have therefore specified
      // each of leniz and lenz as 1000.
      leniz = 1000;
      lenz = 1000;
      z = new double[lenz];
      iz = new int[leniz];
      E04.e04ug(confunE04UG, objfunE04UG, n, m, ncnln, nonln, njnln, iobj, nnz, a, ha, ka, bl,
      bu, start, nname, names, ref ns, xs, istate, clamda, out miniz, out minz, out ninf, out sinf,
      out obj, iz, z, options, out ifail);
      //
      //            Check for error exits
      //
      Console.WriteLine("");
      if (ifail >= (7))
      {
        Console.WriteLine(" ** e04ug returned with ifail = {0, 3}", ifail);
      }
      else if (ifail >= 0)
      {
        Console.WriteLine(" ** e04ug returned with ifail = {0, 3}", ifail);
        Console.WriteLine("");
        Console.WriteLine("  Variable    Istate          Value                  Lagr Mult");
        Console.WriteLine("");
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine("  Varble  {0,2}  {1,3}        {2,14:g6}    {3,12:g4}",i,istate[i - 1],xs[i - 1],clamda[i - 1]);
        }
        Console.WriteLine("");
        Console.WriteLine("");
        Console.WriteLine("  Constrnt    Istate          Value                  Lagr Mult");
        Console.WriteLine("");
        if (ncnln > 0)
        {
          for (i = n + 1 ; i <= n + ncnln ; i++)
          {
            j = i - n;
            Console.WriteLine("  NlnCon  {0,2}  {1,3}        {2,14:g6}    {3,12:g4}",j,istate[i - 1],xs[i - 1],clamda[i - 1]);
          }
        }
        if ((((ncnln == 0)) && ((m == 1))) && ((a[0] == 0.00e0)))
        {
          Console.WriteLine("  DummyRow    {0,3}        {1,14:g6}    {2,12:g4}",istate[n + 1 - 1],xs[n + 1 - 1],clamda[n + 1 - 1]);
        }
        else if (m > ncnln)
        {
          for (i = n + ncnln + 1 ; i <= n + m ; i++)
          {
            j = i - n - ncnln;
            if (i - n == iobj)
            {
              Console.WriteLine("  Free Row    {0,3}        {1,14:g6}    {2,12:g4}",istate[i - 1],xs[i - 1],clamda[i - 1]);
            }
            else
            {
              Console.WriteLine("  LinCon  {0,2}  {1,3}        {2,14:g6}    {3,12:g4}",j,istate[i - 1],xs[i - 1],clamda[i - 1]);
            }
          }
        }
        Console.WriteLine("");
        Console.WriteLine("");
        Console.WriteLine("  Final objective value = {0,15:g7}",obj);
      }
      else
      {
        Console.WriteLine(" ** e04ug returned with ifail = {0, 3}", ifail);
      }
      //
      L160: ;
      //
      }catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
    //
    public static void confun (ref int mode, int ncnln, int njnln, int nnzjac,
    double[] x, double[] f, double[] fjac, int nstate)
    {
      //      Computes the nonlinear constraint functions and their Jacobian.
      if ((mode == 0) || (mode == 2))
      {
        f[0] = 1000.00e+0 * Math.Sin( -x[0] - 0.250e+0) + 1000.00e+0 * Math.Sin( -x[1] - 0.250e+0);
        f[1] = 1000.00e+0 * Math.Sin(x[0] - 0.250e+0) + 1000.00e+0 * Math.Sin(x[0] - x[1] - 0.250e+0);
        f[2] = 1000.00e+0 * Math.Sin(x[1] - x[0] - 0.250e+0) + 1000.00e+0 * Math.Sin(x[1] - 0.250e+0);
      }
      //
      if ((mode == 1) || (mode == 2))
      {
        //
        //         Nonlinear Jacobian elements for column 1.
        //
        fjac[0] =  -1000.00e+0 * Math.Cos( -x[0] - 0.250e+0);
        fjac[1] = 1000.00e+0 * Math.Cos(x[0] - 0.250e+0) + 1000.00e+0 * Math.Cos(x[0] - x[1] - 0.250e+0);
        fjac[2] =  -1000.00e+0 * Math.Cos(x[1] - x[0] - 0.250e+0);
        //
        //         Nonlinear Jacobian elements for column 2.
        //
        fjac[3] =  -1000.00e+0 * Math.Cos( -x[1] - 0.250e+0);
        fjac[4] =  -1000.00e+0 * Math.Cos(x[0] - x[1] - 0.250e+0);
        fjac[5] = 1000.00e+0 * Math.Cos(x[1] - x[0] - 0.250e+0) + 1000.00e+0 * Math.Cos(x[1] - 0.250e+0);
      }
      //
    }
    //
    public static void objfun (ref int mode, int nonln, double[] x, ref double objf,
    double[] objgrd, int nstate)
    {
      //      Computes the nonlinear part of the objective function and its
      //      gradient
      if ((mode == 0) || (mode == 2))
      {
        objf = 1.00e-6 * Math.Pow(x[2] ,3) + 2.00e-6 * Math.Pow(x[3] ,3) / 3.00e+0;
      }
      //
      if ((mode == 1) || (mode == 2))
      {
        objgrd[0] = 0.00e+0;
        objgrd[1] = 0.00e+0;
        objgrd[2] = 3.00e-6 * (x[2])*(x[2]);
        objgrd[3] = 2.00e-6 * (x[3])*(x[3]);
      }
      //
    }
    static void discardmessage(String message)
    {
    }
    static void printmessage(String message)
    {
      Console.WriteLine(message);
    }
  }
}


e04ug Example Program Results
Computed values of the size of z and iz are 758, 628 respectively.

 Calls to E04UGF
 ---------------

      List
      Print level = 10

 *** E04UGF

 Parameters
 ----------

 Frequencies.
 Check frequency.........        60       Expand frequency.......     10000
 Factorization frequency.        50

 QP subproblems.
 Scale tolerance.........  9.00E-01       Minor feasibility tol..  1.05E-08
 Scale option............         1       Minor optimality tol...  1.05E-08
 Partial price...........         1       Crash tolerance........  1.00E-01
 Pivot tolerance.........  2.04E-11       Minor print level......         0
 Crash option............         0       Elastic weight.........  1.00E+02

 The SQP method.
 Minimize................
 Nonlinear objective vars         4       Major optimality tol...  1.05E-08
 Function precision......  1.72E-13       Unbounded step size....  1.00E+20
 Superbasics limit.......         4       Forward difference int.  4.15E-07
 Unbounded objective.....  1.00E+15       Central difference int.  5.56E-05
 Major step limit........  2.00E+00       Derivative linesearch..
 Derivative level........         3       Major iteration limit..      1000
 Linesearch tolerance....  9.00E-01       Verify level...........         0
 Minor iteration limit...       500       Major print level......        10
 Infinite bound size.....  1.00E+20       Iteration limit........     10000

 Hessian approximation.
 Hessian full memory.....                 Hessian updates........  99999999
 Hessian frequency.......  99999999

 Nonlinear constraints.
 Nonlinear constraints...         3       Major feasibility tol..  1.05E-08
 Nonlinear Jacobian vars.         2       Violation limit........  1.00E+01

 Miscellaneous.
 Variables...............         4       Linear constraints.....         3
 Nonlinear variables.....         4       Linear variables.......         0
 LU factor tolerance.....  5.00E+00       LU singularity tol.....  2.04E-11
 LU update tolerance.....  5.00E+00       LU density tolerance...  6.00E-01
 eps (machine precision).  1.11E-16       Monitoring file........        -1
 COLD start..............                 Infeasible exit........

 Workspace provided is                 IZ(    1000),  Z(    1000).
 To start solving the problem we need  IZ(     628),  Z(     758).

 Itn      0 -- Scale option reduced from                1 to                0.

 Itn      0 -- Feasible linear rows.

 Itn      0 -- Norm(x-x0) minimized. Sum of infeasibilities = 0.00E+00.

 confun  sets       6   out of       6   constraint gradients.
 objfun  sets       4   out of       4   objective  gradients.

 Cheap test on confun...

 The Jacobian seems to be OK.

 The largest discrepancy was    4.41E-08  in constraint     2.

 Cheap test on objfun...

 The objective gradients seem to be OK.
 Gradient projected in two directions   0.00000000000E+00   0.00000000000E+00
 Difference approximations              1.74111992322E-19   4.48742248252E-21

 Itn      0 -- All-slack basis B = I selected.

 Itn      7 -- Large multipliers.
               Elastic mode started with weight =  2.0E+02.

  Maj  Mnr    Step Merit Function Feasibl Optimal Cond Hz PD
    0   10 0.0E+00   3.199952E+05 1.7E+00 8.0E-01 2.1E+06 FF  R   i
    1    2 1.0E+00   2.463016E+05 1.2E+00 3.2E+03 4.5E+00 FF s
    2    1 1.0E+00   1.001802E+04 3.3E-02 9.2E+01 4.5E+00 FF
    3    1 1.0E+00   5.253418E+03 6.6E-04 2.5E+01 4.8E+00 FF
    4    1 1.0E+00   5.239444E+03 2.0E-06 2.8E+01 1.0E+02 FF
    5    1 1.0E+00   5.126208E+03 6.0E-04 5.9E-01 1.1E+02 FF
    6    1 1.0E+00   5.126498E+03 4.7E-07 2.9E-02 1.0E+02 FF
    7    1 1.0E+00   5.126498E+03 5.9E-10 1.5E-03 1.1E+02 TF
    8    1 1.0E+00   5.126498E+03 1.2E-12 7.6E-09 1.1E+02 TT

 Exit from NP problem after     8 major iterations,
                               19 minor iterations.

 Variable State     Value       Lower Bound  Upper Bound   Lagr Mult  Residual

 Varble 1    BS   0.118876     -0.55000      0.55000     -1.2529E-07  0.4311
 Varble 2    BS  -0.396234     -0.55000      0.55000      1.9243E-08  0.1538
 Varble 3    BS    679.945           .        1200.0      1.7001E-10   520.1
 Varble 4   SBS    1026.07           .        1200.0     -2.1918E-10   173.9

 Constrnt State     Value       Lower Bound  Upper Bound   Lagr Mult  Residual

 NlnCon 1    EQ   -894.800      -894.80      -894.80      -4.387      3.3644E-09
 NlnCon 2    EQ   -894.800      -894.80      -894.80      -4.106      6.0072E-10
 NlnCon 3    EQ   -1294.80      -1294.8      -1294.8      -5.463      3.3549E-09
 LinCon 1    BS  -0.515110     -0.55000          None          .      3.4890E-02
 LinCon 2    BS   0.515110     -0.55000          None          .       1.065
 Free Row    BS    4091.97          None         None    -1.0000       4092.

 Exit E04UGF - Optimal solution found.

 Final objective value =     5126.498

 ** e04ug returned with ifail =   0

  Variable    Istate          Value                  Lagr Mult

  Varble   1    3              0.118876      -1.253e-07
  Varble   2    3             -0.396234       1.924e-08
  Varble   3    3               679.945         1.7e-10
  Varble   4    2               1026.07      -2.192e-10

  Constrnt    Istate          Value                  Lagr Mult

  NlnCon   1    0                -894.8          -4.387
  NlnCon   2    0                -894.8          -4.106
  NlnCon   3    0               -1294.8          -5.463
  LinCon   1    3              -0.51511               0
  LinCon   2    3               0.51511               0
  Free Row      3               4091.97              -1

  Final objective value =        5126.498


//      e04us Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04USE
  {
    static string datafile = "ExampleData/e04use.d";
    // as a command line argument. It defaults to the named file specified below otherwise.
    //
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04US_CONFUN confunE04US = new E04.E04US_CONFUN(confun);
      E04.E04US_OBJFUN objfunE04US = new E04.E04US_OBJFUN(objfun);
      try
      {
        DataReader sr = new DataReader(datafile);
        double objf = 0.0;
        int i,   iter,   j,   m,   n,   nclin,   ncnln; int ifail;
        Console.WriteLine("e04us Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        m = int.Parse(sr.Next());
        n = int.Parse(sr.Next());
        sr.Reset();
        nclin = int.Parse(sr.Next());
        ncnln = int.Parse(sr.Next());
        double[,] a = new double[nclin, n];
        double[] bl = new double[nclin+ncnln+n];
        double[] bu = new double[nclin+ncnln+n];
        double[] c = new double[ncnln];
        double[,] cjac = new double[ncnln, n];
        double[] clamda = new double[nclin+ncnln+n];
        double[] f = new double[m];
        double[,] fjac = new double[m, n];
        double[,] r = new double[n, n];
        double[] work = new double[n+nclin];
        double[] x = new double[n];
        double[] y = new double[m];
        int[] istate = new int[nclin+ncnln+n];
        //
        //         Read a, y, bl, bu and x from data file
        //
        if (nclin > 0)
        {
          sr.Reset();
          for (i = 1; i <= nclin; i++)
          {
            for (j = 1; j <= n; j++)
            {
              a[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
        }
        sr.Reset();
        for (i = 1; i <= m; i++)
        {
          y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        sr.Reset();
        for (i = 1; i <= n + nclin + ncnln; i++)
        {
          bl[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        sr.Reset();
        for (i = 1; i <= n + nclin + ncnln; i++)
        {
          bu[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        //
        //         Initialise e04.e04us and check for error exits
        //
        E04.e04usOptions options = new E04.e04usOptions();
        options.Set("List");
        options.Set("Print level = 10");
        //
        //            Solve the problem
        //
        E04.e04us(m, n, nclin, ncnln, a, bl, bu, y, confunE04US, objfunE04US, out iter, istate, c,
        cjac, f, fjac, clamda, out objf, r, x, options, out ifail);
        //
        //            Check for error exits
        //
        Console.WriteLine("");
        if (ifail == 9)
        {
          Console.WriteLine("   ** An input parameter is invalid");
        }
        else if (ifail >= 0)
        {
          Console.WriteLine(" ** e04us returned with ifail = {0, 3}", ifail);
          Console.WriteLine("");
          Console.WriteLine("  Varbl    Istate      Value                  Lagr Mult");
          Console.WriteLine("");
          for (i = 1; i <= n; i++)
          {
            Console.WriteLine("  V  {0,3}  {1,3}        {2,14:g6}    {3,12:g4}", i, istate[i - 1], x[i - 1], clamda[i - 1]);
          }
          if (nclin > 0)
          {
            //
            //                  This performs the matrix vector multiplication A*X
            //                  (linear constraint values) and puts the result in
            //                  the first nclin locations of work.
            //
            F06.f06pa("N", nclin, n, 1.00e0, a, x, 1, 0.00e0, work, 1, out ifail);
            Console.WriteLine("");
            Console.WriteLine("");
            Console.WriteLine("  L Con    Istate      Value                  Lagr Mult");
            Console.WriteLine("");
            for (i = n + 1; i <= n + nclin; i++)
            {
              j = i - n;
              Console.WriteLine("  L  {0,3}  {1,3}        {2,14:g6}    {3,12:g4}", j, istate[i - 1],
              work[j - 1], clamda[i - 1]);
            }
          }
          if (ncnln > 0)
          {
            Console.WriteLine("");
            Console.WriteLine("");
            Console.WriteLine("  N Con    Istate      Value                  Lagr Mult");
            Console.WriteLine("");
            for (i = n + nclin + 1; i <= n + nclin + ncnln; i++)
            {
              j = i - n - nclin;
              Console.WriteLine("  N  {0,3}  {1,3}        {2,14:g6}    {3,12:g4}", j, istate[i - 1], c[j - 1], clamda[i - 1]);
            }
          }
          Console.WriteLine("");
          Console.WriteLine("");
          Console.WriteLine("  Final objective value = {0,15:g7}", objf);
        }
        if (ifail < 0)
        {
          Console.WriteLine("  MODE < 0 on exit from OBJFUN or CONFUN.\n\n Problem abandoned.");
        }
        //
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
    public static void objfun(ref int mode, int m, int n, int needfi, double[] x,
    double[] f, double[,] fjac, int nstate)
    {
      //      Evaluates the vector f(x) and its first derivatives.
      double pt49 = 0.490e0;
      double one = 1.00e0;
      double eight = 8.00e0;
      double ai,   temp,   x1,   x2; int i;
      bool mode02 = false,
      mode12 = false;
      double[] a = new double[44] { 8.00e0, 8.00e0, 10.00e0, 10.00e0, 10.00e0, 10.00e0,
      12.00e0, 12.00e0, 12.00e0, 12.00e0, 14.00e0, 14.00e0,
      14.00e0, 16.00e0, 16.00e0, 16.00e0, 18.00e0, 18.00e0,
      20.00e0, 20.00e0, 20.00e0, 22.00e0, 22.00e0, 22.00e0,
      24.00e0, 24.00e0, 24.00e0, 26.00e0, 26.00e0, 26.00e0,
      28.00e0, 28.00e0, 30.00e0, 30.00e0, 30.00e0, 32.00e0,
      32.00e0, 34.00e0, 36.00e0, 36.00e0, 38.00e0, 38.00e0, 40.00e0, 42.00e0 };
      x1 = x[0];
      x2 = x[1];
      mode02 = ((mode == 0) || (mode == 2));
      mode12 = ((mode == 1) || (mode == 2));
      for (i = 1; i <= m; i++)
      {
        if (needfi == i)
        {
          f[i - 1] = x1 + (pt49 - x1) * Math.Exp(-x2 * (a[i - 1] - eight));
        }
        else
        {
          ai = a[i - 1];
          temp = Math.Exp(-x2 * (ai - eight));
          if (mode02)
          {
            f[i - 1] = x1 + (pt49 - x1) * temp;
          }
          if (mode12)
          {
            fjac[i - 1, 0] = one - temp;
            fjac[i - 1, 1] = -(pt49 - x1) * (ai - eight) * temp;
          }
        }
      }
      //
    }
    //
    public static void confun(ref int mode, int ncnln, int n, int[] needc, double[] x,
    double[] c, double[,] cjac, int nstate)
    {
      //      Evaluates the vector c(x) and its first derivatives.
      double zero = 0.00e0;
      double pt09 = 0.090e0;
      double pt49 = 0.490e0;
      int i, j;
      if (nstate == 1)
      {
        // First call to confun.  Set all Jacobian elements to zero.
        // Note that this will only work when 'Derivative Level = 3'
        // (the default; see Section 11.2).
        for (j = 1; j <= n; j++)
        {
          for (i = 1; i <= ncnln; i++)
          {
            cjac[i - 1, j - 1] = zero;
          }
        }
      }
      //
      if (needc[0] > 0)
      {
        if ((mode == 0) || (mode == 2))
        {
          c[0] = -pt09 - x[0] * x[1] + pt49 * x[1];
        }
        if ((mode == 1) || (mode == 2))
        {
          cjac[0, 0] = -x[1];
          cjac[0, 1] = -x[0] + pt49;
        }
      }
      //
    }
  }
}


e04us Example Program Results

 Calls to E04USF
 ---------------

      List
      Print level = 10

 *** E04USF

 Parameters
 ----------

 Linear constraints.....         1       Variables..............         2
 Nonlinear constraints..         1       Subfunctions...........        44

 Infinite bound size....  1.00E+20       COLD start.............
 Infinite step size.....  1.00E+20       EPS (machine precision)  1.11E-16
 Step limit.............  2.00E+00       Hessian................        NO

 Linear feasibility.....  1.05E-08       Crash tolerance........  1.00E-02
 Nonlinear feasibility..  1.05E-08       Optimality tolerance...  3.26E-12
 Line search tolerance..  9.00E-01       Function precision.....  4.37E-15

 Derivative level.......         3       Monitoring file........        -1
 Verify level...........         0

 Major iterations limit.        50       Major print level......        10
 Minor iterations limit.        50       Minor print level......         0

 J'J initial Hessian....                 Reset frequency........         2

 Workspace provided is     IWORK(       9),  WORK(     306).
 To solve problem we need  IWORK(       9),  WORK(     306).

 Verification of the constraint gradients.
 -----------------------------------------

 The constraint Jacobian seems to be ok.

 The largest relative error was    1.89E-08  in constraint    1

 Verification of the objective gradients.
 ----------------------------------------

 The objective Jacobian seems to be ok.

 The largest relative error was    1.04E-08  in subfunction    3

  Maj  Mnr    Step Merit Function Norm Gz  Violtn Cond Hz
    0    2 0.0E+00   2.224070E-02 8.5E-02 3.6E-02 1.0E+00
    1    1 1.0E+00   1.455402E-02 1.5E-03 9.8E-03 1.0E+00
    2    1 1.0E+00   1.436491E-02 4.9E-03 7.2E-04 1.0E+00
    3    1 1.0E+00   1.427013E-02 2.9E-03 9.2E-06 1.0E+00
    4    1 1.0E+00   1.422989E-02 1.6E-04 3.6E-05 1.0E+00
    5    1 1.0E+00   1.422983E-02 5.4E-07 6.4E-08 1.0E+00
    6    1 1.0E+00   1.422983E-02 3.4E-09 9.8E-13 1.0E+00

 Exit from NP problem after     6 major iterations,
                                8 minor iterations.

 Varbl State     Value       Lower Bound   Upper Bound    Lagr Mult   Slack

 V   1    FR   0.419953      0.400000          None           .      1.9953E-02
 V   2    FR    1.28485      -4.00000          None           .       5.285

 L Con State     Value       Lower Bound   Upper Bound    Lagr Mult   Slack

 L   1    FR    1.70480      1.000000          None           .      0.7048

 N Con State     Value       Lower Bound   Upper Bound    Lagr Mult   Slack

 N   1    LL  -9.767742E-13       .            None      3.3358E-02 -9.7677E-13

 Exit E04USF - Optimal solution found.

 Final objective value =   0.1422983E-01

 ** e04us returned with ifail =   0

  Varbl    Istate      Value                  Lagr Mult

  V    1    0              0.419953               0
  V    2    0               1.28485               0

  L Con    Istate      Value                  Lagr Mult

  L    1    0                1.7048               0

  N Con    Istate      Value                  Lagr Mult

  N    1    1          -9.76774e-13         0.03336

  Final objective value =      0.01422983


//      e04vh Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04VHE
  {
    static string datafile = "ExampleData/e04vhe.d";
    // as a command line argument. It defaults to the named file specified below otherwise.
    //
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04VH_USRFUN usrfunE04VH = new E04.E04VH_USRFUN(usrfun);
      try
      {
        DataReader sr = new DataReader(datafile);
        double objadd,   sinf; int i,  lena,  leng,  n,  nea,  neg,  nf,  nfname,  ninf,  ns=0,  nxname,  objrow,  start;
        string prob="";
        int ifail;
        Console.WriteLine("e04vh Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        nf = int.Parse(sr.Next());
        sr.Reset();
        nea = int.Parse(sr.Next());
        neg = int.Parse(sr.Next());
        objrow = int.Parse(sr.Next());
        start = int.Parse(sr.Next());
        //
        lena = Math.Max(1, nea);
        leng = Math.Max(1, neg);
        nxname = (int)n;
        nfname = (int)nf;
        double[] a = new double[lena];
        double[] f = new double[nf];
        double[] flow = new double[nf];
        double[] fmul = new double[nf];
        double[] fupp = new double[nf];
        double[] x = new double[n];
        double[] xlow = new double[n];
        double[] xmul = new double[n];
        double[] xupp = new double[n];
        int[] fstate = new int[nf];
        int[] iafun = new int[lena];
        int[] igfun = new int[leng];
        int[] javar = new int[lena];
        int[] jgvar = new int[leng];
        int[] xstate = new int[n];
        string[] fnames = new string[nf];
        string[] xnames = new string[n];
        objadd = 0.00e0;
        prob = "";
        //
        //         Read the variable names xnames
        sr.Reset();
        for (i = 1 ; i <= nxname ; i++)
        {
          xnames[i - 1] = sr.Next();
        }
        //         Read the function names fnames
        sr.Reset();
        for (i = 1 ; i <= nfname ; i++)
        {
          fnames[i - 1] = sr.Next();
        }
        //
        //         Read the sparse matrix A, the linear part of F
        for (i = 1 ; i <= nea ; i++)
        {
          //            For each element read row, column, A(row,column)
          sr.Reset();
          iafun[i - 1] = int.Parse(sr.Next());
          javar[i - 1] = int.Parse(sr.Next());
          a[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        //
        //         Read the structure of sparse matrix G, the nonlinear part of F
        for (i = 1 ; i <= neg ; i++)
        {
          //            For each element read row, column
          sr.Reset();
          igfun[i - 1] = int.Parse(sr.Next());
          jgvar[i - 1] = int.Parse(sr.Next());
        }
        //
        //         Read the lower and upper bounds on the variables
        for (i = 1 ; i <= n ; i++)
        {
          sr.Reset();
          xlow[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          xupp[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        //
        //         Read the lower and upper bounds on the functions
        for (i = 1 ; i <= nf ; i++)
        {
          sr.Reset();
          flow[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          fupp[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        //
        //         Initialise x, xstate, xmul, f, fstate, fmul
        sr.Reset();
        for (i = 1 ; i <= n ; i++)
        {
          x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        sr.Reset();
        for (i = 1 ; i <= n ; i++)
        {
          xstate[i - 1] = int.Parse(sr.Next());
        }
        sr.Reset();
        for (i = 1 ; i <= n ; i++)
        {
          xmul[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        sr.Reset();
        for (i = 1 ; i <= nf ; i++)
        {
          f[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        sr.Reset();
        for (i = 1 ; i <= nf ; i++)
        {
          fstate[i - 1] = int.Parse(sr.Next());
        }
        sr.Reset();
        for (i = 1 ; i <= nf ; i++)
        {
          fmul[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        //
        //         Initialise e04vh.
        E04.e04vhOptions options = new E04.e04vhOptions();
        //
        //         By default e04vh does not print monitoring
        //         information. Set the print file unit or the summary
        //         file unit to get information.
        options.Set("Print file = 6");
        //
        //         Solve the problem.
        E04.e04vh(start, nf, n, nxname, nfname, objadd, objrow, prob, usrfunE04VH, iafun, javar,
        nea, a, igfun, jgvar, neg, xlow, xupp, xnames, flow, fupp, fnames, x, xstate, xmul, f, fstate,
        fmul, ref ns, out ninf, out sinf, options, out ifail);
        //
        Console.WriteLine("");
        if (ifail >= 0)
        {
          Console.WriteLine("  On exit from e04vh, ifail = {0,5}",ifail);
          if (ifail == 0)
          {
            Console.WriteLine("  Final objective value = {0,11:f1}\n",f[objrow - 1]);
            Console.Write("  Optimal x = ");
            for (i = 1 ; i <= n ; i++)
            {
              Console.Write(" " +" {0, 9:f2}", x[i - 1]);
            }
            Console.WriteLine(" ");
          }
        }
        else
        {
          Console.WriteLine(" ** e04vh returned with ifail = {0, 3}", ifail);
        }
        //
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
    //
    public static void usrfun (ref int status, int n, double[] x, int needf, int nf,
    double[] f, int needg, double[] g)
    {
      if (needf > 0)
      {
        //         The nonlinear components of f_i(x) need to be assigned,
        //         from i = 0 to nf-1
        f[0] = 1000.00e+0 * Math.Sin( -x[0] - 0.250e+0) + 1000.00e+0 * Math.Sin( -x[1] - 0.250e+0);
        f[1] = 1000.00e+0 * Math.Sin(x[0] - 0.250e+0) + 1000.00e+0 * Math.Sin(x[0] - x[1] - 0.250e+0);
        f[2] = 1000.00e+0 * Math.Sin(x[1] - x[0] - 0.250e+0) + 1000.00e+0 * Math.Sin(x[1] - 0.250e+0);
        //         N.B. in this example there is no need to assign for the wholly
        //         linear components f_4(x) and f_5(x).
        f[5] = 1.00e-6 * Math.Pow(x[2] ,3) + 2.00e-6 * Math.Pow(x[3] ,3) / 3.00e+0;
      }
      //
      if (needg > 0)
      {
        //         The derivatives of the function f_i(x) need to be assigned.
        //         g[k-1] should be set to partial derivative df_i(x)/dx_j where
        //         i = igfun[k-1] and j = igvar[k-1], for k = 1 to g.Length().
        g[0] =  -1000.00e+0 * Math.Cos( -x[0] - 0.250e+0);
        g[1] =  -1000.00e+0 * Math.Cos( -x[1] - 0.250e+0);
        g[2] = 1000.00e+0 * Math.Cos(x[0] - 0.250e+0) + 1000.00e+0 * Math.Cos(x[0] - x[1] - 0.250e+0);
        g[3] =  -1000.00e+0 * Math.Cos(x[0] - x[1] - 0.250e+0);
        g[4] =  -1000.00e+0 * Math.Cos(x[1] - x[0] - 0.250e+0);
        g[5] = 1000.00e+0 * Math.Cos(x[1] - x[0] - 0.250e+0) + 1000.00e+0 * Math.Cos(x[1] - 0.250e+0);
        g[6] = 3.00e-6 * (x[2])*(x[2]);
        g[7] = 2.00e-6 * (x[3])*(x[3]);
      }
      //
    }
  }
}


e04vh Example Program Data
 4   6          : Values of N and NF
 8   8   6   0  : Values of NEA, NEG, OBJROW and START

'X1'  'X2'  'X3'  'X4'  : XNAMES
'NlnCon 1'  'NlnCon 2'  'NlnCon 3'  'LinCon 1'  'LinCon 2'  'Objectiv' : FNAMES

1  3 -1.0E0  : Nonzero elements of sparse matrix A, the linear part of F.
2  4 -1.0E0  : Each row IAFUN(i), JAVAR(i), A(IAFUN(i),JAVAR(i)), i = 1 to NEA
4  1 -1.0E0
4  2  1.0E0
5  1  1.0E0
5  2 -1.0E0
6  3  3.0E0
6  4  2.0E0

1  1     : Nonzero row/column structure of G, IGFUN(i), JGVAR(i), i = 1 to NEG
1  2
2  1
2  2
3  1
3  2
6  3
6  4

-0.55E0    0.55E0  : Bounds on the variables, XLOW(i), XUPP(i), for i = 1 to N
-0.55E0    0.55E0
 0.0E0   1200.0E0
 0.0E0   1200.0E0

 -894.8E0 -894.8E0 : Bounds on the functions, FLOW(i), FUPP(i), for i = 1 to NF
 -894.8E0 -894.8E0
-1294.8E0 -1294.8E0
-0.55E0    1.0E25
-0.55E0    1.0E25
-1.0E25    1.0E25

 0.0  0.0  0.0  0.0           : Initial values of X(i), for i = 1 to N
 0    0    0    0             : Initial values of XSTATE(i), for i = 1 to N
 0.0  0.0  0.0  0.0           : Initial values of XMUL(i), for i = 1 to N

 0.0  0.0  0.0  0.0  0.0  0.0 : Initial values of F(i), for i = 1 to NF
 0    0    0    0    0    0   : Initial values of FSTATE(i), for i = 1 to NF
 0.0  0.0  0.0  0.0  0.0  0.0 : Initial values of FMUL(i), for i = 1 to NF


e04vh Example Program Results

 Parameters
 ==========

 Files
 -----
 Solution file..........         0       Old basis file ........         0       (Print file)...........         6
 Insert file............         0       New basis file ........         0       (Summary file).........         0
 Punch file.............         0       Backup basis file......         0
 Load file..............         0       Dump file..............         0

 Frequencies
 -----------
 Print frequency........       100       Check frequency........        60       Save new basis map.....       100
 Summary frequency......       100       Factorization frequency        50       Expand frequency.......     10000

 QP subproblems
 --------------
 QPsolver Cholesky......
 Scale tolerance........     0.900       Minor feasibility tol..  1.00E-06       Iteration limit........     10000
 Scale option...........         0       Minor optimality  tol..  1.00E-06       Minor print level......         1
 Crash tolerance........     0.100       Pivot tolerance........  2.04E-11       Partial price..........         1
 Crash option...........         3       Elastic weight.........  1.00E+04       Prtl price section ( A)         4
                                         New superbasics........        99       Prtl price section (-I)         6

 The SQP Method
 --------------
 Minimize...............                 Cold start.............                 Proximal Point method..         1
 Nonlinear objectiv vars         4       Objective Row..........         6       Function precision.....  1.72E-13
 Unbounded step size....  1.00E+20       Superbasics limit......         4       Difference interval....  4.15E-07
 Unbounded objective....  1.00E+15       Reduced Hessian dim....         4       Central difference int.  5.57E-05
 Major step limit.......  2.00E+00       Derivative linesearch..                 Derivative option......         1
 Major iterations limit.      1000       Linesearch tolerance...   0.90000       Verify level...........         0
 Minor iterations limit.       500       Penalty parameter......  0.00E+00       Major Print Level......         1
                                         Major optimality tol...  2.00E-06

 Hessian Approximation
 ---------------------
 Full-Memory Hessian....                 Hessian updates........  99999999       Hessian frequency......  99999999
                                                                                Hessian flush..........  99999999

 Nonlinear constraints
 ---------------------
 Nonlinear constraints..         3       Major feasibility tol..  1.00E-06       Violation limit........  1.00E+06
 Nonlinear Jacobian vars         2

 Miscellaneous
 -------------
 LU factor tolerance....      3.99       LU singularity tol.....  2.04E-11       Timing level...........         0
 LU update tolerance....      3.99       LU swap tolerance......  1.03E-04       Debug level............         0
 LU partial  pivoting...                 eps (machine precision)  1.11E-16       System information.....        No

 Matrix statistics
 -----------------
               Total      Normal        Free       Fixed     Bounded
 Rows              6           2           1           3           0
 Columns           4           0           0           0           4

 No. of matrix elements                   14     Density      58.333
 Biggest                          1.0000E+00  (excluding fixed columns,
 Smallest                         0.0000E+00   free rows, and RHS)

 No. of objective coefficients             2
 Biggest                          3.0000E+00  (excluding fixed columns)
 Smallest                         2.0000E+00

 Nonlinear constraints       3     Linear constraints       3
 Nonlinear variables         4     Linear variables         0
 Jacobian  variables         2     Objective variables      4
 Total constraints           6     Total variables          4

 The user has defined       8   out of       8   first  derivatives

 Cheap test of user-supplied problem derivatives...

 The constraint gradients seem to be OK.

 -->  The largest discrepancy was    2.20E-08  in constraint     6

 The objective  gradients seem to be OK.

 Gradient projected in one direction   0.00000000000E+00
 Difference approximation              4.48709939860E-21

   Itns Major Minors    Step   nCon  Feasible   Optimal  MeritFunction     L+U BSwap     nS  condHz Penalty
      3     0      3              1   8.0E+02   1.0E+00  0.0000000E+00      17            1 1.7E+07         _  r
      4     1      1 1.2E-03      2   4.0E+02   9.9E-01  9.6317131E+05      16            1 4.8E+06 2.8E+00 _n rl
      5     2      1 1.3E-03      3   2.7E+02   5.5E-01  9.6122945E+05      16                      2.8E+00 _s  l
      5     3      0 7.5E-03      4   8.8E+01   5.4E-01  9.4691061E+05      16                      2.8E+00 _   l
      5     4      0 2.3E-02      5   2.9E+01   5.3E-01  9.0468403E+05      16                      2.8E+00 _   l
      5     5      0 6.9E-02      6   8.9E+00   5.0E-01  7.8452897E+05      16                      2.8E+00 _   l
      6     6      1 2.2E-01      7   2.3E+00   5.5E+01  4.8112339E+05      16            1 8.7E+03 2.8E+00 _   l
      7     7      1 8.3E-01      8   1.7E-01   4.2E+00  2.6898257E+04      16            1 7.6E+03 2.8E+00 _   l
      8     8      1 1.0E+00      9   1.8E-02   8.7E+01  6.2192920E+03      15     1      1 1.2E+02 2.8E+00 _
      9     9      1 1.0E+00     10   1.7E-02   7.9E+00  5.4526185E+03      15            1 9.4E+01 2.8E+00 _
     10    10      1 1.0E+00     11   1.7E-04   9.6E-01  5.1266089E+03      15            1 1.0E+02 2.8E+00 _
     11    11      1 1.0E+00     12   1.7E-06   5.8E-02  5.1264988E+03      15            1 9.5E+01 2.8E+00 _
     12    12      1 1.0E+00     13 ( 1.2E-08)  6.9E-05  5.1264981E+03      15            1 9.5E+01 2.8E+00 _
     13    13      1 1.0E+00     14 ( 6.7E-15)( 3.0E-09) 5.1264981E+03      15            1 9.5E+01 6.0E+00 _

 E04VHU EXIT   0 -- finished successfully
 E04VHU INFO   1 -- optimality conditions satisfied

 Problem name
 No. of iterations                  13   Objective value      5.1264981096E+03
 No. of major iterations            13   Linear objective     4.0919702248E+03
 Penalty parameter           6.032E+00   Nonlinear objective  1.0345278848E+03
 No. of calls to funobj             15   No. of calls to funcon             15
 No. of superbasics                  1   No. of basic nonlinears             3
 No. of degenerate steps             0   Percentage                       0.00
 Max x                       4 1.0E+03   Max pi                      3 5.5E+00
 Max Primal infeas           0 0.0E+00   Max Dual infeas             1 4.6E-08
 Nonlinear constraint violn    5.7E-12

 Name                                    Objective Value      5.1264981096E+03

 Status         Optimal Soln             Iteration     13    Superbasics     1

 Objective               (Min)
 RHS
 Ranges
 Bounds

 Section 1 - Rows

  Number  ...Row.. State  ...Activity...  Slack Activity  ..Lower Limit.  ..Upper Limit.  .Dual Activity    ..i

       5  NlnCon 1    EQ      -894.80000         0.00000      -894.80000      -894.80000        -4.38698      1
       6  NlnCon 2    EQ      -894.80000         0.00000      -894.80000      -894.80000        -4.10563      2
       7  NlnCon 3    EQ     -1294.80000         0.00000     -1294.80000     -1294.80000        -5.46328      3
       8  LinCon 1    BS        -0.51511         0.03489        -0.55000           None           .           4
       9  LinCon 2    BS         0.51511         1.06511        -0.55000           None           .           5
      10  Objectiv    BS      4091.97022      4091.97022           None            None         -1.0          6

 Section 2 - Columns

  Number  .Column. State  ...Activity...  .Obj Gradient.  ..Lower Limit.  ..Upper Limit.  Reduced Gradnt    m+j

       1  X1          BS         0.11888          .             -0.55000         0.55000        -0.00000      7
       2  X2          BS        -0.39623          .             -0.55000         0.55000         0.00000      8
       3  X3         SBS       679.94532         4.38698          .           1200.00000         0.00000      9
       4  X4          BS      1026.06713         4.10563          .           1200.00000        -0.00000     10

  On exit from e04vh, ifail =     0
  Final objective value =      5126.5

  Optimal x =        0.12      -0.40     679.95    1026.07


//      e04vj Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04VJE
  {

    static int lenamx=300;
    static int lengmx=300;
   static int nfname=1;
    static int nxname=1;

    static string datafile = "ExampleData/e04vje.d";
    // as a command line argument. It defaults to the named file specified below otherwise.
    //
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        E04.E04VJ_USRFUN usrfunE04VJ  = new E04.E04VJ_USRFUN(usrfun);
        E04.E04VH_USRFUN usrfunE04VH  = new E04.E04VH_USRFUN(usrfun);
        double objadd=0.0,
        sinf=0.0;
        int i=0,
        lena=0,
        leng=0,
        n=0,
        nea=0,
        neg=0,
        nf=0,
        ninf=0,
        ns=0,
        objrow=0,
        start=0;
        string prob="";
        int ifail   ;
        Console.WriteLine("e04vj Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        nf = int.Parse(sr.Next());
        double[] a = new double[300];
        double[] f = new double[100];
        double[] flow = new double[100];
        double[] fmul = new double[nf];
        double[] fupp = new double[100];
        double[] ruser = new double[1];
        double[] x = new double[n];
        double[] xlow = new double[n];
        double[] xmul = new double[n];
        double[] xupp = new double[n];
        int[] fstate = new int[nf];
        int[] iafun = new int[300];
        int[] igfun = new int[300];
        int[] iuser = new int[1];
        int[] javar = new int[300];
        int[] jgvar = new int[300];
        int[] xstate = new int[100];
        string[] fnames = new string[1];
        string[] xnames = new string[1];
        //
        if ( n > 0 && nf > 0)
        {
          //
          //         Call e04vg to initialise E04VJF.
          E04.e04vhOptions options = new E04.e04vhOptions();
          //
          lena = lenamx;
          leng = lengmx;
          //
          //         Read the bounds on the variables.
          for (i = 1 ; i <= n ; i++)
          {
            sr.Reset();
            xlow[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            xupp[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //
          for (i = 1 ; i <= n ; i++)
          {
            x[i - 1] = 0.00e0;
          }
          //
          //         Determine the Jacobian structure.
          E04.e04vj(nf, n, usrfunE04VJ, iafun, javar, out nea,   a,   igfun, jgvar, out neg, x, xlow,

          xupp,     options, out ifail );
          //
          //         Print the Jacobian structure.
          Console.WriteLine("");
          Console.WriteLine("  NEA (the number of non-zero entries in A) = {0,3}",nea);
          Console.WriteLine("    I     IAFUN(I)   JAVAR(I)          A(I)");
          Console.WriteLine("  ----    --------   --------   -----------");
          for (i = 1 ; i <= nea ; i++)
          {
            Console.WriteLine("  {0,3}{1,10}{2,10}{3,18:e4}",i,iafun[i - 1],javar[i - 1],a[i - 1]);
          }
          Console.WriteLine("");
          Console.WriteLine("  NEG (the number of non-zero entries in G) = {0,3}",neg);
          Console.WriteLine("    I     IGFUN(I)   JGVAR(I)");
          Console.WriteLine("  ----    --------   --------");
          for (i = 1 ; i <= neg ; i++)
          {
            Console.WriteLine("  {0,3}{1,10}{2,10}",i,igfun[i - 1],jgvar[i - 1]);
          }
          //
          //         Now that we have the determined the structure of the
          //         Jacobian, set up the information necessary to solve
          //         the optimization problem.
          start = 0;
          prob = "E04VJF";
          objadd = 0.00e0;
          for (i = 1 ; i <= n ; i++)
          {
            x[i - 1] = 0.00e0;
            xstate[i - 1] = 0;
            xmul[i - 1] = 0.00e0;
          }
          for (i = 1 ; i <= nf ; i++)
          {
            f[i - 1] = 0.00e0;
            fstate[i - 1] = 0;
            fmul[i - 1] = 0.00e0;
          }
          //
          //         The row containing the objective function.
          sr.Reset();
          objrow = int.Parse(sr.Next());
          //
          //         Read the bounds on the functions.
          for (i = 1 ; i <= nf ; i++)
          {
            sr.Reset();
            flow[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            fupp[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //
          //         By default e04vh does not print monitoring
          //         information. Set the print file unit or the summary
          //         file unit to get information.
          options.Set("Print file = 6");
          //
          //         Tell e04vh that we supply no derivatives in USRFUN.
          options.Set("Derivative option = 0");
          //
          //         Solve the problem.
          E04.e04vh(start, nf, n, nxname, nfname, objadd, objrow, prob, usrfunE04VH, iafun, javar,
          nea, a, igfun, jgvar, neg, xlow, xupp, xnames, flow, fupp, fnames, x, xstate, xmul, f, fstate,
          fmul, ref ns, out ninf, out sinf, options, out ifail);
          //
          Console.WriteLine("");
          Console.WriteLine("  On exit from E04VHF, ifail = {0,5}",ifail);
          if ((ifail == 0) || (ifail == 4))
          {
            Console.WriteLine("  Final objective value = {0,11:f1}", f[objrow - 1]);
            Console.WriteLine("");
            Console.Write("  Optimal x = ");
            for (i = 1; i <= n; i++)
            {
              Console.Write(" " + " {0, 9:f2}", x[i - 1]);
            }
            Console.WriteLine(" ");
          }
        }
        else
        {
          Console.WriteLine("  At least one of N or NF is too large");
        }

        //
        return;
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
    //
    public static void usrfun (ref int status, int n, double[] x, int needf, int nf,
    double[] f, int needg, double[] g)
    {
      if (needf > 0)
      {
        f[0] = 1000.00e+0 * Math.Sin( -x[0] - 0.250e+0) + 1000.00e+0 * Math.Sin( -x[1] - 0.250e+0) - x[2];
        f[1] = 1000.00e+0 * Math.Sin(x[0] - 0.250e+0) + 1000.00e+0 * Math.Sin(x[0] - x[1] - 0.250e+0) - x[3];
        f[2] = 1000.00e+0 * Math.Sin(x[1] - x[0] - 0.250e+0) + 1000.00e+0 * Math.Sin(x[1] - 0.250e+0);
        f[3] =  -x[0] + x[1];
        f[4] = x[0] - x[1];
        f[5] = 1.00e-6 * Math.Pow(x[2] ,3) + 2.00e-6 * Math.Pow(x[3] ,
        3) / 3.00e+0 + 3 * x[2] + 2 * x[3];
      }
      //
    }
  }
}


e04vj Example Program Results

  NEA (the number of non-zero entries in A) =   4
    I     IAFUN(I)   JAVAR(I)          A(I)
  ----    --------   --------   -----------
    1         4         1      -1.0000e+000
    2         5         1       1.0000e+000
    3         4         2       1.0000e+000
    4         5         2      -1.0000e+000

  NEG (the number of non-zero entries in G) =  10
    I     IGFUN(I)   JGVAR(I)
  ----    --------   --------
    1         1         1
    2         2         1
    3         3         1
    4         1         2
    5         2         2
    6         3         2
    7         6         3
    8         6         4
    9         1         3
   10         2         4

 Parameters
 ==========

 Files
 -----
 Solution file..........         0       Old basis file ........         0       (Print file)...........         6
 Insert file............         0       New basis file ........         0       (Summary file).........         0
 Punch file.............         0       Backup basis file......         0
 Load file..............         0       Dump file..............         0

 Frequencies
 -----------
 Print frequency........       100       Check frequency........        60       Save new basis map.....       100
 Summary frequency......       100       Factorization frequency        50       Expand frequency.......     10000

 QP subproblems
 --------------
 QPsolver Cholesky......
 Scale tolerance........     0.900       Minor feasibility tol..  1.00E-06       Iteration limit........     10000
 Scale option...........         0       Minor optimality  tol..  1.00E-06       Minor print level......         1
 Crash tolerance........     0.100       Pivot tolerance........  2.04E-11       Partial price..........         1
 Crash option...........         3       Elastic weight.........  1.00E+04       Prtl price section ( A)         4
                                         New superbasics........        99       Prtl price section (-I)         5

 The SQP Method
 --------------
 Minimize...............                 Cold start.............                 Proximal Point method..         1
 Nonlinear objectiv vars         2       Objective Row..........         6       Function precision.....  1.72E-13
 Unbounded step size....  1.00E+20       Superbasics limit......         4       Difference interval....  4.15E-07
 Unbounded objective....  1.00E+15       Reduced Hessian dim....         4       Central difference int.  5.57E-05
 Major step limit.......  2.00E+00       Nonderiv.  linesearch..                 Derivative option......         0
 Major iterations limit.      1000       Linesearch tolerance...   0.90000       Verify level...........         0
 Minor iterations limit.       500       Penalty parameter......  0.00E+00       Major Print Level......         1
                                         Major optimality tol...  2.00E-06

 Hessian Approximation
 ---------------------
 Full-Memory Hessian....                 Hessian updates........  99999999       Hessian frequency......  99999999
                                                                                Hessian flush..........  99999999

 Nonlinear constraints
 ---------------------
 Nonlinear constraints..         3       Major feasibility tol..  1.00E-06       Violation limit........  1.00E+06
 Nonlinear Jacobian vars         4

 Miscellaneous
 -------------
 LU factor tolerance....      3.99       LU singularity tol.....  2.04E-11       Timing level...........         0
 LU update tolerance....      3.99       LU swap tolerance......  1.03E-04       Debug level............         0
 LU partial  pivoting...                 eps (machine precision)  1.11E-16       System information.....        No

 Matrix statistics
 -----------------
               Total      Normal        Free       Fixed     Bounded
 Rows              5           2           0           3           0
 Columns           4           0           0           0           4

 No. of matrix elements                   12     Density      60.000
 Biggest                          1.0000E+00  (excluding fixed columns,
 Smallest                         0.0000E+00   free rows, and RHS)

 No. of objective coefficients             0

 Nonlinear constraints       3     Linear constraints       2
 Nonlinear variables         4     Linear variables         0
 Jacobian  variables         4     Objective variables      2
 Total constraints           5     Total variables          4

 The user has defined       0   out of      10   first  derivatives

   Itns Major Minors    Step   nCon  Feasible   Optimal  MeritFunction     L+U BSwap     nS  condHz Penalty
      3     0      3              1   8.0E+02   1.0E+00  0.0000000E+00      14            1 3.0E+07         _  r
      5     1      2 1.2E-03      2   4.0E+02   1.0E+00  1.7331709E+06      13            1 1.3E+07 5.1E+00 _n rl
      6     2      1 1.3E-03      3   2.7E+02   5.5E-01  1.7301152E+06      13                      5.1E+00 _s  l
      6     3      0 7.5E-03      4   8.8E+01   5.4E-01  8.8193384E+05      13                      2.8E+00 _   l
      6     4      0 2.3E-02      5   2.9E+01   5.3E-01  8.4262007E+05      13                      2.8E+00 _   l
      6     5      0 6.9E-02      6   8.9E+00   5.2E-01  7.3075570E+05      13                      2.8E+00 _   l
      7     6      1 2.2E-01      7   2.3E+00   8.0E+01  4.4817383E+05      13            1 1.2E+04 2.8E+00 _   l
      8     7      1 8.3E-01      8   1.7E-01   9.2E+00  2.4331007E+04      13            1 9.5E+03 2.8E+00 _   l
      9     8      1 1.0E+00      9   6.5E-03   4.0E+01  5.3126226E+03      13     1      1 1.3E+02 2.8E+00 _
     10     9      1 1.0E+00     10   4.6E-03   1.2E+01  5.1602362E+03      13            1 9.4E+01 2.8E+00 _
     11    10      1 1.0E+00     11   2.3E-04   6.2E-02  5.1265653E+03      13            1 9.6E+01 2.8E+00 _
     12    11      1 1.0E+00     12 ( 1.3E-08)  2.9E-04  5.1264981E+03      13            1 1.2E+02 2.8E+00 _      c
     13    11      2 1.0E+00     12 ( 1.3E-08)  2.7E-04  5.1264981E+03      13            1 1.2E+02 2.8E+00 _      c
     14    12      1 1.0E+00     13 ( 5.6E-13)  7.1E-05  5.1264981E+03      13            1 9.5E+01 2.8E+00 _      c
     15    13      1 1.0E+00     14 ( 1.8E-14)( 1.3E-09) 5.1264981E+03      13            1 9.5E+01 2.8E+00 _      c

 E04VHU EXIT   0 -- finished successfully
 E04VHU INFO   1 -- optimality conditions satisfied

 Problem name                 E04VJF
 No. of iterations                  15   Objective value      5.1264981096E+03
 No. of major iterations            13   Linear objective     0.0000000000E+00
 Penalty parameter           2.780E+00   Nonlinear objective  5.1264981096E+03
 No. of calls to funobj            105   No. of calls to funcon            105
 Calls with modes 1,2 (known g)     14   Calls with modes 1,2 (known g)     14
 Calls for forward differencing     48   Calls for forward differencing     48
 Calls for central differencing     24   Calls for central differencing     24
 No. of superbasics                  1   No. of basic nonlinears             3
 No. of degenerate steps             0   Percentage                       0.00
 Max x                       2 1.0E+03   Max pi                      3 5.5E+00
 Max Primal infeas           0 0.0E+00   Max Dual infeas             1 1.3E-08
 Nonlinear constraint violn    1.5E-11

 Name           E04VJF                   Objective Value      5.1264981096E+03

 Status         Optimal Soln             Iteration     15    Superbasics     1

 Objective               (Min)
 RHS
 Ranges
 Bounds

 Section 1 - Rows

  Number  ...Row.. State  ...Activity...  Slack Activity  ..Lower Limit.  ..Upper Limit.  .Dual Activity    ..i

       5  r      1    EQ      -894.80000         0.00000      -894.80000      -894.80000        -4.38698      1
       6  r      2    EQ      -894.80000         0.00000      -894.80000      -894.80000        -4.10563      2
       7  r      3    EQ     -1294.80000         0.00000     -1294.80000     -1294.80000        -5.46328      3
       8  r      4    BS        -0.51511         0.03489        -0.55000           None           .           4
       9  r      5    BS         0.51511         1.06511        -0.55000           None           .           5

 Section 2 - Columns

  Number  .Column. State  ...Activity...  .Obj Gradient.  ..Lower Limit.  ..Upper Limit.  Reduced Gradnt    m+j

       1  x      1    BS         0.11888          .             -0.55000         0.55000         0.00000      6
       2  x      2    BS        -0.39623          .             -0.55000         0.55000        -0.00000      7
       3  x      3   SBS       679.94532         4.38698          .           1200.00000        -0.00000      8
       4  x      4    BS      1026.06713         4.10563          .           1200.00000         0.00000      9

  On exit from E04VHF, ifail =     0
  Final objective value =      5126.5

  Optimal x =        0.12      -0.40     679.95    1026.07


//      e04wd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04WDE
  {
    static string datafile = "ExampleData/e04wde.d";
    // as a command line argument. It defaults to the named file specified below otherwise.
    //
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04WD_CONFUN confunE04WD = new E04.E04WD_CONFUN(confun);
      E04.E04WD_OBJFUN objfunE04WD = new E04.E04WD_OBJFUN(objfun);
      try
      {
        DataReader sr = new DataReader(datafile);
      double objf = 0.0;
      int i,  ifail,  j,  majits,  n,  nclin,  ncnln;
      Console.WriteLine("e04wd Example Program Results");
      //      Skip heading in data file
      sr.Reset();
      sr.Reset();
      n = int.Parse(sr.Next());
      nclin = int.Parse(sr.Next());
      ncnln = int.Parse(sr.Next());
      double[,] a = new double[nclin, n];
      double[] bl = new double[nclin+ncnln+n];
      double[] bu = new double[nclin+ncnln+n];
      double[] ccon = new double[ncnln];
      double[,] cjac = new double[ncnln, n];
      double[] clamda = new double[nclin+ncnln+n];
      double[] grad = new double[n];
      double[,] h = new double[n, n];
      double[] x = new double[n];
      int[] istate = new int[nclin+ncnln+n];
      //
      //         Read a, bl, bu and x from data file
      if (nclin > 0)
      {
        sr.Reset();
        for (i = 1; i <= nclin; i++)
        {
          for (j = 1; j <= n; j++)
          {
            a[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
      }
      sr.Reset();
      for (i = 1; i <= n + nclin + ncnln; i++)
      {
        bl[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
      }
      sr.Reset();
      for (i = 1; i <= n + nclin + ncnln; i++)
      {
        bu[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
      }
      sr.Reset();
      for (i = 1; i <= n; i++)
      {
        x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
      }
      //
      //         Initialise e04wd.
      E04.e04wdOptions options = new E04.e04wdOptions();
      //
      //         By default e04wd does not print monitoring
      //         information. Set the print file unit or the summary
      //         file unit to get information.
      options.Set("Print file = 6");
      //
      //         Solve the problem.
      E04.e04wd(n, nclin, ncnln, a, bl, bu, confunE04WD, objfunE04WD, out majits, istate,
      ccon, cjac, clamda, out objf, grad, h, x, options, out ifail);
      //
      Console.WriteLine("");
      Console.WriteLine("  On exit from e04wd, ifail = {0,5}", ifail);
      if (ifail == 0)
      {
        Console.WriteLine("  Final objective value = {0,11:f3}", objf);
        Console.WriteLine("");
        Console.Write("  Output x");
        for (i = 1; i <= n; i++)
        {
          Console.Write(" " + " {0,11:f3}", x[i - 1]);
        }
        Console.WriteLine(" ");
      }
      //
    }
    catch (Exception e)
    {
      Console.WriteLine(e.Message);
      Console.WriteLine( "Exception Raised");
    }
  }
  //
  public static void objfun(ref int mode, int n, double[] x, ref double objf,
  double[] grad, int nstate)
  {
    //      Routine to evaluate objective function and its 1st derivatives.
    double one = 1.00e0;
    double two = 2.00e0;
    if ((mode == 0) || (mode == 2))
    {
      objf = x[0] * x[3] * (x[0] + x[1] + x[2]) + x[2];
    }
    //
    if ((mode == 1) || (mode == 2))
    {
      grad[0] = x[3] * (two * x[0] + x[1] + x[2]);
      grad[1] = x[0] * x[3];
      grad[2] = x[0] * x[3] + one;
      grad[3] = x[0] * (x[0] + x[1] + x[2]);
    }
    //
  }
  //
  public static void confun(ref int mode, int ncnln, int n, int[] needc, double[] x,
  double[] ccon, double[,] cjac, int nstate)
  {
    //      Routine to evaluate the nonlinear constraints and their 1st
    //      derivatives.
    double zero = 0.00e0;
    double two = 2.00e0;
    int i,  j;
    if (nstate == 1)
    {
      //  First call to confun.  Set all Jacobian elements to zero.
      //  Note that this will only work when 'Derivative Level = 3'
      for (j = 1; j <= n; j++)
      {
        for (i = 1; i <= ncnln; i++)
        {
          cjac[i - 1, j - 1] = zero;
        }
      }
    }
    //
    if (needc[0] > 0)
    {
      if ((mode == 0) || (mode == 2))
      {
        ccon[0] = (x[0]) * (x[0]) + (x[1]) * (x[1]) + (x[2]) * (x[2]) + (x[3]) * (x[3]);
      }
      if ((mode == 1) || (mode == 2))
      {
        cjac[0, 0] = two * x[0];
        cjac[0, 1] = two * x[1];
        cjac[0, 2] = two * x[2];
        cjac[0, 3] = two * x[3];
      }
    }
    //
    if (needc[1] > 0)
    {
      if ((mode == 0) || (mode == 2))
      {
        ccon[1] = x[0] * x[1] * x[2] * x[3];
      }
      if ((mode == 1) || (mode == 2))
      {
        cjac[1, 0] = x[1] * x[2] * x[3];
        cjac[1, 1] = x[0] * x[2] * x[3];
        cjac[1, 2] = x[0] * x[1] * x[3];
        cjac[1, 3] = x[0] * x[1] * x[2];
      }
    }
    //
  }
}
}


e04wd Example Program Results

 Parameters
 ==========

 Files
 -----
 Solution file..........         0       Old basis file ........         0       (Print file)...........         6
 Insert file............         0       New basis file ........         0       (Summary file).........         0
 Punch file.............         0       Backup basis file......         0
 Load file..............         0       Dump file..............         0

 Frequencies
 -----------
 Print frequency........       100       Check frequency........        60       Save new basis map.....       100
 Summary frequency......       100       Factorization frequency        50       Expand frequency.......     10000

 QP subproblems
 --------------
 QPsolver Cholesky......
 Scale tolerance........     0.900       Minor feasibility tol..  1.00E-06       Iteration limit........     10000
 Scale option...........         0       Minor optimality  tol..  1.00E-06       Minor print level......         1
 Crash tolerance........     0.100       Pivot tolerance........  2.04E-11       Partial price..........         1
 Crash option...........         3       Elastic weight.........  1.00E+04       Prtl price section ( A)         4
                                         New superbasics........        99       Prtl price section (-I)         3

 The SQP Method
 --------------
 Minimize...............                 Cold start.............                 Proximal Point method..         1
 Nonlinear objectiv vars         4       Major optimality tol...  2.00E-06       Function precision.....  1.72E-13
 Unbounded step size....  1.00E+20       Superbasics limit......         4       Difference interval....  4.15E-07
 Unbounded objective....  1.00E+15       Reduced Hessian dim....         4       Central difference int.  5.57E-05
 Major step limit.......  2.00E+00       Derivative linesearch..                 Derivative level.......         3
 Major iterations limit.      1000       Linesearch tolerance...   0.90000       Verify level...........         0
 Minor iterations limit.       500       Penalty parameter......  0.00E+00       Major Print Level......         1

 Hessian Approximation
 ---------------------
 Full-Memory Hessian....                 Hessian updates........  99999999       Hessian frequency......  99999999
                                                                                Hessian flush..........  99999999

 Nonlinear constraints
 ---------------------
 Nonlinear constraints..         2       Major feasibility tol..  1.00E-06       Violation limit........  1.00E+06
 Nonlinear Jacobian vars         4

 Miscellaneous
 -------------
 LU factor tolerance....      1.10       LU singularity tol.....  2.04E-11       Timing level...........         0
 LU update tolerance....      1.10       LU swap tolerance......  1.03E-04       Debug level............         0
 LU partial  pivoting...                 eps (machine precision)  1.11E-16       System information.....        No

 Matrix statistics
 -----------------
               Total      Normal        Free       Fixed     Bounded
 Rows              3           3           0           0           0
 Columns           4           0           0           0           4

 No. of matrix elements                   12     Density     100.000
 Biggest                          1.0000E+00  (excluding fixed columns,
 Smallest                         0.0000E+00   free rows, and RHS)

 No. of objective coefficients             0

 Nonlinear constraints       2     Linear constraints       1
 Nonlinear variables         4     Linear variables         0
 Jacobian  variables         4     Objective variables      4
 Total constraints           3     Total variables          4

 The user has defined       8   out of       8   constraint gradients.
 The user has defined       4   out of       4   objective  gradients.

 Cheap test of user-supplied problem derivatives...

 The constraint gradients seem to be OK.

 -->  The largest discrepancy was    1.84E-07  in constraint     6

 The objective  gradients seem to be OK.

 Gradient projected in one direction   4.99993000077E+00
 Difference approximation              4.99993303560E+00

   Itns Major Minors    Step   nCon  Feasible   Optimal  MeritFunction     L+U BSwap     nS  condHz Penalty
      2     0      2              1   1.7E+00   2.8E+00  1.6000000E+01       7            2 1.0E+00         _  r
      4     1      2 1.0E+00      2   1.3E-01   3.2E-01  1.7726188E+01       8            1 6.2E+00 8.3E-02 _n r
      5     2      1 1.0E+00      3   3.7E-02   1.7E-01  1.7099571E+01       7            1 2.0E+00 8.3E-02 _s
      6     3      1 1.0E+00      4   2.2E-02   1.1E-02  1.7014005E+01       7            1 1.8E+00 8.3E-02 _
      7     4      1 1.0E+00      5   1.5E-04   6.0E-04  1.7014018E+01       7            1 1.8E+00 9.2E-02 _
      8     5      1 1.0E+00      6 ( 3.3E-07)  2.3E-05  1.7014017E+01       7            1 1.9E+00 3.6E-01 _
      9     6      1 1.0E+00      7 ( 4.2E-10)( 2.4E-08) 1.7014017E+01       7            1 1.9E+00 3.6E-01 _

 E04WDM EXIT   0 -- finished successfully
 E04WDM INFO   1 -- optimality conditions satisfied

 Problem name                      NLP
 No. of iterations                   9   Objective value      1.7014017287E+01
 No. of major iterations             6   Linear objective     0.0000000000E+00
 Penalty parameter           3.599E-01   Nonlinear objective  1.7014017287E+01
 No. of calls to funobj              8   No. of calls to funcon              8
 No. of superbasics                  1   No. of basic nonlinears             2
 No. of degenerate steps             0   Percentage                       0.00
 Max x                       2 4.7E+00   Max pi                      2 5.5E-01
 Max Primal infeas           0 0.0E+00   Max Dual infeas             3 4.8E-08
 Nonlinear constraint violn    2.7E-09

 Variable         State      Value       Lower bound     Upper bound   Lagr multiplier       Slack

 variable     1     LL   1.0000000       1.0000000        5.000000        1.087871            .
 variable     2     FR    4.743000       1.0000000        5.000000            .             0.2570
 variable     3     FR    3.821150       1.0000000        5.000000            .              1.179
 variable     4     FR    1.379408       1.0000000        5.000000            .             0.3794

 Linear constrnt  State      Value       Lower bound     Upper bound   Lagr multiplier       Slack

 lincon       1     FR    10.94356          None          20.00000            .              9.056

 Nonlin constrnt  State      Value       Lower bound     Upper bound   Lagr multiplier       Slack

 nlncon       1     UL    40.00000          None          40.00000      -0.1614686         -0.2700E-08
 nlncon       2     LL    25.00000        25.00000          None         0.5522937         -0.2215E-08

  On exit from e04wd, ifail =     0
  Final objective value =      17.014

  Output x        1.000        4.743        3.821        1.379


//      e04xa Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04XAE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04XA_OBJFUN objfunE04XA = new E04.E04XA_OBJFUN(objfun);
      double epsrf,  objf;
      int i,  ifail,  imode,  iwarn,  j,  mode,  msglvl;
      int n = 4;
      int lhes = n;
      double[] hcntrl = new double[4];
      double[,] hesian = new double[lhes, n];
      double[] hforw = new double[4];
      double[] objgrd = new double[4];
      double[] user = new double[1];
      double[] x = new double[4];
      int[] info = new int[4];
      int[] iuser = new int[1];
      string[] rc = new string[3];
      try
      {
        Console.WriteLine("e04xa Example Program Results");
        msglvl = 0;
        //      Set the point at which the derivatives are to be estimated.
        x[0] = 3.00e0;
        x[1] = -1.00e0;
        x[2] = 0.00e0;
        x[3] = 1.00e0;
        rc[0] = "Find gradients and Hessian diagonals given function only";
        rc[1] = "Find Hessian matrix given function and gradients";
        rc[2] = "Find gradients and Hessian matrix given function only";
        //      Take default value of epsrf.
        epsrf = -1.00e0;
        //      Illustrate the different values of mode.
        for (imode = 0; imode <= 2; imode++)
        {
          mode = (int)imode;
          //         Set hforw[i-1] = -1.0 so that E04.e04xa computes the initial trial
          //         interval.
          for (i = 1; i <= n; i++)
          {
            hforw[i - 1] = -1.00e0;
          }
          //
          E04.e04xa(msglvl, n, epsrf, x, ref mode, objfunE04XA, hforw, out objf, objgrd, hcntrl,
          hesian, out iwarn, info, out ifail);
          //
          if ((ifail == 0) || (ifail == 2))
          {
            Console.WriteLine("  \n {0}\n  ( i.e. MODE ={1,2} ).", rc[mode + 1 - 1], mode);
            Console.WriteLine(" {0}{1,12:e4}", "Function value is ", objf);
            if (mode == 1)
            {
              Console.WriteLine("{0,12:e4}", "Gradient vector is");
              for (i = 1; i <= n; i++)
              {
                Console.Write(" " + "{0,12:e4}", objgrd[i - 1]);
              }
              Console.WriteLine(" ");
            }
            else
            {
              Console.WriteLine("{0}", "Estimated gradient vector is");
              for (i = 1; i <= n; i++)
              {
                Console.Write(" " + "{0,12:e4}", objgrd[i - 1]);
              }
              Console.WriteLine(" ");
            }
            if (mode == 0)
            {
              Console.WriteLine("{0,12:e4}", "Estimated Hessian matrix diagonal is");
              for (i = 1; i <= n; i++)
              {
                Console.Write(" " + "{0, 12:e4}", hesian[i - 1, 0]);
              }
              Console.WriteLine(" ");
            }
            else
            {
              Console.WriteLine("{0}", "Estimated Hessian matrix (machine dependent) is");
              Console.WriteLine("");
              for (i = 1; i <= n; i++)
              {
                for (j = 1; j <= n; j++)
                {
                  Console.Write(" " + "{0, 12:e4}", hesian[i - 1, j - 1]);
                }
                Console.WriteLine("");
              }
              Console.WriteLine(" ");
            }
          }
          else
          {
            Console.WriteLine(" ** e04xa returned with ifail = {0, 3}", ifail);
            goto L60;
          }
        }
        L60: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
    //
    public static void objfun(ref int mode, int n, double[] x, ref double objf,
    double[] objgrd, int nstate)
    {
      double a,  b,  c,  d;
      a = x[0] + 10.00e0 * x[1];
      b = x[2] - x[3];
      c = x[1] - 2.00e0 * x[2];
      d = x[0] - x[3];
      objf = (a) * (a) + 5.00e0 * (b) * (b) + Math.Pow(c, 4) + 10.00e0 * Math.Pow(d,
      4);
      if (mode == 1)
      {
        objgrd[0] = 4.00e1 * Math.Pow(x[0],3) + 2.00e0 * x[0] -
                    1.20e2 * x[3] * x[0] * x[0] + 1.20e2 * x[0] * x[3] * x[3] +
                    2.00e1 * x[1] - 4.00e1 * Math.Pow(x[3], 3);
        objgrd[1] = 2.00e2 * x[1] + 2.00e1 * x[0] + 4.00e0 * Math.Pow(x[1],3) +
                    4.80e1 * x[1] * x[2] * x[2] - 2.40e1 * x[2] * (x[1]) * (x[1]) -
                    32.00e0 * Math.Pow(x[2], 3);
        objgrd[2] = 1.00e1 * x[2] - 1.00e1 * x[3] - 8.00e0 * Math.Pow(x[1],3) +
                    4.80e1 * x[2] * (x[1]) * (x[1]) - 9.60e1 * x[1] *
                    x[2] * x[2] + 6.40e1 * Math.Pow(x[2], 3);
        objgrd[3] = 1.00e1 * x[3] - 1.00e1 * x[2] - 4.00e1 * Math.Pow(x[0],3) +
                    1.20e2 * x[3] * (x[0]) * (x[0]) - 1.20e2 * x[0] * x[3] * x[3] +
                    4.00e1 * Math.Pow(x[3], 3);
      }
    }
  }
}


//      e04ya Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04YAE
  {
    static int mdec = 15;
    static int ndec = 3;
    static double[,] t = new double[mdec, ndec];
    static double[] y = new double[mdec];
    static string datafile = "ExampleData/e04yae.d";
    // as a command line argument. It defaults to the named file specified below otherwise.
    //
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04YA_LSQFUN lsqfunE04YA = new E04.E04YA_LSQFUN(lsqfun);
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,  j,  m,  n;
        double[,] fjac = new double[mdec, ndec];
        double[] fvec = new double[mdec];
        double[] x = new double[ndec];
        int ifail;
        Console.WriteLine("e04ya Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        n = ndec;
        m = mdec;
        //      Observations of tj (j = 1, 2, 3) are held in t[i-1, j-1]
        //      (i = 1, 2, . . . , 15)
        for (i = 1; i <= m; i++)
        {
          sr.Reset();
          y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          for (j = 1; j <= n; j++)
          {
            t[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        //      Set up an arbitrary point at which to check the 1st
        //      derivatives
        x[0] = 0.190e0;
        x[1] = -1.340e0;
        x[2] = 0.880e0;
        Console.WriteLine("");
        Console.WriteLine(" {0}", "The test point is");
        for (j = 1; j <= n; j++)
        {
          Console.Write(" " + " {0, 10:f5}", x[j - 1]);
        }
        Console.WriteLine(" ");
        //
        E04.e04ya(m, n, lsqfunE04YA, x, fvec, fjac, out ifail);
        //
        Console.WriteLine("");
        if (ifail < 0)
        {
          Console.WriteLine(" ** e04ya returned with ifail = {0, 3}", ifail);
        }
        else if (ifail == 1)
        {
          Console.WriteLine(" {0}", "A parameter is outside its expected range");
        }
        else
        {
          if (ifail == 0)
          {
            Console.WriteLine(" {0}", "1st derivatives are consistent with residual values");
          }
          else if (ifail == 2)
          {
            Console.WriteLine(" {0}\n", "Probable error in calculation of 1st derivatives");
          }
          Console.WriteLine("");
          Console.WriteLine(" {0}", "At the test point, LSQFUN gives");
          Console.WriteLine("");
          Console.WriteLine("{0}\r\n", "      Residuals                   1st derivatives");
          for (i = 1; i <= m; i++)
          {
            Console.Write(" " + "{0, 15:e3}", fvec[i - 1]);
            for (j = 1; j <= n; j++)
            {
              Console.Write(" " + "{0, 15:e3}", fjac[i - 1, j - 1]);
            }
            Console.WriteLine(" ");
          }
          Console.WriteLine(" ");
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
    //
    public static void lsqfun(ref int iflag, int m, int n, double[] xc, double[] fvec,
    double[,] fjac)
    {
      //      Routine to evaluate the residuals and their 1st derivatives
      double denom,  dummy;
      int i = 0;
      for (i = 1; i <= m; i++)
      {
        denom = xc[1] * t[i - 1, 1] + xc[2] * t[i - 1, 2];
        if (iflag != 1)
        {
          fvec[i - 1] = xc[0] + t[i - 1, 0] / denom - y[i - 1];
        }
        if (iflag != 0)
        {
          fjac[i - 1, 0] = 1.00e0;
          dummy = -1.00e0 / (denom * denom);
          fjac[i - 1, 1] = t[i - 1, 0] * t[i - 1, 1] * dummy;
          fjac[i - 1, 2] = t[i - 1, 0] * t[i - 1, 2] * dummy;
        }
      }
    }
  }
}


//      e04yb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class E04YBE
  {
    static int mdec = 15;
    static int ndec = 3;
    public static double[,] t = new double[mdec, ndec];
    public static double[] y = new double[mdec];
    static string datafile = "ExampleData/e04ybe.d";
    // as a command line argument. It defaults to the named file specified below otherwise.
    //
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      E04.E04YA_LSQFUN lsqfunE04YA = new E04.E04YA_LSQFUN(lsqfun);
      E04.E04YB_LSQFUN lsqfunE04YB = new E04.E04YB_LSQFUN(lsqfun);
      E04.E04YB_LSQHES lsqhesE04YB = new E04.E04YB_LSQHES(lsqhes);
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,  ifail,  j,  k,  m,  n;
        Console.WriteLine("e04yb Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        m = mdec;
        n = ndec;
        int lb = n * (n + 1) / 2;
        double[] b = new double[lb];
        double[,] fjac = new double[m, n];
        double[] fvec = new double[m];
        double[] x = new double[n];
        int[] iw = new int[1];
        // Observations of tj (j = 1, 2, 3) are held in t[i-1, j-1]
        //(i = 1, 2, . . . , 15)
        for (i = 1; i <= m; i++)
        {
          sr.Reset();
          y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          for (j = 1; j <= n; j++)
          {
            t[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        //      Set up an arbitrary point at which to check the derivatives
        x[0] = 0.190e0;
        x[1] = -1.340e0;
        x[2] = 0.880e0;
        //      Check the 1st derivatives
        E04.e04ya(m, n, lsqfunE04YA, x, fvec, fjac, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine(" ** e04ya returned with ifail = {0, 3}", ifail);
          goto L60;
        }
        //
        Console.WriteLine("");
        Console.WriteLine(" {0}", "The test point is");
        for (j = 1; j <= n; j++)
        {
          Console.Write(" " + " {0, 10:f5}", x[j - 1]);
        }
        Console.WriteLine(" ");
        //
        //      Check the evaluation of B
        E04.e04yb(m, n, lsqfunE04YB, lsqhesE04YB, x, fvec, fjac, b, out ifail);
        //
        Console.WriteLine("");
        if (ifail == 1)
        {
          Console.WriteLine(" {0}", "A parameter is outside its expected range");
        }
        else if (ifail >= 0)
        {
          if (ifail == 0)
          {
            Console.WriteLine(" {0}", "The matrix B is consistent with 1st derivatives");
          }
          else if (ifail == 2)
          {
            Console.WriteLine(" {0}", "Probable error in calculation of the matrix B");
          }
          Console.WriteLine("");
          Console.WriteLine(" {0}", "At the test point, LSQFUN gives");
          Console.WriteLine("");
          Console.WriteLine("{0}\n", "      Residuals                   1st derivatives");
          Console.WriteLine("");
          for (i = 1; i <= m; i++)
          {
            Console.Write(" " + "{0,15:e3}", fvec[i - 1]);
            for (j = 1; j <= n; j++)
            {
              Console.Write(" " + "{0,15:e3}", fjac[i - 1, j - 1]);
            }
            Console.WriteLine(" ");
          }
          Console.WriteLine("");
          Console.WriteLine(" {0}", "and LSQHES gives the lower triangle of the matrix B");
          Console.WriteLine("");
          k = 1;
          for (i = 1; i <= n; i++)
          {
            for (j = k; j <= k + i - 1; j++)
            {
              Console.Write(" " + " {0, 15:e3}", b[j - 1]);
            }
            Console.WriteLine(" ");
            k = k + i;
          }
        }
        else if (ifail == -399)
        {
          Console.WriteLine(" ** e04yb returned with ifail = {0, 3}", ifail);
        }
        else
        {
          Console.WriteLine("  {0}{1,3}{2}", "IFLAG was set to ", ifail, "in LSQFUN or LSQHES");
        }
        L60: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
    //
    public static void lsqfun(ref int iflag, int m, int n, double[] xc, double[] fvec,
    double[,] fjac)
    {
      //      Routine to evaluate the residuals and their 1st derivatives
      double denom,  dummy;
      int i = 0;
      for (i = 1; i <= m; i++)
      {
        denom = xc[1] * t[i - 1, 1] + xc[2] * t[i - 1, 2];
        fvec[i - 1] = xc[0] + t[i - 1, 0] / denom - y[i - 1];
        fjac[i - 1, 0] = 1.00e0;
        dummy = -1.00e0 / (denom * denom);
        fjac[i - 1, 1] = t[i - 1, 0] * t[i - 1, 1] * dummy;
        fjac[i - 1, 2] = t[i - 1, 0] * t[i - 1, 2] * dummy;
      }
    }
    //
    public static void lsqhes(ref int iflag, int m, int n, double[] fvec, double[] xc,
    double[] b)
    {
      //      Routine to compute the lower triangle of the matrix B
      //      (stored by rows in the array B)
      double dummy,  sum22,  sum32,  sum33;
      int i = 0;
      b[0] = 0.00e0;
      b[1] = 0.00e0;
      sum22 = 0.00e0;
      sum32 = 0.00e0;
      sum33 = 0.00e0;
      for (i = 1; i <= m; i++)
      {
        dummy = 2.00e0 * t[i - 1, 0] / Math.Pow((xc[1] * t[i - 1, 1] + xc[2] * t[i - 1, 2]), 3);
        sum22 = sum22 + fvec[i - 1] * dummy * (t[i - 1, 1]) * (t[i - 1, 1]);
        sum32 = sum32 + fvec[i - 1] * dummy * t[i - 1, 1] * t[i - 1, 2];
        sum33 = sum33 + fvec[i - 1] * dummy * (t[i - 1, 2]) * (t[i - 1, 2]);
      }
      b[2] = sum22;
      b[3] = 0.00e0;
      b[4] = sum32;
      b[5] = sum33;
    }
  }
}


//      e05jb Example Program Text
//
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class E05JBE
  {
    const int n=2;
    static string datafile = "ExampleData/e05jbe.d";
    static bool lplot;
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        //      values of optional parameters associated with e05jb
        //
        double infbnd,   obj; int i,  ibound,  iinit,  j,  sdlist,  stclim;
        string lcsrch="";
        E05.E05JB_OBJFUN objfunE05JB = new E05.E05JB_OBJFUN(objfun);
        E05.E05JB_MONIT monitE05JB = new E05.E05JB_MONIT(monit);
        //
        int ifail=0;
        Console.WriteLine("e05jb Example Program Results");
        //
        //      Skip heading in data file
        //
        sr.Reset();
        //
        //      Read sdlist from data file
        //
        sr.Reset();
        sdlist = int.Parse(sr.Next());
        double[] bl = new double[n];
        double[] bu = new double[n];
        double[,] list = new double[n, sdlist];
        double[] ruser = new double[1];
        double[] x = new double[n];
        int[] initpt = new int[n];
        int[] numpts = new int[n];
        //
        //
        //         Read ibound, bl, and bu from data file
        //
        sr.Reset();
        ibound = int.Parse(sr.Next());
        //
        if (ibound == 0)
        {
          //
          //            Read in the whole of each bound
          //
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            bl[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            bu[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //
        }
        else if (ibound == 3)
        {
          //
          //            Bounds are uniform: read in only the first entry of each
          //
          sr.Reset();
          bl[0] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          sr.Reset();
          bu[0] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          //
        }
        //
        //         Read in iinit (and list, numpts and initpt if necessary)
        //         from data file
        //
        sr.Reset();
        iinit = int.Parse(sr.Next());
        //
        if (iinit == 3)
        {
          //
          //            User is specifying the initialization list
          //
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            numpts[i - 1] = int.Parse(sr.Next());
          }
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            for (j = 1 ; j <= numpts[i - 1] ; j++)
            {
              list[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            initpt[i - 1] = int.Parse(sr.Next());
          }
          //
        }
        //
        //         Read lplot. Its value determines whether monit displays
        //         information on the current search box
        //
        sr.Reset();
        lplot = bool.Parse(sr.Next());
        //
        //         Initialize e05jb
        //
        E05.e05jbOptions options = new E05.e05jbOptions();
        //
        if (ifail >= 0)
        {
          //
          //            Use e05jb to read some options from the end of the data
          //            file
          //
          options.Set(sr);
          Console.WriteLine("");
          //
          //            Set 'Static Limit'
          //
          stclim = 4 * n;
          options.Set("Static Limit", stclim);
          //
          //            Set 'Infinite Bound Size' tenfold
          //
          infbnd = 1.00e100;
          options.Set("Infinite Bound Size", infbnd);
          //
          //            Set the option 'Local Searches Limit = 40'
          //
          options.Set("Local Searches Limit = 40");
          //
          //            Set the option 'Local Searches' to 'On'
          //
          lcsrch = "On";
          options.Set("Local Searches", lcsrch);
          //
          //            Solve the problem.
          //
          E05.e05jb(n, objfunE05JB, ibound, iinit, bl, bu, list, numpts, initpt, monitE05JB, x,
                    out obj,
          options, out ifail);
          //
          Console.WriteLine("");
          if (ifail >= 0)
          {
            Console.WriteLine("  On exit from e05jb, ifail ={0,5}",ifail);
            //
            if (ifail == 0)
            {
              Console.WriteLine("  Final objective value ={0,11:f5}",obj);
              Console.Write("Global optimum x = ");
              for (i = 1 ; i <= n ; i++)
              {
                Console.Write(" {0, 9:f5}", x[i - 1]);
              }
              Console.WriteLine();
            }
          }
          else
          {
            Console.WriteLine(" ** e05jb returned with ifail = {0, 3}", ifail);
          }
          //
        }
        //
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    //
    public static void objfun (int n, double[] x, out double f, int nstate,
    out int inform)
    {
      //
      //      Routine to evaluate objective function.
      //
      double x1,   x2;
      //
      inform = 0;
      f = 0.0;
      if ((inform) >= 0)
      {
        //
        //         If inform >= 0 then we're prepared to evaluate objfun
        //         at the current x
        //
        if (nstate == 1)
        {
          //
          //            This is the first call to objfun
          //
          Console.WriteLine("");
          Console.WriteLine("  (OBJFUN was just called for the first time)");
        }
        //
        x1 = x[0];
        x2 = x[1];
        //
        f = 3.0e0*(1.0e0-x1)*(1.0e0-x1)*Math.Exp(-(x1*x1)-(x2+1)*(x2+1)) -
        1.0e1*(x1/5.0e0-Math.Pow(x1, 3)-Math.Pow(x2,5))*Math.Exp(-x1*x1-x2*x2) -
        1.0e0/3.0e0*Math.Exp(-(x1+1.0e0)*(x1+1.0e0)-x2*x2);
      }
      //
      //
    }
    //
    public static void monit (int n, int ncall, double[] xbest, int[] icount,
    double[,] list, int[] numpts, int[] initpt, int nbaskt, double[,] xbaskt,
    double[] boxl, double[] boxu, int nstate, out int inform)
    {
      //
      //      Monitoring method.
      //
      int i,  j; //  inform;
      //
      inform = 0;
      if ((inform) >= 0)
      {
        //
        //         We are going to allow the iterations to continue.
        //         Extract plot from the integer communication-array
        //
        //
        if ((nstate == 0) || (nstate == 1))
        {
          //
          //            When nstate == 1, monit is called for the first time. When
          //            nstate == 0, monit is called for the first AND last time.
          //            Display a welcome message
          //
          Console.WriteLine("");
          Console.WriteLine("  *** Begin monitoring information ***");
          Console.WriteLine("");
          //
          if (lplot && n == 2)
          {
            Console.WriteLine("  <Begin displaying search boxes>");
            Console.WriteLine("");
          }
          //
        }
        //
        if (lplot && n == 2)
        {
          //
          //            Display the coordinates of the edges of the current search
          //            box
          //
          outbox(ref n, boxl, boxu);
          //
        }
        //
        if (nstate <= 0)
        {
          //
          //            monit is called for the last time
          //
          if (lplot && n == 2)
          {
            Console.WriteLine("  <End displaying search boxes>");
            Console.WriteLine("");
          }
          //
          Console.WriteLine("  Total sub-boxes ={0,5}",icount[0]);
          Console.WriteLine("  Total function evaluations ={0,5}",ncall);
          Console.WriteLine("  Total function evaluations used in local search ={0,5}",icount[1]);
          Console.WriteLine("  Total points used in local search ={0,5}",icount[2]);
          Console.WriteLine("  Total sweeps through levels ={0,5}",icount[3]);
          Console.WriteLine("  Total splits by init. list ={0,5}",icount[4]);
          Console.WriteLine("  Lowest level with nonsplit boxes ={0,5}",icount[5]);
          Console.WriteLine("  Number of candidate minima in the \"shopping basket\" ={0,5}",nbaskt);
          Console.WriteLine("  Shopping basket:");
          //
          for (i = 1 ; i <= n ; i++)
          {
            Console.Write("xbaskt({0,3},:) = ",  i);
            for (j = 1 ; j <= nbaskt ; j++)
            {
              Console.Write(" {0, 9:f5}", xbaskt[i - 1 , j - 1]);
            }
            Console.WriteLine();
          }
          //
          Console.WriteLine("");
          Console.WriteLine("  *** End monitoring information ***");
          Console.WriteLine("");
        }
        //
      }
      //
      //
    }
    public static void outbox (ref int n, double[] boxl, double[] boxu)
    {
      //
      //      Displays edges of box with bounds boxl and boxu in format suitable
      //      for plotting.
      //
      //
      //
      Console.WriteLine("{0,20:f15}  {1,20:f15}",boxl[0],boxl[1]);
      Console.WriteLine("{0,20:f15}  {1,20:f15}",boxl[0],boxu[1]);
      Console.WriteLine("");
      Console.WriteLine("{0,20:f15}  {1,20:f15}",boxl[0],boxl[1]);
      Console.WriteLine("{0,20:f15}  {1,20:f15}",boxu[0],boxl[1]);
      Console.WriteLine("");
      Console.WriteLine("{0,20:f15}  {1,20:f15}",boxl[0],boxu[1]);
      Console.WriteLine("{0,20:f15}  {1,20:f15}",boxu[0],boxu[1]);
      Console.WriteLine("");
      Console.WriteLine("{0,20:f15}  {1,20:f15}",boxu[0],boxl[1]);
      Console.WriteLine("{0,20:f15}  {1,20:f15}",boxu[0],boxu[1]);
      Console.WriteLine("");
      //
      //
    }
  }
}


e05jc Example Program Data
  3                                                     : SDLIST
  0                                                     : IBOUND
  -3.0   -3.0                                           : Lower bounds BL
  3.0   3.0                                             : Upper bounds BU
  3                                                     : IINIT
  3   3   3                                             : NUMPTS
  -3.0   -1.0   3.0   -3.0   0.0   3.0                  : Matrix LIST
  2   2   2                                             : INITPT
  F                                                     : LPLOT
Begin example options file
* Comment lines like this begin with an asterisk
* Set the maximum number of function evaluations
Function Evaluations Limit = 100000
* Set the local search termination tolerance
Local Searches Tolerance = 1.0D-10
* Set the maximum number of times a given box may be split
Splits Limit = 20
End


e05jb Example Program Results

  (OBJFUN was just called for the first time)

  *** Begin monitoring information ***

  Total sub-boxes =  180
  Total function evaluations =  185
  Total function evaluations used in local search =  102
  Total points used in local search =    9
  Total sweeps through levels =    9
  Total splits by init. list =    5
  Lowest level with nonsplit boxes =    6
  Number of candidate minima in the "shopping basket" =    2
  Shopping basket:
xbaskt(  1,:) =    0.22828  -1.34740
xbaskt(  2,:) =   -1.62553   0.20452

  *** End monitoring information ***

  On exit from e05jb, ifail =    0
  Final objective value =   -6.55113
Global optimum x =    0.22828  -1.62553


//    Mark 24 Release. NAG Copyright 2012.
//      C# version, NAG Copyright 2012
using System;
using NagLibrary;
using System.Globalization;

namespace NagDotNetExamples
{

    public class E05UCE
    {

        public static void schwefel_obj(ref int mode, int n, double[] x, ref double objf, double[] objgrd, int nstate)
        {
            if ((mode == 0) || (mode == 2))
            {
                //          Evaluate the objective function.
                objf = 0.0;
                for(int j=0; j< n ;j++){

                objf = objf + x[j] * Math.Sin(Math.Sqrt(Math.Abs(x[j ])));
                }
            }
            if ((mode == 1) || (mode == 2))
            {

                for(int j=0; j< n ;j++){
                //          Calculate the gradient of the objective function.
                objgrd[j] = Math.Sin(Math.Sqrt(Math.Abs(x[j]))) + 0.5 * Math.Sqrt(Math.Abs(x[j])) * Math.Cos(Math.Sqrt(Math.Abs(x[j])));
           }
                }
        }

        public static void schwefel_confun(ref int mode, int ncnln, int n, int[] needc, double[] x, double[] c, double[,] cjsl, int nstate)
        {
            double t1,
            t2;
            int k = 0;
            if ((mode == 0) || (mode == 2))
            {
                //          Constraint values are required.
                //          Only those for which needc is non-zero need be set.
                for (k = 1; k <= ncnln; k++)
                {
                    if (needc[k - 1] > 0)
                    {
                        switch (k)
                        {
                            case 1:
                                c[k - 1] = (x[0]) * (x[0]) - (x[1]) * (x[1]) + 3.0 * x[0] * x[1];
                                break;
                               case 2:
                                c[k - 1] = Math.Cos(((x[0] / 200.0)) * ((x[0] / 200.0)) + (x[1] / 100.0));
                                break;
                        }
                    }
                }
            }
            if ((mode == 1) || (mode == 2))
            {
                //          Constraint derivatives are required.
                for (k = 1; k <= ncnln; k++)
                {
                    switch (k)
                    {
                        case 1:

                            cjsl[k - 1, 0] = 2.0 * x[0] + 3.0 * x[1];
                            cjsl[k - 1, 1] = -2.0 * x[1] + 3.0 * x[0];
                          break;
                        case 2:
                            t1 = x[0] / 200.0;
                            t2 = x[1] / 100.0;
                            cjsl[k - 1, 0] = -Math.Sin((t1) * (t1) + t2) * 2.0 * t1 / 200.0;
                            cjsl[k - 1, 1] = -Math.Sin((t1) * (t1) + t2) / 100.0;
                            break;
                    }
                }
            }
        }

        public static void mystart(ref int npts, double[,] quas, ref int n, ref bool repeat, double[] bl, double[] bu, int[] iuser, double[] ruser, ref int mode)
        {
            //        Sets an initial point.
            //        quas(1:n,1:npts) is pre-assigned to zero.
            for (int j = 0; j < n; j++)
            {
                quas[j, 0] = 420.9687;
            }
        }

        static string datafile = "ExampleData/e05uce.d";
        // Specify data file as a command line argument.
        // It defaults to the named file specified below otherwise.

    static void Main(String[] args)
    {
      if (args.Length == 1)
      {

        datafile = args[0];
      }
      StartExample();
    }
         public static void StartExample()
    {
            try{
                E05.E05UC_CONFUN schwefel_confunE05UCF = new E05.E05UC_CONFUN(schwefel_confun);
                E05.E05UC_OBJFUN schwefel_objE05UCF = new E05.E05UC_OBJFUN(schwefel_obj);
                E05.E05UC_START e05uczE05UCF = new E05.E05UC_START(E05.e05ucz);
                DataReader sr = new DataReader(datafile);
                //      e05uc Example Main Program
                int n = 2,
                nclin = 1,
                ncnln = 2;
                int i = 0,
                ifail = 0,
                j = 0,
                k = 0,
                l = 0,
                lda = 0,
                ldc = 0,
                ldcjac = 0,
                ldclda = 0,
                ldobjd = 0,
                ldr = 0,
                ldx = 0,
                listat = 0,
                nb = 0,
                npts = 0,
                sda = 0,
                sdcjac = 0,
                sdr = 0;
                bool repeat = false;
                double[,] a;
                double[] bl = { -500.0, -500.0, -10000.0, -1.0, -0.9 };
                double[] bu = { 500.0, 500.0, 10.0, 500000.0, 0.9 };
                double[,] c;
                double[,,] cjac;
                double[,] clamda;
                double[] objf;
                double[,] objgrd;
                double[,,] r;
                double[] work;
                double[,] x;
                double[] ruser = new double[1];
                int[] info;
                int[,] istate;
                int[] iter;
                int[] iuser = new int[1];
                Console.WriteLine(" {0}", "e05uc Example Program Results");
                //      Skip heading in data file
                sr.Reset();
                sr.Reset();
                nb = int.Parse(sr.Next());
                npts = int.Parse(sr.Next());
                sr.Reset();
                repeat = bool.Parse(sr.Next());
                lda = (int)nclin;
                if (nclin > 0)
                {
                    sda = (int)n;
                }
                else
                {
                    sda = 1;
                }
                ldx = (int)n;
                ldobjd = (int)n;
                ldc = (int)ncnln;
                ldcjac = (int)ncnln;
                if (ncnln > 0)
                {
                    sdcjac = (int)n;
                }
                else
                {
                    sdcjac = 0;
                }
                ldr = (int)n;
                sdr = (int)n;
                ldclda = n + nclin + ncnln;
                listat = n + nclin + ncnln;
                // allocate
               a= new double[lda, sda];
               x = new double[ldx, nb];
                objf= new double[nb];
                    objgrd= new double[ldobjd, nb];
                    iter= new int[nb];
                        c= new double[ldc, nb];
                        cjac= new double[ldcjac,sdcjac, nb ];
                            r = new double[ldr, sdr, nb];
                                clamda= new double[ldclda, nb];
                                istate= new int[listat, nb];
                                    info=new int[nb];
                work= new double[nclin];
                a[0,0] = 3.0;
                a[0,1] = -2.0;
                //      Initialize the solver.
                ifail = 0;
                E05.e05ucOptions options = new E05.e05ucOptions();
                //      Solve the problem.
                //      USE mystart and pass this instead of e05ucz to e05uc
                //      to set your own start points.
                ifail = -1;
                E05.e05uc(n, nclin, ncnln, a, bl, bu, schwefel_confunE05UCF, schwefel_objE05UCF, npts, x, e05uczE05UCF, repeat, nb, objf, objgrd, iter, c, cjac, sdcjac, r, sdr, clamda, istate, options,  info, out ifail);
                switch (ifail)
                {
                    case 0:

                        l = (int)nb;
                       break;
                    case 8:
                        l = info[nb - 1];
                        Console.WriteLine(" {0} {1}", iter[nb - 1], " starting points converged");
                        break;
                    default:
                        break;
                }
                for (i = 1; i <= l; i++)
                {
                    Console.WriteLine("\n  Solution number{0,16}", i);
                    Console.WriteLine("\n  Local minimization exited with code{0,5}", info[i - 1]);
                    Console.WriteLine("\n  {0}    Istate      Value                  Lagr Mult\n", "Varbl");
                    for (j = 1; j <= n; j++)
                    {
                        Console.WriteLine("  {0}  {1,3}  {2,3}        {3,14:f6}    {4,12:f4}", "V", j, istate[j - 1, i - 1], x[j - 1, i - 1], clamda[j - 1, i - 1]);
                    }
                    if (nclin > 0)
                    {
                        Console.WriteLine("\n  {0}    Istate      Value                  Lagr Mult\n", "L Con");
                        //          Below is a call to the level 2 BLAS routine DGEMV.
                        //          This performs the matrix vector multiplication A*X
                        //          (linear constraint values) and puts the result in
                        //          the first NCLIN locations of WORK.F06.dgemv("N", nclin, n, 1.0, a, ArraySlice.ArraySlice1(x, 1, i), 1, 0.0, work, 1);
                      //  dgemv('N',nclin,n,1.0_nag_wp,a,lda,x(1,i),1,0.0_nag_wp,work,1)
                        double[] intx = new double[n];

                        for (int lindex = 0; lindex < n; lindex++)
                        {
                            intx[lindex] = x[lindex,i-1 ];
                        }

                    F06.f06pa( "N" , nclin , n ,
                        1.0 , a , intx , 1 ,
                        0.0 , work , 1 , out ifail );

                        for (k = n + 1; k <= n + nclin; k++)
                        {
                            j = k - n;
                            Console.WriteLine("  {0}  {1,3}  {2,3}        {3,14:f6}    {4,12:f4}", "L", j, istate[k - 1, i - 1], work[j - 1], clamda[k - 1, i - 1]);
                        }
                    }
                    if (ncnln > 0)
                    {
                        Console.WriteLine("\n  {0}    Istate      Value                  Lagr Mult\n", "N Con");
                        for (k = n + nclin + 1; k <= n + nclin + ncnln; k++)
                        {
                            j = k - n - nclin;
                            Console.WriteLine("  {0}  {1,3}  {2,3}        {3,14:f6}    {4,12:f4}", "N", j, istate[k - 1, i - 1], c[j - 1, i - 1], clamda[k - 1, i - 1]);
                        }
                    }
                    Console.WriteLine("\n  Final objective value =   {0,15:f7}", objf[i - 1]);
                    Console.WriteLine("\n  QP multipliers");
                    for (k = 1; k <= n + nclin + ncnln; k++)
                    {
                        Console.WriteLine(" {0,12:f4}", clamda[k-1,i-1]);
                    }
                    Console.WriteLine();
                    Console.WriteLine("");
                    Console.WriteLine(" {0}", " ------------------------------------------------------ ");
                }

            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
                Console.WriteLine("Exception Raised");
            }
        }
    }
}


e05uc Example Program Data
2 1000                                  : NB, NPTS
T                                       : REPEAT


//    e05us Example Program Text
//    Mark 24 Release. NAG Copyright 2012.
//      C# version, NAG Copyright 2012
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{

    public class E05USE
    {
        public static void objfun(ref int mode, int m, int n, int needfi, double[] x, double[] f, double[,] fjac, int nstate)
        {
            //        Routine to evaluate the subfunctions and their 1st derivatives.

            double[] a = { 8.0, 8.0, 10.0, 10.0, 10.0, 10.0, 12.0, 12.0, 12.0, 12.0, 14.0, 14.0, 14.0, 16.0, 16.0, 16.0, 18.0, 18.0, 20.0, 20.0, 20.0, 22.0, 22.0, 22.0, 24.0, 24.0, 24.0, 26.0, 26.0, 26.0, 28.0, 28.0, 30.0, 30.0, 30.0, 32.0, 32.0, 34.0, 36.0, 36.0, 38.0, 38.0, 40.0, 42.0 };
            double ai,
            temp,
            x1,
            x2;
            int i = 0;
            bool mode02 = false,
            mode12 = false;
            x1 = x[0];
            x2 = x[1];
            mode02 = ((mode == 0) || (mode == 2));
            mode12 = ((mode == 1) || (mode == 2));
            for (i = 1; i <= m; i++)
            {
                if (needfi == i)
                {
                    f[i - 1] = x1 + (0.49 - x1) * Math.Exp(-x2 * (a[i - 1] - 8.0));
                }
                ai = a[i - 1];
                temp = Math.Exp(-x2 * (ai - 8.0));
                if (mode02)
                {
                    f[i - 1] = x1 + (0.49 - x1) * temp;
                }
                if (mode12)
                {
                    fjac[i - 1, 0] = 1 - temp;
                    fjac[i - 1, 1] = -(0.49 - x1) * (ai - 8.0) * temp;
                }
            }
        }

        public static void confun(ref int mode, int ncnln, int n, int[] needc, double[] x, double[] c, double[,] cjac, int nstate)
        {
            //        Routine to evaluate the nonlinear constraint and its 1st
            //        derivatives.
            if (nstate == 1)
            {
                //          First call to CONFUN.  Set all Jacobian elements to zero.
                //          Note that this will only work when 'Derivative Level = 3'
                //          (the default; see Section 11.2).
                for (int i = 1; i <= ncnln; i++)
                {
                    for (int j = 1; j <= n; j++)
                    {
                        cjac[i- 1, j  - 1] = 0;
                    }
                }
            }
            if (needc[0] > 0)
            {
                if ((mode == 0) || (mode == 2))
                {
                    c[0] = -0.09 - x[0] * x[1] + 0.49 * x[1];
                }
                if ((mode == 1) || (mode == 2))
                {
                    cjac[0, 0] = -x[1];
                    cjac[0, 1] = -x[0] + 0.49;
                }
            }
        }

        public static void mystart(int lnpts, double[,] quas, int n, bool repeat, double[] bl, double[] bu, ref int mode)
        {
            //        All elements of quas(1:n,1:lnpts) are pre-assigned to zero
            //        so we only need to set non-zero elements
            quas[0, 0] = 0.4;
        }

        // Specify data file as a command line argument.
        // It defaults to the named file specified below otherwise.

        static string datafile = "ExampleData/e05use.d";

        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
        {

                E05.E05US_CONFUN confunE05USF = new E05.E05US_CONFUN(confun);
                E05.E05US_OBJFUN objfunE05USF = new E05.E05US_OBJFUN(objfun);
                E05.E05US_START mystartE05USF = new E05.E05US_START(mystart);
try
            {
        DataReader sr = new DataReader(datafile);
                //      e05us Example Main Program
                int mmax = 44,
                nb = 1,
                nclin = 1,
                nclmax = 1,
                ncnln = 1,
                ncnmax = 2,
                nmax = 2,
                npts = 1;
                int sda = nmax;
                int sdcjac = nmax;
                int sdfjac = nmax;
                int sdr = nmax;
                int lbjgrd = nmax;
                int lda = nclmax;
                int ldc = ncnmax;
                int ldcjac = ncnmax;
                int ldclda = nmax + nclmax + ncnmax;
                int ldfjac = mmax;
                int ldr = nmax;
                int ldx = nmax;
                int listat = nmax + nclmax + ncnmax;
                bool repeat = true;
                int i = 0,
                ifail = 0,
                j = 0,
                k = 0,
                l = 0,
                m = 0,
                n = 0;
                m = 44;
                n = 2;
                double[,] a = new double[lda,sda];
                double[] bl = new double[n+ nclin+ncnln];
                double[] bu= new double[n + nclin + ncnln];
                double[,] c = new double [ncnmax, nb];
                double[,,] cjac = new double[ldcjac, sdcjac, nb];
                double[,] clamda = new double[ldclda, nb];
                double[,] f = new double[m, nb];
                double[,,] fjac = new double[ldfjac, sdfjac, nb];
                double[] work = new double[nclin];
                double[,] x = new double[n, nb];
                double[] y = new double[m];
                double[] objf = new double[nb];
                int lrwsav = 485;
                int liwsav = 740;
                double[] rwsav = new double[lrwsav];
                double[] user = new double[1];
                int[] info = new int[nb];
                int[,] istate = new int[listat, nb];
                int[] iter = new int[nb];
                int[] iuser = new int[1];
                int[] iwsav = new int[liwsav];
                Console.WriteLine(" {0}", "e05us Example Program Results");
                //      Skip heading in data file
                sr.Reset();

                // allocate
                if (nclin > 0)
                {
                    sr.Reset();
                    for (i = 0; i < nclin; i++)
                    {
                        for (j = 0; j < sda; j++)
                        {

                            a[i , j] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                        }
                    }
                }
                sr.Reset();
                for (j = 0; j < m; j++) {
                y[j ] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }
                sr.Reset();
                for (j = 0; j < n + nclin + ncnln; j++)
                {
                    bl[j] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }
                sr.Reset();
                for (j = 0; j < n + nclin + ncnln; j++)
                {
                    bu[j ] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }
                //      Initialise e05us and check for error exits
                ifail = 0;
                E05.e05usOptions options = new E05.e05usOptions();

                options.Set("List");
                options.Set("print level = 10");

                //      Solve the problem
                ifail = -1;
                E05.e05us(m, n, nclin, ncnln, a, bl, bu, y, confunE05USF, objfunE05USF, npts, x, mystartE05USF, repeat, nb, objf, f, fjac, sdfjac, iter, c, cjac, sdcjac, clamda, istate, options, info, out ifail);
                //      Check for error exits
                if (ifail==0)
                {	l = (int)nb;
        }
        else if (ifail ==2)
            {
                    l=0;
                }
            else if (ifail==3){
                l=0;}
                else if (ifail==8){

                        l = info[nb - 1];
                        Console.WriteLine(" {0} {1} {2}", "ONLY ", l, " SOLUTIONS FOUND");
                        Console.WriteLine(" {0} {1}", iter[nb - 1], " starting points converged");
                }
                else if (ifail==9){
            Console.WriteLine("   ** An input parameter is invalid");
                        l = 0;
                }
                else if (ifail==7){
            Console.WriteLine("  User supplied derivatives are incorrect");
                        l = 0;}
            else if (ifail ==-399)
            {
               Console.WriteLine("   ** e05us returned with ifail = {0,5}", ifail);
                        l = 0;
            }
            else{
                        Console.WriteLine(" Unexpected error exit, ifail = {0,5}", ifail);
                        l = 0;
            }

                for (i = 1; i <= l; i++)
                {
                    Console.WriteLine(" {0} {1}", "Solution number ", i);
                    Console.WriteLine("");
                    Console.WriteLine("  e05us returned with ifail = {0,4}", info[i - 1]);
                    Console.WriteLine("");
                    Console.WriteLine("  Varbl    Istate      Value                  Lagr Mult");
                    Console.WriteLine("");
                    for (j = 1; j <= n; j++)
                    {
                        Console.WriteLine("  V  {0,3}  {1,3}        {2,14:f6}    {3,12:f4}", j, istate[j - 1, i - 1], x[j - 1, i - 1], clamda[j - 1, i - 1]);
                    }
                    if (nclin > 0)
                    {
                        //          Below is a call to the level 2 BLAS routine DGEMV.
                        //          This performs the matrix vector multiplication A*X
                        //          (linear constraint values) and puts the result in
                        //          the first NCLIN locations of WORK.F06.dgemv("N", nclin, n, 1.00e0, a, ArraySlice.ArraySlice1(x, 1, i), 1, 0.00e0, work, 1);
                        Console.WriteLine("");
                        Console.WriteLine("");
                        Console.WriteLine("  L Con    Istate      Value                  Lagr Mult");
                        Console.WriteLine("");
                        for (k = n + 1; k <= n + nclin; k++)
                        {
                            j = k - n;
                            Console.WriteLine("  L  {0,3}  {1,3}        {2,14:f6}    {3,12:f4}", j, istate[k - 1, i - 1], work[j - 1], clamda[k - 1, i - 1]);
                        }
                    }
                    if (ncnln > 0)
                    {
                        Console.WriteLine("");
                        Console.WriteLine("");
                        Console.WriteLine("  N Con    Istate      Value                  Lagr Mult");
                        Console.WriteLine("");
                        for (k = n + nclin + 1; k <= n + nclin + ncnln; k++)
                        {
                            j = k - n - nclin;
                            Console.WriteLine("  N  {0,3}  {1,3}        {2,14:f6}    {3,12:f4}", j, istate[k - 1, i - 1], c[j - 1, i - 1], clamda[k - 1, i - 1]);
                        }
                    }
                    Console.WriteLine("");
                    Console.WriteLine("");
                    Console.WriteLine("  Final objective value = {0,15:f7}", objf[i - 1]);
                    Console.WriteLine("");
                    Console.WriteLine(" {0}", "QP multipliers");
                    for (k = 0; k < n + nclin + ncnln; k++)
                    {

                        Console.WriteLine(" {0,12:f4}", clamda[k,i-1]);
                    }
                    Console.WriteLine();
                    Console.WriteLine("");
                    Console.WriteLine(" {0}", " ------------------------------------------------------ ");
                    Console.WriteLine("");
                }

            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
                Console.WriteLine("Exception Raised");
            }
        }
    }

}


 e05us Example Program Results

 Calls to E05USF
 ---------------

      LIST
      PRINT LEVEL = 10

 *** E05USF

 Parameters
 ----------

 Linear constraints.....         1       Variables..............         2
 Nonlinear constraints..         1       Subfunctions...........        44

 Infinite bound size....  1.00E+20       COLD start.............
 Infinite step size.....  1.00E+20       EPS (machine precision)  1.11E-16
 Step limit.............  2.00E+00       Hessian................        NO

 Linear feasibility.....  1.05E-08       Crash tolerance........  1.00E-02
 Nonlinear feasibility..  1.05E-08       Optimality tolerance...  3.26E-12
 Line search tolerance..  9.00E-01       Function precision.....  4.37E-15

 Derivative level.......         3       Monitoring file........        -1
 Verify level...........         0

 Major iterations limit.        50       Major print level......        10
 Minor iterations limit.        50       Minor print level......         0

 J'J initial Hessian....                 Reset frequency........         2

 Workspace provided is     IWORK(       9),  WORK(     306).
 To solve problem we need  IWORK(       9),  WORK(     306).

 Verification of the constraint gradients.
 -----------------------------------------

 The constraint Jacobian seems to be ok.

 The largest relative error was    1.89E-08  in constraint    1

 Verification of the objective gradients.
 ----------------------------------------

 The objective Jacobian seems to be ok.

 The largest relative error was    1.04E-08  in subfunction    3

  Maj  Mnr    Step Merit Function Norm Gz  Violtn Cond Hz
    0    2 0.0E+00   2.224070E-02 8.5E-02 3.6E-02 1.0E+00
    1    1 1.0E+00   1.455402E-02 1.5E-03 9.8E-03 1.0E+00
    2    1 1.0E+00   1.436491E-02 4.9E-03 7.2E-04 1.0E+00
    3    1 1.0E+00   1.427013E-02 2.9E-03 9.2E-06 1.0E+00
    4    1 1.0E+00   1.422989E-02 1.6E-04 3.6E-05 1.0E+00
    5    1 1.0E+00   1.422983E-02 5.4E-07 6.4E-08 1.0E+00
    6    1 1.0E+00   1.422983E-02 3.4E-09 9.8E-13 1.0E+00

 Exit from NP problem after     6 major iterations,
                                8 minor iterations.

 Varbl State     Value       Lower Bound   Upper Bound    Lagr Mult   Slack

 V   1    FR   0.419953      0.400000          None           .      1.9953E-02
 V   2    FR    1.28485      -4.00000          None           .       5.285

 L Con State     Value       Lower Bound   Upper Bound    Lagr Mult   Slack

 L   1    FR    1.70480      1.000000          None           .      0.7048

 N Con State     Value       Lower Bound   Upper Bound    Lagr Mult   Slack

 N   1    LL  -9.767742E-13       .            None      3.3358E-02 -9.7677E-13

 Exit E05USF - Optimal solution found.

 Final objective value =   0.1422983E-01
 Solution number  1

  e05us returned with ifail =    0

  Varbl    Istate      Value                  Lagr Mult

  V    1    0              0.419953          0.0000
  V    2    0              1.284845          0.0000

  L Con    Istate      Value                  Lagr Mult

  L    1    0              0.000000          0.0000

  N Con    Istate      Value                  Lagr Mult

  N    1    1              0.000000          0.0334

  Final objective value =       0.0142298

 QP multipliers
       0.0000
       0.0000
       0.0000
       0.0334

  ------------------------------------------------------


//      f01ed Example Program Text
//      C# version, NAG Copyright 2012

using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
    public class F01EDE
    {

        // Specify data file as a command line argument.
        // It defaults to the named file specified below otherwise.
        static string datafile = "ExampleData/f01ede.d";

        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
        {

        try {

                DataReader sr = new DataReader(datafile);
                //      f01ed Example Program Text
                //      Mark 25 Release. NAG Copyright 2013.

                int i = 0,
                                   ifail = 0,
                                   lda = 0,
                                   n = 0;

                string uplo = "";

                Console.WriteLine(" {0}", "F01EDF Example Program Results");

                Console.WriteLine("");

                //      Skip heading in data file
                sr.Reset();

                sr.Reset();
                n = int.Parse(sr.Next());

                sr.Reset();
                uplo = sr.Next();

                lda = (int)n;

                double[,] a = new double[lda, n];

                // allocate
                int j = 0;
                //      Read A from data file
                if ((uplo == "U") || (uplo == "u"))
                {

                    sr.Reset();

                    for (i = 1; i <= n; i++)
                    {
                        for (j = i; j <= n; j++)
                        {
                            a[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                        }
                    }

                }
                else
                {
                    sr.Reset();

                    for (i = 1; i <= n; i++)
                    {
                        for (j = 1; j <= i; j++)
                        {
                            a[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                        }
                    }

                }

                //      ifail: behaviour on error exit
                //             =0 for hard exit, =1 for quiet-soft, =-1 for noisy-soft
                ifail = 0;

                //      Find exp( A )
                F01.f01ed(uplo, n, a, out ifail);

                //      Print solution
            X04.x04ca(uplo, "N", n, n, a, "Symmetric Exp(A)", out ifail);

            }

            catch (Exception e)
            {
                Console.WriteLine(e.Message);
                Console.WriteLine("Exception Raised");
            }

        }
    }
}


//    f01ef Example Program Text
//    Mark 25 Release. NAG Copyright 2013.
//      C# version, NAG Copyright 2012

using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
    public class F01EFE
    {

        public static void f(ref int iflag, int n, double[] x, double[] fx)
        {
            int j = 0;
            for (j = 1; j <= n; j++)
            {

                fx[j - 1] = Math.Cos(x[j - 1]);

            }
        }

        // Specify data file as a command line argument.
        // It defaults to the named file specified below otherwise.
        static string datafile = "ExampleData/f01efe.d";

        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
        {

            try
            {
                F01.F01EF_F fF01EFF = new F01.F01EF_F(f);

                DataReader sr = new DataReader(datafile);
                //      f01ef Example Main Program
                int i = 0,
                                   ierr = 0,
                                   ifail = 0,
                                   iflag = 0,
                                   lda = 0,
                                   n = 0;

                string uplo = "";

                double[] ruser = new double[1];

                int[] iuser = new int[1];

                Console.WriteLine(" {0}", "F01EFF Example Program Results");

                Console.WriteLine("");

                //      Skip heading in data file
                sr.Reset();

                sr.Reset();
                n = int.Parse(sr.Next());

                sr.Reset();
                uplo = sr.Next();

                int j = 0;
                lda = (int)n;
                double[,] a = new double[lda,n];
                // allocate

                //      Read A from data file
                if ((uplo == "U") || (uplo == "u"))
                {

                    sr.Reset();

                    for (i = 1; i <= n; i++)
                    {
                        for (j = i; j <= n; j++)
                        {

                            a[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                        }
                    }

                }
                else
                {
                    sr.Reset();

                    for (i = 1; i <= n; i++)
                    {
                        for (j = 1; j <= i; j++)
                        {
                            a[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                        }
                    }

                }

                //      Find f( A )
                ifail = 0;
                F01.f01ef(uplo, n, a, fF01EFF, out iflag, out ifail);

                //      Print solution
                ierr = 0;
                X04.x04ca(uplo, "N", n, n, a, "Symmetric f(A)", out ierr);

            }

            catch (Exception e)
            {
                Console.WriteLine(e.Message);
                Console.WriteLine("Exception Raised");
            }
        }
    }
}


F01EFF Example Program Data

  4                      :Value of N
 'U'                     :Value of UPLO

  1.0   2.0   3.0   4.0
        1.0   2.0   3.0
              1.0   2.0
                    1.0  :End of matrix A


//      f01fc Example Program Text
//      C# version, NAG Copyright 2012

using System;
using NagLibrary;
namespace NagDotNetExamples
{
    public class F01FCE
    {

        // Specify data file as a command line argument.
        // It defaults to the named file specified below otherwise.
        static string datafile = "ExampleData/f01fce.d";

        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
        {

            try
            {

                DataReader sr = new DataReader(datafile);
                //      f01fc Example Program Text
                //      Mark 25 Release. NAG Copyright 2013.
                int i = 0,
                                   ierr = 0,
                                   ifail = 0,
                                   lda = 0,
                                   n = 0;

                Console.WriteLine(" {0}", "F01FCF Example Program Results");

                Console.WriteLine("");

                //      Skip heading in data file
                sr.Reset();

                sr.Reset();
                n = int.Parse(sr.Next());

                int j = 0;
                lda = (int)n;
                Complex[,] a = new Complex[lda, n];
                // allocate

                //      Read A from data file
                sr.Reset();

                for (i = 1; i <= n; i++)
                {
                    for (j = 1; j <= n; j++)
                    {
                        a[i - 1, j - 1] = Complex.Parse(sr.Next());
                    }
                }

                //      ifail: behaviour on error exit
                //              =0 for hard exit, =1 for quiet-soft, =-1 for noisy-soft
                ifail = 0;

                //      Find exp( A )
                F01.f01fc(n, a, out ifail);

                //      Print solution
                ierr = 0;
                X04.x04da("General", "", n, n, a, "Exp(A)", out ierr);

            }

            catch (Exception e)
            {
                Console.WriteLine(e.Message);
                Console.WriteLine("Exception Raised");
            }
        }
    }
}


//      f01fd Example Program Text
//      C# version, NAG Copyright 2012

using System;
using NagLibrary;
namespace NagDotNetExamples
{
    public class F01FDE
    {

        // Specify data file as a command line argument.
        // It defaults to the named file specified below otherwise.
        static string datafile = "ExampleData/f01fde.d";

        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
{

 try

   {

  DataReader sr = new DataReader(datafile);
//      f01fd Example Program Text
//      Mark 25 Release. NAG Copyright 2013.

int i=0,
                   ierr=0,
                   ifail=0,
                   lda=0,
                   n=0;

string uplo="";

Console.WriteLine(" {0}","F01FDF Example Program Results");

Console.WriteLine("");

//      Skip heading in data file
  sr.Reset();

  sr.Reset();
    n = int.Parse(sr.Next());

  sr.Reset();
    uplo = sr.Next();

     int j=0;
lda = (int)n;
Complex[,] a = new Complex[lda, n];
// allocate

//      Read A from data file
 if ((uplo=="U") || ( uplo== "u"))
 {

  sr.Reset();

 for (i = 1 ; i <= n ; i++)
 {
      for (j = i ; j <= n ; j++)
 {
    a[ i - 1 , j - 1] = Complex.Parse(sr.Next());
}
 }

}
 else
 {
  sr.Reset();

 for (i = 1 ; i <= n ; i++)
 {
           for (j = 1 ; j <= i ; j++)
 {
   a[ i - 1 , j  - 1] = Complex.Parse(sr.Next());
}
 }

}

//      Find exp( A )
ifail = 0;
F01.f01fd(uplo, n, a, out ifail);

//      Print solution
ierr = 0;
X04.x04da(uplo, "N", n, n, a, "Hermitian Exp(A)", out ierr);

     }

     catch (Exception e)
    {
      Console.WriteLine(e.Message);
      Console.WriteLine( "Exception Raised");
    }
  }
    }
}


//    f01ff Example Program Text
//    Mark 25 Release. NAG Copyright 2013.
//      C# version, NAG Copyright 2012

using System;
using NagLibrary;
namespace NagDotNetExamples
{
    public class F01FFE
    {

        public static void f(ref int iflag, int n, double[] x, double[] fx)
{
 for (int i = 1 ; i <= n ; i++)
 {

fx[ i - 1] = Math.Cos(x[ i - 1]);

     }
        }

        // Specify data file as a command line argument.
        // It defaults to the named file specified below otherwise.
        static string datafile = "ExampleData/f01ffe.d";

        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
{

 try

   {
F01.F01FF_F fF01FFF = new F01.F01FF_F(f);

  DataReader sr = new DataReader(datafile);
//      f01ff Example Main Program
int i=0,
                   ierr=0,
                   ifail=0,
                   iflag=0,
                   lda=0,
                   n=0;

string uplo="";

double[] ruser = new double[1];

int[] iuser = new int[1];

Console.WriteLine(" {0}","F01FFF Example Program Results");

Console.WriteLine("");

//      Skip heading in data file
  sr.Reset();

  sr.Reset();
    n = int.Parse(sr.Next());

  sr.Reset();
    uplo = sr.Next();

lda = (int)n;

Complex[,] a = new Complex[lda, n];
// allocate

//      Read A from data file
 if ((uplo =="U") || ( uplo == "u"))
 {

  sr.Reset();

 for (i = 1 ; i <= n ; i++)
 {
      for (int j = i ; j <= n ; j++)
 {
    a [i - 1 , j - 1] = Complex.Parse(sr.Next());
}
 }

}
 else
 {
  sr.Reset();

 for (i = 1 ; i <= n ; i++)
 {
           for (int j = 1 ; j <= i ; j++)
 {
    a [ i - 1 , j - 1] = Complex.Parse(sr.Next());
}
 }

}

//      Find f( A )
ifail = 0;
F01.f01ff(uplo, n, a, fF01FFF, out iflag, out ifail);

//      Print solution
ierr = 0;
X04.x04da(uplo, "N", n, n, a, "Hermitian f(A)", out ierr);

     }

     catch (Exception e)
    {
      Console.WriteLine(e.Message);
      Console.WriteLine( "Exception Raised");
    }
  }
    }
}


//      f01va Example Program Text
//      C# version, NAG Copyright 2012

using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
    public class F01VAE
    {

        static string datafile = "ExampleData/f01vae.d";

        // Specify data file as a command line argument.
        // It defaults to the named file specified below otherwise.

        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
{

 try

   {

  DataReader sr = new DataReader(datafile);
//      f01va Example Program Text
//      Mark 25 Release. NAG Copyright 2013.
int inc1 = 1,
                   indent = 0,
                   ncols = 80;

string diag = "N",
                   intlabel = "I",
                   matrix = "G",
                   nolabel = "N";

string form = "F5.2";

int i=0,
                   ifail=0,
                   info=0,
                   lda=0,
                   lenap=0,
                   n=0;

string title="";

string uplo="";

string[] clabs = new string[1];

string[] rlabs = new string[1];

Console.WriteLine(" {0}","F01VAF Example Program Results");

//      Skip heading in data file
  sr.Reset();

Console.WriteLine("");

  sr.Reset();
    n = int.Parse(sr.Next());
    uplo = sr.Next();

lda = (int)n;
double[,] a = new double[lda, n];
lenap =  (n * (n+1))/ 2;
double[] ap = new double[lenap];
// allocate
  sr.Reset();
//      Read a triangular matrix of order n
 for (i = 1 ; i <= n ; i++)
 {
     for (int j = 1; j <= n; j++)
     {

         a[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);

     }
}

//      Print the unpacked matrix
title = "Unpacked Matrix A:";

ifail = 0;
X04.x04cb(uplo, diag, n, n, a, form, title, intlabel, rlabs, intlabel, clabs, ncols, indent, out ifail);

Console.WriteLine("");

//      Convert to packed vector form
info = 0;

//      The NAG name equivalent of dtrttp is f01vaf
     F01.f01va(uplo, n, a, ap, out info);

//      Print the packed vector
title = "Packed Matrix AP: ";

ifail = 0;
X04.x04cb(matrix, diag, lenap, inc1, ap, form, title, intlabel, rlabs, nolabel, clabs, ncols, indent, out ifail);

    }

     catch (Exception e)
    {
      Console.WriteLine(e.Message);
      Console.WriteLine( "Exception Raised");
    }
  }
    }
}


//      f01vb Example Program Text
//      C# version, NAG Copyright 2012

using System;
using NagLibrary;
namespace NagDotNetExamples
{
    public class F01VBE
    {

        static string datafile = "ExampleData/f01vbe.d";

        // Specify data file as a command line argument.
        // It defaults to the named file specified below otherwise.

        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
{

 try

   {

  DataReader sr = new DataReader(datafile);
//      f01vb Example Program Text
//      Mark 25 Release. NAG Copyright 2013.
int inc1 = 1,
                   indent = 0,
                   ncols = 80;

string brac = "B",
                   diag = "N",
                   intlabel = "I",
                   matrix = "G",
                   nolabel = "N";

string form = "F5.2";

int i=0,
                   ifail=0,
                   info=0,
                   lda=0,
                   lenap=0,
                   n=0;

string title="";

string uplo="";

string[] clabs = new string[1];

string[] rlabs = new string[1];

Console.WriteLine(" {0}","F01VBF Example Program Results");

//      Skip heading in data file
  sr.Reset();

Console.WriteLine("");

  sr.Reset();
    n = int.Parse(sr.Next());
    uplo = sr.Next();

lda = (int)n;
lenap = (n * (n + 1)) / 2;

Complex[,] a = new Complex[lda, n];

Complex[] ap = new Complex[lenap];

// allocate
  sr.Reset();
//      Read a triangular matrix of order n
 for (i = 1 ; i <= n ; i++)
 {
      for (int j = 1 ; j <= n ; j++)
 {

    a [ i - 1 , j  - 1] = Complex.Parse(sr.Next());
      }

}

//      Print the unpacked matrix
title = "Unpacked Matrix A:";

ifail = 0;
X04.x04db(uplo, diag, n, n, a, brac, form, title, intlabel, rlabs, intlabel, clabs, ncols, indent, out ifail);

Console.WriteLine("");

//      Convert to packed vector form
info = 0;

//      The NAG name equivalent of ztrttp is f01vbf
     F01.f01vb(uplo, n, a, ap, out info);

//      Print the packed vector
title = "Packed Matrix AP: ";

ifail = 0;
X04.x04db(matrix, diag, lenap, inc1, ap, brac, form, title, intlabel, rlabs, nolabel, clabs, ncols, indent, out ifail);

     }

     catch (Exception e)
    {
      Console.WriteLine(e.Message);
      Console.WriteLine( "Exception Raised");
    }
  }
    }
}


//      f01vc Example Program Text
//      C# version, NAG Copyright 2012

using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
    public class F01VCE
    {

        static string datafile = "ExampleData/f01vce.d";

        // Specify data file as a command line argument.
        // It defaults to the named file specified below otherwise.

        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
{

 try

   {

  DataReader sr = new DataReader(datafile);
//      f01vc Example Program Text
//      Mark 25 Release. NAG Copyright 2013.
int inc1 = 1,
                   indent = 0,
                   ncols = 80;

string diag = "N",
                   intlabel = "I",
                   matrix = "G",
                   nolabel = "N";

string form = "F5.2";

int i=0,
                   ifail=0,
                   info=0,
                   lda=0,
                   lenap=0,
                   n=0;

string title="";

string uplo="";

double[,] a;

double[] ap;

string[] clabs = new string[1];

string[] rlabs = new string[1];

Console.WriteLine(" {0}","F01VCF Example Program Results");

//      Skip heading in data file
  sr.Reset();

Console.WriteLine("");

  sr.Reset();
    n = int.Parse(sr.Next());
    uplo = sr.Next();

lda = (int)n;

lenap = (n*(n+1)) /2;

a = new double[lda, n];
ap = new double[lenap];
// allocate

//      Read a packed vector of order n
 for (i = 1 ; i <= lenap ; i++)
 {

  sr.Reset();
    ap [ i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);

}

//      Print the packed vector
title = "Packed Matrix AP: ";

ifail = 0;
X04.x04cb(matrix, diag, lenap, inc1, ap, form, title, intlabel, rlabs, nolabel, clabs, ncols, indent, out ifail);

Console.WriteLine("");

//      Convert to triangular form
info = 0;

//      The NAG name equivalent of dtpttr is f01vcf
     F01.f01vc(uplo, n, ap, a, out info);

//      Print the unpacked matrix
title = "Unpacked Matrix A:";

ifail = 0;
X04.x04cb(uplo, diag, n, n, a, form, title, intlabel, rlabs, intlabel, clabs, ncols, indent, out ifail);

     }

     catch (Exception e)
    {
      Console.WriteLine(e.Message);
      Console.WriteLine( "Exception Raised");
    }
  }
    }
}


F01VCF Example Program Data
4 'U'                             : n, uplo
 1.1                              : Packed Matrix AP
 1.2
 2.2
 1.3
 2.3
 3.3
 1.4
 2.4
 3.4
 4.4


//      f01vd Example Program Text
//      C# version, NAG Copyright 2012

using System;
using NagLibrary;
namespace NagDotNetExamples
{
    public class F01VDE
    {

        static string datafile = "ExampleData/f01vde.d";

        // Specify data file as a command line argument.
        // It defaults to the named file specified below otherwise.

        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
{

 try

   {

  DataReader sr = new DataReader(datafile);
//      f01vd Example Program Text
//      Mark 25 Release. NAG Copyright 2013.
int inc1 = 1,
                   indent = 0,
                   ncols = 80;

string brac = "B",
                   diag = "N",
                   intlabel = "I",
                   matrix = "G",
                   nolabel = "N";

string form = "F5.2";

int i=0,
                   ifail=0,
                   info=0,
                   lda=0,
                   lenap=0,
                   n=0;

string title="";

string uplo="";

string[] clabs = new string[1];

string[] rlabs = new string[1];

Console.WriteLine(" {0}","F01VDF Example Program Results");

//      Skip heading in data file
  sr.Reset();

Console.WriteLine("");

  sr.Reset();
    n = int.Parse(sr.Next());
    uplo = sr.Next();

lda = (int)n;

lenap = (n * (n + 1)) / 2;

Complex[,] a = new Complex[lda, n];

Complex[] ap = new Complex[lenap];

// allocate

//      Read a packed vector of order n
 for (i = 1 ; i <= lenap ; i++)
 {

  sr.Reset();
    ap [i - 1] = Complex.Parse(sr.Next());

}

//      Print the packed vector
title = "Packed Matrix AP: ";

ifail = 0;
X04.x04db(matrix, diag, lenap, inc1, ap, brac, form, title, intlabel, rlabs, nolabel, clabs, ncols, indent, out ifail);

Console.WriteLine("");

//      Convert to triangular form
info = 0;

//      The NAG name equivalent of ztpttr is f01vdf
     F01.f01vd(uplo, n, ap, a, out info);

//      Print the unpacked matrix
title = "Unpacked Matrix A:";

ifail = 0;
X04.x04db(uplo, diag, n, n, a, brac, form, title, intlabel, rlabs, intlabel, clabs, ncols, indent, out ifail);

     }

     catch (Exception e)
    {
      Console.WriteLine(e.Message);
      Console.WriteLine( "Exception Raised");
    }
  }
    }
}


//      f01ve Example Program Text
//      C# version, NAG Copyright 2012

using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
    public class F01VEE
    {

        static string datafile = "ExampleData/f01vee.d";

        // Specify data file as a command line argument.
        // It defaults to the named file specified below otherwise.

        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
{

 try

   {

  DataReader sr = new DataReader(datafile);
//      f01ve Example Program Text
//      Mark 25 Release. NAG Copyright 2013.
int inc1 = 1,
                   indent = 0,
                   ncols = 80;

string diag = "N",
                   intlabel = "I",
                   matrix = "G",
                   nolabel = "N";

string form = "F5.2";

int i=0,
                   ifail=0,
                   info=0,
                   lda=0,
                   lenarf=0,
                   n=0;

string title="";

string transr="",
                   uplo="";

double[,] a;

double[] arf;

string[] clabs = new string[1];

string[] rlabs = new string[1];

Console.WriteLine(" {0}","F01VEF Example Program Results");

//      Skip heading in data file
  sr.Reset();

Console.WriteLine("");

  sr.Reset();
    n = int.Parse(sr.Next());
    uplo = sr.Next();
    transr = sr.Next();

lda = (int)n;

a = new double[lda, n];

lenarf =  n*(n+1)/2;

arf = new double[lenarf];
// allocate
  sr.Reset();
//      Read a triangular matrix of order n into array A
 for (i = 1 ; i <= n ; i++)
 {
      for (int j = 1 ; j <= n ; j++)
 {

    a [ i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);

 }

}

//      Print the unpacked array A
title = "Unpacked Matrix A:   ";

ifail = 0;
X04.x04cb(uplo, diag, n, n, a, form, title, intlabel, rlabs, intlabel, clabs, ncols, indent, out ifail);

Console.WriteLine("");

//      Convert to Rectangular Full Packed form
info = 0;

//      The NAG name equivalent of dtrttf is f01vef
     F01.f01ve(transr, uplo, n, a, arf, out info);

//      Print the Rectangular Full Packed array
title = "RFP Packed Array ARF:";

ifail = 0;
X04.x04cb(matrix, diag, lenarf, inc1, arf, form, title, intlabel, rlabs, nolabel, clabs, ncols, indent, out ifail);

     }

     catch (Exception e)
    {
      Console.WriteLine(e.Message);
      Console.WriteLine( "Exception Raised");
    }
  }
    }
}


//      f01vf Example Program Text
//      C# version, NAG Copyright 2012

using System;
using NagLibrary;
namespace NagDotNetExamples
{
    public class F01VFE
    {

        static string datafile = "ExampleData/f01vfe.d";

        // Specify data file as a command line argument.
        // It defaults to the named file specified below otherwise.

        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
{

 try

   {

  DataReader sr = new DataReader(datafile);
//      f01vf Example Program Text
//      Mark 25 Release. NAG Copyright 2013.
int inc1 = 1,
                   indent = 0,
                   ncols = 80;

string brac = "B",
                   diag = "N",
                   intlabel = "I",
                   matrix = "G",
                   nolabel = "N";

string form = "F5.2";

int i=0,
                   ifail=0,
                   info=0,
                   lda=0,
                   lenarf=0,
                   n=0;

string title="";

string transr="",
                   uplo="";

string[] clabs = new string[1];

string[] rlabs = new string[1];

Console.WriteLine(" {0}","F01VFF Example Program Results");

//      Skip heading in data file
  sr.Reset();

Console.WriteLine("");

  sr.Reset();
    n = int.Parse(sr.Next());
    uplo = sr.Next();
    transr = sr.Next();

lda = (int)n;

lenarf = n*(n+1)/2;

Complex[,] a = new Complex[lda, n];

Complex[] arf = new Complex[lenarf];

// allocate
  sr.Reset();
//      Read a triangular matrix of order n into array A
 for (i = 1 ; i <= n ; i++)
 {
      for (int j= 1 ; j <= n ; j++)
 {

    a[i - 1 , j -1] = Complex.Parse(sr.Next());

      }
}

//      Print the unpacked array
title = "Unpacked Matrix A:   ";

ifail = 0;
X04.x04db(uplo, diag, n, n, a, brac, form, title, intlabel, rlabs, intlabel, clabs, ncols, indent, out ifail);

Console.WriteLine("");

//      Convert to Rectangular Full Packed form
info = 0;

//      The NAG name equivalent of ztrttf is f01vff
     F01.f01vf(transr, uplo, n, a, arf, out info);

//      Print the Rectangular Full Packed array
title = "RFP Packed Array ARF:";

ifail = 0;
X04.x04db(matrix, diag, lenarf, inc1, arf, brac, form, title, intlabel, rlabs, nolabel, clabs, ncols, indent, out ifail);

     }

     catch (Exception e)
    {
      Console.WriteLine(e.Message);
      Console.WriteLine( "Exception Raised");
    }
  }
    }
}


//      f01vg Example Program Text
//      C# version, NAG Copyright 2012

using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
    public class F01VGE
    {

        static string datafile = "ExampleData/f01vge.d";

        // Specify data file as a command line argument.
        // It defaults to the named file specified below otherwise.

        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
        {

            try
            {

                DataReader sr = new DataReader(datafile);
                //      f01vg Example Program Text
                //      Mark 25 Release. NAG Copyright 2013.
                int inc1 = 1,
                                   indent = 0,
                                   ncols = 80;

                string diag = "N",
                                   intlabel = "I",
                                   matrix = "G",
                                   nolabel = "N";

                string form = "F5.2";

                int ifail = 0,
                                   info = 0,
                                   lda = 0,
                                   lenarf = 0,
                                   n = 0;

                string title = "";

                string transr = "",
                                   uplo = "";

                string[] clabs = new string[1];

                string[] rlabs = new string[1];

                Console.WriteLine(" {0}", "F01VGF Example Program Results");

                //      Skip heading in data file
                sr.Reset();

                Console.WriteLine("");

                sr.Reset();
                n = int.Parse(sr.Next());
                uplo = sr.Next();
                transr = sr.Next();

                lda = (int)n;

                lenarf = n * (n + 1) / 2;

                double[,] a = new double[lda, n];

                double[] arf = new double[lenarf];
                // allocate

                //      Read an RFP matrix into array ARF
                sr.Reset();
                for (int i = 1; i <= lenarf; i++)
                {
                    arf[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }

                //      Print the Rectangular Full Packed array
                title = "RFP Packed Array ARF:";

                ifail = 0;
                X04.x04cb(matrix, diag, lenarf, inc1, arf, form, title, intlabel, rlabs, nolabel, clabs, ncols, indent, out ifail);

                Console.WriteLine("");

                //      Convert to triangular form
                info = 0;

                //      The NAG name equivalent of dtfttr is f01vgf
                F01.f01vg(transr, uplo, n, arf, a, out info);

                //      Print the unpacked array
                ifail = 0;

                title = "Unpacked Matrix A:   ";

                ifail = 0;
                X04.x04cb(uplo, diag, n, n, a, form, title, intlabel, rlabs, intlabel, clabs, ncols, indent, out ifail);

            }

            catch (Exception e)
            {
                Console.WriteLine(e.Message);
                Console.WriteLine("Exception Raised");
            }
        }
    }
}


//      f01vh Example Program Text
//      C# version, NAG Copyright 2012

using System;
using NagLibrary;
namespace NagDotNetExamples
{
    public class F01VHE
    {

        static string datafile = "ExampleData/f01vhe.d";

        // Specify data file as a command line argument.
        // It defaults to the named file specified below otherwise.

        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
        {

           try
            {

               DataReader sr = new DataReader(datafile);
                //      f01vh Example Program Text
                //      Mark 25 Release. NAG Copyright 2013.
                int inc1 = 1,
                                   indent = 0,
                                   ncols = 80;

                string brac = "B",
                                   diag = "N",
                                   intlabel = "I",
                                   matrix = "G",
                                   nolabel = "N";

                string form = "F5.2";

                int ifail = 0,
                                   info = 0,
                                   lda = 0,
                                   lenarf = 0,
                                   n = 0;

                string title = "";

                string transr = "",
                                   uplo = "";

                Complex[,] a;

                Complex[] arf;

                string[] clabs = new string[1];

                string[] rlabs = new string[1];

                Console.WriteLine(" {0}", "F01VHF Example Program Results");

                //      Skip heading in data file
                sr.Reset();

                Console.WriteLine("");

                sr.Reset();
                n = int.Parse(sr.Next());
                uplo = sr.Next();
                transr = sr.Next();

                lda = (int)n;

                lenarf = n * (n + 1) / 2;
                arf = new Complex[lenarf];
                a = new Complex[lda, n];
                // allocate

                //      Read an RFP matrix into array ARF
                sr.Reset();
                for (int i = 1; i <= lenarf; i++)
                {
                    arf[i-1] = Complex.Parse(sr.Next());
                }

                //      Print the Rectangular Full Packed array
                title = "RFP Packed Array ARF:";

                ifail = 0;
                X04.x04db(matrix, diag, lenarf, inc1, arf, brac, form, title, intlabel, rlabs, nolabel, clabs, ncols, indent, out ifail);

                Console.WriteLine("");

                //      Convert to triangular form
                info = 0;

                //      The NAG name equivalent of ztfttr is f01vhf
                F01.f01vh(transr, uplo, n, arf, a, out info);

                //      Print the unpacked array
                title = "Unpacked Matrix A:   ";

                ifail = 0;
                X04.x04db(uplo, diag, n, n, a, brac, form, title, intlabel, rlabs, intlabel, clabs, ncols, indent, out ifail);

            }

            catch (Exception e)
            {
                Console.WriteLine(e.Message);
                Console.WriteLine("Exception Raised");
            }
        }
    }
}


//      f01vj Example Program Text
//      C# version, NAG Copyright 2012

using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
    public class F01VJE
    {

        static string datafile = "ExampleData/f01vje.d";

        // Specify data file as a command line argument.
        // It defaults to the named file specified below otherwise.

        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
{

 try

   {

  DataReader sr = new DataReader(datafile);
//      f01vj Example Program Text
//      Mark 25 Release. NAG Copyright 2013.
int inc1 = 1,
                   indent = 0,
                   ncols = 80;

string diag = "N",
                   intlabel = "I",
                   matrix = "G",
                   nolabel = "N";

string form = "F5.2";

int ifail=0,
                   info=0,
                   lenap=0,
                   lenarf=0,
                   n=0;

string title="";

string transr="",
                   uplo="";

double[] ap;

double[] arf;

string[] clabs = new string[1];

string[] rlabs = new string[1];

Console.WriteLine(" {0}","F01VJF Example Program Results");

//      Skip heading in data file
  sr.Reset();

Console.WriteLine("");

  sr.Reset();
    n = int.Parse(sr.Next());
    uplo = sr.Next();
    transr = sr.Next();

lenap = (n * (n + 1)) / 2;

lenarf = (int)lenap;

// allocate

ap = new double[lenap];
arf = new double[lenarf];

//      Read an order n matrix packed into a 1-D array
  sr.Reset();
  for (int i = 1; i <= lenap; i++)
  {

          ap[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);

  }

//      Print the packed array
title = "Packed Array AP:     ";

ifail = 0;
X04.x04cb(matrix, diag, lenap, inc1, ap, form, title, intlabel, rlabs, nolabel, clabs, ncols, indent, out ifail);

Console.WriteLine("");

//      Convert to Rectangular Full Packed form
info = 0;

//      The NAG name equivalent of dtpttf is f01vjf
     F01.f01vj(transr, uplo, n, ap, arf, out info);

//      Print the Rectangular Full Packed array
title = "RFP Packed Array ARF:";

ifail = 0;
X04.x04cb(matrix, diag, lenarf, inc1, arf, form, title, intlabel, rlabs, nolabel, clabs, ncols, indent, out ifail);

     }

     catch (Exception e)
    {
      Console.WriteLine(e.Message);
      Console.WriteLine( "Exception Raised");
    }
  }
    }
}


F01VJF Example Program Data
4 'U' 'N'                        : n, uplo, transr
 1.1
 1.2
 2.2
 1.3
 2.3
 3.3
 1.4
 2.4
 3.4
 4.4                             : Packed Matrix AP


//      f01vk Example Program Text
//      C# version, NAG Copyright 2012

using System;
using NagLibrary;
namespace NagDotNetExamples
{
    public class F01VKE
    {

        static string datafile = "ExampleData/f01vke.d";

        // Specify data file as a command line argument.
        // It defaults to the named file specified below otherwise.

        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
{

 try

   {

  DataReader sr = new DataReader(datafile);
//      f01vk Example Program Text
//      Mark 25 Release. NAG Copyright 2013.
int inc1 = 1,
                   indent = 0,
                   ncols = 80;

string brac = "B",
                   diag = "N",
                   intlabel = "I",
                   matrix = "G",
                   nolabel = "N";

string form = "F5.2";

int ifail=0,
                   info=0,
                   lenap=0,
                   lenarf=0,
                   n=0;

string title="";

string transr="",
                   uplo="";

Complex[] ap;

Complex[] arf;

string[] clabs = new string[1];

string[] rlabs = new string[1];

Console.WriteLine(" {0}","F01VKF Example Program Results");

//      Skip heading in data file
  sr.Reset();

Console.WriteLine("");

  sr.Reset();
    n = int.Parse(sr.Next());
    uplo = sr.Next();
    transr = sr.Next();

lenap = (n * (n + 1)) / 2;

lenarf = (int)lenap;
ap = new Complex[lenap];
arf = new Complex[lenarf];
// allocate

//      Read an order n matrix packed into a 1-D array
  sr.Reset();
  for (int i = 1; i <= lenap; i++)
  {
      ap[i-1] = Complex.Parse(sr.Next());
  }

//      Print the packed vector
title = "Packed Array AP:     ";

ifail = 0;
X04.x04db(matrix, diag, lenap, inc1, ap, brac, form, title, intlabel, rlabs, nolabel, clabs, ncols, indent, out ifail);

Console.WriteLine("");

//      Convert to Rectangular Full Packed form
info = 0;

//      The NAG name equivalent of ztpttf is f01vkf
     F01.f01vk(transr, uplo, n, ap, arf, out info);

//      Print the Rectangular Full Packed array
title = "RFP Packed Array ARF:";

ifail = 0;
X04.x04db(matrix, diag, lenarf, inc1, arf, brac, form, title, intlabel, rlabs, nolabel, clabs, ncols, indent, out ifail);

     }

     catch (Exception e)
    {
      Console.WriteLine(e.Message);
      Console.WriteLine( "Exception Raised");
    }
  }
    }
}


//      f01vl Example Program Text
//      C# version, NAG Copyright 2012

using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
    public class F01VLE
    {

        static string datafile = "ExampleData/f01vle.d";

        // Specify data file as a command line argument.
        // It defaults to the named file specified below otherwise.

        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
{

 try

   {

  DataReader sr = new DataReader(datafile);
//      f01vl Example Program Text
//      Mark 25 Release. NAG Copyright 2013.
int inc1 = 1,
                   indent = 0,
                   ncols = 80;

string diag = "N",
                   intlabel = "I",
                   matrix = "G",
                   nolabel = "N";

string form = "F5.2";

int ifail=0,
                   info=0,
                   lenap=0,
                   lenarf=0,
                   n=0;

string title="";

string transr="",
                   uplo="";

double[] ap;

double[] arf;

string[] clabs = new string[1];

string[] rlabs = new string[1];

Console.WriteLine(" {0}","F01VLF Example Program Results");

//      Skip heading in data file
  sr.Reset();

Console.WriteLine("");

  sr.Reset();
    n = int.Parse(sr.Next());
    uplo = sr.Next();
    transr = sr.Next();

lenap = (n * (n + 1)) / 2;

lenarf = (int)lenap;
ap = new double[lenap];
arf = new double[lenarf];
// allocate

//      Read an RFP matrix into array ARF
  sr.Reset();
     for (int j = 1; j<=lenarf; j++){
    arf[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
     }

//      Print the Rectangular Full Packed array
title = "RFP Packed Array ARF:";

ifail = 0;
X04.x04cb(matrix, diag, lenarf, inc1, arf, form, title, intlabel, rlabs, nolabel, clabs, ncols, indent, out ifail);

Console.WriteLine("");

//      Convert to packed vector form
info = 0;

//      The NAG name equivalent of dtfttp is f01vlf
     F01.f01vl(transr, uplo, n, arf, ap, out info);

//      Print the packed vector
title = "Packed Array AP:     ";

ifail = 0;
X04.x04cb(matrix, diag, lenap, inc1, ap, form, title, intlabel, rlabs, nolabel, clabs, ncols, indent, out ifail);

     }

     catch (Exception e)
    {
      Console.WriteLine(e.Message);
      Console.WriteLine( "Exception Raised");
    }
  }
    }
}


//      f01vm Example Program Text
//      C# version, NAG Copyright 2012

using System;
using NagLibrary;
namespace NagDotNetExamples
{
      public class F01VME
     {

       static string datafile = "ExampleData/f01vme.d";

       // Specify data file as a command line argument.
       // It defaults to the named file specified below otherwise.

    static void Main(String[] args)
    {
      if (args.Length == 1)
        {
         datafile = args[0];
        }
       StartExample();
   }

public static void StartExample()
{

 try

   {

  DataReader sr = new DataReader(datafile);
//      f01vm Example Program Text
//      Mark 25 Release. NAG Copyright 2013.
int inc1 = 1,
                   indent = 0,
                   ncols = 80;

string brac = "B",
                   diag = "N",
                   intlabel = "I",
                   matrix = "G",
                   nolabel = "N";

string form = "F5.2";

int ifail=0,
                   info=0,
                   lenap=0,
                   lenarf=0,
                   n=0;

string title="";

string transr="",
                   uplo="";

Complex[] ap;

Complex[] arf;

string[] clabs = new string[1];

string[] rlabs = new string[1];

Console.WriteLine(" {0}","F01VMF Example Program Results");

//      Skip heading in data file
  sr.Reset();

Console.WriteLine("");

  sr.Reset();
    n = int.Parse(sr.Next());
    uplo = sr.Next();
    transr = sr.Next();

lenap = (n * (n + 1)) / 2;

lenarf = (int)lenap;
     ap = new Complex[lenap];
     arf = new Complex[lenarf];
// allocate

//      Read an RFP matrix into array ARF
  sr.Reset();
  for (int i = 1; i < lenarf; i++)
  {
      arf[i-1] = Complex.Parse(sr.Next());
  }

//      Print the Rectangular Full Packed array
title = "RFP Packed Array ARF:";

ifail = 0;
X04.x04db(matrix, diag, lenarf, inc1, arf, brac, form, title, intlabel, rlabs, nolabel, clabs, ncols, indent, out ifail);

Console.WriteLine("");

//      Convert to packed vector form
info = 0;

//      The NAG name equivalent of ztfttp is f01vmf
     F01.f01vm(transr, uplo, n, arf, ap, out info);

//      Print the packed vector
title = "Packed Array AP:     ";

ifail = 0;
X04.x04db(matrix, diag, lenap, inc1, ap, brac, form, title, intlabel, rlabs, nolabel, clabs, ncols, indent, out ifail);

     }

     catch (Exception e)
    {
      Console.WriteLine(e.Message);
      Console.WriteLine( "Exception Raised");
    }
  }
}
}


//      f06bn Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F06BNE
  {

    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        double a = 3;
        double b = 4;
    double return_val=0;

    return_val = F06.f06bn(a,b);

        Console.WriteLine("Return value = {0}", return_val);

      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }

}
}


//      f06db Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F06DBE
  {

    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        int n = 3;
        int incx = 2;
    int[] x = new int[1+(n-1)*incx ];
    int con = 2;
    int ifail ;

    F06.f06db(n, con, x, incx, out ifail);

    for (int i =0; i<x.Length; i++)
    {
        Console.WriteLine("x[{0}] = {1}", i, x[i]);
    }

      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }

}
}


//      f06ea Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F06EAE
  {

    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        int n = 3;
    double[] x = { 1, 2, 3};
    double[] y = { 1, 2, 3};
        int incx = 1;
    int incy = 1;
    int ifail ;
    double return_val;
    return_val= F06.f06ea(n, x, incx, y, incy, out ifail);

        Console.WriteLine("Scalar Product of x and y : {0}", return_val);

      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }

}
}


Scalar Product of x and y : 14


//      f06ef Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F06EFE
  {

    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        int n = 3;
    double[] x = { 1, 2, 3};
    double[] y = { 0, 0, 0};
        int incx = 1;
    int incy = 1;
    int ifail ;
   F06.f06ef(n, x, incx, y, incy, out ifail);

       for (int i =0; i<n; i++)
    {
        Console.WriteLine("y[{0}] = {1}", i, y[i]);
    }

      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }

}
}


//      f06ej Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F06EJE
  {

    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        int n = 3;
    double[] x = { 1, 2, 3};
        int incx = 1;
    int ifail ;
    double return_val;
    return_val= F06.f06ej(n, x, incx, out ifail);

        Console.WriteLine("Euclidian norm of x : {0}", return_val);

      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }

}
}


//      f06fd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F06FDE
  {

    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        int n = 3;
    double alpha = 2;
    double[] x = { 1, 2, 3};
    double[] y = { 0, 0, 0};
        int incx = 1;
    int incy = 1;
    int ifail ;
   F06.f06fd(n, alpha, x, incx, y, incy, out ifail);

       for (int i =0; i<n; i++)
    {
        Console.WriteLine("y[{0}] = {1}", i, y[i]);
    }

      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }

}
}


//      f06jj Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F06JJE
  {

    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        int n = 3;
    Complex[] x = { new Complex(1,1), new Complex(1,2), new Complex(2,1)};
        int incx = 1;
    int ifail ;
    double return_val;
    return_val= F06.f06jj(n, x, incx, out ifail);

        Console.WriteLine("Euclidian norm of x : {0}", return_val);

      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }

}
}


//      f06pa Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F06PAE
  {

    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        double[,] a = { { 1, 2 }, { 3, 4 }};
        double[,] b = { {  5,6 }, {  7,8 } };
    double[] x = { 1, 1 };
        double[] y = {  1,1 };

    int m = 2;
    int n = 2;
    int incx = 1;
    int incy = 1;
        double alpha = 1.0;
        double beta = 1.0;
        int ifail;
        string trans = "N";

        F06.f06pa(trans, m, n, alpha, a, x, incx, beta, y, incy, out ifail);

    for (int i=0; i< m; i++){
            Console.WriteLine("y[{0}] = {1}", i, y[i]);
    }

      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      f06pj Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F06PJE
  {

    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        double[,] a = { { 1, 2 , 3}, { 4, 5, 6 }, { 7, 8, 9}};
    double[] x = {1, 2, 3};

    int lda =3;
    int n = 3;
    int incx = 1;

        int ifail;
    string uplo = "U";
        string trans = "N";
    string diag = "N";

        F06.f06pj(uplo, trans, diag, n, a, x, incx, out ifail);

    for (int i=0; i< lda; i++){
            Console.WriteLine("x[{0}] = {1}", i, x[i]);
    }

      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      f06qf1 Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F06QFE
  {

    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        double[,] a = { { 1, 2 , 3}, { 4, 5, 6 }, {7, 8, 9}};
    double[,] b = { { 0, 0 , 0}, { 0, 0, 0 }, { 0, 0, 0}};

    int m =3;
    int n = 3;

        int ifail;
    string matrix = "G";

        F06.f06qf(matrix, m, n, a, b,  out ifail);

    for (int i=0; i< m; i++){
        for (int j=0; j< n; j++){
            Console.WriteLine("b[{0},{1}] = {2}",i, j,  b[i,j]);
        }
    }

      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      f06qh Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F06QHE
  {

    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        double[,] a = { { 0, 0 , 0}, { 0, 0, 0 }, { 0, 0, 0}};

    int m =3;
    int n = 3;

    double con = 1;
    double diag= 2;
        int ifail;
    string matrix = "G";

        F06.f06qh(matrix, m, n, con, diag, a ,  out ifail);

    for (int i=0; i< m; i++){
        for (int j=0; j< n; j++){
            Console.WriteLine("a[{0},{1}] = {2}",i, j,  a[i,j]);
        }
    }

      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      f06ya Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F06YAE
  {
    static int m = 2;
    static int n = 2;
    static int k = 2;
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        double[,] a = { { 1, 2 }, { 3, 4 }};
        double[,] b = { {  5,6 }, {  7,8 } };
        double[,] cN = new double[m, n];
        double[,] cT = new double[m, n];
        double alpha = 1.0;
        double beta = 1.0;
        int ifail;
        Console.WriteLine("\nMATRIX A MULTIPLIED BY MATRIX B WITH BOTH NON TRANSPOSED \n");
        Console.WriteLine("\n======================================================\n");
        string transa = "N";
        string transb = "N";
        F06.f06ya(transa, transb, m, n, k, alpha, a, b, beta, cN, out ifail);
        displayMatrices(a, b, cN);
        Console.WriteLine("\nMATRIX A MULTIPLIED BY MATRIX B WITH BOTH  TRANSPOSED \n");
        Console.WriteLine("\n======================================================\n");
        transa = "T";
        transb = "T";
        F06.f06ya(transa, transb, m, n, k, alpha, a, b, beta, cT, out ifail);
        displayMatrices(a, b, cT);
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    private static void displayMatrices(double[,]a , double[,]b, double[,]c)
    {
      Console.WriteLine("\nMATRIX A\n\n");
      for (int i = 0; i < m; i++)
      {
        for (int j = 0; j < k; j++)
        {
          Console.Write("{0,10:f2}", a[i, j]);
        }
        Console.WriteLine("");
      }
      Console.WriteLine("\nMATRIX B \n\n");
      for (int i = 0; i < k; i++)
      {
        for (int j = 0; j < n; j++)
        {
          Console.Write("{0,10:f2}", b[i, j]);
        }
        Console.WriteLine("");
      }
      Console.WriteLine("\nRESULTANT MATRIX C \n\n");
      for (int i = 0; i < m; i++)
      {
        for (int j = 0; j < n; j++)
        {
          Console.Write("{0,10:f2}", c[i, j]);
        }
        Console.WriteLine("");
      }
    }
  }
}


//      f06ya Example Program Text
//      C# version, NAG Copyright 2013
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
    public class F06YJE
    {

        static void Main(String[] args)
        {
            StartExample();
        }
        public static void StartExample()
        {
            try
            {
                double[,] a = { { 1, 2, 3 }, { 0, 5, 6 }, { 0, 0, 9 } };
                double[,] b = { { 1, 1, 0, 1}, { 0, 1, 1, 0}, { 0, 0, 1, 1 } };

                int m = a.GetLength(0);
                int n = b.GetLength(1);
                double alpha = 2.0;
                int ifail;
                string side = "L";
                string uplo = "U";
                string transa = "N";
                string diag = "N";

                F06.f06yj(side, uplo, transa, diag, m, n, alpha, a, b, out ifail);

                for (int i = 0; i < m; i++)
                {
                    for (int j = 0; j < n; j++)
                    {
                        Console.Write("{0,12:f4} ",  b[i, j]);
                    }
                    Console.WriteLine("");
                }

            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
                Console.WriteLine("Exception Raised");
            }
        }
    }
}


//      f07ab Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F07ABE
  {
    static string datafile = "ExampleData/f07abe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double rcond=0.0;
        double rgf;
        int i,   info,   j,   n,   nrhs; string equed="";
        Console.WriteLine("f07ab Example Program Results");
        Console.WriteLine("");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        nrhs = int.Parse(sr.Next());
        double[,] a = new double[n, n];
        double[,] af = new double[n, n];
        double[,] b = new double[n, nrhs];
        double[] berr = new double[nrhs];
        double[] c = new double[n];
        double[] ferr = new double[nrhs];
        double[] r = new double[n];
        double[,] x = new double[n, nrhs];
        int[] ipiv = new int[n];
        int ifail;
        if (n > 0 )
        {
          //
          //         Read A and B from data file
          //
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            for (j = 1 ; j <= n ; j++)
            {
              a[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            for (j = 1 ; j <= nrhs ; j++)
            {
              b[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //
          //         Solve the equations ax = b for x
          //
          F07.f07ab("Equilibration", "No transpose", n, nrhs, a, af, ipiv,  ref equed, r, c, b, x, out rcond, ferr, berr,out rgf ,out info);

          if (info < 0)
          {
              return;
          }

            if (((info == 0)) || ((info == n + 1)))
          {
            //
            //            Print solution, error bounds, condition number, the form
            //            of equilibration and the pivot growth factor
            //
            X04.x04ca("General", "", n, nrhs, x, "Solution(s)", out ifail);
            //
            Console.WriteLine("");
            Console.WriteLine(" {0}","Backward errors (machine-dependent)");
            for (j = 1 ; j <= nrhs ; j++)
            {
              Console.Write(" {0, 3:e1}", berr[j - 1]);
            }
            Console.WriteLine("");
            Console.WriteLine("");
            Console.WriteLine(" {0}","Estimated forward error bounds (machine-dependent)");
            for (j = 1 ; j <= nrhs ; j++)
            {
              Console.Write(" {0, 3:e1}", ferr[j - 1]);
            }
            Console.WriteLine("");
            Console.WriteLine("");
            if (equed == "N")
            {
              Console.WriteLine(" {0}","A has not been equilibrated");
            }
            else if (equed == "R")
            {
              Console.WriteLine(" {0}","A has been row scaled as diag(R)*A");
            }
            else if (equed == "C")
            {
              Console.WriteLine(" {0}","A has been column scaled as A*diag(C)");
            }
            else if (equed == "B")
            {
              Console.WriteLine(" {0}","A has been row and column scaled as diag(R)*A*diag(C)");
            }
            Console.WriteLine("");
            Console.WriteLine(" {0}","Reciprocal condition number estimate of scaled matrix");
            Console.WriteLine("      {0,11:e1}",rcond);
            Console.WriteLine("");
            Console.WriteLine(" {0}","Estimate of reciprocal pivot growth factor");
            Console.WriteLine("      {0,11:e1}",rgf);
            //
            if (info == n + 1)
            {
              Console.WriteLine("");
              Console.WriteLine(" {0}","The matrix A is singular to working precision");
            }
          }

          else if(info > 0)
          {
            Console.WriteLine("  {0}{1,3}{2}{3,3}{4}{5}","The (",info,",",info,")"," element of the factor U is zero");
          }
        }
        else
        {
          Console.WriteLine(" {0}","n < = 0");
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


f07ab Example Program Results

 Solution(s)
             1          2
 1      1.0000     3.0000
 2     -1.0000     2.0000
 3      3.0000     4.0000
 4     -5.0000     1.0000

 Backward errors (machine-dependent)
 6.8e-017 9.1e-017

 Estimated forward error bounds (machine-dependent)
 2.4e-014 3.6e-014

 A has been row scaled as diag(R)*A

 Reciprocal condition number estimate of scaled matrix
         1.8e-002

 Estimate of reciprocal pivot growth factor
         7.4e-001


//      f07ap Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F07APE
  {
    static string datafile = "ExampleData/f07ape.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double rcond=0.0;
        double rgf;
        int i,   info,   j,   n,   nrhs; string equed="";
        string[] clabs = new string[1];
        string[] rlabs = new string[1];
        Console.WriteLine("f07ap Example Program Results");
        Console.WriteLine("");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        nrhs = int.Parse(sr.Next());
        Complex[,] a = new Complex[n, n];
        Complex[,] af = new Complex[n, n];
        Complex[,] b = new Complex[n, nrhs];
        Complex[,] x = new Complex[n, nrhs];
        double[] berr = new double[nrhs];
        double[] c = new double[n];
        double[] ferr = new double[nrhs];
        double[] r = new double[n];
        int[] ipiv = new int[n];
        if (n > 0 )
        {
          //
          //         Read A and B from data file
          //
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            for (j = 1 ; j <= n ; j++)
            {
              a[i - 1 , j - 1] = Complex.Parse(sr.Next());
            }
          }
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            for (j = 1 ; j <= nrhs ; j++)
            {
              b[i - 1 , j - 1] = Complex.Parse(sr.Next());
            }
          }
          //
          //         Solve the equations ax = b for x
          //
          F07.f07ap("Equilibrate", "No transpose", n, nrhs, a, af, ipiv,  ref equed, r, c, b, x, out rcond, ferr,
          berr, out rgf, out info);

          if (info < 0)
          {
              return;
          }
          //
          if (info == 0 || info == n + 1)
          {
            //
            //            Print solution, error bounds, condition number, the form
            //            of equilibration and the pivot growth factor
            //
            Console.WriteLine("Solution(s)\n");
            for (i = 1 ; i <= n ; i++)
            {
              for (j = 1 ; j <= nrhs ; j++)
              {
                Console.Write("{0, 20:f4}", x[i-1,j-1]);
              }
              Console.WriteLine("");
            }
            Console.WriteLine("");
            Console.WriteLine(" {0}","Backward errors (machine-dependent)");
            for (j = 1 ; j <= nrhs ; j++)
            {
              Console.Write(" {0, 3:e1}", berr[j - 1]);
            }
            Console.WriteLine("");
            Console.WriteLine("");
            Console.WriteLine(" {0}","Estimated forward error bounds (machine-dependent)");
            for (j = 1 ; j <= nrhs ; j++)
            {
              Console.Write(" {0, 3:e1}", ferr[j - 1]);
            }
            Console.WriteLine("");
            Console.WriteLine("");
            if (equed == "N")
            {
              Console.WriteLine(" {0}","A has not been equilibrated");
            }
            else if (equed == "R")
            {
              Console.WriteLine(" {0}","A has been row scaled as diag(R)*A");
            }
            else if (equed == "C")
            {
              Console.WriteLine(" {0}","A has been column scaled as A*diag(C)");
            }
            else if (equed == "B")
            {
              Console.WriteLine(" {0}","A has been row and column scaled as diag(R)*A*diag(C)");
            }
            Console.WriteLine("");
            Console.WriteLine(" {0}","Reciprocal condition number estimate of scaled matrix");
            Console.WriteLine("      {0,11:e1}",rcond);
            Console.WriteLine("");
            Console.WriteLine(" {0}","Estimate of reciprocal pivot growth factor");
            Console.WriteLine("      {0,11:e1}", rgf);
            //
            if (info == n + 1)
            {
              Console.WriteLine("");
              Console.WriteLine(" {0}","The matrix A is singular to working precision");
            }
          }
          else if (info > 0)
          {
            Console.WriteLine("  {0}{1,3}{2}{3,3}{4}{5}","The (",info,",",info,")"," element of the factor U is zero");
          }
        }
        else
        {
          Console.WriteLine(" {0}","n <= 0");
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


f07ap Example Program Results

Solution(s)

    (1.0000,1.0000)   (-1.0000,-2.0000)
   (2.0000,-3.0000)     (5.0000,1.0000)
  (-4.0000,-5.0000)    (-3.0000,4.0000)
    (0.0000,6.0000)    (2.0000,-3.0000)

 Backward errors (machine-dependent)
 5.3e-017 7.6e-017

 Estimated forward error bounds (machine-dependent)
 5.8e-014 7.8e-014

 A has been row scaled as diag(R)*A

 Reciprocal condition number estimate of scaled matrix
         1.0e-002

 Estimate of reciprocal pivot growth factor
         8.3e-001


//      f07ar Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F07ARE
  {
    static string datafile = "ExampleData/f07are.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   info,   j,   m,   n; string[] clabs = new string[1];
        string[] rlabs = new string[1];
        Console.WriteLine("f07ar Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        m = int.Parse(sr.Next());
        n = int.Parse(sr.Next());
        Complex[,] a = new Complex[m, n];
        int[] ipiv = new int[n];
        if (m >0 && n > 0)
        {
          //
          //         Read A from data file
          //
          sr.Reset();
          for (i = 1; i <= m; i++)
          {
            for (j = 1; j <= n; j++)
            {
              a[i - 1, j - 1] = Complex.Parse(sr.Next());
            }
          }
          //
          //         Factorize A
          //

          F07.f07ar(m, n, a, ipiv, out info);
          //
          //         Print details of factorization
          //

          if (info < 0)
          {
              return;
          }

          for (i = 1; i <= m; i++)
          {
            for (j = 1; j <= n; j++)
            {
              Console.Write("({0, 7:f4}, {1, 7:f4}){2}", a[i-1, j-1].re, a[i-1, j-1].im, j%4==0?"\n":" ");
            }
          }
          Console.WriteLine("");
          //
          //         Print pivot indices
          //

          if (info >= 0)
          {
              Console.WriteLine("");
              Console.WriteLine(" {0}", "IPIV");
              for (i = 1; i <= Math.Min(m, n); i++)
              {
                  Console.Write(" {0}", ipiv[i - 1]);
              }
              Console.WriteLine(" ");
              //
              if (info != 0)
              {
                  Console.WriteLine(" {0}", "The factor U is singular");
              }
          }
          //
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      f07as Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F07ASE
  {
    static string datafile = "ExampleData/f07ase.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   info,   j,   n,   nrhs; string[] clabs = new string[1];
        string[] rlabs = new string[1];
        string trans = "N";
        Console.WriteLine("f07as Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        nrhs = int.Parse(sr.Next());
        Complex[,] a = new Complex[n, n];
        Complex[,] b = new Complex[n, nrhs];
        int[] ipiv = new int[8];
        if (n > 0 && nrhs > 0)
        {
          //
          //         Read A and B from data file
          //
          sr.Reset();
          for (i = 1; i <= n; i++)
          {
            for (j = 1; j <= n; j++)
            {
              a[i - 1, j - 1] = Complex.Parse(sr.Next());
            }
          }
          sr.Reset();
          for (i = 1; i <= n; i++)
          {
            for (j = 1; j <= nrhs; j++)
            {
              b[i - 1, j - 1] = Complex.Parse(sr.Next());
            }
          }
          //
          //         Factorize A
          //
          F07.f07ar(n, n, a, ipiv, out info);
          //
          Console.WriteLine("");
          if (info == 0)
          {
            //
            //            Compute solution
            //

            F07.f07as(trans, n, nrhs, a, ipiv, b, out info);

            if (info < 0)
            {
                return;
            }

            //
            //            Print solution
            //
            for (i = 1; i <= n; i++)
            {
              for (j = 1; j <= nrhs; j++)
              {
                Console.Write("({0, 7:f4}, {1, 7:f4}){2}",
                b[i-1, j-1].re, b[i-1, j-1].im, j%4==0 || j==nrhs?"\n":" ");
              }
            }
            Console.WriteLine("");
          }
          else
          {
            Console.WriteLine(" {0}", "The factor U is singular");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      f07fb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F07FBE
  {
    static string datafile = "ExampleData/f07fbe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double rcond=0.0;
        int i,   info,   j,   n,   nrhs; string equed="";
        int ifail;
        Console.WriteLine("f07fb Example Program Results");
        Console.WriteLine("");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        nrhs = int.Parse(sr.Next());
        double[,] a = new double[n, n];
        double[,] af = new double[n, n];
        double[,] b = new double[n, nrhs];
        double[] berr = new double[nrhs];
        double[] ferr = new double[nrhs];
        double[] s = new double[n];
        double[,] x = new double[n, nrhs];
        if (n > 0)
        {
          //
          //         Read the upper triangular part of A from data file
          //
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            for (j = i ; j <= n ; j++)
            {
              a[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //
          //         Read B from data file
          //
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            for (j = 1 ; j <= nrhs ; j++)
            {
              b[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //
          //         Solve the equations ax = b for x
          //
          F07.f07fb("Equilibration", "Upper", n, nrhs, a, af,  ref equed, s, b, x, out rcond, ferr, berr, out info);
          if (info < 0)
          {
              return;
          }
          //
          if (info == 0 || info == n + 1)
          {
            //
            //            Print solution, error bounds, condition number and the form
            //            of equilibration
            //
            X04.x04ca("General", "", n, nrhs, x, "Solution(s)", out ifail);
            //
            Console.WriteLine("");
            Console.WriteLine(" {0}","Backward errors (machine-dependent)");
            for (j = 1 ; j <= nrhs ; j++)
            {
              Console.Write(" {0, 3:e3}", berr[j - 1]);
            }
            Console.WriteLine("");
            Console.WriteLine("");
            Console.WriteLine(" {0}","Estimated forward error bounds (machine-dependent)");
            for (j = 1 ; j <= nrhs ; j++)
            {
              Console.Write(" {0, 3:e3}", ferr[j - 1]);
            }
            Console.WriteLine("");
            Console.WriteLine("");
            Console.WriteLine(" {0}","Estimate of reciprocal condition number");
            Console.WriteLine("      {0,11:e1}",rcond);
            Console.WriteLine("");
            if (equed == "N")
            {
              Console.WriteLine(" {0}","A has not been equilibrated");
            }
            else if (equed == "Y")
            {
              Console.WriteLine(" {0}","A has been row and column scaled as diag(S)*A*diag(S)");
            }
            //
            if (info == n + 1)
            {
              Console.WriteLine("");
              Console.WriteLine(" {0}","The matrix A is singular to working precision");
            }
          }
          else if (info > 0)
          {
            Console.WriteLine("  {0}{1,3}{2}","The leading minor of order ",info," is not positive definite");
          }
        }
        else
        {
          Console.WriteLine(" {0}","n <= 0");
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


f07fb Example Program Results

 Solution(s)
             1          2
 1      1.0000     4.0000
 2     -1.0000     3.0000
 3      2.0000     2.0000
 4     -3.0000     1.0000

 Backward errors (machine-dependent)
 6.653e-017 7.892e-017

 Estimated forward error bounds (machine-dependent)
 2.336e-014 2.307e-014

 Estimate of reciprocal condition number
         1.0e-002

 A has not been equilibrated


//      f07fp Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F07FPE
  {
    static string datafile = "ExampleData/f07fpe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double rcond=0.0;
        int i,   info,   j,   n,   nrhs; string equed="";
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        nrhs = int.Parse(sr.Next());
        Complex[,] a = new Complex[n, n];
        Complex[,] af = new Complex[n, n];
        Complex[,] b = new Complex[n, nrhs];
        Complex[,] x = new Complex[n, nrhs];
        double[] berr = new double[nrhs];
        double[] ferr = new double[nrhs];
        double[] s = new double[n];
        string[] clabs = new string[1];
        string[] rlabs = new string[1];
        Console.WriteLine("f07fp Example Program Results");
        Console.WriteLine("");
        //      Skip heading in data file
        if (n > 0 )
        {
          //
          //         Read the upper triangular part of A from data file
          //
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            for (j = i ; j <= n ; j++)
            {
              a[i - 1 , j - 1] = Complex.Parse(sr.Next());
            }
          }
          //
          //         Read B from data file
          //
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            for (j = 1 ; j <= nrhs ; j++)
            {
              b[i - 1 , j - 1] = Complex.Parse(sr.Next());
            }
          }
          //
          //         Solve the equations ax = b for x
          //
          F07.f07fp("Equilibration", "Upper", n, nrhs, a, af,   ref equed, s, b, x, out rcond, ferr, berr, out info);

          if (info < 0)
          {
              return;
          }
          //
          if (((info == 0)) || ((info == n + 1)))
          {
            //
            //            Print solution, error bounds, condition number and the form
            //            of equilibration
            //
            Console.WriteLine("Solution(s)\n");
            for (i = 1 ; i <= n ; i++)
            {
              for (j = 1 ; j <= nrhs ; j++)
              {
                Console.Write("{0, 20:f4}", x[i-1,j-1]);
              }
              Console.WriteLine("");
            }
            Console.WriteLine("");
            Console.WriteLine(" {0}","Backward errors (machine-dependent)");
            for (j = 1 ; j <= nrhs ; j++)
            {
              Console.Write(" {0, 3:e1}", berr[j - 1]);
            }
            Console.WriteLine("");
            Console.WriteLine("");
            Console.WriteLine(" {0}","Estimated forward error bounds (machine-dependent)");
            for (j = 1 ; j <= nrhs ; j++)
            {
              Console.Write(" {0, 3:e1}", ferr[j - 1]);
            }
            Console.WriteLine("");
            Console.WriteLine("");
            Console.WriteLine(" {0}","Estimate of reciprocal condition number");
            Console.WriteLine("      {0,11:e1}",rcond);
            Console.WriteLine("");
            if (equed == "N")
            {
              Console.WriteLine(" {0}","A has not been equilibrated");
            }
            else if (equed == "Y")
            {
              Console.WriteLine(" {0}","A has been row and column scaled as diag(S)*A*diag(S)");
            }
            //
            if (info == n + 1)
            {
              Console.WriteLine("");
              Console.WriteLine(" {0}","The matrix A is singular to working precision");
            }
          }
          else if (info > 0)
          {
            Console.WriteLine("  {0}{1,3}{2}","The leading minor of order ",info," is not positive definite");
          }
        }
        else
        {
          Console.WriteLine(" {0}","n <= 0");
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      f07hd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F07HDE
  {
    static string datafile = "ExampleData/f07hde.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,  info,  j,  kd,  n;
        string uplo="";
        int ifail;
        Console.WriteLine("f07hd Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        kd = int.Parse(sr.Next());
        double[,] ab = new double[kd+1, n];
        if (n > 0 && kd > 0)
        {
          //
          //         Read A from data file
          //
          sr.Reset();
          uplo = sr.Next();
          if (uplo == "U")
          {
            for (i = 1 ; i <= n ; i++)
            {
              sr.Reset();
              for (j = i ; j <= Math.Min(n, i + kd) ; j++)
              {
                ab[kd + 1 + i - j - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
            }
          }
          else if (uplo == "L")
          {
            for (i = 1 ; i <= n ; i++)
            {
              sr.Reset();
              for (j = Math.Max(1, i - kd) ; j <= i ; j++)
              {
                ab[1 + i - j - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
            }
          }
          //
          //         Factorize A
          //

          F07.f07hd(uplo, n, kd, ab, out info);

          if (info < 0)
          {
              return;
          }
          //
          Console.WriteLine("");
          if (info == 0)
          {
            //
            //            Print factor
            //
            //
            if (uplo == "U")
            {
              //
              X04.x04ce(n, n, 0, kd, ab, "Factor", out ifail);
              //
            }
            else if (uplo == "L")
            {
              //
              X04.x04ce(n, n, kd, 0, ab, "Factor", out ifail);
              //
            }
            //
          }
          else if (info > 0)
          {
            Console.WriteLine(" {0}","A is not positive-definite");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


f07hd Example Program Data
  4  1                        :Values of N and KD
  'L'                         :Value of UPLO
  5.49
  2.68   5.63
        -2.39   2.60
               -2.22   5.17   :End of matrix A


//      f07he Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F07HEE
  {
    static string datafile = "ExampleData/f07hee.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,  info,  j,  kd,  n,  nrhs;
        string uplo="";
        int ifail;
        Console.WriteLine("f07he Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        kd = int.Parse(sr.Next());
        nrhs = int.Parse(sr.Next());
        double[,] ab = new double[kd+1, n];
        double[,] b = new double[n, nrhs];
        if (n > 0 && kd > 0 && nrhs > 0)
        {
          //
          //         Read A and B from data file
          //
          sr.Reset();
          uplo = sr.Next();
          if (uplo == "U")
          {
            for (i = 1 ; i <= n ; i++)
            {
              sr.Reset();
              for (j = i ; j <= Math.Min(n, i + kd) ; j++)
              {
                ab[kd + 1 + i - j - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
            }
          }
          else if (uplo == "L")
          {
            for (i = 1 ; i <= n ; i++)
            {
              sr.Reset();
              for (j = Math.Max(1, i - kd) ; j <= i ; j++)
              {
                ab[1 + i - j - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
            }
          }
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            for (j = 1 ; j <= nrhs ; j++)
            {
              b[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //
          //         Factorize A
          //
          F07.f07hd(uplo, n, kd, ab, out info);
          if (info < 0)
          {
              return;
          }
          //
          Console.WriteLine("");
          if (info == 0)
          {
            //
            //            Compute solution
            //
            F07.f07he(uplo, n, kd, nrhs, ab, b, out info);
            if (info < 0)
            {
                return;
            }
            //
            //            Print solution
            //
            //
            X04.x04ca("General", "", n, nrhs, b, "Solution(s)", out ifail);
            //
          }
          else if (info > 0)
          {
            Console.WriteLine(" {0}","A is not positive-definite");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      f07te Example Program Text
//      Mark 15 Release. NAG Copyright 1991.
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F07TEE
  {
    static string datafile = "ExampleData/f07tee.d";
    const int nin=5;
    const int nmax=8;
    const int lda=nmax;
    const int nrhmax=nmax;
    const int ldb=nmax;
    const string trans="N";
    const string diag="N";

    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }

    public static void StartExample()
    {
      try
      {
        DataReader sr = null;
        sr = new DataReader(datafile);
        int i=0,
        info=0,
        j=0,
        n=0,
        nrhs=0;
        string uplo="";
        double[,] a = new double[lda, nmax];
        double[,] b = new double[ldb, nrhmax];
        int ifail;
        Console.WriteLine("f07te Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        nrhs = int.Parse(sr.Next());
        if ((n <= nmax) && (nrhs <= nrhmax))
        {
          //
          //         Read A and B from data file
          //
          sr.Reset();
          uplo = sr.Next();
          if (uplo == "U")
          {
            sr.Reset();
            for (i = 1 ; i <= n ; i++)
            {
              for (j = i ; j <= n ; j++)
              {
                a[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
            }
          }
          else if (uplo == "L")
          {
            sr.Reset();
            for (i = 1 ; i <= n ; i++)
            {
              for (j = 1 ; j <= i ; j++)
              {
                a[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
            }
          }
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            for (j = 1 ; j <= nrhs ; j++)
            {
              b[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //
          //         Compute solution
          //
          F07.f07te(uplo, trans, diag, n, nrhs, a, b, out info);
          //
          //         Print solution
          //
          Console.WriteLine("");
          if (info == 0)
          {
            X04.x04ca("General", "", n, nrhs, b, "Solution(s)", out ifail);
          }
          else
          {
            Console.WriteLine(" {0}","A is singular");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      f07th Example Program Text
//      Mark 15 Release. NAG Copyright 1991.
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F07THE
  {
    static string datafile = "ExampleData/f07the.d";
    const int nin=5;
    const int nmax=8;
    const int nrhmax=nmax;
    const int lda=nmax;
    const int ldb=nmax;
    const int ldx=nmax;
    const string trans="N";
    const string diag="N";

    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }

    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i=0,
        info=0,
        j=0,
        n=0,
        nrhs=0;
        string uplo="";
        double[,] a = new double[lda, nmax];
        double[,] b = new double[ldb, nrhmax];
        double[] berr = new double[8];
        double[] ferr = new double[8];
        double[] work = new double[24];
        double[,] x = new double[ldx, nmax];
        int[] iwork = new int[8];
        int ifail;
        Console.WriteLine("f07th Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        nrhs = int.Parse(sr.Next());
        if ((n <= nmax) && (nrhs <= nrhmax))
        {
          //
          //         Read A and B from data file, and copy B to X
          //
          sr.Reset();
          uplo = sr.Next();
          if (uplo == "U")
          {
            sr.Reset();
            for (i = 1 ; i <= n ; i++)
            {
              for (j = i ; j <= n ; j++)
              {
                a[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
            }
          }
          else if (uplo == "L")
          {
            sr.Reset();
            for (i = 1 ; i <= n ; i++)
            {
              for (j = 1 ; j <= i ; j++)
              {
                a[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
            }
          }
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            for (j = 1 ; j <= nrhs ; j++)
            {
              b[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //
        F06.f06qf("General", n, nrhs, b, x,out info);
          //
          //         Compute solution in the array X
          //
          F07.f07te(uplo, trans, diag, n, nrhs, a, x, out info);
          //
          //         Compute backward errors and estimated bounds on the
          //         forward errors
          //
          F07.f07th(uplo, trans, diag, n, nrhs, a, b, x, ferr, berr, out info);
          //
          //         Print solution
          //
          Console.WriteLine("");
          X04.x04ca("General", "", n, nrhs, x, "Solution(s)", out ifail);
          Console.WriteLine("");
          Console.WriteLine(" {0}","Backward errors (machine-dependent)");
          for (j = 1 ; j <= nrhs ; j++)
          {
            // nested do in write
            Console.WriteLine(" {0}", berr[j - 1]);
          }
          Console.WriteLine("");
          Console.WriteLine(" {0}","Estimated forward error bounds (machine-dependent)");
          for (j = 1 ; j <= nrhs ; j++)
          {
            // nested do in write
            Console.WriteLine(" {0}", ferr[j - 1]);
          }
          Console.WriteLine("");
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      f07tj Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F07TJE
  {
    static string datafile = "ExampleData/f07tje.d";
    const string diag="N";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,  info,  j,  n;
        string uplo="";
        int ifail;
        Console.WriteLine("f07tj Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        double[,] a = new double[n, n];
        if (n > 0)
        {
          //
          //         Read A from data file
          //
          sr.Reset();
          uplo = sr.Next();
          if (uplo == "U")
          {
            sr.Reset();
            for (i = 1 ; i <= n ; i++)
            {
              for (j = i ; j <= n ; j++)
              {
                a[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
            }
          }
          else if (uplo == "L")
          {
            sr.Reset();
            for (i = 1 ; i <= n ; i++)
            {
              for (j = 1 ; j <= i ; j++)
              {
                a[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
            }
          }
          //
          //         Compute inverse of A
          //

          F07.f07tj(uplo, diag, n, a, out info);

          if (info < 0)
          {
              return;
          }
          //
          //         Print inverse
          //
          if (info >= 0)
          {
              Console.WriteLine("");
              X04.x04ca(uplo, diag, n, n, a, "Inverse", out ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


f07tj Example Program Data
  4                           :Value of N
  'L'                         :Value of UPLO
  4.30
 -3.96  -4.87
  0.40   0.31  -8.02
 -0.27   0.07  -5.95   0.12   :End of matrix A


//      f08aa Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F08AAE
  {
    static string datafile = "ExampleData/f08aae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double rnorm=0.0;
        int i,   info,   j,   ldb,   m,   n,   nrhs;
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        m = int.Parse(sr.Next());
        n = int.Parse(sr.Next());
        nrhs = 1;
        double[,] a = new double[m, n];
        double[,] b = new double[Math.Max(m,n),nrhs];
        Console.WriteLine("f08aa Example Program Results");
        Console.WriteLine("");
        if (m > 0 && n > 0 && m >= n)
        {
          //
          //         Read A and B from data file
          //
          sr.Reset();
          for (i = 1 ; i <= m ; i++)
          {
            for (j = 1 ; j <= n ; j++)
            {
              a[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          sr.Reset();
          for (i = 1 ; i <= m ; i++)
          {
            b[i - 1,0] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //
          //         Solve the least squares problem min( norm2(b - Ax) ) for x
          //
          ldb = (int)m;
          //
          F08.f08aa("No transpose", m, n, nrhs, a, b, out info);
          //
          //         Print solution
          //

          if (info < 0)
          {
              return;
          }

            Console.WriteLine(" {0}","Least squares solution");
          for (i = 1 ; i <= n ; i++)
          {
            Console.Write(" {0, 11:f4}", b[i - 1,0]);
          }
          Console.WriteLine();
          //
          //         Compute and print estimate of the square root of the residual
          //         sum of squares
          //
          // Compute rnorm
          for (i = Math.Min(m,n); i < Math.Max(m,n); i++)
          {
            rnorm += b[i,0]*b[i,0];
          }
          rnorm = Math.Sqrt(rnorm);
          Console.WriteLine("");
          Console.WriteLine(" {0}","Square root of the residual sum of squares");
          Console.WriteLine("      {0,8:e2}",rnorm);

        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


f08aa Example Program Results

 Least squares solution
      1.5339      1.8707     -1.5241      0.0392

 Square root of the residual sum of squares
      2.22e-002


//      f08an Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F08ANE
  {
    static string datafile = "ExampleData/f08ane.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double rnorm=0.0;
        int i,   info,   j,   m,   n;
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        m = int.Parse(sr.Next());
        n = int.Parse(sr.Next());
        int nrhs = 1;
        Complex[,] a = new Complex[m, n];
        Complex[,] b = new Complex[Math.Max(m,n),nrhs];
        Console.WriteLine("f08an Example Program Results");
        Console.WriteLine("");
        if (m >0 && n > 0  && m >= n)
        {
          //
          //         Read A and B from data file
          //
          sr.Reset();
          for (i = 1 ; i <= m ; i++)
          {
            for (j = 1 ; j <= n ; j++)
            {
              a[i - 1 , j - 1] = Complex.Parse(sr.Next());
            }
          }
          sr.Reset();
          for (i = 1 ; i <= m ; i++)
          {
            b[i - 1,0] = Complex.Parse(sr.Next());
          }
          //
          //         Solve the least squares problem min( norm2(b - Ax) ) for x
          //
          F08.f08an("No transpose", m, n, nrhs, a, b, out info);

          if (info < 0)
          {
              return;
          }
          //
          //         Print solution
          //

              Console.WriteLine(" {0}", "Least squares solution");
              for (i = 1; i <= n; i++)
              {
                  Console.Write(" {0, 10:f4}", b[i - 1, 0]);
              }
              Console.WriteLine();
              //
              //         Compute and print estimate of the square root of the residual
              //         sum of squares
              //
              Complex[] ArraySlice_b = new Complex[m - n];
              for (i = 0; i < m - n; i++)
                  ArraySlice_b[i] = b[n + i, 0];
              int ifail;
              rnorm = F06.f06jj(m - n, ArraySlice_b, 1, out ifail);
              Console.WriteLine("");
              Console.WriteLine(" {0}", "Square root of the residual sum of squares");
              Console.WriteLine("  {0,10:e2}", rnorm);

        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


f08an Example Program Results

 Least squares solution
 (-0.5044,-1.2179)  (-2.4281,2.8574)  (1.4872,-2.1955)  (0.4537,2.6904)

 Square root of the residual sum of squares
   6.88e-002


//      f08be Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F08BEE
  {
    static string datafile = "ExampleData/f08bee.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);

        double tol=0.0;
        int i,  info,  j,  k,  m,  n,  nrhs;
        int ifail;
        Console.WriteLine("f08be Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        m = int.Parse(sr.Next());
        n = int.Parse(sr.Next());
        nrhs = int.Parse(sr.Next());
        double[,] a = new double[m, n];
        double[,] b = new double[m, nrhs];
        double[] tau = new double[Math.Min(m,n)];
        double[] work = new double[512];
        double[,] x = new double[n, nrhs];
        int[] jpvt = new int[n];
        if ((m >= 1 && n >= 1 && m >= n) && nrhs >= 1)
        {
          //
          //         Read A and B from data file
          //
          sr.Reset();
          for (i = 1 ; i <= m ; i++)
          {
            for (j = 1 ; j <= n ; j++)
            {
              a[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          sr.Reset();
          for (i = 1 ; i <= m ; i++)
          {
            for (j = 1 ; j <= nrhs ; j++)
            {
              b[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //
          //         Initialize jpvt to be zero so that all columns are free
          //
          F06.f06db(n, 0, jpvt, 1, out ifail);
          //
          //         Compute the QR factorization of a
          //
          F08.f08be(m, n, a, jpvt, tau, out info);

          if (info < 0)
          {
              return;
          }
          //
          //         Choose tol to reflect the relative accuracy of the input data
          //
          tol = 0.010e0;
          //
          //         Determine which columns of R to use
          //
          for (k = 1 ; k <= n ; k++)
          {
            if (Math.Abs(a[k - 1 , k - 1]) <= tol * Math.Abs(a[0 , 0]))
            {
              goto L40;
            }
          }
          //
          //         Compute C = (Q**T)*B, storing the result in B
          //
          L40: ;
          k = k - 1;
          //
          F08.f08ag("Left", "Transpose", m, nrhs, n, a, tau, b, out info);
          //
          //         Compute least-squares solution by backsubstitution in R*B = C
          //
          double [] bcolumn = new double [m];
          for (i = 1 ; i <= nrhs ; i++)
          {
            //
            for (j = 0; j < k; j++)
            bcolumn[j] = b[j,i-1];
            F06.f06pj("Upper", "No transpose", "Non-Unit", k, a, bcolumn, 1, out ifail);
            //
            //            Copy bcolumn to b's column including zero elements
            for (j = 0; j < m; j++)
            b[j,i-1] = bcolumn[j];
            //
          }
          //
          //         Unscramble the least-squares solution stored in B
          //
          for (i = 1 ; i <= n ; i++)
          {
            for (j = 1 ; j <= nrhs ; j++)
            {
              x[jpvt[i - 1] - 1 , j - 1] = b[i - 1 , j - 1];
            }
          }
          //
          //         Print least-squares solution
          //
          Console.WriteLine("");
          //
          X04.x04ca("General", "", n, nrhs, x, "Least-squares solution", out ifail);
          //
        }
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      f08bf Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F08BFE
  {
    const double one=1.00e0;
    const double zero=0.00e0;
    static string datafile = "ExampleData/f08bfe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double tol=0.0;
        int i,   info,   j,   k,   m,   n,   nrhs; sr.Reset();
        sr.Reset();
        m = int.Parse(sr.Next());
        n = int.Parse(sr.Next());
        nrhs = int.Parse(sr.Next());
        double[,] a = new double[m, n];
        double[,] b = new double[m, nrhs];
        double[] rnorm = new double[n];
        double[] tau = new double[Math.Min(m,n)];
        double[] work = new double[n];
        int[] jpvt = new int[n];
        int ifail;
        Console.WriteLine("f08bf Example Program Results");
        Console.WriteLine("");
        //      Skip heading in data file
        double [] ArraySlice_b = new double [n];
        if (m > 0 && n > 0 && m >= n && nrhs > 0)
        {
          //
          //         Read A and B from data file
          //
          sr.Reset();
          for (i = 1 ; i <= m ; i++)
          {
            for (j = 1 ; j <= n ; j++)
            {
              a[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          sr.Reset();
          for (i = 1 ; i <= m ; i++)
          {
            for (j = 1 ; j <= nrhs ; j++)
            {
              b[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //
          //         Initialize jpvt to be zero so that all columns are free
          //
          F06.f06db(n, 0, jpvt, 1, out ifail);

         if (ifail < 0)
          {
              return;
          }

          //
          //         Compute the QR factorization of a
          //
          F08.f08bf(m, n, a, jpvt, tau, out info);
          if (info < 0)
          {
              return;
          }

          //
          //         Compute c = (c1) = (q**t)*b, storing the result in B
          //                     (c2)
          //
          F08.f08ag("Left", "Transpose", m, nrhs, n, a, tau, b, out info);
          //
          //         Choose tol to reflect the relative accuracy of the input data
          //
          tol = 0.010e0;
          //
          //         Determine and print the rank, k, of r relative to tol
          //
          for (k = 1 ; k <= n ; k++)
          {
            if (Math.Abs(a[k - 1 , k - 1]) <= tol * Math.Abs(a[0 , 0]))
            {
              goto L40;
            }
          }
          L40: ;
          k = k - 1;
          //
          Console.WriteLine(" {0}","Tolerance used to estimate the rank of A");
          Console.WriteLine("     {0,11:e2}",tol);
          Console.WriteLine(" {0}","Estimated rank of A");
          Console.WriteLine("  {0,8}",k);
          Console.WriteLine("");
          //
          //         Compute least-squares solutions by backsubstitution in
          //         r(1:k,1:k)*y = c1, storing the result in b
          //
          F06.f06yj("Left", "Upper", "No transpose", "Non-Unit", k, nrhs, one, a, b, out ifail);
          //
          //         Compute estimates of the square roots of the residual sums of
          //         squares (2-norm of each of the columns of c2)
          //
          for (j = 1 ; j <= nrhs ; j++)
          {
            for (int ind=0; ind < m-k; ind++)
            ArraySlice_b[ind]=b[k+ind,j-1];
            rnorm[j - 1] = F06.f06ej(m - k, ArraySlice_b, 1, out ifail);
          }
          //
          //         Set the remaining elements of the solutions to zero (to give
          //         the basic solutions)
          //
          double [, ] ArraySlice_b_2d = new double [n-k,  nrhs];
          F06.f06qh("General", n - k, nrhs, zero, zero, ArraySlice_b_2d, out ifail);
          for (i=0; i<n-k;i++)
          for (j=0; j <nrhs; j++)
          b[k+i, j] = ArraySlice_b_2d[i,j];
          //
          //         Permute the least-squares solutions stored in B to give x = p*y
          //
          for (j = 1 ; j <= nrhs ; j++)
          {
            for (i = 1 ; i <= n ; i++)
            {
              work[jpvt[i - 1] - 1] = b[i - 1 , j - 1];
            }
            F06.f06ef(n, work, 1, ArraySlice_b, 1, out ifail);
            for (int ind = 0; ind < n; ind++)
            b[ind, j-1] = ArraySlice_b[ind];
          }
          //
          //         Print least-squares solutions
          //
          X04.x04ca("General", "", n, nrhs, b, "Least-squares solution(s)", out ifail);
          //
          //         Print the square roots of the residual sums of squares
          //
          Console.WriteLine(" {0}","Square root(s) of the residual sum(s) of squares");
          for (j = 1 ; j <= nrhs ; j++)
          {
            Console.Write("      {0, 11:e2}", rnorm[j - 1]);
          }
          Console.WriteLine();
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


f08bf Example Program Results

 Tolerance used to estimate the rank of A
       1.00e-002
 Estimated rank of A
         4

 Least-squares solution(s)
             1          2
 1      0.9767     4.0159
 2      1.9861     2.9867
 3      0.0000     0.0000
 4      2.9927     2.0032
 5      4.0272     0.9976
 Square root(s) of the residual sum(s) of squares
        2.54e-002        3.65e-002


//      f08fa Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F08FAE
  {
    static string datafile = "ExampleData/f08fae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double eerrbd,   eps; int i,  info,  j,  n;
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        double[,] a = new double[n, n];
        double[] rcondz = new double[n];
        double[] w = new double[n];
        double[] zerrbd = new double[n];
        int ifail;
        Console.WriteLine("f08fa Example Program Results");
        Console.WriteLine("");
        if (n > 0)
        {
          //
          //         Read the upper triangular part of the matrix A from data file
          //
          sr.Reset();
          for (i = 1; i <= n; i++)
          {
            for (j = i; j <= n; j++)
            {
              a[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //
          //         Solve the symmetric eigenvalue problem
          //
          F08.f08fa("Vectors", "Upper", n, a, w, out info);
          if (info < 0)
          {
              return;
          }

          //
          if (info == 0)
          {
            //
            //            Print solution
            //
            Console.WriteLine(" {0}", "Eigenvalues");
            for (j = 1; j <= n; j++)
            {
              Console.Write(" {0,8:f4}", w[j - 1]);
            }
            Console.WriteLine("");
            //
            X04.x04ca("General", "", n, n, a, "Eigenvectors", out ifail);
            //
            //            Get the machine precision, eps and compute the approximate
            //            error bound for the computed eigenvalues.  Note that for
            //            the 2-norm, max( abs(w[i-1]) ) = norm(a), and since the
            //            eigenvalues are returned in ascending order
            //            max( abs(w[i-1]) ) = max( abs(w[0]), abs(w[n-1]))
            //
            eps = X02.x02aj();
            eerrbd = eps * Math.Max(Math.Abs(w[0]), Math.Abs(w[n - 1]));
            //
            //            Call f08fl to estimate reciprocal condition
            //            numbers for the eigenvectors
            //
            F08.f08fl("Eigenvectors", n, n, w, rcondz, out info);
            //
            //            Compute the error estimates for the eigenvectors
            //
            for (i = 1; i <= n; i++)
            {
              zerrbd[i - 1] = eerrbd / rcondz[i - 1];
            }
            //
            //            Print the approximate error bounds for the eigenvalues
            //            and vectors
            //
            Console.WriteLine("");
            Console.WriteLine(" {0}", "Error estimate for the eigenvalues");
            Console.WriteLine("        {0,11:e1}", eerrbd);
            Console.WriteLine("");
            Console.WriteLine(" {0}", "Error estimates for the eigenvectors");
            for (i = 1; i <= n; i++)
            {
              Console.Write(" {0, 11:e1}", zerrbd[i - 1]);
            }
            Console.WriteLine();
          }
          else
          {
            Console.WriteLine("  {0}{1,4}", "Failure in DSYEV. INFO =", info);
          }
          //
          //         Print workspace information
          //
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


f08fa Example Program Data

  4                  :Value of N

  1.0  2.0  3.0  4.0
       2.0  3.0  4.0
            3.0  4.0
                 4.0 :End of matrix A


//      f08fb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.Threading;
namespace NagDotNetExamples
{
  public class F08FBE
  {
    const double zero=0.00e+0;
    static string datafile = "ExampleData/f08fbe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
  StartExample();

    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double abstol,   vl,   vu; int i,  il,  info,  iu,  j,  m,  n;
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        double[,] a = new double[n, n];
        double[] w = new double[n];
        double[,] z = new double[n, n];
        int[] jfail = new int[n];
        int ifail;
        il = 0;
        iu = 0;
        Console.WriteLine("f08fb Example Program Results");
        Console.WriteLine("");
        if (n > 0)
        {
          //
          //         Read the lower and upper bounds of the interval to be searched,
          //         and read the upper triangular part of the matrix A from data
          //         file
          //
          sr.Reset();
          vl = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          vu = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            for (j = i ; j <= n ; j++)
            {
              a[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //
          //         Set the absolute error tolerance for eigenvalues.  With abstol
          //         set to zero, the default value is used instead
          //
          abstol = zero;
          //
          //         Solve the symmetric eigenvalue problem
          //
          F08.f08fb("Vectors", "Values in range", "Upper", n, a, vl, vu, il, iu, abstol, out m, w, z, jfail, out info);

          if (info < 0)
          {
              return;
          }

          //
          if (info >= 0 && m > 0)
          {
            //
            //            Print solution
            //
            Console.WriteLine("  {0}{1,5}","Number of eigenvalues found =",m);
            Console.WriteLine("");
            Console.WriteLine(" {0}","Eigenvalues");
            for (j = 1 ; j <= m ; j++)
            {
              Console.Write(" {0, 10:f4}", w[j - 1]);
            }
            Console.WriteLine();
            //
            X04.x04ca("General", "", n, m, z, "Selected eigenvectors", out ifail);
            if (info > 0)
            {
              Console.WriteLine("  {0}{1,5}","INFO eigenvectors failed to converge, INFO =",info);
              Console.WriteLine(" {0}","Indices of eigenvectors that did not converge");
              for (j = 1 ; j <= m ; j++)
              {
                Console.Write(" {0}", jfail[j - 1]);
              }
              Console.WriteLine();
            }
          }
          else if (m <= 0)
          {
            Console.WriteLine("  {0}{1,5}","M <= 0 =",m);
          }
          else
          {
            Console.WriteLine("  {0}{1,5}","Failure in F08.f08fb. info =",info);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


f08fb Example Program Data
  4                  :Value of N
 -1.0  1.0           :Values of VL and VU
  1.0  2.0  3.0  4.0
       2.0  3.0  4.0
            3.0  4.0
                 4.0 :End of matrix A


f08fb Example Program Results

  Number of eigenvalues found =    2

 Eigenvalues
    -0.5146    -0.2943
 Selected eigenvectors
          1       2
 1  -0.5144  0.2767
 2   0.4851 -0.6634
 3   0.5420  0.6504
 4  -0.4543 -0.2457


//      f08fp Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F08FPE
  {
    const double zero=0.00e+0;
    static string datafile = "ExampleData/f08fpe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double abstol,   vl,   vu; int i,  il,  info,  iu,  j,  m,  n;
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        Complex[,] a = new Complex[n, n];
        Complex[,] z = new Complex[n, n];
        double[] w = new double[n];
        int[] jfail = new int[n];
        int ifail;
        il = 0;
        iu = 0;
        Console.WriteLine("f08fp Example Program Results");
        Console.WriteLine("");
        if (n > 0)
        {
          //
          //         Read the lower and upper bounds of the interval to be searched,
          //         and read the upper triangular part of the matrix A from data
          //         file
          //
          sr.Reset();
          vl = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          vu = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            for (j = i ; j <= n ; j++)
            {
              a[i - 1 , j - 1] = Complex.Parse(sr.Next());
            }
          }
          //
          //         Set the absolute error tolerance for eigenvalues.  With abstol
          //         set to zero, the default value is used instead
          //
          abstol = zero;
          //
          //         Solve the Hermitian eigenvalue problem
          //
          F08.f08fp("Vectors", "Values in range", "Upper", n, a, vl, vu, il, iu, abstol, out m, w, z, jfail, out info);

          if (info < 0)
          {
              return;
          }
          //
          if (info >= 0 && m >= 1)
          {
            //
            //            Print solution
            //
            Console.WriteLine("  {0}{1,5}","Number of eigenvalues found =",m);
            Console.WriteLine("");
            Console.WriteLine(" {0}","Eigenvalues");
            for (j = 1 ; j <= m ; j++)
            {
              Console.Write(" {0, 10:f4}", w[j - 1]);
            }
            Console.WriteLine();
            //
            X04.x04da("General", "", n, m, z, "Selected eigenvectors", out ifail);
            if (info > 0)
            {
              Console.WriteLine("  {0}{1,5}","INFO eigenvectors failed to converge, INFO =",info);
              Console.WriteLine(" {0}","Indices of eigenvectors that did not converge");
              for (j = 1 ; j <= m ; j++)
              {
                Console.Write(" {0}", jfail[j - 1]);
              }
              Console.WriteLine();
            }
          }
          else
          {
            Console.WriteLine("  {0}{1,5}","Failure in ZHEEVX. INFO =",info);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      f08kb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F08KBE
  {
    static string datafile = "ExampleData/f08kbe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double eps,   serrbd; int i,  info,  j,  m,  n;
        sr.Reset();
        sr.Reset();
        m = int.Parse(sr.Next());
        n = int.Parse(sr.Next());
        double[,] a = new double[m, n];
        double[,] dummy = new double[1, 1];
        double[] rcondu = new double[Math.Min(m,n)];
        double[] rcondv = new double[Math.Min(m,n)];
        double[] s = new double[Math.Min(m,n)];
        double[] uerrbd = new double[Math.Min(m,n)];
        double[] verrbd = new double[Math.Min(m,n)];
        double[,] vt = new double[n, n];
        int ifail;
        Console.WriteLine("f08kb Example Program Results");
        Console.WriteLine("");
        //      Skip heading in data file
        if (m > 0 && n > 0)
        {
          //
          //         Read the m by n matrix A from data file
          //
          sr.Reset();
          for (i = 1 ; i <= m ; i++)
          {
            for (j = 1 ; j <= n ; j++)
            {
              a[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //
          //         Compute the singular values and left and right singular vectors
          //         of A (A = U*S*(V**T), m.ge.n)
          //
          F08.f08kb("Overwrite A by U", "Singular vectors (V)", m, n, a, s, dummy, vt,
          out info);

          if (info < 0)
          {
              return;
          }
          //
          if (info == 0)
          {
            //
            //            Print solution
            //
            Console.WriteLine(" {0}","Singular values");
            for (j = 1 ; j <= n ; j++)
            {
              Console.Write(" {0, 10:f4}", s[j - 1]);
            }
            Console.WriteLine();
            //
            X04.x04ca("General", "", m, n, a, "Left singular vectors (first n columns of U)",
            out ifail);
            Console.WriteLine("");
            X04.x04ca("General", "", n, n, vt, "Right singular vectors by row (V**T)",
            out ifail);
            //
            //            Get the machine precision, eps and compute the approximate
            //            error bound for the computed singular values.  Note that for
            //            the 2-norm, s[0] = norm(a)
            //
            eps = X02.x02aj();
            serrbd = eps * s[0];
            //
            //            Call f08fl to estimate reciprocal condition
            //            numbers for the singular vectors
            //
            F08.f08fl("Left", m, n, s, rcondu, out info);
            F08.f08fl("Right", m, n, s, rcondv, out info);
            //
            //            Compute the error estimates for the singular vectors
            //
            for (i = 1 ; i <= n ; i++)
            {
              uerrbd[i - 1] = serrbd / rcondu[i - 1];
              verrbd[i - 1] = serrbd / rcondv[i - 1];
            }
            //
            //            Print the approximate error bounds for the singular values
            //            and vectors
            //
            Console.WriteLine("");
            Console.WriteLine(" {0}","Error estimate for the singular values");
            Console.WriteLine("        {0,11:e1}",serrbd);
            Console.WriteLine("");
            Console.WriteLine(" {0}","Error estimates for the left singular vectors");
            for (i = 1 ; i <= n ; i++)
            {
              Console.Write(" {0, 10:e1}", uerrbd[i - 1]);
            }
            Console.WriteLine();
            Console.WriteLine("");
            Console.WriteLine(" {0}","Error estimates for the right singular vectors");
            for (i = 1 ; i <= n ; i++)
            {
              Console.Write(" {0, 10:e1}", verrbd[i - 1]);
            }
            Console.WriteLine();
          }
          else
          {
            Console.WriteLine("  {0}{1,4}","Failure in DGESVD. INFO =",info);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      f08kp Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F08KPE
  {
    static string datafile = "ExampleData/f08kpe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double eps,   serrbd; int i,  info,  j,  m,  n;
        int ifail;
        Console.WriteLine("f08kp Example Program Results");
        Console.WriteLine("");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        m = int.Parse(sr.Next());
        n = int.Parse(sr.Next());
        Complex[,] a = new Complex[m, n];
        Complex[,] dummy = new Complex[1, 1];
        Complex[,] vt = new Complex[n, n];
        double[] rcondu = new double[n];
        double[] rcondv = new double[n];
        double[] s = new double[n];
        double[] uerrbd = new double[n];
        double[] verrbd = new double[n];
        if (m > 1 && n > 1)
        {
          //
          //         Read the m by n matrix A from data file
          //
          sr.Reset();
          for (i = 1 ; i <= m ; i++)
          {
            for (j = 1 ; j <= n ; j++)
            {
              a[i - 1 , j - 1] = Complex.Parse(sr.Next());
            }
          }
          //
          //         Compute the singular values and left and right singular vectors
          //         of A (A = U*S*(V**H), m.ge.n)
          //
          F08.f08kp("Overwrite A by U", "Singular vectors (V)", m, n, a, s, dummy, vt,
          out info);
          if (info < 0)
          {
              return;
          }
          //
          if (info == 0)
          {
            //
            //            Print solution
            //
            Console.WriteLine(" {0}","Singular values");
            for (j = 1 ; j <= n ; j++)
            {
              Console.Write(" {0, 8:f4}", s[j - 1]);
            }
            Console.WriteLine();
            //
            X04.x04da("General", "", m, n, a, "Left singular vectors (first n columns of U)",
            out ifail);
            Console.WriteLine("");
            X04.x04da("General", "", n, n, vt,
            ("Conjugates of ") + ("right singular vectors by row (V**H)"), out ifail);
            //
            //            Get the machine precision, eps and compute the approximate
            //            error bound for the computed singular values.  Note that for
            //            the 2-norm, s[0] = norm(a)
            //
            eps = X02.x02aj();
            serrbd = eps * s[0];
            //
            //            Call f08fl to estimate reciprocal condition
            //            numbers for the singular vectors
            //
            F08.f08fl("Left", m, n, s, rcondu, out info);
            F08.f08fl("Right", m, n, s, rcondv, out info);
            //
            //            Compute the error estimates for the singular vectors
            //
            for (i = 1 ; i <= n ; i++)
            {
              uerrbd[i - 1] = serrbd / rcondu[i - 1];
              verrbd[i - 1] = serrbd / rcondv[i - 1];
            }
            //
            //            Print the approximate error bounds for the singular values
            //            and vectors
            //
            Console.WriteLine("");
            Console.WriteLine(" {0}","Error estimate for the singular values");
            Console.WriteLine("        {0,11:e1}",serrbd);
            Console.WriteLine("");
            Console.WriteLine(" {0}","Error estimates for the left singular vectors");
            for (i = 1 ; i <= n ; i++)
            {
              Console.Write(" {0, 11:e1}", uerrbd[i - 1]);
            }
            Console.WriteLine();
            Console.WriteLine("");
            Console.WriteLine(" {0}","Error estimates for the right singular vectors");
            for (i = 1 ; i <= n ; i++)
            {
              Console.Write(" {0, 11:e1}", verrbd[i - 1]);
            }
            Console.WriteLine();
          }
          else
          {
            Console.WriteLine("  {0}{1,4}","Failure in ZGESVD. INFO =",info);
          }
        }
        else
        {
          Console.WriteLine(" {0}","m or n < 1.");
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      f08nb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F08NBE
  {
    static string datafile = "ExampleData/f08nbe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        Complex eig= new Complex(0.0,0.0);
        double abnrm,   eps,   erbnd,   rcnd,   tol; int i,  ihi,  ilo,  info,  j,  n;
        Console.WriteLine("f08nb Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        double[,] a = new double[n, n];
        double[] rconde = new double[n];
        double[] rcondv = new double[n];
        double[] scale = new double[n];
        double[,] vl = new double[n, n];
        double[,] vr = new double[n, n];
        double[] wi = new double[n];
        double[] wr = new double[n];
        if (n > 1)
        {
          //
          //         Read the matrix A from data file
          //
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            for (j = 1 ; j <= n ; j++)
            {
              a[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //
          //         Solve the eigenvalue problem
          //
          F08.f08nb("Balance", "Vectors (left)", "Vectors (right)",
          "Both reciprocal condition numbers", n, a, wr, wi, vl, vr, out ilo, out ihi, scale, out abnrm, rconde, rcondv, out info);
          //

          if (info < 0)
          {
              return;
          }

          if (info == 0)
          {
            //
            //            Compute the machine precision
            //
            eps = X02.x02aj();
            tol = eps * abnrm;
            //
            //            Print the eigenvalues and vectors, and associated condition
            //            number and bounds
            //
            for (j = 1 ; j <= n ; j++)
            {
              //
              //               Print information on jth eigenvalue
              //
              Console.WriteLine("");
              if (wi[j - 1] == 0.00e0)
              {
                Console.WriteLine("  {0}{1,2}{2}{3,11:e4}","Eigenvalue(",j,") = ",wr[j - 1]);
              }
              else
              {
                eig = new Complex(wr[j - 1], wi[j - 1]);
                Console.WriteLine("  {0}{1,2}{2}({3,11:e4},{3,11:e4})","Eigenvalue(",j,") = ",eig.re, eig.im);
              }
              rcnd = rconde[j - 1];
              Console.WriteLine("");
              Console.WriteLine("  {0}{1,8:e1}","Reciprocal condition number = ",rcnd);
              if (rcnd > 0.00e0)
              {
                erbnd = tol / rcnd;
                Console.WriteLine("  {0}{1,8:e1}","Error bound                 = ",erbnd);
              }
              else
              {
                Console.WriteLine(" {0}","Error bound is infinite");
              }
              //
              //               Print information on jth eigenvector
              //
              Console.WriteLine("");
              Console.WriteLine("  {0}{1,2}{2}","Eigenvector(",j,")");
              if (wi[j - 1] == 0.00e0)
              {
                for (i = 1 ; i <= n ; i++)
                {
                  Console.WriteLine(" {0, 11:e4}", vr[i - 1 , j - 1]);
                }
                Console.WriteLine();
              }
              else if (wi[j - 1] > 0.00e0)
              {
                for (i = 1 ; i <= n ; i++)
                {
                  Console.WriteLine(" ({0, 11:e4}, {1, 11:e4})", vr[i - 1 , j - 1], vr[i - 1 , j + 1 - 1]);
                }
                Console.WriteLine();
              }
              else
              {
                for (i = 1 ; i <= n ; i++)
                {
                  Console.WriteLine("({0, 11:e4}, {1, 11:e4})", vr[i - 1 , j - 1 - 1],  -vr[i - 1 , j - 1]);
                }
                Console.WriteLine();
              }
              rcnd = rcondv[j - 1];
              Console.WriteLine("");
              Console.WriteLine("  {0}{1,8:e1}","Reciprocal condition number = ",rcnd);
              if (rcnd > 0.00e0)
              {
                erbnd = tol / rcnd;
                Console.WriteLine("  {0}{1,8:e1}","Error bound                 = ",erbnd);
              }
              else
              {
                Console.WriteLine(" {0}","Error bound is infinite");
              }
            }
          }
          else
          {
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,4}","Failure in DGEEVX.  INFO = ",info);
          }
          //
          //         Print workspace information
          //
        }
        else
        {
          Console.WriteLine("");
          Console.WriteLine(" {0}","n < 1.");
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      f08np Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F08NPE
  {
    static string datafile = "ExampleData/f08npe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double abnrm,   eps,   erbnd,   rcnd,   tol; int i,  ihi,  ilo,  info,  j,  n;
        Console.WriteLine("f08np Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        Complex[,] a = new Complex[n, n];
        Complex[,] vl = new Complex[n, n];
        Complex[,] vr = new Complex[n, n];
        Complex[] w = new Complex[n];
        double[] rconde = new double[n];
        double[] rcondv = new double[n];
        double[] scale = new double[n];
        if (n > 1)
        {
          //
          //         Read the matrix A from data file
          //
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            for (j = 1 ; j <= n ; j++)
            {
              a[i - 1 , j - 1] = Complex.Parse(sr.Next());
            }
          }
          //
          //         Solve the eigenvalue problem
          //
          F08.f08np("Balance", "Vectors (left)", "Vectors (right)",
          "Both reciprocal condition numbers", n, a, w, vl, vr, out ilo, out ihi, scale, out abnrm, rconde, rcondv, out info);
          if (info < 0)
          {
              return;
          }

            //
          if (info == 0)
          {
            //
            //            Compute the machine precision
            //
            eps = X02.x02aj();
            tol = eps * abnrm;
            //
            //            Print the eigenvalues and vectors, and associated condition
            //            number and bounds
            //
            for (j = 1 ; j <= n ; j++)
            {
              //
              //               Print information on jth eigenvalue
              //
              Console.WriteLine("");
              Console.WriteLine("  {0}{1,2}{2}{3,11:e4}","Eigenvalue(",j,") = ",w[j - 1]);
              rcnd = rconde[j - 1];
              Console.WriteLine("");
              Console.WriteLine("  {0}{1,8:e1}","Reciprocal condition number = ",rcnd);
              if (rcnd > 0.00e0)
              {
                erbnd = tol / rcnd;
                Console.WriteLine("  {0}{1,8:e1}","Error bound                 = ",erbnd);
              }
              else
              {
                Console.WriteLine(" {0}","Error bound is infinite");
              }
              //
              //               Print information on jth eigenvector
              //
              Console.WriteLine("");
              Console.Write(" {0}",  "Eigenvector(");
              Console.Write(" {0}",  j);
              Console.WriteLine(" {0}",  ")");
              for (i = 1 ; i <= n ; i++)
              {
                Console.Write(" {0, 11:e4}{1}", vr[i - 1 , j - 1], i%3==0?"\n":"");
              }
              Console.WriteLine();
              rcnd = rcondv[j - 1];
              Console.WriteLine("");
              Console.WriteLine("  {0}{1,8:e1}","Reciprocal condition number = ",rcnd);
              if (rcnd > 0.00e0)
              {
                erbnd = tol / rcnd;
                Console.WriteLine("  {0}{1,8:e1}","Error bound                 = ",erbnd);
              }
              else
              {
                Console.WriteLine(" {0}","Error bound is infinite");
              }
            }
          }
          else
          {
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,4}","Failure in ZGEEVX. INFO =",info);
          }
        }
        else
        {
          Console.WriteLine("");
          Console.WriteLine(" {0}","n < 1.");
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      f08wb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F08WBE
  {
    static string datafile = "ExampleData/f08wbe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        Complex eig= new Complex(0.0,0.0);
        double abnorm,   abnrm,   bbnrm,   eps,   erbnd,   rcnd,   small,   tol; int i,  ihi,  ilo,  info,  j,  n;
        Console.WriteLine("f08wb Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        double[,] a = new double[n, n];
        double[] alphai = new double[n];
        double[] alphar = new double[n];
        double[,] b = new double[n, n];
        double[] beta = new double[n];
        double[,] dummy = new double[1, 1];
        double[] lscale = new double[n];
        double[] rconde = new double[n];
        double[] rcondv = new double[n];
        double[] rscale = new double[n];
        double[,] vr = new double[n, n];
        if (n > 1)
        {
          //
          //         Read in the matrices A and B
          //
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            for (j = 1 ; j <= n ; j++)
            {
              a[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            for (j = 1 ; j <= n ; j++)
            {
              b[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //
          //         Solve the generalized eigenvalue problem
          //
          F08.f08wb("Balance", "No vectors (left)", "Vectors (right)",
          "Both reciprocal condition numbers", n, a, b, alphar, alphai, beta, dummy, vr, out ilo, out ihi, lscale, rscale, out abnrm,
          out bbnrm, rconde, rcondv, out info);

          if (info < 0)
          {
              return;
          }

          //
          if (info > 0)
          {
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,4}","Failure in DGGEVX. INFO =",info);
          }
          else
          {
            //
            //            Compute the machine precision, the safe range parameter
            //            small and sqrt(abnrm**2+bbnrm**2)
            //
            eps = X02.x02aj();
            small = X02.x02am();
            abnorm = F06.f06bn(abnrm, bbnrm);
            tol = eps * abnorm;
            //
            //            Print out eigenvalues and vectors and associated condition
            //            number and bounds
            //
            for (j = 1 ; j <= n ; j++)
            {
              //
              //               Print out information on the jth eigenvalue
              //
              Console.WriteLine("");
              if (((Math.Abs(alphar[j - 1]) + Math.Abs(alphai[j - 1])) * small) >= (Math.Abs(beta[j - 1])))
              {
                Console.WriteLine("  {0}{1,2}{2}{3}\n  {4}{5,2}{6}{7,11:e4}{8}{9,2}{10}{11,11:e4}{12}{13,2}{14}{15,11:e4}","Eigenvalue(",j,")"," is numerically infinite or undetermined","ALPHAR(",j,") = ",alphar[j - 1],", ALPHAI(",j,") = ",alphai[j - 1],", BETA(",j,") = ",beta[j - 1]);
              }
              else
              {
                if (alphai[j - 1] == 0.00e0)
                {
                  Console.WriteLine("  {0}{1,2}{2}{3,11:e4}","Eigenvalue(",j,") = ",alphar[j - 1] / beta[j - 1]);
                }
                else
                {
                  eig = new Complex(alphar[j - 1], alphai[j - 1]) / beta[j - 1];
                  Console.WriteLine("  {0}{1,2}{2}{3,11:e4}","Eigenvalue(",j,") = ",eig);
                }
              }
              rcnd = rconde[j - 1];
              Console.WriteLine("");
              Console.WriteLine("  {0}{1,8:e1}","Reciprocal condition number = ",rcnd);
              if (rcnd > 0.00e0)
              {
                erbnd = tol / rcnd;
                Console.WriteLine("  {0}{1,8:e1}","Error bound                 = ",erbnd);
              }
              else
              {
                Console.WriteLine(" {0}","Error bound is infinite");
              }
              //
              //               Print out information on the jth eigenvector
              //
              Console.WriteLine("");
              Console.WriteLine("  {0}{1,2}{2}","Eigenvector(",j,")");
              if (alphai[j - 1] == 0.00e0)
              {
                for (i = 1 ; i <= n ; i++)
                {
                  Console.WriteLine(" {0, 11:e4}", vr[i - 1 , j - 1]);
                }
                Console.WriteLine();
              }
              else if (alphai[j - 1] > 0.00e0)
              {
                for (i = 1 ; i <= n ; i++)
                {
                  Console.WriteLine(" ( {0, 11:e4}, {1, 11:e4})", vr[i - 1 , j - 1], vr[i - 1 , j + 1 - 1]);
                }
                Console.WriteLine();
              }
              else
              {
                for (i = 1 ; i <= n ; i++)
                {
                  Console.WriteLine("( {0, 11:e4}, {1, 11:e4})", vr[i - 1 , j - 1 - 1], -vr[i - 1 , j - 1]);
                }
                Console.WriteLine();
              }
              rcnd = rcondv[j - 1];
              Console.WriteLine("");
              Console.WriteLine("  {0}{1,8:e1}","Reciprocal condition number = ",rcnd);
              if (rcnd > 0.00e0)
              {
                erbnd = tol / rcnd;
                Console.WriteLine("  {0}{1,8:e1}","Error bound                 = ",erbnd);
              }
              else
              {
                Console.WriteLine(" {0}","Error bound is infinite");
              }
            }
            //
          }
        }
        else
        {
          Console.WriteLine("");
          Console.WriteLine(" {0}","n < 1.");
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      f08wp Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class F08WPE
  {
    static string datafile = "ExampleData/f08wpe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double abnorm,   abnrm,   bbnrm,   eps,   erbnd,   rcnd,   small,   tol; int i,  ihi,  ilo,  info,  j,  n;
        Console.WriteLine("f08wp Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        Complex[,] a = new Complex[n, n];
        Complex[] alpha = new Complex[n];
        Complex[,] b = new Complex[n, n];
        Complex[] beta = new Complex[n];
        Complex[,] dummy = new Complex[1, 1];
        Complex[,] vr = new Complex[n, n];
        double[] lscale = new double[n];
        double[] rconde = new double[n];
        double[] rcondv = new double[n];
        double[] rscale = new double[n];
        if (n > 1)
        {
          //
          //         Read in the matrices A and B
          //
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            for (j = 1 ; j <= n ; j++)
            {
              a[i - 1 , j - 1] = Complex.Parse(sr.Next());
            }
          }
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            for (j = 1 ; j <= n ; j++)
            {
              b[i - 1 , j - 1] = Complex.Parse(sr.Next());
            }
          }
          //
          //         Solve the generalized eigenvalue problem
          //
          F08.f08wp("Balance", "No vectors (left)", "Vectors (right)",
          "Both reciprocal condition numbers", n, a, b, alpha, beta, dummy, vr, out ilo, out ihi, lscale, rscale, out abnrm, out bbnrm,
          rconde, rcondv, out info);
          //
          if (info > 0)
          {
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,4}","Failure in ZGGEVX. INFO =",info);
          }
          else
          {
            //
            //            Compute the machine precision, the safe range parameter
            //            small and sqrt(abnrm**2+bbnrm**2)
            //
            eps = X02.x02aj();
            small = X02.x02am();
            abnorm = F06.f06bn(abnrm, bbnrm);
            tol = eps * abnorm;
            //
            //            Print out eigenvalues and vectors and associated condition
            //            number and bounds
            //
            for (j = 1 ; j <= n ; j++)
            {
              //
              //               Print out information on the jth eigenvalue
              //
              Console.WriteLine("");
              if (((Complex.Abs(alpha[j - 1])) * small) >= (Complex.Abs(beta[j - 1])))
              {
                Console.WriteLine("  {0}{1,2}{2}{3}\n  {4}{5,2}{6}({7,11:e4},{8,11:e4}){9}{10,2}{11}(","Eigenvalue(",j,")"," is numerically infinite or undetermined","ALPHA(",j,") = ",alpha[j - 1],", BETA(",j,") = ",beta[j - 1]);
              }
              else
              {
                Console.WriteLine("  {0}{1,2}{2}{3,11:e4}","Eigenvalue(",j,") = ",alpha[j - 1] / beta[j - 1]);
              }
              rcnd = rconde[j - 1];
              Console.WriteLine("");
              Console.WriteLine("  {0}{1,8:e1}","Reciprocal condition number = ",rcnd);
              if (rcnd > 0.00e0)
              {
                erbnd = tol / rcnd;
                Console.WriteLine("  {0}{1,8:e1}","Error bound                 = ",erbnd);
              }
              else
              {
                Console.WriteLine(" {0}","Error bound is infinite");
              }
              //
              //               Print out information on the jth eigenvector
              //
              Console.WriteLine("");
              Console.Write(" {0}",  "Eigenvector(");
              Console.Write(" {0}",  j);
              Console.WriteLine(" {0}",  ")");
              for (i = 1 ; i <= n ; i++)
              {
                Console.Write("{0, 11:e4}{1}", vr[i - 1 , j - 1], i%3==0?"\n":"");
              }
              Console.WriteLine();
              rcnd = rcondv[j - 1];
              Console.WriteLine("");
              Console.WriteLine("  {0}{1,8:e1}","Reciprocal condition number = ",rcnd);
              if (rcnd > 0.00e0)
              {
                erbnd = tol / rcnd;
                Console.WriteLine("  {0}{1,8:e1}","Error bound                 = ",erbnd);
              }
              else
              {
                Console.WriteLine(" {0}","Error bound is infinite");
              }
            }
            //
          }
        }
        else
        {
          Console.WriteLine("");
          Console.WriteLine(" {0}","n < 1.");
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g01aa Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01AAE
  {
    static string datafile = "ExampleData/g01aae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double s2,  s3,  s4,  wtsum,  xmax,  xmean,  xmin;
        int i,  iwt,  j,  n,  nprob;
        int ifail;
        Console.WriteLine("g01aa Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        nprob = int.Parse(sr.Next());
        for (j = 1; j <= nprob; j++)
        {
          sr.Reset();
          n = int.Parse(sr.Next());
          iwt = int.Parse(sr.Next());
          if (n > 0 )
          {
            double[] wt = new double[n];
            double[] wtin = new double[n];
            double[] x = new double[n];
            sr.Reset();
            for (i = 1; i <= n; i++)
            {
              x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            if (iwt == 1)
            {
              sr.Reset();
              for (i = 1; i <= n; i++)
              {
                wtin[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              F06.f06ef(n, wtin, 1, wt, 1, out ifail);
            }
            //
            G01.g01aa(n, x, ref iwt, wt, out xmean, out s2, out s3, out s4, out xmin, out xmax,
            out wtsum, out  ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("");
              Console.WriteLine("  {0}{1,5}", "Problem ", j);
              Console.WriteLine("  {0}{1,5}", "Number of cases ", n);
              Console.WriteLine(" {0}", "Data as input -");
              for (i = 1; i <= n; i++)
              {
                Console.Write(" {0, 12:f1}{1}", x[i - 1], i%5==0?"\n":"");
              }
              Console.WriteLine("");
              if (iwt == 1)
              {
                Console.WriteLine(" {0}", "Weights as input -");
                for (i = 1; i <= n; i++)
                {
                  Console.Write(" {0, 12:f1}{1}", wtin[i - 1], i%5==0?"\n":"");
                }
                Console.WriteLine("");
              }
              Console.WriteLine("");
            }
            if (ifail == 0)
            {
              Console.WriteLine(" {0}", "Successful call of g01aa");
              Console.WriteLine("  {0}{1,5}", "No. of valid cases    ", iwt);
              Console.WriteLine("  {0}{1,13:f1}", "Mean          ", xmean);
              Console.WriteLine("  {0}{1,13:f1}", "Std devn      ", s2);
              Console.WriteLine("  {0}{1,13:f1}", "Skewness      ", s3);
              Console.WriteLine("  {0}{1,13:f1}", "Kurtosis      ", s4);
              Console.WriteLine("  {0}{1,13:f1}", "Minimum       ", xmin);
              Console.WriteLine("  {0}{1,13:f1}", "Maximum       ", xmax);
              Console.WriteLine("  {0}{1,13:f1}", "Sum of weights", wtsum);
            }
            else if (ifail > 0)
            {
              Console.WriteLine(" {0}", "Unsuccessful call of g01aa");
              Console.WriteLine("  {0}{1,5}", "ifail =", ifail);
              if (ifail == 2)
              {
                Console.WriteLine("  {0}{1,5}", "No. of valid cases", iwt);
                Console.WriteLine("  {0}{1,13:f1}", "Mean          ", xmean);
                Console.WriteLine("  {0}{1,13:f1}", "Minimum       ", xmin);
                Console.WriteLine("  {0}{1,13:f1}", "Maximum       ", xmax);
                Console.WriteLine("  {0}{1,13:f1}", "Sum of weights", wtsum);
                Console.WriteLine(" {0}", "Std devn and coeffts of skewness");
                Console.WriteLine(" {0}", "and kurtosis not defined");
              }
            }
            else
            {
              Console.WriteLine("** g01aa failed with ifail = {0,5}", ifail);
              goto L40;
            }
          }
          else
          {
            goto L40;
          }
        }
        L40: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g01ad Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01ADE
  {
    static string datafile = "ExampleData/g01ade.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double s2,  s3,  s4,  xmean; int i, j, k, kmin1, n, nprob;
        int ifail;
        Console.WriteLine("g01ad Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        nprob = int.Parse(sr.Next());
        for (j = 1; j <= nprob; j++)
        {
          sr.Reset();
          kmin1 = int.Parse(sr.Next());
          k = kmin1 + 1;
          double[] x = new double[k];
          int[] ifreq = new int[k];
          if (k >= 2)
          {
            sr.Reset();
            for (i = 1; i <= kmin1; i++)
            {
              x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              ifreq[i - 1] = int.Parse(sr.Next());
            }
            x[k - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,4}", "Problem ", j);
            Console.WriteLine("  {0}{1,4}", "Number of classes ", kmin1);
            //
            G01.g01ad(k, x, ifreq, out xmean, out s2, out s3, out s4, out n, out  ifail);
            //
            if (ifail == 0)
            {
              Console.WriteLine("");
              Console.WriteLine(" {0}", "Successful call of g01ad");
              Console.WriteLine("");
              Console.WriteLine(" {0}", "          Class          Frequency");
              Console.WriteLine("");
              Console.WriteLine("");
              for (i = 1; i <= kmin1; i++)
              {
                Console.WriteLine(" \t{0,2:f2}\t{1,5:f2}\t\t{2}", x[i - 1], x[i + 1 - 1], ifreq[i - 1]);
              }
              Console.WriteLine("");
              Console.WriteLine("  {0}{1,16:f4}", " \tMean \t\t", xmean);
              Console.WriteLine("  {0}{1,13:f4}", " \tStd devn\t\t", s2);
              Console.WriteLine("  {0}{1,13:f4}", " \tSkewness\t\t", s3);
              Console.WriteLine("  {0}{1,13:f4}", " \tKurtosis\t\t", s4);
              Console.WriteLine("  {0}{1,8}", " \tNumber of cases\t\t", n);
            }
            else
            {
              Console.WriteLine("** g01ad failed with ifail = {0,5}", ifail);
            }
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g01ae Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01AEE
  {
    static string datafile = "ExampleData/g01aee.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double xmax,  xmin; int i, iclass, j, k, n, nprob;
        int ifail;
        Console.WriteLine("g01ae Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        nprob = int.Parse(sr.Next());
        for (i = 1; i <= nprob; i++)
        {
          sr.Reset();
          n = int.Parse(sr.Next());
          iclass = int.Parse(sr.Next());
          k = int.Parse(sr.Next());
          double[] cb = new double[k+2];
          double[] x = new double[n];
          int[] ifreq = new int[k+2];
          if ( n >= 1 && k >= 2)
          {
            sr.Reset();
            for (j = 1; j <= n; j++)
            {
              x[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,4}", "Problem ", i);
            Console.WriteLine("  {0}{1,4}", "Number of cases", n);
            Console.WriteLine("  {0}{1,4}", "Number of classes", k);
            k++;
            if (iclass != 1)
            {
              Console.WriteLine(" {0}", "Routine-supplied class boundaries");
            }
            else
            {
              sr.Reset();
              for (j = 1; j <= k; j++)
              {
                cb[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              Console.WriteLine(" {0}", "User-supplied class boundaries");
            }
            k = k + 1;
            //
            G01.g01ae(n, k, x, iclass, cb, ifreq, out xmin, out xmax, out  ifail);
            //
            Console.WriteLine("");
            if (ifail == 0)
            {
              Console.WriteLine(" {0}", "Successful call of g01ae");
              Console.WriteLine("");
              Console.WriteLine(" {0}", "*** Frequency  distribution ***");
              Console.WriteLine("");
              Console.WriteLine(" {0}", "       Class            Frequency");
              Console.WriteLine("");
              Console.WriteLine("  {0}{1,8:f2}{2,9}", "   \t Up to    ", cb[0], ifreq[0]);
              k = k - 1;
              if (k > 1)
              {
                for (j = 2; j <= k; j++)
                {
                  Console.WriteLine("\t {0,2:f2}{1,2:f2}{2,2:f2}\t {3,5}", cb[j - 1 - 1], " to    ", cb[j - 1], ifreq[j - 1]);
                }
                Console.WriteLine("");
              }
              Console.WriteLine("     {0,8:f2}{1}{2,6}", cb[k - 1], "    and over  ", ifreq[k + 1 - 1]);
              Console.WriteLine("");
              Console.WriteLine("  {0}{1,6}", "Total frequency = ", n);
              Console.WriteLine("  {0}{1,9:f2}", "Minimum = ", xmin);
              Console.WriteLine("  {0}{1,9:f2}", "Maximum = ", xmax);
            }
            else
            {
              Console.WriteLine("** g01ae failed with ifail = {0,5}", ifail);
            }
          }
          //
        }
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01ae Example Program Results

  Problem    1
  Number of cases  70
  Number of classes   5
 Routine-supplied class boundaries

 Successful call of g01ae

 *** Frequency  distribution ***

        Class            Frequency

          Up to       20.70        0
     20.70 to    21.28	     6
     21.28 to    21.86	    16
     21.86 to    22.44	    21
     22.44 to    23.02	    14
     23.02 to    23.60	    13

        23.60    and over       0

  Total frequency =     70
  Minimum =     20.70
  Maximum =     23.60


//      g01af Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01AFE
  {
    static string datafile = "ExampleData/g01afe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double chis = 0.0;
        int i,  j,  k,  m,  m1,  m2,  n,  n1,  n2,  ndf,  npos,  nprob,  num; double[] p = new double[21];
        int ifail;
        Console.WriteLine("g01af Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        nprob = int.Parse(sr.Next());
        for (i = 1; i <= nprob; i++)
        {
          sr.Reset();
          m = int.Parse(sr.Next());
          n = int.Parse(sr.Next());
          double[,] pred = new double[m+1, n+1];
          int[,] nobs = new int[m+1, n+1];
          num = int.Parse(sr.Next());
          if (m >= 1 && n >= 1)
          {
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,4}", "Problem ", i);
            for (j = 1; j <= m; j++)
            {
              sr.Reset();
              for (k = 1; k <= n; k++)
              {
                nobs[j - 1, k - 1] = int.Parse(sr.Next());
              }
            }
            Console.WriteLine(" {0}", "Data as input -");
            Console.WriteLine("  {0}{1,3}", "Number of rows", m);
            Console.WriteLine("  {0}{1,3}", "Number of columns", n);
            Console.WriteLine("  {0}{1,3}{2}", "NUM =", num, " (NUM = 1 means table reduced in size if necessary)");
            m = m + 1;
            n = n + 1;
            //
            G01.g01af(m, n, nobs, ref num, pred, out chis, p, out npos, out ndf, out m1, out n1,
            out  ifail);
            //
            if (ifail == 0)
            {
              Console.WriteLine("");
              if (num == 0)
              {
                Console.WriteLine(" {0}", "Successful call of g01af");
                m2 = m - 1;
                n2 = n - 1;
                if (m1 != m2)
                {
                  Console.WriteLine("  {0}{1,3}{2}{3,3}", "No. of rows reduced from ", m2, " to ", m1);
                }
                if (n1 != n2)
                {
                  Console.WriteLine("  {0}{1,3}{2}{3,3}", "No. of cols reduced from ", n2, " to ", n1);
                }
                Console.WriteLine("");
                Console.WriteLine(" {0}", "Table of observed and expected frequencies");
                Console.WriteLine("");
                Console.WriteLine(" {0}", "              Column");
                Console.Write("{0, 10}", "");
                for (k = 1; k <= n1; k++)
                {
                  Console.Write(" {0,4}", k);
                }
                Console.WriteLine("");
                Console.WriteLine(" {0}", "Row");
                for (j = 1; j <= m1; j++)
                {
                  Console.Write(" {0, 2}\t", j);
                  for (k = 1; k <= n1; k++)
                  {
                    Console.Write("{0,6}", nobs[j - 1, k - 1]);
                  }
                  Console.Write("\n\t");
                  for (k = 1; k <= n1; k++)
                  {
                    Console.Write("{0,6:f0}", pred[j - 1, k - 1]);
                  }
                  Console.WriteLine("");
                  Console.WriteLine("{0, 58}{1,7}", "Row total = ", nobs[j - 1, n - 1]);
                }
                Console.WriteLine(" {0}", "Column");
                Console.Write(" {0}", "totals");
                for (k = 1; k <= n1; k++)
                {
                  Console.Write("   {0, 6}", nobs[m - 1, k - 1]);
                }
                Console.WriteLine("");
                Console.WriteLine("{0, 60}{1,7}", "Grand total = ", nobs[m - 1, n - 1]);
                Console.WriteLine("");
                Console.WriteLine("  {0}{1,10:f3}{2}{3,3}", "Chi-squared = ", chis, "   D.F. = ", ndf);
              }
              else
              {
                Console.WriteLine("");
                Console.WriteLine(" {0}", "Fisher's exact test for 2*2 table");
                Console.WriteLine("");
                Console.WriteLine(" {0}", "Table of observed frequencies");
                Console.WriteLine("");
                Console.WriteLine(" {0}", "          Column");
                Console.WriteLine(" {0}", "          1    2");
                Console.WriteLine(" {0}", "Row");
                for (j = 1; j <= 2; j++)
                {
                  Console.WriteLine(" {0}", j);
                  for (k = 1; k <= 2; k++)
                  {
                    Console.Write(" {0}", nobs[j - 1, k - 1]);
                  }
                  Console.WriteLine("");
                  Console.WriteLine("                                                                                                  {0}{1,7}", "Row total = ", nobs[j - 1, n - 1]);
                }
                Console.WriteLine("");
                Console.WriteLine(" {0}", "Column");
                Console.WriteLine(" {0}", "totals");
                for (k = 1; k <= 2; k++)
                {
                  Console.Write(" {0}", nobs[m - 1, k - 1]);
                }
                Console.WriteLine("");
                Console.WriteLine("                                                                                                  {0}{1,7}", "Grand total = ", nobs[m - 1, n - 1]);
                Console.WriteLine("");
                Console.WriteLine("  {0}{1,4}{2}", "This table corresponds to element ", npos, " in vector P below");
                Console.WriteLine("");
                Console.WriteLine(" {0}", "Vector P");
                Console.WriteLine("");
                Console.WriteLine(" {0}", " I   P(I)");
                for (j = 1; j <= num; j++)
                {
                  Console.Write(" {0}", j, p[j - 1]);
                }
                Console.WriteLine("");
              }
            }
            else
            {
              Console.WriteLine("** g01af failed with ifail = {0,5}", ifail);
            }
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01af Example Program Data
   1
   2   3   0
    86    51    13
   130   115    41


g01af Example Program Results

  Problem    1
 Data as input -
  Number of rows  2
  Number of columns  3
  NUM =  0 (NUM = 1 means table reduced in size if necessary)

 Successful call of g01af

 Table of observed and expected frequencies

               Column
              1    2    3
 Row
  1	    86    51    13
        74    57    19
                                              Row total =     150
  2	   130   115    41
       142   109    35
                                              Row total =     286
 Column
 totals      216      166       54
                                              Grand total =     436

  Chi-squared =      6.352   D.F. =   2


//      g01al Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01ALE
  {
    static string datafile = "ExampleData/g01ale.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,  n; double[] res = new double[5];
        int ifail;
        Console.WriteLine("g01al Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        double[] x = new double[n];
        for (i = 1; i <= n; i++)
        {
          x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        //
        G01.g01al(n, x, res, out  ifail);
        //
        if (ifail == 0)
        {
          //
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,16:f4}", "Maximum     ", res[4]);
          Console.WriteLine("  {0}{1,16:f4}", "Upper Hinge ", res[3]);
          Console.WriteLine("  {0}{1,16:f4}", "Median      ", res[2]);
          Console.WriteLine("  {0}{1,16:f4}", "Lower Hinge ", res[1]);
          Console.WriteLine("  {0}{1,16:f4}", "Minimum     ", res[0]);
        }
        else
        {
          Console.WriteLine("");
          Console.WriteLine("** g01al failed with ifail = {0,5}", ifail);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01al Example Program Results

  Maximum              12.0000
  Upper Hinge           9.5000
  Median                6.5000
  Lower Hinge           2.5000
  Minimum               1.0000


//      g01am Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01AME
  {
    static string datafile = "ExampleData/g01ame.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,  n,  nq; int ifail;
        Console.WriteLine("g01am Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        //      Read in problem size and check array sizes
        sr.Reset();
        n = int.Parse(sr.Next());
        nq = int.Parse(sr.Next());
        if (n < 1 || nq < 1)
        {
          Console.WriteLine("   ** Problem size is too small.");
          return;
        }
        //      Read in rest of the data
        double[] q = new double[nq];
        double[] qv = new double[nq];
        double[] rv = new double[n];
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          rv[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        sr.Reset();
        for (i = 1; i <= nq; i++)
        {
          q[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        //      Display the data
        Console.WriteLine("");
        Console.WriteLine(" {0}", "Data Values:");
        Console.WriteLine("");
        for (i = 1; i <= n; i++)
        {
          Console.Write(" {0,4:f2}", rv[i - 1]);
        }
        Console.WriteLine("");
        //      Call NAG method
        G01.g01am(n, rv, nq, q, qv, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g01am failed with ifail = {0,5}", ifail);
          return;
        }
        //      Display the results
        Console.WriteLine("");
        Console.WriteLine(" {0}", "Quantile     \tResult");
        Console.WriteLine("");
        for (i = 1; i <= nq; i++)
        {
          Console.WriteLine("  {0,7:f2}        {1,7:f2}", q[i - 1], qv[i - 1]);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01am Example Program Data
11 3                                        : N and NQ
4.9 7.0 3.9 9.5 1.3 3.1 9.7 0.3 8.5 0.6 6.2 : The N data values
0.25 0.5 1.0                                : The NQ required quantiles


//      g01bj Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01BJE
  {
    static string datafile = "ExampleData/g01bje.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double p,   peqk,   pgtk,    plek;  int k,  n;  int ifail;
        Console.WriteLine("g01bj Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "   N     P      K     PLEK      PGTK      PEQK");
        Console.WriteLine("");
        L20: ;
        try
        {
          sr.Reset();
          n = int.Parse(sr.Next());
          p = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          k = int.Parse(sr.Next());
        }
        catch
        {
          goto L40;
        }
        //
        G01.g01bj(n, p, k, out plek, out pgtk, out peqk, out  ifail);
        //
        if (ifail == 0)
        {
          //
          Console.WriteLine("  {0,4}{1,8:f3}{2,5}{3,10:f5}{4,10:f5}{5,10:f5}", n, p, k, plek, pgtk, peqk);
          goto L20;
        }
        else
        {
          Console.WriteLine("** g01bj failed with ifail = {0,5}", ifail);
        }
        L40: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g01bk Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01BKE
  {
    static string datafile = "ExampleData/g01bke.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double peqk,  pgtk,   plek,   rlamda;  int k;
        int ifail;
        bool carryon = true;
        Console.WriteLine("g01bk Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "    RLAMDA     K     PLEK      PGTK      PEQK");
        Console.WriteLine("");
        while (carryon)
        {
          try
          {
            sr.Reset();
            rlamda = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            k = int.Parse(sr.Next());
          }
          catch
          {
            break;
          }
          //
          G01.g01bk(rlamda, k, out plek, out pgtk, out peqk, out  ifail);
          //
          if (ifail >= 0)
          {
            //
            Console.WriteLine("  {0,10:f3}{1,6}{2,10:f5}{3,10:f5}{4,10:f5}", rlamda, k, plek, pgtk, peqk);
          }
          else
          {
            Console.WriteLine("** g01bk failed with ifail = {0,5}", ifail);
            break;
          }
          }        //
        }
        catch (Exception e)
        {
          Console.WriteLine(e.Message);
          Console.WriteLine( "Exception Raised");
        }
      }
    }
  }


//      g01bl Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01BLE
  {
    static string datafile = "ExampleData/g01ble.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double peqk,  pgtk,   plek;  int k, l,  m,  n;
        int ifail;
        bool carryon = true;
        Console.WriteLine("g01bl Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "   N   L   M   K     PLEK      PGTK      PEQK");
        Console.WriteLine("");
        while (carryon)
        {
          try
          {
            sr.Reset();
            n = int.Parse(sr.Next());
            l = int.Parse(sr.Next());
            m = int.Parse(sr.Next());
            k = int.Parse(sr.Next());
          }
          catch
          {
            break;
          }
          //
          G01.g01bl(n, l, m, k, out plek, out pgtk, out peqk, out  ifail);
          //
          if (ifail >= 0)
          {
            //
            Console.WriteLine("  {0,4}{1,4}{2,4}{3,4}{4,10:f5}{5,10:f5}{6,10:f5}", n, l, m, k, plek, pgtk, peqk);
          }
          else
          {
            Console.WriteLine("** g01bl failed with ifail = {0,5}", ifail);
            break;
          }
        }
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g01da Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01DAE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int n = 15;
        double errest,  etol; int i, j;
        double[] pp = new double[n];
        int ifail;
        Console.WriteLine("g01da Example Program Results");
        etol = 0.0010e0;
        for (j = 5; j <= n; j += 5)
        {
          //
          G01.g01da(j, pp, etol, out errest, out  ifail);
          //
          if (ifail < 0)
          {
            Console.WriteLine("");
            Console.WriteLine("** g01da failed with ifail = {0,5}", ifail);
            break;
          }
          else
          {
            //
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,2}", "Set size = ", j);
            Console.WriteLine("  {0}{1,13:e3}", "Error tolerance (input) = ", etol);
            Console.WriteLine("  {0}{1,13:e3}", "Error estimate (output) = ", errest);
            Console.WriteLine(" {0}", "Normal scores");
            Console.WriteLine("\t" + "");
            for (i = 1; i <= j; i++)
            {
              Console.Write(" {0,7:f3}{1}", pp[i - 1],i%5==0?"\n\t":"");
            }
            Console.WriteLine("");
            if (ifail != 0)
            {
              Console.WriteLine("  {0}{1,5}", "g01da fails with ifail = ", ifail);
            }
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01da Example Program Data


//      g01db Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01DBE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        int i;
        const int n = 10;
        double[] pp = new double[n];
        int ifail;
        Console.WriteLine("g01db Example Program Results");
        //
        G01.g01db(n, pp, out  ifail);
        //
        if (ifail != 0)
        {
          Console.WriteLine("");
          Console.WriteLine("** g01db failed with ifail = {0,5}", ifail);
        }
        else
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,2}", "Sample size = ", n);
          Console.WriteLine(" {0}", "Normal scores");
          for (i = 1; i <= n; i++)
          {
            Console.Write(" {0,8:f4}{1}", pp[i - 1],i%5==0?"\n":"");
          }
          Console.WriteLine("");
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01db Example Program Data


//      g01dc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01DCE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int n = 6;
        double errest,  etol,   exp1,   exp2,   sumssq;  int i, j,  k;
        double[] pp = new double[n];
        double[] vec = new double[n*(n+1)/2];
        int ifail;
        Console.WriteLine("g01dc Example Program Results");
        etol = 0.00010e0;
        //
        G01.g01da(n, pp, etol, out errest, out  ifail);
        //
        if (ifail == 0)
        {
          exp1 = pp[n - 1];
          exp2 = pp[n - 2];
          sumssq = 0.00e0;
          for (i = 1; i <= n; i++)
          {
            sumssq = sumssq + pp[i - 1] * pp[i - 1];
          }
          //
          G01.g01dc(n, exp1, exp2, sumssq, vec, out  ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,2}", "Sample size = ", n);
            Console.WriteLine(" {0}", "Variance-covariance matrix");
            k = 1;
            for (j = 1; j <= n; j++)
            {
              for (i = k; i <= k + j - 1; i++)
              {
                Console.Write(" {0,5:f4}", vec[i - 1]);
              }
              Console.WriteLine("");
              k = k + j;
            }
          }
          else
          {
            Console.WriteLine("");
            Console.WriteLine("** g01dc failed with ifail = {0,5}", ifail);
          }
        }
        else
        {
          Console.WriteLine("");
          Console.WriteLine("** g01da failed with ifail = {0,5}", ifail);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01dc Example Program Data


//      g01dd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01DDE
  {
    static string datafile = "ExampleData/g01dde.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double pw,  w;  int i, j,  n;
        bool calwts = false;
        int ifail;
        Console.WriteLine("g01dd Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        calwts = true;
        sr.Reset();
        n = int.Parse(sr.Next());
        double[] a = new double[n];
        double[] x = new double[n];
        if (n > 0 )
        {
          for (j = 1; j <= 2; j++)
          {
            sr.Reset();
            for (i = 1; i <= n; i++)
            {
              x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            Array.Sort(x);
            //
            G01.g01dd(x, n, calwts, a, out w, out pw, out  ifail);
            //
            if (ifail != 0)
            {
              Console.WriteLine("");
              Console.WriteLine("** g01dd failed with ifail = {0,5}", ifail);
              return;
            }
            //
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,1}{2}{3,7:f4}", "For sample number ", j, ", value of W statistic = ", w);
            Console.WriteLine("  {0}{1,8:f4}", "                     Significance level is ", pw);
            calwts = false;
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01dd Example Program Results

  For sample number 1, value of W statistic =  0.9005
                       Significance level is   0.0421

  For sample number 2, value of W statistic =  0.9590
                       Significance level is   0.5246


//      g01dh Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01DHE
  {
    static string datafile = "ExampleData/g01dhe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,  n;  int ifail;
        Console.WriteLine("g01dh Example Program Results");
        Console.WriteLine("");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        double[] r = new double[n];
        double[] x = new double[n];
        if (n >= 1)
        {
          sr.Reset();
          for (i = 1; i <= n; i++)
          {
            x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //
          G01.g01dh("Savage", "Average", n, x, r, out  ifail);
          //
          if (ifail == 0)
          {
            //
            Console.WriteLine(" {0}", "The Savage Scores : ");
            Console.WriteLine(" {0}", "  (Average scores are used for tied observations)");
            for (i = 1; i <= n; i++)
            {
              Console.WriteLine(" {0,5:f4}", r[i - 1]);
            }
            Console.WriteLine("");
          }
          else
          {
            Console.WriteLine("");
            Console.WriteLine("** g01dh failed with ifail = {0,5}", ifail);
          }
        }
        else
        {
          Console.WriteLine(" {0}", "N is larger than NMAX");
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01dh Example Program Data
5
2 0 2 2 0


g01dh Example Program Results

 The Savage Scores :
   (Average scores are used for tied observations)
 1.4500
 0.3250
 1.4500
 1.4500
 0.3250


//      g01ea Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01EAE
  {
    static string datafile = "ExampleData/g01eae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double prob,   x;  int i; string tail;
        int ifail;
        Console.WriteLine("g01ea Example Program Results");
        Console.WriteLine("");
        //      Skip heading in data file
        sr.Reset();
        for (i = 1; i <= 4; i++)
        {
          sr.Reset();
          tail = sr.Next();
          x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          //
          prob = G01.g01ea(tail, x, out  ifail);
          //
          if (ifail == 0)
          {
            if (i == 1)
            {
              Console.WriteLine(" {0}", "   Tail        X              Probability ");
              Console.WriteLine("");
            }
            Console.WriteLine("      {0,1}        {1,4:f2}              {2,6:f4}", tail, x, prob);
          }
          else
          {
            Console.WriteLine("** g01ea failed with ifail = {0,5}", ifail);
            goto L40;
          }
        }
        L40: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01ea Example Program Results

    Tail        X              Probability

      L        1.96              0.9750
      U        1.96              0.0250
      C        1.96              0.9500
      S        1.96              0.0500


//      g01eb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01EBE
  {
    static string datafile = "ExampleData/g01ebe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double df,  prob,   t;  string tail;
        int ifail;
        bool carryon = true;
        Console.WriteLine("g01eb Example Program Results");
        //      Skip heading in data file
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     T      DF     PROB  TAIL");
        Console.WriteLine("");
        sr.Reset();
        while (carryon)
        {
          try
          {
            sr.Reset();
            t = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            df = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            tail = sr.Next();
          }
          catch
          {
            break;
          }
          //
          prob = G01.g01eb(tail, t, df, out  ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine("  {0,6:f3}{1,8:f3}{2,8:f4}    {3,1}", t, df, prob, tail);
          }
          else
          {
            Console.WriteLine("** g01eb failed with ifail = {0,5}", ifail);
            break;
          }
        }
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01eb Example Program Data
0.85  20.0  'L'    :T DF TAIL
0.85  20.0  'S'    :T DF TAIL
0.85  20.0  'C'    :T DF TAIL
0.85  20.0  'U'    :T DF TAIL


//      g01ec Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01ECE
  {
    static string datafile = "ExampleData/g01ece.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double df,  prob,   x;  int ifail;
        bool carryon = true;
        Console.WriteLine("g01ec Example Program Results");
        Console.WriteLine("");
        Console.WriteLine(" {0}", "   x       df    prob");
        Console.WriteLine("");
        //      Skip heading in data file
        sr.Reset();
        while (carryon)
        {
          try
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            df = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          catch
          {
            break;
          }
          //
          prob = G01.g01ec("Lower", x, df, out  ifail);
          //
          if (ifail >= 0)
          {
            //
            if (ifail == 0)
            {
              Console.WriteLine("  {0,6:f3}{1,8:f3}{2,8:f4}", x, df, prob);
            }
            else
            {
              Console.WriteLine("  {0,6:f3}{1,8:f3}{2,8:f4}{3}{4,1}", x, df, prob, " NOTE: ifail = ", ifail);
            }
            continue;
            //
          }
          else
          {
            Console.WriteLine("** g01ec failed with ifail = {0,5}", ifail);
            break;
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g01ed Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01EDE
  {
    static string datafile = "ExampleData/g01ede.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double df1,  df2,   f,   prob;  int ifail;
        bool carryon = true;
        Console.WriteLine("g01ed Example Program Results");
        Console.WriteLine("");
        Console.WriteLine(" {0}","   F      DF1     DF2    PROB");
        Console.WriteLine("");
        //      Skip heading in data file
        sr.Reset();
        while (carryon)
        {
          try
          {
            sr.Reset();
            f = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            df1 = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            df2 = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          catch
          {
            break;
          }
          //
          prob = G01.g01ed("Lower", f, df1, df2, out  ifail);
          //
          if (ifail >= 0)
          {
            if (ifail == 0)
            {
              Console.WriteLine("  {0,6:f3}{1,8:f3}{2,8:f3}{3,8:f4}",f,df1,df2,prob);
            }
            else
            {
              Console.WriteLine("  {0,6:f3}{1,8:f3}{2,8:f3}{3,8:f4}{4}{5,1}",f,df1,df2,prob," NOTE: ifail = ",ifail);
            }
            continue;
          }
          else
          {
            Console.WriteLine("** g01ed failed with ifail = {0,5}", ifail);
            break;
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g01ee Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01EEE
  {
    static string datafile = "ExampleData/g01eee.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double a,   b,    p,    pdf,    q,    tol,    x;  int ifail; bool carryon = true;
        Console.WriteLine("g01ee Example Program Results");
        Console.WriteLine("");
        Console.WriteLine(" {0}", "    x           a          b          p          q         pdf");
        Console.WriteLine("");
        //      Skip heading in data file
        sr.Reset();
        while (carryon)
        {
          try
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            a = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            b = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            tol = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          catch
          {
            break;
          }
          //
          G01.g01ee(x, a, b, tol, out p, out q, out pdf, out  ifail);
          //
          if (ifail >= 0)
          {
            if (ifail == 0)
            {
              Console.WriteLine("  {0,7:f4}    {1,7:f4}    {2,7:f4}    {3,7:f4}    {4,7:f4}    {5,7:f4}    ", x, a, b, p, q, pdf);
            }
            else
            {
              Console.WriteLine("  {0,7:f4}    {1,7:f4}    {2,7:f4}    {3,7:f4}    {4,7:f4}    {5,7:f4}    {6}{7,1}", x, a, b, p, q, pdf, " NOTE: ifail = ", ifail);
            }
            continue;
          }
          else
          {
            Console.WriteLine("** g01ee failed with ifail = {0,5}", ifail);
          }
          break;
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g01ef Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01EFE
  {
    static string datafile = "ExampleData/g01efe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double a,   b,    g,    p;  int ifail; bool carryon = true;
        Console.WriteLine("g01ef Example Program Results");
        Console.WriteLine("");
        Console.WriteLine(" {0}", "Gamma deviate    Alpha     Beta    Lower tail prob.");
        Console.WriteLine("");
        //      Skip heading in data file
        sr.Reset();
        while (carryon)
        {
          try
          {
            sr.Reset();
            g = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            a = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            b = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          catch
          {
            break;
          }
          //
          p = G01.g01ef("Lower", g, a, b, out  ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine("  {0,9:f2}{1,13:f2}{2,9:f2}{3,14:f4}", g, a, b, p);
            continue;
          }
          else
          {
            Console.WriteLine("** g01ef failed with ifail = {0,5}", ifail);
            break;
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g01em Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01EME
  {
    static string datafile = "ExampleData/g01eme.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double q,  v,   valp; int i,  ir;
        int ifail;
        Console.WriteLine("g01em Example Program Results");
        Console.WriteLine("");
        //      Skip heading in data file
        sr.Reset();
        for (i = 1; i <= 3; i++)
        {
          sr.Reset();
          q = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          v = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          ir = int.Parse(sr.Next());
          //
          valp = G01.g01em(q, v, ir, out  ifail);
          //
          if (ifail == 0)
          {
            if (i == 1)
            {
              Console.WriteLine(" {0}", "  Q          V     IR       Probability");
              Console.WriteLine("");
            }
            Console.WriteLine("  {0,7:f4}    {1,4:f1}  {2,3}  {3,10:f4}", q, v, ir, valp);
          }
          else
          {
            Console.WriteLine("** g01em failed with ifail = {0,5}", ifail);
            return;
          }
        }
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g01ep Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01EPE
  {
    static string datafile = "ExampleData/g01epe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double d,  pdl,   pdu;  int ip, n;
        int ifail;
        Console.WriteLine("g01ep Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        ip = int.Parse(sr.Next());
        d = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        //
        if (n > ip)
        {
          //
          G01.g01ep(n, ip, d, out pdl, out pdu, out ifail);
          //
          Console.WriteLine("");
          if (ifail == 0)
          {
            Console.WriteLine("  {0}{1,10:f4}", " Durbin-Watson statistic ", d);
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,10:f4}", " Probability for the lower bound = ", pdl);
            Console.WriteLine("  {0}{1,10:f4}", " Probability for the upper bound = ", pdu);
          }
          else
          {
            Console.WriteLine("** g01ep failed with ifail = {0,5}", ifail);
          }
        }
        else
        {
          Console.WriteLine(" {0}", " n <= ip.");
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01ep Example Program Data
 10 2 0.9238


g01ep Example Program Results

   Durbin-Watson statistic     0.9238

   Probability for the lower bound =     0.0610
   Probability for the upper bound =     0.0060


//      g01er Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01ERE
  {
    static string datafile = "ExampleData/g01ere.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double p,  t,   vk;  int i, n;
        int ifail;
        Console.WriteLine("g01er Example Program Results");
        Console.WriteLine("");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        for (i = 1; i <= n; i++)
        {
          sr.Reset();
          t = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          vk = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          p = G01.g01er(t, vk, out  ifail);
          //
          if (ifail != 0)
          {
            Console.WriteLine("");
            Console.WriteLine("** g01er failed with ifail = {0,5}", ifail);
            return;
          }
          else
          {
            Console.WriteLine(" P = {0,10:f4}", p);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g01et Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01ETE
  {
    static string datafile = "ExampleData/g01ete.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double x,  y;
        bool carryon = true;
        Console.WriteLine("g01et Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "  x          y");
        Console.WriteLine("");
        while (carryon)
        {
          try
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          catch
          {
            break;
          }
          //
          //         Compute the value of the Landau distribution function
          //
          y = G01.g01et(x);
          //
          Console.WriteLine("  {0,4:f1}      {1,12:e4}", x, y);
          continue;
          //
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01et Example Program Data
 0.5  : Value of X


g01et Example Program Results

   x          y

   0.5       3.7328e-001


//      g01eu Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01EUE
  {
    static string datafile = "ExampleData/g01eue.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        const int mode = 1;
        double beta2,  c1,   c2,   rkappa,   x,   xl,   xu,   y;
        double[] comm = new double[322];
        int ifail;
        bool carryon = true;
        Console.WriteLine("g01eu Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        c1 = -X02.x02al();
        c2 = -X02.x02al();
        while (carryon)
        {
          try
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            rkappa = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            beta2 = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          catch
          {
            break;
          }
          if (rkappa != c1 || beta2 != c2)
          {
            //
            //         Initialise array comm before the call to g01eu
            //
            //
            G01.g01zu(rkappa, beta2, mode, out xl, out xu, comm, out  ifail);
            //
            Console.WriteLine("");
            if (ifail == 0)
            {
              Console.WriteLine("     {0,2}          {1,6}        {2,5}           {3,1}        {4,5}\n", "x", "rkappa", "beta2", "y", "ifail");
            }
            else
            {
              Console.WriteLine("** g01zu failed with ifail = {0,5}", ifail);
              break;
            }
            //
          }
          //
          //      Compute the value of the Vavilov distribution function
          //
          //
          y = G01.g01eu(x, comm, out  ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine("   {0,4:f1}          {1,4:f1}          {2,4:f1}      {3,12:e4}     {4,2}", x, rkappa, beta2, y, ifail);
            c1 = (double)rkappa;
            c2 = (double)beta2;
            continue;
          }
          else
          {
            Console.WriteLine("");
            Console.WriteLine("** g01eu failed with ifail = {0,5}", ifail);
            break;
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01eu Example Program Data
 0.1  2.5  0.7 : Values of X, RKAPPA and BETA2


g01eu Example Program Results

      x          rkappa        beta2           y        ifail

    0.1           2.5           0.7       9.9982e-001      0


//      g01ey Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01EYE
  {
    static string datafile = "ExampleData/g01eye.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double d,  prob;   int n;
        int ifail;
        bool carryon = true;
        Console.WriteLine("g01ey Example Program Results");
        Console.WriteLine("");
        Console.WriteLine(" {0}", "    D          N            One-sided probability");
        Console.WriteLine("");
        //      Skip heading in data file
        sr.Reset();
        while (carryon)
        {
          try
          {
            sr.Reset();
            n = int.Parse(sr.Next());
            d = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          catch
          {
            break;
          }
          //
          prob = G01.g01ey(n, d, out  ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine("  {0,7:f4}    {1,4}                    {2,7:f4}", d, n, prob);
            continue;
          }
          else
          {
            Console.WriteLine("** g01ey failed with ifail = {0,5}", ifail);
            break;
          }
          //
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g01ez Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01EZE
  {
    static string datafile = "ExampleData/g01eze.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double d,  prob;  int n1, n2;
        int ifail;
        bool carryon = true;
        Console.WriteLine("g01ez Example Program Results");
        Console.WriteLine("");
        Console.WriteLine(" {0}", "    D          N1      N2                Two-sided probability");
        Console.WriteLine("");
        //      Skip heading in data file
        sr.Reset();
        while (carryon)
        {
          try
          {
            sr.Reset();
            n1 = int.Parse(sr.Next());
            n2 = int.Parse(sr.Next());
            d = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          catch
          {
            break;
          }
          //
          prob = G01.g01ez(n1, n2, d, out  ifail);
          //
          if (ifail >= 0)
          {
            if (ifail == 0)
            {
              Console.WriteLine("  {0,7:f4}    {1,4}    {2,4}                    {3,7:f4}",
              d, n1, n2, prob);
            }
            else
            {
              Console.WriteLine("  {0,7:f4}    {1,4}    {2,4}                    {3,7:f4}{4}{5,2}",
              d, n1, n2, prob, " ifail = ", ifail);
            }
            continue;
          }
          else
          {
            Console.WriteLine("** g01ez failed with ifail = {0,5}", ifail);
            break;
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g01fa Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01FAE
  {
    static string datafile = "ExampleData/g01fae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double dev,   p;  int i; string tail;
        int ifail;
        Console.WriteLine("g01fa Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", " Tail                  Probability             Deviate ");
        Console.WriteLine("");
        for (i = 1; i <= 4; i++)
        {
          sr.Reset();
          tail = sr.Next();
          p = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          //
          dev = G01.g01fa(tail, p, out  ifail);
          //
          if (ifail == 0)
          {
            //
            Console.WriteLine("      {0,1}                  {1,5:f3}                  {2,6:f4}", tail, p, dev);
            //
          }
          else
          {
            Console.WriteLine("** g01fa failed with ifail = {0,5}", ifail);
            break;
          }
        }
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01fa Example Program Results

  Tail                  Probability             Deviate

      L                  0.975                  1.9600
      U                  0.025                  1.9600
      C                  0.950                  1.9600
      S                  0.050                  1.9600


//      g01fb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01FBE
  {
    static string datafile = "ExampleData/g01fbe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double df,  p,   x;  string tail;
        int ifail;
        bool carryon = true;
        Console.WriteLine("g01fb Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "    P        DF      TAIL           X");
        Console.WriteLine("");
        while (carryon)
        {
          try
          {
            sr.Reset();
            p = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            df = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            tail = sr.Next();
          }
          catch
          {
            break;
          }
          //
          x = G01.g01fb(tail, p, df, out  ifail);
          //
          if (ifail >= 0)
          {
            if (ifail == 0)
            {
              Console.WriteLine("  {0,8:f3}{1,8:f3}      {2,1}      {3,8:f3}", p, df, tail, x);
            }
            else if (ifail > 0)
            {
              Console.WriteLine("  {0,8:f3}{1,8:f3}      {2,1}      {3,8:f3}{4}{5,1}", p, df, tail, x, " NOTE: ifail = ", ifail);
            }
            continue;
            //
          }
          else
          {
            Console.WriteLine("** g01fb failed with ifail = {0,5}", ifail);
            break;
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01fb Example Program Data
0.0100  20.0  'S'         :P DF TAIL
0.01     7.5  'L'         :P DF TAIL
0.99    45.0  'C'         :P DF TAIL


//      g01fc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01FCE
  {
    static string datafile = "ExampleData/g01fce.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double df,  p,  x; int ifail;
        bool carryon = true;
        Console.WriteLine("g01fc Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     P       DF      X");
        Console.WriteLine("");
        while (carryon)
        {
          try
          {
            sr.Reset();
            p = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            df = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          catch
          {
            break;
          }
          //
          x = G01.g01fc(p, df, out  ifail);
          //
          if (ifail >= 0)
          {
            if (ifail == 0)
            {
              Console.WriteLine("  {0,8:f3}{1,8:f3}{2,8:f3}", p, df, x);
            }
            else if (ifail > 0)
            {
              Console.WriteLine("  {0,8:f3}{1,8:f3}{2,8:f3}{3}{4,1}", p, df, x, " NOTE: ifail = ", ifail);
            }
            continue;
          }
          else
          {
            Console.WriteLine("** g01fc failed with ifail = {0,5}", ifail);
            break;
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g01fd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01FDE
  {
    static string datafile = "ExampleData/g01fde.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double df1,  df2,  f,   p;  int ifail;
        bool carryon = true;
        Console.WriteLine("g01fd Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}","     P      DF1     DF2      F");
        Console.WriteLine("");
        while (carryon)
        {
          try
          {
            sr.Reset();
            p = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            df1 = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            df2 = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          catch
          {
            break;
          }
          //
          f = G01.g01fd(p, df1, df2, out  ifail);
          //
          if (ifail >= 0)
          {
            if (ifail == 0)
            {
              Console.WriteLine("  {0,8:f3}{1,8:f3}{2,8:f3}{3,8:f3}",p,df1,df2,f);
            }
            else if (ifail > 0)
            {
              Console.WriteLine("  {0,8:f3}{1,8:f3}{2,8:f3}{3,8:f3}{4}{5,1}",p,df1,df2,f," NOTE: ifail = ",ifail);
            }
            continue;
          }
          else
          {
            Console.WriteLine("** g01fd failed with ifail = {0,5}", ifail);
            break;
          }
        }
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g01fe Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01FEE
  {
    static string datafile = "ExampleData/g01fee.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double a,   b,    p,    tol,    x;  int ifail; bool carryon = true;
        Console.WriteLine("g01fe Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}"," Probability     A         B     Deviate");
        Console.WriteLine("");
        while (carryon)
        {
          try
          {
            sr.Reset();
            p = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            a = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            b = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          catch
          {
            break;
          }
          tol = 0.00e0;
          //
          x = G01.g01fe(p, a, b, tol, out  ifail);
          //
          if (ifail >= 0)
          {
            if (ifail == 0)
            {
              Console.WriteLine("  {0,9:f4}{1,10:f3}{2,10:f3}{3,10:f4}",p,a,b,x);
            }
            else if (ifail > 0)
            {
              Console.WriteLine("  {0,9:f4}{1,10:f3}{2,10:f3}{3,10:f4}{4}{5,1}",p,a,b,x," NOTE: ifail = ",ifail);
            }
            continue;
          }
          else
          {
            Console.WriteLine("** g01fe failed with ifail = {0,5}", ifail);
            break;
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g01ff Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01FFE
  {
    static string datafile = "ExampleData/g01ffe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double a,   b,   p,   tol,   x; int ifail; bool carryon = true;
        Console.WriteLine("g01ff Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}","       P       A       B        X");
        Console.WriteLine("");
        while (carryon)
        {
          try
          {
            sr.Reset();
            p = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            a = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            b = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          catch
          {
            break;
          }
          tol = 0.00e0;
          //
          x = G01.g01ff(p, a, b, tol, out  ifail);
          //
          if (ifail >= 0)
          {
            if (ifail == 0)
            {
              Console.WriteLine("  {0,8:f3}{1,8:f3}{2,8:f3}{3,10:f3}",p,a,b,x);
            }
            else if (ifail > 0)
            {
              Console.WriteLine("  {0,8:f3}{1,8:f3}{2,8:f3}{3,10:f3}{4}{5,1}",p,a,b,x," NOTE: ifail = ",ifail);
            }
            continue;
          }
          else
          {
            Console.WriteLine("** g01ff failed with ifail = {0,5}", ifail);
            break;
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g01fm Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01FME
  {
    static string datafile = "ExampleData/g01fme.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double p,  v,  valq; int i, ir;
        int ifail;
        Console.WriteLine("g01fm Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}","    P     V       IR      Quantile ");
        Console.WriteLine("");
        for (i = 1 ; i <= 3 ; i++)
        {
          sr.Reset();
          p = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          v = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          ir = int.Parse(sr.Next());
          //
          valq = G01.g01fm(p, v, ir, out  ifail);
          //
          if ((ifail == 0) || (ifail == 3))
          {
            Console.WriteLine("  {0,5:f2}    {1,4:f1}  {2,3}  {3,10:f4}",p,v,ir,valq);
          }
          else
          {
            Console.WriteLine("** g01fm failed with ifail = {0,5}", ifail);
            break;
          }
        }
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g01ft Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01FTE
  {
    static string datafile = "ExampleData/g01fte.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double x,  y;  int ifail;
        bool carryon = true;
        Console.WriteLine("g01ft Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "  x          y            ifail");
        Console.WriteLine("");
        while (carryon)
        {
          try
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          catch
          {
            break;
          }
          //
          //      Compute the value of the inverse of the Landau distribution function
          //
          //
          y = G01.g01ft(x, out  ifail);
          //
          if (ifail >= 0)
          {
            Console.WriteLine("  {0,4:f1}      {1,12:e4}{2,6}", x, y, ifail);
            continue;
          }
          else
          {
            Console.WriteLine("** g01ft failed with ifail = {0,5}", ifail);
            break;
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01ft Example Program Data
 0.5  : Value of X


g01ft Example Program Results

   x          y            ifail

   0.5       1.3558e+000     0


//      g01gb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01GBE
  {
    static string datafile = "ExampleData/g01gbe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double delta,  df,   prob,   t,   tol;  int maxit;
        int ifail;
        bool carryon = true;
        Console.WriteLine("g01gb Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     T       DF    DELTA    PROB");
        Console.WriteLine("");
        tol = 0.50e-5;
        maxit = 50;
        while (carryon)
        {
          try
          {
            sr.Reset();
            t = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            df = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            delta = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          catch
          {
            break;
          }
          //
          prob = G01.g01gb(t, df, delta, tol, maxit, out  ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine("  {0,8:f3}{1,8:f3}{2,8:f3}{3,8:f4}", t, df, delta, prob);
            continue;
          }
          else
          {
            Console.WriteLine("** g01gb failed with ifail = {0,5}", ifail);
            break;
          }
        }
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01gb Example Program Data
 -1.528  20.0  2.0           :T DF DELTA
 -0.188   7.5  1.0           :T DF DELTA
  1.138  45.0  0.0           :T DF DELTA


//      g01gc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01GCE
  {
    static string datafile = "ExampleData/g01gce.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double df,  prob,  rlamda,  tol,  x; int maxit;
        int ifail;
        bool carryon = true;
        Console.WriteLine("g01gc Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}","     x       df     rlamda   prob");
        Console.WriteLine("");
        tol = 0.50e-5;
        maxit = 50;
        while (carryon)
        {
          try
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            df = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            rlamda = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          catch
          {
            break;
          }
          //
          prob = G01.g01gc(x, df, rlamda, tol, maxit, out  ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine("  {0,8:f3}{1,8:f3}{2,8:f3}{3,8:f4}",x,df,rlamda,prob);
          }
          else if (ifail > 0)
          {
            Console.WriteLine("  {0,8:f3}{1,8:f3}{2,8:f3}{3,8:f4}{4}{5,1}",x,df,rlamda,prob," NOTE: ifail = ",ifail);
          }
          else
          {
            Console.WriteLine("** g01gc failed with ifail = {0,5}", ifail);
            break;
          }
          continue;
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01gc Example Program Data
  8.26   20.0   3.5            :X DF RLAMDA
  6.2     7.5   2.0            :X DF RLAMDA
 55.76   45.0   1.0            :X DF RLAMDA


//      g01gd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01GDE
  {
    static string datafile = "ExampleData/g01gde.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double df1,  df2,  f,  prob,  rlamda,  tol; int maxit;
        int ifail;
        bool carryon = true;
        Console.WriteLine("g01gd Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     F      DF1     DF2     RLAMDA   PROB");
        Console.WriteLine("");
        tol = 0.50e-5;
        maxit = 50;
        while (carryon)
        {
          try
          {
            sr.Reset();
            f = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            df1 = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            df2 = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            rlamda = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          catch
          {
            break;
          }
          //
          prob = G01.g01gd(f, df1, df2, rlamda, tol, maxit, out  ifail);
          //
          if (ifail >= 0)
          {
            if (ifail == 0)
            {
              Console.WriteLine("  {0,8:f3}{1,8:f3}{2,8:f3}{3,8:f3}{4,8:f4}", f, df1, df2, rlamda, prob);
            }
            else if (ifail > 0)
            {
              Console.WriteLine("  {0,8:f3}{1,8:f3}{2,8:f3}{3,8:f3}{4,8:f4}{5}{6,1}", f, df1, df2, rlamda, prob, " NOTE: ifail = ", ifail);
            }
            continue;
          }
          else
          {
            Console.WriteLine("** g01gd failed with ifail = {0,5}", ifail);
            break;
          }
        }
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01gd Example Program Data
  5.5   1.5    25.5   3.0          :F DF1 DF2 RLAMDA
 39.9   1.0     1.0   2.0          :F DF1 DF2 RLAMDA
  2.5  20.25    1.0   0.0          :F DF1 DF2 RLAMDA


//      g01ge Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01GEE
  {
    static string datafile = "ExampleData/g01gee.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double a,  b,  prob,  rlamda,  tol,  x; int maxit;
        int ifail;
        bool carryon = true;
        Console.WriteLine("g01ge Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}","     x       a       b      rlamda   prob");
        Console.WriteLine("");
        tol = 0.50e-5;
        maxit = 50;
        while (carryon)
        {
          try
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            a = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            b = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            rlamda = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          catch
          {
            break;
          }
          //
          prob = G01.g01ge(x, a, b, rlamda, tol, maxit, out  ifail);
          //
          if (ifail >= 0)
          {
            if (ifail == 0)
            {
              Console.WriteLine("  {0,8:f3}{1,8:f3}{2,8:f3}{3,8:f3}{4,8:f4}",x,a,b,rlamda,prob);
            }
            else if (ifail > 0)
            {
              Console.WriteLine("  {0,8:f3}{1,8:f3}{2,8:f3}{3,8:f3}{4,8:f4}{5}{6,1}",x,a,b,rlamda,prob," NOTE: ifail = ",ifail);
            }
            continue;
          }
          else
          {
            Console.WriteLine("** g01ge failed with ifail = {0,5}", ifail);
            break;
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01ge Example Program Data
 0.25  1.0  2.0  1.0         :X A B RLAMDA
 0.75  1.5  1.5  0.5         :X A B RLAMDA
 0.5   2.0  1.0  0.0         :X A B RLAMDA


//      g01ha Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01HAE
  {
    static string datafile = "ExampleData/g01hae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double prob,   rho,   x,   y; int ifail; bool carryon = true;
        Console.WriteLine("g01ha Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}","     x       y       rho    prob");
        Console.WriteLine("");
        while (carryon)
        {
          try
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            y = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            rho = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          catch
          {
            break;
          }
          //
          prob = G01.g01ha(x, y, rho, out  ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine("  {0,8:f3}{1,8:f3}{2,8:f3}{3,8:f4}",x,y,rho,prob);
            continue;
          }
          else
          {
            Console.WriteLine("** g01ha failed with ifail = {0,5}", ifail);
            break;
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g01hb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01HBE
  {
    static string datafile = "ExampleData/g01hbe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double prob,   tol; int i,  j,  n; string tail;
        int ifail;
        Console.WriteLine("g01hb Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        double[] a = new double[n];
        double[] b = new double[n];
        double[,] sig = new double[n, n];
        double[] xmu = new double[n];
        tol = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        tail = sr.Next();
        if (n >=1 && n <=10)
        {
          sr.Reset();
          for (j = 1 ; j <= n ; j++)
          {
            xmu[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          for (i = 1 ; i <= n ; i++)
          {
            sr.Reset();
            for (j = 1 ; j <= n ; j++)
            {
              sig[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          if ((((tail == "C") || (tail == "c")) || (tail == "U")) || (tail == "u"))
          {
            sr.Reset();
            for (j = 1 ; j <= n ; j++)
            {
              a[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          if ((((tail == "C") || (tail == "c")) || (tail == "L")) || (tail == "l"))
          {
            sr.Reset();
            for (j = 1 ; j <= n ; j++)
            {
              b[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //
          prob = G01.g01hb(tail, n, a, b, xmu, sig, tol, out  ifail);
          //
          if ((ifail == 0) || (ifail > 3))
          {
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,6:f4}","Multivariate Normal probability = ",prob);
          }
          else
          {
            Console.WriteLine("");
            Console.WriteLine("** g01hb failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01hb Example Program Results

  Multivariate Normal probability = 0.9142


//      g01jc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01JCE
  {
    static string datafile = "ExampleData/g01jce.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double c,   p,   pdf,   tol; int i,  maxit = 500,  n;
        const int nmax=4;
        double[] a = new double[nmax];
        double[] rlamda = new double[nmax];
        int[] mult = new int[nmax];
        int ifail;
        Console.WriteLine("g01jc Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}","        A     MULT  RLAMDA");
        tol = 0.00010e0;
        bool carryon = true;
        while (carryon)
        {
          try
          {
            sr.Reset();
            n = int.Parse(sr.Next());
            c = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          catch
          {
            break;
          }
          Console.WriteLine("");
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            a[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            mult[i - 1] = int.Parse(sr.Next());
          }
          sr.Reset();
          for (i = 1 ; i <= n ; i++)
          {
            rlamda[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //
          G01.g01jc(a, mult, rlamda, n, c, out p, out pdf, tol, maxit, out  ifail);
          //
          if ((ifail == 0) || (ifail >= (4)))
          {
            for (i = 1 ; i <= n ; i++)
            {
              Console.WriteLine("  {0,10:f2}{1,6}{2,9:f2}",a[i - 1],mult[i - 1],rlamda[i - 1]);
            }
            Console.WriteLine("  {0}{1,6:f2}{2}{3,6:f4}","C = ",c,"    PROB = ",p);
            continue;
          }
          else
          {
            Console.WriteLine("** g01jc failed with ifail = {0,5}", ifail);
            break;
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g01jd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01JDE
  {
    static string datafile = "ExampleData/g01jde.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        const int n=10;
        double c,   d,   prob; int i;
        string method="";
        double[] rlam = new double[n];
        int ifail;
        Console.WriteLine("g01jd Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        method = sr.Next();
        d = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        c = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        sr.Reset();
        for (i = 1 ; i <= n ; i++)
        {
          rlam[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        //
        //
        G01.g01jd(method, n, rlam, d, c, out prob, out  ifail);
        //
        if (ifail == 0)
        {
          Console.WriteLine("");
          Console.Write(" {0}",  " Values of lambda ");
          for (i = 1 ; i <= n ; i++)
          {
            Console.Write(" {0, 6:f2}", rlam[i - 1]);
          }
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,6:f2}"," Value of D       ",d);
          Console.WriteLine("  {0}{1,6:f2}"," value of C       ",c);
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,10:f4}"," Probability = ",prob);
        }
        else
        {
          Console.WriteLine("");
          Console.WriteLine("** g01jd failed with ifail = {0,5}", ifail);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01jd Example Program Results

  Values of lambda   -9.00  -7.00  -5.00  -3.00  -1.00   2.00   4.00   6.00   8.00  10.00
   Value of D         1.00
   value of C         0.00

   Probability =     0.5749


//      g01mb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01MBE
  {
    static string datafile = "ExampleData/g01mbe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double rm,   x,   xmu,   xsig,   z; int i;
        Console.WriteLine("g01mb Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine("    mean        sigma        x      reciprocal");
        Console.WriteLine("                                    mills ratio\n");
        for (i = 1 ; i <= 3 ; i++)
        {
          sr.Reset();
          x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          xmu = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          xsig = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          z = (x - xmu) / xsig;
          rm = G01.g01mb(z) / xsig;
          Console.WriteLine("  {0,7:f4}    {1,7:f4}    {2,7:f4}    {3,7:f4}    ",
          xmu, xsig, x, rm);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g01mt Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01MTE
  {
    static string datafile = "ExampleData/g01mte.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double x, y;
        bool carryon = true;
        Console.WriteLine("g01mt Example Program Results");
        //         Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}","  x          y");
        Console.WriteLine("");
        while (carryon)
        {
          try
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          catch
          {
            break;
          }
          //
          //         Compute the value of the Landau density function
          //
          y = G01.g01mt(x);
          //
          Console.WriteLine("  {0,4:f1}      {1,12:e4}",x,y);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01mt Example Program Data
 0.5  : Value of X


g01mt Example Program Results

   x          y

   0.5       1.6523e-001


//      g01mu Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01MUE
  {
    static string datafile = "ExampleData/g01mue.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        const int mode = 0;
        double beta2,   c1,   c2,   rkappa,   x,   xl,   xu,   y;
        double[] comm = new double[322];
        int ifail;
        bool carryon = true;
        Console.WriteLine("g01mu Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        c1 = -X02.x02al();
        c2 = -X02.x02al();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "  x           rkappa          beta2         y         ifail");
        Console.WriteLine("");
        while (carryon)
        {
          try
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            rkappa = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            beta2 = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          catch
          {
            break;
          }
          if (((rkappa != c1)) || ((beta2 != c2)))
          {
            //
            //         Initialise array comm before the the first call to G01.g01mu and
            //         on subsequent calls when rkappa or beta2 has changed.
            //
            //
            G01.g01zu(rkappa, beta2, mode, out xl, out xu, comm, out  ifail);
            //
            if (ifail != 0)
            {
              Console.WriteLine("** g01zu failed with ifail = {0,5}", ifail);
              break;
            }
            //
          }
          //
          //      Compute the value of the Vavilov density function
          //
          //
          y = G01.g01mu(x, comm, out  ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine("  {0,4:f1}          {1,4:f1}          {2,4:f1}      {3,12:e4}{4,6}", x, rkappa, beta2, y, ifail);
            c1 = (double)rkappa;
            c2 = (double)beta2;
            continue;
          }
          else
          {
            Console.WriteLine("** g01mu failed with ifail = {0,5}", ifail);
          }
          //
        }
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01mu Example Program Data
 2.5  0.4  0.1 : Values of X, RKAPPA and BETA2


g01mu Example Program Results

   x           rkappa          beta2         y         ifail

   2.5           0.4           0.1       8.3675e-002     0


//      g01na Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01NAE
  {
    static string datafile = "ExampleData/g01nae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double beta,   con; int i,  j,  l,  n;
        int ifail;
        Console.WriteLine("g01na Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        beta = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        con = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        sr.Reset();
        n = int.Parse(sr.Next());
        l = int.Parse(sr.Next());
        if (n >= 1 && l <= 12)
        {
          //
          //         Compute a, emu, and sigma for simple autoregression
          //
          double[,] a = new double[n, n];
          double[] emu = new double[n];
          double[] rkum = new double[l];
          double[] rmom = new double[l];
          double[,] sigma = new double[n, n];
          for (i = 1; i <= n; i++)
          {
            for (j = i; j <= n; j++)
            {
              a[j - 1, i - 1] = 0.00e0;
            }
          }
          for (i = 1; i <= n - 1; i++)
          {
            a[i + 1 - 1, i - 1] = 0.50e0;
          }
          emu[0] = con * beta;
          for (i = 1; i <= n - 1; i++)
          {
            emu[i + 1 - 1] = beta * emu[i - 1];
          }
          sigma[0, 0] = 1.00e0;
          for (i = 2; i <= n; i++)
          {
            sigma[i - 1, i - 1] = beta * beta * sigma[i - 1 - 1, i - 1 - 1] + 1.00e0;
          }
          for (i = 1; i <= n; i++)
          {
            for (j = i + 1; j <= n; j++)
            {
              sigma[j - 1, i - 1] = beta * sigma[j - 1 - 1, i - 1];
            }
          }
          //
          G01.g01na("M", "M", n, a, emu, sigma, l, rkum, rmom, out  ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine("");
            Console.WriteLine("{0}{1,3}{2}{3,6:f3}{4}{5,6:f3}", " N = ", n, " BETA = ", beta, " CON = ", con);
            Console.WriteLine("");
            Console.WriteLine(" {0}", "    Cumulants          Moments");
            Console.WriteLine("");
            for (i = 1; i <= l; i++)
            {
              Console.WriteLine("{0,3}{1,12:e4}        {2,12:e4}", i, rkum[i - 1], rmom[i - 1]);
            }
          }
          else
          {
            Console.WriteLine("");
            Console.WriteLine("** g01na failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01na Example Program Data
0.8  1.0   : BETA, CON
10   4     : N, L


//      g01nb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01NBE
  {
    static string datafile = "ExampleData/g01nbe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double abserr,   beta,   eps,   y0; int i,  j,  l1,  l2,  lmax,  n;
        int ifail;
        Console.WriteLine("g01nb Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        beta = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        y0 = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        sr.Reset();
        n = int.Parse(sr.Next());
        l1 = int.Parse(sr.Next());
        l2 = int.Parse(sr.Next());
        if (n >=1 && l2 <= 12)
        {
          double[,] a = new double[n, n];
          double[,] b = new double[n, n];
          double[,] c = new double[n, n];
          double[] ela = new double[n];
          double[] emu = new double[n];
          double[] rmom = new double[l2-l1+1];
          double[,] sigma = new double[n, n];
          //
          //         Compute a, emu, and sigma for simple autoregression
          //
          for (i = 1 ; i <= n ; i++)
          {
            for (j = i ; j <= n ; j++)
            {
              a[j - 1 , i - 1] = 0.00e0;
              b[j - 1 , i - 1] = 0.00e0;
            }
          }
          for (i = 1 ; i <= n - 1 ; i++)
          {
            a[i + 1 - 1 , i - 1] = 0.50e0;
            b[i - 1 , i - 1] = 1.00e0;
          }
          emu[0] = y0 * beta;
          for (i = 1 ; i <= n - 1 ; i++)
          {
            emu[i + 1 - 1] = beta * emu[i - 1];
          }
          sigma[0 , 0] = 1.00e0;
          for (i = 2 ; i <= n ; i++)
          {
            sigma[i - 1 , i - 1] = beta * beta * sigma[i - 1 - 1 , i - 1 - 1] + 1.00e0;
          }
          for (i = 1 ; i <= n ; i++)
          {
            for (j = i + 1 ; j <= n ; j++)
            {
              sigma[j - 1 , i - 1] = beta * sigma[j - 1 - 1 , i - 1];
            }
          }
          eps = 0.00e0;
          //
          G01.g01nb("Ratio", "Mean", n, a, b, c, ela, emu, sigma, l1, l2, out lmax, rmom, out abserr, eps, out  ifail);
          //
          if ((ifail == 0) || (ifail >= (6)))
          {
            Console.WriteLine("");
            Console.WriteLine("{0}{1,3}{2}{3,6:f3}{4}{5,6:f3}"," N = ",n," BETA = ",beta," Y0 = ",y0);
            Console.WriteLine("");
            Console.WriteLine(" {0}","      Moments");
            Console.WriteLine("");
            j = 0;
            for (i = l1 ; i <= lmax ; i++)
            {
              j = j + 1;
              Console.WriteLine("{0,3}{1,12:e3}",i,rmom[j - 1]);
            }
          }
          else
          {
            Console.WriteLine("");
            Console.WriteLine("** g01nb failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01nb Example Program Data
0.8 1.0     : Beta Y0
10  1   3   : N  L1  L1


//      g01pt Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01PTE
  {
    static string datafile = "ExampleData/g01pte.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double x,   y; bool carryon = true;
        Console.WriteLine("g01pt Example Program Results");
        //         Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}","  x          y");
        Console.WriteLine("");
        while (carryon)
        {
          try
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          catch
          {
            break;
          }
          //
          //         Compute the value of the first moment of the Landau density function
          //
          y = G01.g01pt(x);
          //
          Console.WriteLine("  {0,4:f1}      {1,12:e4}",x,y);
        }
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01pt Example Program Data
 0.5  : Value of X


g01pt Example Program Results

   x          y

   0.5      -6.2932e-001


//      g01qt Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01QTE
  {
    static string datafile = "ExampleData/g01qte.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double x,  y; bool carryon = true;
        Console.WriteLine("g01qt Example Program Results");
        //         Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}","  x          y");
        Console.WriteLine("");
        while (carryon)
        {
          try
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          catch
          {
            break;
          }
          //
          //         Compute the value of the second moment of the Landau density function
          //
          y = G01.g01qt(x);
          //
          Console.WriteLine("  {0,4:f1}      {1,12:e4}",x,y);
          continue;
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01qt Example Program Data
 0.5  : Value of X


g01qt Example Program Results

   x          y

   0.5       9.0868e-001


//      g01rt Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G01RTE
  {
    static string datafile = "ExampleData/g01rte.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double x,   y; bool carryon = true;
        Console.WriteLine("g01rt Example Program Results");
        //         Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}","  x          y");
        Console.WriteLine("");
        while (carryon)
        {
          try
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          catch
          {
            break;
          }
          //
          //         Compute the value of the derivative of the Landau density function
          //
          y = G01.g01rt(x);
          //
          Console.WriteLine("  {0,4:f1}      {1,12:e4}",x,y);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g01rt Example Program Data
 0.5  : Value of X


g01rt Example Program Results

   x          y

   0.5      -3.6034e-002


//      g02aa Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02AAE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        double errtol,   nrmgrd; int feval,  i,  iter,  j,  maxit,  maxits,  n;
        int ifail;
        Console.WriteLine("g02aa Example Program Results");
        Console.WriteLine("");
        //
        //      Set up matrix G
        n = 4;
        double[,] g = new double[n, n];
        double[,] x = new double[n, n];
        for (j = 1; j <= n; j++)
        {
          for (i = 1; i <= n; i++)
          {
            g[i - 1, j - 1] = 0.0;
          }
          g[j - 1, j - 1] = 2.00e0;
        }
        for (j = 2; j <= n; j++)
        {
          g[j - 1 - 1, j - 1] = -1.00e0;
          g[j - 1, j - 1 - 1] = -1.00e0;
        }
        //
        //      Set up method parameters
        errtol = 1.00e-7;
        maxits = 200;
        maxit = 10;
        //
        G02.g02aa(g, n, errtol, maxits, maxit, x, out iter, out feval, out nrmgrd, out ifail);
        //
        if (ifail == 0)
        {
          Console.WriteLine(" {0}", "     Nearest Correlation Matrix\r\n");
          for (i = 1; i <= n; i++)
          {
            for (j = 1; j <= n; j++)
            {
              Console.Write(" {0,11:f5}{1}", x[i - 1, j - 1],j%4==0? "\n":"");
            }
          }
          Console.WriteLine("");
          Console.WriteLine("");
          Console.WriteLine("{0}{1,11}", " Number of Newton steps taken:", iter);
          Console.WriteLine("{0}{1,9}", " Number of function evaluations:", feval);
          if (nrmgrd > errtol)
          {
            Console.WriteLine("{0}{1,11:e3}", " Norm of gradient of last Newton step:", nrmgrd);
          }
        }
        else
        {
          Console.WriteLine("** g02aa failed with ifail = {0,5}", ifail);
        }
        Console.WriteLine("");
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g02ab Example Program Text
//      C# version, NAG Copyright 2012
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{

    public class G02ABE
    {

        static string datafile = "ExampleData/g02abe.d";
        // Specify data file as a command line argument.
        // It defaults to the named file specified below otherwise.

        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
        {
            try
            {
               DataReader sr = new DataReader(datafile);
                //      g02ab Example Program Text
                //      Mark 24 Release. NAG Copyright 2012.

                double alpha,
                errtol,
                nrmgrd;
                int feval = 0,
                i = 0,
                ifail = 0,
                iter = 0,
                ldg = 0,
                ldx = 0,
                lwork = 0,
                maxit = 0,
                maxits = 0,
                n = 0;
                string opt = "";

                Console.WriteLine(" {0}", "g02ab Example Program Results");
                Console.WriteLine("");
                //      Skip heading in data file
                sr.Reset();
                //      Read in the problem size, opt and alpha
                sr.Reset();
                n = int.Parse(sr.Next());
                opt = sr.Next();
                alpha = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                ldg = (int)n;
                ldx = (int)n;
                lwork = 66 * n;
                // allocate
                //      Read in the matrix G

                double[] eig = new double[n];
                double[,] g = new double[ldg, n];
                double[] w = new double[n];
                double[] work = new double[lwork];
                double[,] x = new double[ldx, n];
                sr.Reset();
                for (i = 1; i <= n; i++)
                {
                    for (int j = 0; j < n; j++)
                    {
                        g[i - 1, j] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                    }

                }
                //      Read in the vector W
                sr.Reset();
                for (int j = 0; j < n; j++)
                {
                    w[j] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }
                //      Use the defaults for ERRTOL, MAXITS and MAXIT
                errtol = 0.00e0;
                maxits = 0;
                maxit = 0;
                //      Calculate nearest correlation matrix
                ifail = 0;
                G02.g02ab(g, n, opt, alpha, w, errtol, maxits, maxit, x, out iter, out feval, out nrmgrd, out ifail);
                //      Display results
                ifail = 0;
                X04.x04ca("General", "", n, n, x, "Nearest Correlation Matrix X", out ifail);
                Console.WriteLine("");
                Console.WriteLine("  {0}{1,11}", "Number of Newton steps taken:", iter);
                Console.WriteLine("  {0}{1,9}", "Number of function evaluations:", feval);
                Console.WriteLine("");
                Console.WriteLine("  {0}{1,37:f3}", "ALPHA: ", alpha);
                ifail = 0;
                //      The NAG name equivalent of dsyev is F08.f08fa;
                String jobz = "N";
                String uplo = "U";
                F08.f08fa(jobz, uplo, n, x, eig, out ifail);

                Console.WriteLine("");
                double[,] eig_prime = new double[1, n];
                for (i = 0; i < n; i++)
                {
                    eig_prime[0, i] = eig[i];
                }
                X04.x04ca("General", "", 1, n, eig_prime, "Eigenvalues of X", out ifail);
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
                Console.WriteLine("Exception Raised");
            }
        }
    }
}


//      g02ae Example Program Text
//      C# version, NAG Copyright 2012
using System;
using NagLibrary;
using System.Globalization;
using System.Runtime.InteropServices;/* Provides mappings between C# and native code */

namespace NagDotNetExamples
{

    public class G02AEE
    {
        static string datafile = "ExampleData/g02aee.d";
        // Specify data file as a command line argument.
        // It defaults to the named file specified below otherwise.

        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
        {
            try
            {
                DataReader sr = new DataReader(datafile);
                double one = 1.0;
                double zero = 0.0;
               // int nin = 5,
               // nout = 6;
                double errtol,
                nrmpgd;
                int feval = 0,
                i = 0,
                ifail = 0,
                iter = 0,
                k = 0,
                lda = 0,
                ldg = 0,
                ldx = 0,
                maxit = 0,
                n = 0;

                Console.WriteLine(" {0}", "g02ae Example Program Results");
                Console.WriteLine("");
                //      Skip heading in data file
                sr.Reset();
                //      Read in the problem size
                sr.Reset();
                n = int.Parse(sr.Next());
                lda = (int)n;
                ldg = (int)n;
                ldx = (int)n;
                double[,] a = new double[lda, n];
                double[,] g = new double[ldg, n];
                double[,] x = new double[ldx, n];

                // allocate
                //      Read in the matrix G
                sr.Reset();
                for (i = 1; i <= n; i++)
                {
                    for (int j = 0; j < n; j++)
                    {
                        g[i - 1, j] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                    }
                }
                //      Use the defaults for ERRTOL and MAXIT
                errtol = (double)zero;
                maxit = 0;
                //      Set k value
                k = 2;
                //      Calculate the nearest factor loading matrix
                ifail = 0;
                G02.g02ae(g, n, k, errtol, maxit, x, out iter, out feval, out nrmpgd, out ifail);
                //      Display results
                ifail = 0;
                X04.x04ca("General", "", n, k, x, "Factor Loading Matrix X", out ifail);
                Console.WriteLine("");
                Console.WriteLine("  {0}{1,11}", "Number of steps taken:", iter);
                Console.WriteLine("  {0}{1,9}", "Number of function evaluations:", feval);
                //      Generate Nearest k factor correlation matrix
                //      The NAG name equivalent of dgemm is f06ya;

                F06.f06ya("N", "T", n, n, k, one, x, x, zero, a, out ifail);
                for (i = 1; i <= n; i++)
                {
                    a[i - 1, i - 1] = one;
                }
                Console.WriteLine("");
                ifail = 0;
                X04.x04ca("General", "", n, n, a, "Nearest Correlation Matrix", out ifail);

            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
                Console.WriteLine("Exception Raised");
            }
        }
    }
}


//      g02ba Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02BAE
  {
    static string datafile = "ExampleData/g02bae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   j;
        const int m = 3;
        const int n = 5;
        double[,] r = new double[m, m];
        double[,] ssp = new double[m, m];
        double[] std = new double[m];
        double[,] x = new double[n, m];
        double[] xbar = new double[m];
        int ifail;
        Console.WriteLine("g02ba Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= m; j++)
          {
            x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        Console.WriteLine(" ");
        Console.WriteLine("  {0}{1,5}", "Number of variables (columns) =", m);
        Console.WriteLine("  {0}{1,5}", "Number of cases     (rows)    =", n);
        Console.WriteLine(" ");
        Console.Write(" {0}", "Data matrix is:-");
        Console.Write("\r\n   ");
        for (j = 1; j <= m; j++)
        {
          Console.Write("{0,10}", j);
        }
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          Console.Write("   " + i + "    ");
          for (j = 1; j <= m; j++)
          {
            Console.Write(" {0,8:f4}", x[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        //
        G02.g02ba(n, m, x, xbar, std, ssp, r, out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02ba failed with ifail = {0,5}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.Write("  {0}{1,5}", "Routine fails, ifail =", ifail);
          }
          else
          {
            Console.Write(" {0}", "Variable   Mean    St. dev.\n");
            for (i = 1; i <= m; i++)
            {
              Console.Write("     {0}  {1,10:f4}{2,10:f4}", i, xbar[i - 1], std[i - 1]);
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.Write(" {0}", "Sums of squares and cross-products of deviations\r\n");
            for (i = 1; i <= m; i++)
            {
              Console.Write("{0,14}", i);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write(" {0}", i);
              for (j = 1; j <= m; j++)
              {
                Console.Write(" \t{0,10:f4}", ssp[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.Write(" {0}", "Correlation coefficients\r\n");
            for (i = 1; i <= m; i++)
            {
              Console.Write("{0,14}", i);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write(" {0}", i);
              for (j = 1; j <= m; j++)
              {
                Console.Write(" \t{0,10:f4}", r[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write("Exception Raised");
      }
    }
  }
}


//      g02bb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02BBE
  {
    static string datafile = "ExampleData/g02bbe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i, j, ncases;
        const int m = 3;
        const int n = 5;
        double[,] r = new double[m, m];
        double[,] ssp = new double[m, m];
        double[] std = new double[m];
        double[,] x = new double[n, m];
        double[] xbar = new double[m];
        double[] xmiss = new double[m];
        int[] miss = new int[3];
        int ifail;
        Console.WriteLine("g02bb Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= m; j++)
          {
            x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        Console.WriteLine(" ");
        Console.WriteLine("  {0}{1,5}", "Number of variables (columns) =", m);
        Console.WriteLine("  {0}{1,5}", "Number of cases     (rows)    =", n);
        Console.WriteLine(" ");
        Console.Write(" {0}", "Data matrix is:-");
        Console.WriteLine(" ");
        for (j = 1; j <= m; j++)
        {
          Console.Write(" {0,10}", j);
        }
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          Console.Write(" {0}", i);
          for (j = 1; j <= m; j++)
          {
            Console.Write(" {0,10:f4}", x[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        //
        //      Set up missing values before calling method
        //
        miss[0] = 1;
        miss[1] = 0;
        miss[2] = 1;
        xmiss[0] = 0.00e0;
        xmiss[2] = 0.00e0;
        //
        G02.g02bb(n, m, x, miss, xmiss, xbar, std, ssp, r, out ncases, out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02bb failed with ifail = {0,5}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.Write("  {0}{1,5}", "Routine fails, ifail =", ifail);
          }
          else
          {
            Console.Write(" {0}", "Variable   Mean    St. dev.\r\n");
            for (i = 1; i <= m; i++)
            {
              Console.Write("     {0}  {1,10:f4}{2,10:f4}", i, xbar[i - 1], std[i - 1]);
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.Write(" {0}", "Sums of squares and cross-products of deviations");
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write("{0,14}", i);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write(" {0}", i);
              for (j = 1; j <= m; j++)
              {
                Console.Write(" \t{0,10:f4}", ssp[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.Write(" {0}", "Correlation coefficients");
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write("{0,14}", i);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write("{0}", i);
              for (j = 1; j <= m; j++)
              {
                Console.Write(" \t{0,10:f4}", r[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.WriteLine("  {0}{1,5}", "Number of cases actually used: ", ncases);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write("Exception Raised");
      }
    }
  }
}


//      g02bc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02BCE
  {
    static string datafile = "ExampleData/g02bce.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   j,   ncases;
        const int m = 3;
        const int n = 5;
        double[,] cnt = new double[m, m];
        double[,] r = new double[m, m];
        double[,] ssp = new double[m, m];
        double[] std = new double[m];
        double[,] x = new double[n, m];
        double[] xbar = new double[m];
        double[] xmiss = new double[m];
        int[] miss = new int[m];
        int ifail;
        Console.WriteLine("g02bc Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= m; j++)
          {
            x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        Console.WriteLine(" ");
        Console.WriteLine("  {0}{1,2}", "Number of variables (columns) =", m);
        Console.WriteLine("  {0}{1,2}", "Number of cases     (rows)    =", n);
        Console.WriteLine(" ");
        Console.Write(" {0}", "Data matrix is:-");
        Console.Write("\r\n   ");
        for (j = 1; j <= m; j++)
        {
          Console.Write("{0,10}", j);
        }
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          Console.Write("   " + i + "    ");
          for (j = 1; j <= m; j++)
          {
            Console.Write(" {0,8:f4}", x[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        //
        //      Set up missing values before calling method
        //
        miss[0] = 1;
        miss[1] = 1;
        miss[2] = 1;
        xmiss[0] = 0.00e0;
        xmiss[1] = -1.00e0;
        xmiss[2] = 0.00e0;
        //
        G02.g02bc(n, m, x, miss, xmiss, xbar, std, ssp, r, out ncases, cnt, out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02bc failed with ifail = {0,5}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.Write("  {0}{1,5}", "Routine fails, ifail =", ifail);
          }
          else
          {
            Console.Write(" {0}", "Variable   Mean    St. dev.\n");
            for (i = 1; i <= m; i++)
            {
              Console.Write("     {0}  {1,10:f4}{2,10:f4}", i, xbar[i - 1], std[i - 1]);
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.Write(" {0}", "Sums of squares and cross-products of deviations\r\n");
            for (i = 1; i <= m; i++)
            {
              Console.Write("{0,14}", i);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write(" {0}", i);
              for (j = 1; j <= m; j++)
              {
                Console.Write(" \t{0,10:f4}", ssp[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.Write(" {0}", "Correlation coefficients\r\n");
            for (i = 1; i <= m; i++)
            {
              Console.Write("{0,14}", i);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write(" {0}", i);
              for (j = 1; j <= m; j++)
              {
                Console.Write(" \t{0,10:f4}", r[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.Write("  {0}{1,2}", "Minimum number of cases used for any pair of variables: ", ncases);
            Console.WriteLine(" ");
            Console.Write(" {0}", "Numbers used for each pair are:\r\n");
            for (i = 1; i <= m; i++)
            {
              Console.Write("{0,6}   ", i);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write("{0, 3}", i);
              for (j = 1; j <= m; j++)
              {
                Console.Write(" {0,8:f4}", cnt[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write("Exception Raised");
      }
    }
  }
}


//      g02bd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02BDE
  {
    static string datafile = "ExampleData/g02bde.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   j;
        const int m = 3;
        const int n = 5;
        double[,] rz = new double[m, m];
        double[,] sspz = new double[m, m];
        double[] std = new double[3];
        double[,] x = new double[n, m];
        double[] xbar = new double[3];
        int ifail;
        Console.WriteLine("g02bd Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= m; j++)
          {
            x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        Console.WriteLine(" ");
        Console.WriteLine("  {0}{1,5}", "Number of variables (columns) =", m);
        Console.WriteLine("  {0}{1,5}", "Number of cases     (rows)    =", n);
        Console.WriteLine(" ");
        Console.Write(" {0}", "Data matrix is:-");
        Console.WriteLine(" ");
        for (j = 1; j <= m; j++)
        {
          Console.Write("{0,8}", j);
        }
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          Console.Write("{0}", i);
          for (j = 1; j <= m; j++)
          {
            Console.Write(" {0,8:f4}", x[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        //
        G02.g02bd(n, m, x, xbar, std, sspz, rz, out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02bd failed with ifail = {0,5}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.Write("  {0}{1,5}", "Routine fails, ifail =", ifail);
          }
          else
          {
            Console.Write(" {0}", "Variable   Mean    St. dev.\n");
            for (i = 1; i <= m; i++)
            {
              Console.Write("     {0}  {1,10:f4}{2,10:f4}", i, xbar[i - 1], std[i - 1]);
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.Write(" {0}", ("Sums of squares and cross-products about") + (" zero"));
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write("{0,14}", i);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write(" {0}", i);
              for (j = 1; j <= m; j++)
              {
                Console.Write(" \t{0,10:f4}", sspz[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.Write(" {0}", "Correlation-like coefficients\r\n");
            for (i = 1; i <= m; i++)
            {
              Console.Write("{0,14}", i);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write("{0}", i);
              for (j = 1; j <= m; j++)
              {
                Console.Write(" \t{0,10:f4}", rz[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write("Exception Raised");
      }
    }
  }
}


//      g02be Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02BEE
  {
    static string datafile = "ExampleData/g02bee.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   j,   ncases;
        const int m = 3;
        const int n = 5;
        double[,] rz = new double[m, m];
        double[,] sspz = new double[m, m];
        double[] std = new double[m];
        double[,] x = new double[n, m];
        double[] xbar = new double[m];
        double[] xmiss = new double[m];
        int[] miss = new int[m];
        int ifail;
        Console.WriteLine("g02be Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= m; j++)
          {
            x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        Console.WriteLine(" ");
        Console.WriteLine("  {0}{1,5}", "Number of variables (columns) =", m);
        Console.WriteLine("  {0}{1,5}", "Number of cases     (rows)    =", n);
        Console.WriteLine(" ");
        Console.Write(" {0}", "Data matrix is:-");
        Console.Write("\r\n     ");
        for (j = 1; j <= m; j++)
        {
          Console.Write("{0,10}", j);
        }
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          Console.Write("   " + i + "    ");
          for (j = 1; j <= m; j++)
          {
            Console.Write(" {0,8:f4}", x[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        //
        //      Set up missing values before calling method
        //
        miss[0] = 1;
        miss[1] = 0;
        miss[2] = 1;
        xmiss[0] = 0.00e0;
        xmiss[2] = 0.00e0;
        //
        G02.g02be(n, m, x, miss, xmiss, xbar, std, sspz, rz, out ncases, out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02be failed with ifail = {0,5}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.Write("  {0}{1,5}", "Routine fails, ifail =", ifail);
          }
          else
          {
            Console.Write(" {0}", "Variable   Mean    St. dev.\n");
            for (i = 1; i <= m; i++)
            {
              Console.Write("     {0}  {1,10:f4}{2,10:f4}", i, xbar[i - 1], std[i - 1]);
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.Write(" {0}", ("Sums of squares and cross-products about") + (" zero"));
            Console.Write("\r\n       ");
            for (i = 1; i <= m; i++)
            {
              Console.Write("{0,13}", i);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write("\t{0}", i);
              for (j = 1; j <= m; j++)
              {
                Console.Write(" \t{0,10:f4}", sspz[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.Write(" {0}", "Correlation-like coefficients\r\n");
            Console.Write("       ");
            for (i = 1; i <= m; i++)
            {
              Console.Write("{0,14}", i);
            }
            Console.Write("\r\n    ");
            for (i = 1; i <= m; i++)
            {
              Console.Write("\t{0}", i);
              for (j = 1; j <= m; j++)
              {
                Console.Write(" \t{0,10:f4}", rz[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.WriteLine("  {0}{1,5}", "Number of cases actually used: ", ncases);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write("Exception Raised");
      }
    }
  }
}


//      g02bf Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02BFE
  {
    static string datafile = "ExampleData/g02bfe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   j,   ncases;
        const int m = 3;
        const int n = 5;
        double[,] cnt = new double[m, m];
        double[,] rz = new double[m, m];
        double[,] sspz = new double[m, m];
        double[] std = new double[m];
        double[,] x = new double[n, m];
        double[] xbar = new double[m];
        double[] xmiss = new double[m];
        int[] miss = new int[m];
        int ifail;
        Console.WriteLine("g02bf Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= m; j++)
          {
            x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        Console.Write("\r\n");
        Console.WriteLine("  {0}{1,5}", "Number of variables (columns) =", m);
        Console.WriteLine("  {0}{1,5}", "Number of cases     (rows)    =", n);
        Console.Write("\r\n");
        Console.Write(" {0}", "Data matrix is:-");
        Console.Write("\r\n    ");
        for (j = 1; j <= m; j++)
        {
          Console.Write("{0,10}", j);
        }
        Console.Write("\r\n");
        for (i = 1; i <= n; i++)
        {
          Console.Write("   " + i + "    ");
          for (j = 1; j <= m; j++)
          {
            Console.Write(" {0,8:f4}", x[i - 1, j - 1]);
          }
          Console.Write("\r\n");
        }
        Console.Write("\r\n");
        Console.Write("\r\n");
        //
        //      Set up missing values before calling method
        //
        miss[0] = 1;
        miss[1] = 1;
        miss[2] = 1;
        xmiss[0] = 0.00e0;
        xmiss[1] = -1.00e0;
        xmiss[2] = 0.00e0;
        //
        G02.g02bf(n, m, x, miss, xmiss, xbar, std, sspz, rz, out ncases, cnt, out ifail);
        //
        if (ifail < 0)
        {
          Console.Write("\r\n");
          Console.WriteLine("** g02bf failed with ifail = {0,5}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.Write("  {0}{1,5}", "Routine fails, ifail =", ifail);
          }
          else
          {
            Console.Write(" {0}", "Variable   Mean    St. dev.\n");
            for (i = 1; i <= m; i++)
            {
              Console.Write("     {0}  {1,10:f4}{2,10:f4}", i, xbar[i - 1], std[i - 1]);
              Console.Write("\r\n");
            }
            Console.Write("\r\n");
            Console.Write("\r\n");
            Console.Write(" {0}", ("Sums of squares and cross-products about") + (" zero\r\n"));
            for (i = 1; i <= m; i++)
            {
              Console.Write("{0,14}", i);
            }
            Console.Write("\r\n");
            for (i = 1; i <= m; i++)
            {
              Console.Write(" {0}", i);
              for (j = 1; j <= m; j++)
              {
                Console.Write(" \t{0,10:f4}", sspz[i - 1, j - 1]);
              }
              Console.Write("\r\n");
            }
            Console.Write("\r\n");
            Console.Write(" {0}", "Correlation-like coefficients\r\n");
            for (i = 1; i <= m; i++)
            {
              Console.Write("{0,14}", i);
            }
            Console.Write("\r\n");
            for (i = 1; i <= m; i++)
            {
              Console.Write(" {0}", i);
              for (j = 1; j <= m; j++)
              {
                Console.Write(" \t{0,10:f4}", rz[i - 1, j - 1]);
              }
              Console.Write("\r\n");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.Write("  {0}{1,5}", "Minimum number of cases used for any pair of variables: ", ncases);
            Console.WriteLine(" ");
            Console.Write(" {0}", "Numbers used for each pair are:\n");
            for (i = 1; i <= m; i++)
            {
              Console.Write(" {0,5}  ", i);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write(" {0}  ", i);
              for (j = 1; j <= m; j++)
              {
                Console.Write(" {0,5:f4}", cnt[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write("Exception Raised");
      }
    }
  }
}


//      g02bg Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02BGE
  {
    static string datafile = "ExampleData/g02bge.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   j;
        const int m = 4;
        const int n = 5;
        const int nvars = 3;
        double[,] r = new double[nvars, nvars];
        double[,] ssp = new double[nvars, nvars];
        double[] std = new double[nvars];
        double[,] x = new double[n, m];
        double[] xbar = new double[nvars];
        int[] kvar = new int[nvars];
        int ifail;
        Console.WriteLine("g02bg Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        kvar[0] = 4;
        kvar[1] = 1;
        kvar[2] = 2;
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= m; j++)
          {
            x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        Console.WriteLine(" ");
        Console.WriteLine("  {0}{1,5}", "Number of variables (columns) =", m);
        Console.WriteLine("  {0}{1,5}", "Number of cases     (rows)    =", n);
        Console.WriteLine(" ");
        Console.Write(" {0}", "Data matrix is:-");
        Console.Write("\r\n   ");
        for (j = 1; j <= m; j++)
        {
          Console.Write("{0,10}", j);
        }
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          Console.Write("   " + i + "    ");
          for (j = 1; j <= m; j++)
          {
            Console.Write(" {0,8:f4}", x[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        //
        G02.g02bg(n, m, x, nvars, kvar, xbar, std, ssp, r, out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02bg failed with ifail = {0,5}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.Write("  {0}{1,5}", "Routine fails, ifail =", ifail);
          }
          else
          {
            Console.Write(" {0}", "Variable   Mean    St. dev.\n");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write("     {0}  {1,10:f4}{2,10:f4}", kvar[i - 1], xbar[i - 1], std[i - 1]);
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.Write(" {0}", "Sums of squares and cross-products of deviations\n");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0,14}", kvar[i - 1]);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0}", kvar[i - 1]);
              for (j = 1; j <= nvars; j++)
              {
                Console.Write(" \t{0,10:f4}", ssp[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.Write(" {0}", "Correlation coefficients\n");
            Console.Write("   ");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0,11}", kvar[i - 1]);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0}", kvar[i - 1]);
              for (j = 1; j <= nvars; j++)
              {
                Console.Write(" \t{0,10:f4}", r[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02bh Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02BHE
  {
    static string datafile = "ExampleData/g02bhe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   j,   mistyp,   ncases;
        const int m = 4;
        const int n = 5;
        const int nvars = 3;
        double[,] r = new double[nvars, nvars];
        double[,] ssp = new double[nvars, nvars];
        double[] std = new double[nvars];
        double[,] x = new double[n, m];
        double[] xbar = new double[nvars];
        double[] xmiss = new double[m];
        int[] kvar = new int[nvars];
        int[] miss = new int[m];
        int ifail;
        Console.WriteLine("g02bh Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= m; j++)
          {
            x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        kvar[0] = 4;
        kvar[1] = 1;
        kvar[2] = 2;
        mistyp = 0;
        Console.WriteLine(" ");
        Console.WriteLine("  {0}{1,5}", "Number of variables (columns) =", m);
        Console.WriteLine("  {0}{1,5}", "Number of cases     (rows)    =", n);
        Console.WriteLine(" ");
        Console.Write(" {0}", "Data matrix is:-");
        Console.Write("\r\n   ");
        for (j = 1; j <= m; j++)
        {
          Console.Write("{0,10}", j);
        }
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          Console.Write("   " + i + "    ");
          for (j = 1; j <= m; j++)
          {
            Console.Write(" {0,8:f4}", x[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        //
        //      Set up missing values before calling method
        //
        miss[0] = 0;
        miss[1] = 1;
        miss[2] = 0;
        miss[3] = 1;
        xmiss[1] = 0.00e0;
        xmiss[3] = 0.00e0;
        //
        G02.g02bh(n, m, x, miss, xmiss, mistyp, nvars, kvar, xbar, std, ssp, r, out ncases,
        out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02bh failed with ifail = {0,5}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.Write("  {0}{1,5}", "Routine fails, ifail =", ifail);
          }
          else
          {
            Console.Write(" {0}", "Variable   Mean    St. dev.\n");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write("     {0}  {1,10:f4}{2,10:f4}", kvar[i - 1], xbar[i - 1], std[i - 1]);
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.Write(" {0}", "Sums of squares and cross-products of deviations\n");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0,13}", kvar[i - 1]);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0}", kvar[i - 1]);
              for (j = 1; j <= nvars; j++)
              {
                Console.Write(" \t{0,10:f4}", ssp[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.Write(" {0}", "Correlation coefficients\n");
            Console.Write("    ");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0,11}", kvar[i - 1]);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0}", kvar[i - 1]);
              for (j = 1; j <= nvars; j++)
              {
                Console.Write(" \t{0,10:f4}", r[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine("  {0}{1,5}", "Number of cases actually used:", ncases);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02bj Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02BJE
  {
    static string datafile = "ExampleData/g02bje.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   j,   ncases;
        const int m = 4;
        const int n = 5;
        const int nvars = 3;
        double[,] cnt = new double[nvars, nvars];
        double[,] r = new double[nvars, nvars];
        double[,] ssp = new double[nvars, nvars];
        double[] std = new double[nvars];
        double[,] x = new double[n, m];
        double[] xbar = new double[nvars];
        double[] xmiss = new double[m];
        int[] kvar = new int[nvars];
        int[] miss = new int[m];
        int ifail;
        Console.WriteLine("g02bj Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= m; j++)
          {
            x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        kvar[0] = 4;
        kvar[1] = 1;
        kvar[2] = 2;
        Console.WriteLine(" ");
        Console.WriteLine("  {0}{1,5}", "Number of variables (columns) =", m);
        Console.WriteLine("  {0}{1,5}", "Number of cases     (rows)    =", n);
        Console.WriteLine(" ");
        Console.Write(" {0}", "Data matrix is:-");
        Console.Write("\r\n   ");
        for (j = 1; j <= m; j++)
        {
          Console.Write("{0,10}", j);
        }
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          Console.Write("   " + i + "    ");
          for (j = 1; j <= m; j++)
          {
            Console.Write(" {0,8:f4}", x[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        //
        //      Set up missing values before calling method
        //
        miss[0] = 1;
        miss[1] = 1;
        miss[2] = 0;
        miss[3] = 1;
        xmiss[0] = -1.00e0;
        xmiss[1] = 0.00e0;
        xmiss[3] = 0.00e0;
        //
        G02.g02bj(n, m, x, miss, xmiss, nvars, kvar, xbar, std, ssp, r, out ncases, cnt,
        out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02bj failed with ifail = {0,5}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.Write("  {0}{1,5}", "Routine fails, ifail =", ifail);
          }
          else
          {
            Console.Write(" {0}", "Variable   Mean    St. dev.\n");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write("     {0}  {1,10:f4}{2,10:f4}", kvar[i - 1], xbar[i - 1], std[i - 1]);
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.Write(" {0}", "Sums of squares and cross-products of deviations\n");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0,13}", kvar[i - 1]);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0}", kvar[i - 1]);
              for (j = 1; j <= nvars; j++)
              {
                Console.Write(" \t{0,10:f4}", ssp[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.Write(" {0}", "Correlation coefficients\n");
            Console.Write("    ");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0,11}", kvar[i - 1]);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0}", kvar[i - 1]);
              for (j = 1; j <= nvars; j++)
              {
                Console.Write(" \t{0,10:f4}", r[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.Write("  {0}{1,5}", "Minimum number of cases used for any pair of variables:", ncases);
            Console.WriteLine(" ");
            Console.Write(" {0}", "Numbers used for each pair are:\n");
            Console.Write("  ");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0,13}", kvar[i - 1]);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0}", kvar[i - 1]);
              for (j = 1; j <= nvars; j++)
              {
                Console.Write(" {0,13:f4}", cnt[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02bk Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02BKE
  {
    static string datafile = "ExampleData/g02bke.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   j;
        const int m = 4;
        const int n = 5;
        const int nvars = 3;
        double[,] rz = new double[nvars, nvars];
        double[,] sspz = new double[nvars, nvars];
        double[] std = new double[nvars];
        double[,] x = new double[n, m];
        double[] xbar = new double[nvars];
        int[] kvar = new int[nvars];
        int ifail;
        Console.WriteLine("g02bk Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= m; j++)
          {
            x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        kvar[0] = 4;
        kvar[1] = 1;
        kvar[2] = 2;
        Console.WriteLine(" ");
        Console.WriteLine("  {0}{1,5}", "Number of variables (columns) =", m);
        Console.WriteLine("  {0}{1,5}", "Number of cases     (rows)    =", n);
        Console.WriteLine(" ");
        Console.Write(" {0}", "Data matrix is:-");
        Console.Write("\r\n  ");
        for (j = 1; j <= m; j++)
        {
          Console.Write("{0,10}", j);
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          Console.Write("   " + i + "    ");
          for (j = 1; j <= m; j++)
          {
            Console.Write(" {0,8:f4}", x[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        //
        G02.g02bk(n, m, x, nvars, kvar, xbar, std, sspz, rz, out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02bk failed with ifail = {0,5}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.Write("  {0}{1,5}", "Routine fails, ifail =", ifail);
          }
          else
          {
            Console.Write(" {0}", "Variable   Mean    St. dev.\n");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write("     {0}  {1,10:f4}{2,10:f4}", kvar[i - 1], xbar[i - 1], std[i - 1]);
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.Write(" {0}", ("Sums of squares and cross-products about") + (" zero\n"));
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0,13}", kvar[i - 1]);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0}", kvar[i - 1]);
              for (j = 1; j <= nvars; j++)
              {
                Console.Write(" \t{0,10:f4}", sspz[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.Write(" {0}", "Correlation-like coefficients\n");
            Console.Write("    ");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0,11}", kvar[i - 1]);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0}", kvar[i - 1]);
              for (j = 1; j <= nvars; j++)
              {
                Console.Write(" \t{0,10:f4}", rz[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02bl Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02BLE
  {
    static string datafile = "ExampleData/g02ble.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   j,   mistyp,   ncases;
        const int m = 4;
        const int n = 5;
        const int nvars = 3;
        double[,] rz = new double[nvars, nvars];
        double[,] sspz = new double[nvars, nvars];
        double[] std = new double[nvars];
        double[,] x = new double[n, m];
        double[] xbar = new double[nvars];
        double[] xmiss = new double[m];
        int[] kvar = new int[nvars];
        int[] miss = new int[m];
        int ifail;
        Console.WriteLine("g02bl Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= m; j++)
          {
            x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        kvar[0] = 4;
        kvar[1] = 1;
        kvar[2] = 2;
        mistyp = 0;
        Console.WriteLine(" ");
        Console.WriteLine("  {0}{1,5}", "Number of variables (columns) =", m);
        Console.WriteLine("  {0}{1,5}", "Number of cases     (rows)    =", n);
        Console.WriteLine(" ");
        Console.Write(" {0}", "Data matrix is:-");
        Console.Write("\r\n  ");
        for (j = 1; j <= m; j++)
        {
          Console.Write("{0,10}", j);
        }
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          Console.Write("   " + i + "    ");
          for (j = 1; j <= m; j++)
          {
            Console.Write(" {0,8:f4}", x[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        //
        //      Set up missing values before calling method
        //
        miss[0] = 0;
        miss[1] = 1;
        miss[2] = 0;
        miss[3] = 1;
        xmiss[1] = 0.00e0;
        xmiss[3] = 0.00e0;
        //
        G02.g02bl(n, m, x, miss, xmiss, mistyp, nvars, kvar, xbar, std, sspz, rz, out ncases,
        out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02bl failed with ifail = {0,5}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.Write("  {0}{1,5}", "Routine fails, ifail =", ifail);
          }
          else
          {
            Console.Write(" {0}", "Variable   Mean    St. dev.\n");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write("     {0}  {1,10:f4}{2,10:f4}", kvar[i - 1], xbar[i - 1], std[i - 1]);
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.Write(" {0}", ("Sums of squares and cross-products about") + (" zero\n"));
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0,13}", kvar[i - 1]);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0}", kvar[i - 1]);
              for (j = 1; j <= nvars; j++)
              {
                Console.Write(" \t{0,10:f4}", sspz[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.Write(" {0}", "Correlation-like coefficients\n");
            Console.Write("    ");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0,11}", kvar[i - 1]);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0}", kvar[i - 1]);
              for (j = 1; j <= nvars; j++)
              {
                Console.Write(" \t{0,10:f4}", rz[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.WriteLine("  {0}{1,5}", "Number of cases actually used:", ncases);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02bm Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02BME
  {
    static string datafile = "ExampleData/g02bme.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   j,   ncases;
        const int m = 4;
        const int n = 5;
        const int nvars = 3;
        double[,] cnt = new double[nvars, nvars];
        double[,] rz = new double[nvars, nvars];
        double[,] sspz = new double[nvars, nvars];
        double[] std = new double[nvars];
        double[,] x = new double[n, m];
        double[] xbar = new double[nvars];
        double[] xmiss = new double[m];
        int[] kvar = new int[nvars];
        int[] miss = new int[m];
        int ifail;
        Console.WriteLine("g02bm Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= m; j++)
          {
            x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        kvar[0] = 4;
        kvar[1] = 1;
        kvar[2] = 2;
        Console.WriteLine(" ");
        Console.WriteLine("  {0}{1,5}", "Number of variables (columns) =", m);
        Console.WriteLine("  {0}{1,5}", "Number of cases     (rows)    =", n);
        Console.WriteLine(" ");
        Console.Write(" {0}", "Data matrix is:-");
        Console.Write("\r\n  ");
        for (j = 1; j <= m; j++)
        {
          Console.Write("{0,10}", j);
        }
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          Console.Write("   " + i + "    ");
          for (j = 1; j <= m; j++)
          {
            Console.Write(" {0,8:f4}", x[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        //
        //      Set up missing values before calling method
        //
        miss[0] = 1;
        miss[1] = 1;
        miss[2] = 0;
        miss[3] = 1;
        xmiss[0] = -1.00e0;
        xmiss[1] = 0.00e0;
        xmiss[3] = 0.00e0;
        //
        G02.g02bm(n, m, x, miss, xmiss, nvars, kvar, xbar, std, sspz, rz, out ncases, cnt,
        out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02bm failed with ifail = {0,5}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.Write("  {0}{1,5}", "Routine fails, ifail =", ifail);
          }
          else
          {
            Console.Write(" {0}", "Variable   Mean    St. dev.\n");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write("     {0}  {1,10:f4}{2,10:f4}", kvar[i - 1], xbar[i - 1], std[i - 1]);
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.Write(" {0}", ("Sums of squares and cross-products about") + (" zero\n\n"));
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0,13}", kvar[i - 1]);
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0}", kvar[i - 1]);
              for (j = 1; j <= nvars; j++)
              {
                Console.Write(" \t{0,10:f4}", sspz[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.Write(" {0}", "Correlation-like coefficients\n\n");
            Console.Write("");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0,13}", kvar[i - 1]);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0}", kvar[i - 1]);
              for (j = 1; j <= nvars; j++)
              {
                Console.Write(" \t{0,10:f4}", rz[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.Write("  {0}{1,5}", "Minimum number of cases used for any pair of variables:", ncases);
            Console.WriteLine(" ");
            Console.Write(" {0}", "Numbers used for each pair are:\n\n");
            Console.Write("");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0,13}", kvar[i - 1]);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= nvars; i++)
            {
              Console.Write(" {0}", kvar[i - 1]);
              for (j = 1; j <= nvars; j++)
              {
                Console.Write(" {0,13:f4}", cnt[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02bn Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02BNE
  {
    static string datafile = "ExampleData/g02bne.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        const int m = 3;
        const int n = 9;
        int i,   itype,   j; double[,] rr = new double[m, m];
        double[,] x = new double[n, m];
        int ifail;
        Console.WriteLine("g02bn Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= m; j++)
          {
            x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        Console.WriteLine(" ");
        Console.WriteLine("  {0}{1,5}", "Number of variables (columns) =", m);
        Console.WriteLine("  {0}{1,5}", "Number of cases     (rows)    =", n);
        Console.WriteLine(" ");
        Console.Write(" {0}", "Data matrix is:-");
        Console.Write("\r\n  ");
        for (j = 1; j <= m; j++)
        {
          Console.Write("{0,10}", j);
        }
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          Console.Write("   " + i + "    ");
          for (j = 1; j <= m; j++)
          {
            Console.Write(" {0,8:f4}", x[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        itype = 0;
        //
        G02.g02bn(n, m, x, itype, rr, out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02bn failed with ifail = {0,5}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.Write("  {0}{1,5}", "Routine fails, ifail =", ifail);
          }
          else
          {
            Console.Write(" {0}", "Matrix of ranks:-");
            Console.WriteLine(" ");
            for (j = 1; j <= m; j++)
            {
              Console.Write(" {0,7} ", j);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= n; i++)
            {
              Console.Write(" {0}", i);
              for (j = 1; j <= m; j++)
              {
                Console.Write(" {0,8:f4}", x[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "Matrix of rank correlation coefficients:");
            Console.WriteLine(" {0}", "Upper triangle -- Spearman's");
            Console.WriteLine(" {0}", "Lower triangle -- Kendall's tau");
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write(" {0,10}", i);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write(" {0}", i);
              for (j = 1; j <= m; j++)
              {
                Console.Write(" {0,10:f4}", rr[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02bp Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02BPE
  {
    static string datafile = "ExampleData/g02bpe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   itype,   j,   ncases;
        const int m = 3;
        const int n = 9;
        double[,] rr = new double[m, m];
        double[,] x = new double[n, m];
        double[] xmiss = new double[m];
        int[] incase = new int[n];
        int[] miss = new int[m];
        int ifail;
        Console.WriteLine("g02bp Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= m; j++)
          {
            x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        Console.WriteLine(" ");
        Console.WriteLine("  {0}{1,5}", "Number of variables (columns) =", m);
        Console.WriteLine("  {0}{1,5}", "Number of cases     (rows)    =", n);
        Console.WriteLine(" ");
        Console.Write(" {0}", "Data matrix is:-");
        Console.Write("\r\n  ");
        for (j = 1; j <= m; j++)
        {
          Console.Write("{0,10}", j);
        }
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          Console.Write("   " + i + "    ");
          for (j = 1; j <= m; j++)
          {
            Console.Write(" {0,8:f4}", x[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        //
        //      Set up missing values before calling method
        //
        miss[0] = 1;
        miss[1] = 0;
        miss[2] = 1;
        xmiss[0] = 0.990e0;
        xmiss[2] = 0.000e0;
        itype = 0;
        //
        G02.g02bp(n, m, x, miss, xmiss, itype, rr, out ncases, incase, out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02bp failed with ifail = {0,5}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.Write("  {0}{1,5}", "Routine fails, ifail =", ifail);
          }
          else
          {
            Console.Write(" {0}", "Matrix of ranks:-");
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "(1 in the column headed In/Out indicates the case was included,");
            Console.WriteLine(" {0}", " 0 in the column headed In/Out indicates the case was omitted.)");
            Console.WriteLine(" ");
            Console.Write(" {0}", "Case   In/Out");
            for (j = 1; j <= m; j++)
            {
              Console.Write(" {0,8}", j);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= n; i++)
            {
              Console.Write(" {0, 3} {1, 7}", i, incase[i-1]);
              for (j = 1; j <= m; j++)
              {
                Console.Write(" {0,10:f4}", x[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "Matrix of rank correlation coefficients:");
            Console.WriteLine(" {0}", "Upper triangle -- Spearman's");
            Console.WriteLine(" {0}", "Lower triangle -- Kendall's tau");
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write(" {0,10}", i);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write(" {0}", i);
              for (j = 1; j <= m; j++)
              {
                Console.Write(" {0,10:f4}", rr[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.WriteLine("  {0}{1,5}", "Number of cases actually used:", ncases);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02bq Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02BQE
  {
    static string datafile = "ExampleData/g02bqe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   itype,   j;
        const int m = 3;
        const int n = 9;
        double[,] rr = new double[m, m];
        double[,] x = new double[n, m];
        int ifail;
        Console.WriteLine("g02bq Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= m; j++)
          {
            x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        Console.WriteLine(" ");
        Console.WriteLine("  {0}{1,5}", "Number of variables (columns) =", m);
        Console.WriteLine("  {0}{1,5}", "Number of cases     (rows)    =", n);
        Console.WriteLine(" ");
        Console.Write(" {0}", "Data matrix is:-");
        Console.Write("\r\n ");
        for (j = 1; j <= m; j++)
        {
          Console.Write(" {0,7} ", j);
        }
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          Console.Write(" {0}", i);
          for (j = 1; j <= m; j++)
          {
            Console.Write(" {0,8:f4}", x[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        itype = 0;
        //
        G02.g02bq(n, m, x, itype, rr, out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02bq failed with ifail = {0,5}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.Write("  {0}{1,5}", "Routine fails, ifail =", ifail);
          }
          else
          {
            Console.WriteLine(" {0}", "Matrix of rank correlation coefficients:");
            Console.WriteLine(" {0}", "Upper triangle -- Spearman's");
            Console.WriteLine(" {0}", "Lower triangle -- Kendall's tau");
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write(" {0,10}", i);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write(" {0}", i);
              for (j = 1; j <= m; j++)
              {
                Console.Write(" {0,10:f4}", rr[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02br Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02BRE
  {
    static string datafile = "ExampleData/g02bre.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   itype,   j,   ncases;
        const int m = 3;
        const int n = 9;
        double[,] rr = new double[m, m];
        double[,] x = new double[n, m];
        double[] xmiss = new double[m];
        int[] incase = new int[n];
        int[] miss = new int[m];
        int ifail;
        Console.WriteLine("g02br Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= m; j++)
          {
            x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        Console.WriteLine(" ");
        Console.WriteLine("  {0}{1,5}", "Number of variables (columns) =", m);
        Console.WriteLine("  {0}{1,5}", "Number of cases     (rows)    =", n);
        Console.WriteLine(" ");
        Console.Write(" {0}", "Data matrix is:-");
        Console.Write("\r\n ");
        for (j = 1; j <= m; j++)
        {
          Console.Write(" {0,7} ", j);
        }
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          Console.Write(" {0}", i);
          for (j = 1; j <= m; j++)
          {
            Console.Write(" {0,8:f4}", x[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        //
        //      Set up missing values before calling method
        //
        miss[0] = 1;
        miss[1] = 0;
        miss[2] = 1;
        xmiss[0] = 0.990e0;
        xmiss[2] = 0.000e0;
        itype = 0;
        //
        G02.g02br(n, m, x, miss, xmiss, itype, rr, out ncases, incase, out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02br failed with ifail = {0,5}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.Write("  {0}{1,5}", "Routine fails, ifail =", ifail);
          }
          else
          {
            Console.WriteLine(" {0}", "Matrix of rank correlation coefficients:");
            Console.WriteLine(" {0}", "Upper triangle -- Spearman's");
            Console.WriteLine(" {0}", "Lower triangle -- Kendall's tau");
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write(" {0,10}", i);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write(" {0}", i);
              for (j = 1; j <= m; j++)
              {
                Console.Write(" {0,10:f4}", rr[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.WriteLine("  {0}{1,5}", "Number of cases actually used:", ncases);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02bs Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02BSE
  {
    static string datafile = "ExampleData/g02bse.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   itype,   j,   ncases;
        const int m = 3;
        const int n = 9;
        double[,] cnt = new double[m, m];
        double[,] rr = new double[m, m];
        double[,] x = new double[n, m];
        double[] xmiss = new double[m];
        int[] miss = new int[m];
        int ifail;
        Console.WriteLine("g02bs Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= m; j++)
          {
            x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        Console.WriteLine(" ");
        Console.WriteLine("  {0}{1,5}", "Number of variables (columns) =", m);
        Console.WriteLine("  {0}{1,5}", "Number of cases     (rows)    =", n);
        Console.WriteLine(" ");
        Console.Write(" {0}", "Data matrix is:-");
        Console.Write("\r\n ");
        for (j = 1; j <= m; j++)
        {
          Console.Write(" {0,7} ", j);
        }
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          Console.Write(" {0}", i);
          for (j = 1; j <= m; j++)
          {
            Console.Write(" {0,8:f4}", x[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        //
        //      Set up missing values before calling method
        //
        miss[0] = 1;
        miss[1] = 1;
        miss[2] = 1;
        xmiss[0] = 0.990e0;
        xmiss[1] = 9.00e0;
        xmiss[2] = 0.000e0;
        itype = 0;
        //
        G02.g02bs(n, m, x, miss, xmiss, itype, rr, out ncases, cnt, out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02bs failed with ifail = {0,5}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.Write("  {0}{1,5}", "Routine fails, ifail =", ifail);
          }
          else
          {
            Console.WriteLine(" {0}", "Matrix of rank correlation coefficients:");
            Console.WriteLine(" {0}", "Upper triangle -- Spearman's");
            Console.WriteLine(" {0}", "Lower triangle -- Kendall's tau");
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write(" {0,10}", i);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write(" {0}", i);
              for (j = 1; j <= m; j++)
              {
                Console.Write(" {0,10:f4}", rr[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.Write("  {0}{1,5}", "Minimum number of cases used for any pair of variables:", ncases);
            Console.WriteLine(" ");
            Console.Write(" {0}", "Numbers used for each pair are:\n\n");
            for (i = 1; i <= m; i++)
            {
              Console.Write(" {0,10}", i);
            }
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write(" {0}", i);
              for (j = 1; j <= m; j++)
              {
                Console.Write(" {0,10:f4}", cnt[i - 1, j - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02bt Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02BTE
  {
    static string datafile = "ExampleData/g02bte.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        const double one = 1.00e0;
        const int incx = 1;
        double alpha,   sw,   wt; int i,  j,  m,  mm,  n,  nprint;
        string mean = "";
        int ifail;
        Console.WriteLine("g02bt Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        try
        {
          sr.Reset();
          mean = sr.Next();
          m = int.Parse(sr.Next());
          n = int.Parse(sr.Next());
          nprint = int.Parse(sr.Next());
        }
        catch
        {
          goto L40;
        }
        sw = 0.00e0;
        double[] c = new double[(m*m+m)/2];
        double[] v = new double[(m*m+m)/2];
        double[] x = new double[m*incx];
        double[] xbar = new double[m];
        if (m >= 1)
        {
          for (i = 1; i <= n; i++)
          {
            sr.Reset();
            wt = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            for (j = 1; j <= m; j++)
            {
              x[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            //
            //            Calculate the sums of squares and cross-products matrix
            G02.g02bt(mean, m, wt, x, incx, ref sw, xbar, c, out ifail);
            if (ifail == 0)
            {
              //
              if (((i % nprint) == 0) || (i == n))
              {
                Console.WriteLine(" ");
                Console.WriteLine(" {0}", "---------------------------------------------");
                Console.WriteLine("  {0}{1,4}{2}{3,13:f4}", "Observation: ", i, "      Weight = ", wt);
                Console.WriteLine(" {0}", "---------------------------------------------");
                Console.WriteLine(" ");
                Console.WriteLine(" {0}", "Means");
                for (j = 1; j <= m; j++)
                {
                  Console.Write(" {0,10:f4}", xbar[j - 1]);
                }
                Console.WriteLine(" ");
                Console.WriteLine(" ");
                //                  Print the sums of squares and cross products matrix
                X04.x04cc("Upper", "Non-unit", m, c, "Sums of squares and cross-products", out ifail);
                if (sw > one)
                {
                  //                     Calculate the variance matrix
                  alpha = one / (sw - one);
                  mm = (m * (m + 1)) / 2;
                  F06.f06fd(mm, alpha, c, 1, v, 1, out ifail);
                  //                     Print the variance matrix
                  Console.WriteLine(" ");
                  X04.x04cc("Upper", "Non-unit", m, v, "Variance matrix", out ifail);
                }
              }
            }
            else
            {
              Console.WriteLine(" ");
              Console.WriteLine("** g02bt failed with ifail = {0,5}", ifail);
              goto L40;
            }
          }
        }
        else
        {
          Console.Write("  {0}{1,5}", "M is too large. M =", m);
        }
        L40: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02bu Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02BUE
  {
    static string datafile = "ExampleData/g02bue.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        const double one = 1.00e0;
        double alpha,   sw; int j,  k,  m,  mm,  n;
        string mean = "",
        weight = "";
        int ifail;
        Console.WriteLine("g02bu Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        try
        {
          sr.Reset();
          mean = sr.Next();
          weight = sr.Next();
          m = int.Parse(sr.Next());
          n = int.Parse(sr.Next());
        }
        catch
        {
          goto L20;
        }
        double[] c = new double[(m*m+m)/2];
        double[] v = new double[(m*m+m)/2];
        double[] wmean = new double[m];
        double[] wt = new double[n];
        double[,] x = new double[n, m];
        if (m >= 1 && n >= 1)
        {
          sr.Reset();
          for (j = 1; j <= n; j++)
          {
            wt[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          sr.Reset();
          for (j = 1; j <= n; j++)
          {
            for (k = 1; k <= m; k++)
            {
              x[j - 1, k - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //
          //         Calculate sums of squares and cross-products matrix
          G02.g02bu(mean, weight, n, m, x, wt, out sw, wmean, c, out ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine(" ");
            Console.Write(" {0}", "Means\n\n");
            for (j = 1; j <= m; j++)
            {
              Console.Write(" {0,10:f4}", wmean[j - 1]);
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.Write(" {0}", "Weights\n\n");
            for (j = 1; j <= n; j++)
            {
              Console.Write(" {0,10:f4}", wt[j - 1]);
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            //            Print the sums of squares and cross products matrix
            X04.x04cc("Upper", "Non-unit", m, c, "Sums of squares and cross-products", out ifail);
            if (sw > one)
            {
              //               Calculate the variance matrix
              alpha = one / (sw - one);
              mm = (m * (m + 1)) / 2;
              F06.f06fd(mm, alpha, c, 1, v, 1, out ifail);
              //               Print the variance matrix
              Console.WriteLine(" ");
              X04.x04cc("Upper", "Non-unit", m, v, "Variance matrix", out ifail);
            }
          }
          else
          {
            Console.WriteLine(" ");
            Console.WriteLine("** g02bu failed with ifail = {0,5}", ifail);
          }
        }
        else
        {
          Console.Write("  {0}{1,6}{2}{3,6}", "M or N is too large. M =", m, ", N =", n);
        }
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02bw Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02BWE
  {
    static string datafile = "ExampleData/g02bwe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double sw = 0.0;
        int j,   k,   m,   n; string mean = "",  weight = "";
        int ifail;
        Console.WriteLine("g02bw Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        try
        {
          sr.Reset();
          mean = sr.Next();
          weight = sr.Next();
          m = int.Parse(sr.Next());
          n = int.Parse(sr.Next());
        }
        catch
        {
          goto L20;
        }
        double[] r = new double[(m*m+m)/2];
        double[] wmean = new double[m];
        double[] wt = new double[n];
        double[,] x = new double[n, m];
        if (m >=1 && n >= 1)
        {
          sr.Reset();
          for (j = 1; j <= n; j++)
          {
            wt[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          sr.Reset();
          for (j = 1; j <= n; j++)
          {
            for (k = 1; k <= m; k++)
            {
              x[j - 1, k - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //
          //         Calculate the sums of squares and cross-products matrix
          G02.g02bu(mean, weight, n, m, x, wt, out sw, wmean, r, out ifail);
          //
          if (ifail == 0)
          {
            //
            //            Calculate the correlation matrix
            G02.g02bw(m, r, out ifail);
            //
            //            Print the correlation matrix
            if (ifail == 0)
            {
              Console.WriteLine(" ");
              X04.x04cc("Upper", "Non-unit", m, r, "Correlation matrix", out ifail);
            }
            else if (ifail == 2)
            {
              Console.WriteLine(" ");
              Console.Write(" {0}", " NOTE: some variances are zero");
              Console.WriteLine(" ");
              X04.x04cc("Upper", "Non-unit", m, r, "Correlation matrix", out ifail);
            }
            else
            {
              Console.WriteLine(" ");
              Console.WriteLine("** g02bw failed with ifail = {0,5}", ifail);
            }
          }
          else
          {
            Console.WriteLine(" ");
            Console.WriteLine("** g02bu failed with ifail = {0,5}", ifail);
          }
        }
        else
        {
          Console.Write("  {0}{1,6}{2}{3,6}", "M or N is too large. M =", m, ", N =", n);
        }
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02bx Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02BXE
  {
    static string datafile = "ExampleData/g02bxe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   j,   m,   n; string weight = "";
        int ifail;
        Console.WriteLine("g02bx Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        weight = sr.Next();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        double[,] r = new double[m, m];
        double[] std = new double[m];
        double[,] v = new double[m, m];
        double[] wt = new double[n];
        double[,] x = new double[n, m];
        double[] xbar = new double[m];
        if (m >= 1 && n > 1)
        {
          if ((weight == "W") || (weight == "w"))
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              wt[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          else
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
            }
          }
          //
          G02.g02bx(weight, n, m, x, wt, xbar, std, v, r, out ifail);
          //
          if ((ifail == 0) || (ifail == 5))
          {
            Console.WriteLine(" ");
            Console.Write(" {0}", "     Means");
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write(" {0,10:f4}", xbar[i - 1]);
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.Write(" {0}", "     Standard deviations");
            Console.WriteLine(" ");
            for (i = 1; i <= m; i++)
            {
              Console.Write(" {0,10:f4}", std[i - 1]);
            }
            Console.WriteLine(" ");
            //
            //            Print the correlation matrix
            //
            if (ifail == 5)
            {
              Console.WriteLine(" ");
              Console.Write(" {0}", " NOTE: some variances are zero");
            }
            Console.WriteLine(" ");
            X04.x04ca("Upper", "Non-unit", m, m, r, "     Correlation matrix", out ifail);
            Console.WriteLine(" ");
          }
          else
          {
            Console.WriteLine(" ");
            Console.WriteLine("** g02bx failed with ifail = {0,5}", ifail);
          }
        }
        else
        {
          Console.Write("  {0}{1,6}{2}{3,6}", "M or N is too large. M =", m, ", N =", n);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02by Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02BYE
  {
    static string datafile = "ExampleData/g02bye.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int j,   k,   m,   n,   nx,   ny; int ifail;
        Console.WriteLine("g02by Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        double[,] p = new double[m, m];
        double[,] r = new double[m, m];
        double[] std = new double[m];
        double[] wt = new double[n];
        double[,] x = new double[n, m];
        double[] xbar = new double[m];
        int[] isz = new int[m];
        if (m >=1 && n >= 1)
        {
          sr.Reset();
          for (j = 1; j <= n; j++)
          {
            for (k = 1; k <= m; k++)
            {
              x[j - 1, k - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //
          //         Calculate correlation matrix
          //
          //
          G02.g02bx("U", n, m, x, wt, xbar, std, r, p, out ifail);
          //
          if (ifail == 0)
          {
            //
            //            Print the correlation matrix
            //
            Console.WriteLine(" ");
            X04.x04ca("Upper", "Non-unit", m, m, p, "Correlation matrix", out ifail);
            sr.Reset();
            ny = int.Parse(sr.Next());
            nx = int.Parse(sr.Next());
            sr.Reset();
            for (j = 1; j <= m; j++)
            {
              isz[j - 1] = int.Parse(sr.Next());
            }
            //
            //            Calculate partial correlation matrix
            //
            //
            G02.g02by(m, ny, nx, isz, r, p, out ifail);
            //
            if (ifail == 0)
            {
              //
              //               Print partial correlation matrix
              //
              Console.WriteLine(" ");
              X04.x04ca("Upper", "Unit", ny, ny, p, "Partial Correlation matrix", out ifail);
            }
            else
            {
              Console.WriteLine(" ");
              Console.WriteLine("** g02by failed with ifail = {0,5}", ifail);
            }
          }
          else
          {
            Console.WriteLine(" ");
            Console.WriteLine("** g02bx failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02ca Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02CAE
  {
    static string datafile = "ExampleData/g02cae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i = 0;
        const int n = 8;
        double[] result = new double[20];
        double[] x = new double[n];
        double[] y = new double[n];
        int ifail;
        Console.WriteLine("g02ca Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        Console.WriteLine(" ");
        Console.WriteLine(" {0}", " Case     Independent     Dependent");
        Console.Write(" {0}", "number     variable       variable");
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          Console.Write("   {0}{1,15:f4}{2,15:f4}", i, x[i - 1], y[i - 1]);
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        //
        G02.g02ca(n, x, y, result, out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02ca failed with ifail = {0,5}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.Write("  {0}{1,5}", "Routine fails, ifail =", ifail);
          }
          else
          {
            Console.WriteLine("  {0}{1,8:f4}", "Mean of independent variable               = ", result[0]);
            Console.WriteLine("  {0}{1,8:f4}", "Mean of   dependent variable               = ", result[1]);
            Console.WriteLine("  {0}{1,8:f4}", "Standard deviation of independent variable = ", result[2]);
            Console.WriteLine("  {0}{1,8:f4}", "Standard deviation of   dependent variable = ", result[3]);
            Console.WriteLine("  {0}{1,8:f4}", "Correlation coefficient                    = ", result[4]);
            Console.WriteLine(" ");
            Console.WriteLine("  {0}{1,8:f4}", "Regression coefficient                     = ", result[5]);
            Console.WriteLine("  {0}{1,8:f4}", "Standard error of coefficient              = ", result[7]);
            Console.WriteLine("  {0}{1,8:f4}", "t-value for coefficient                    = ", result[9]);
            Console.WriteLine(" ");
            Console.WriteLine("  {0}{1,8:f4}", "Regression constant                        = ", result[6]);
            Console.WriteLine("  {0}{1,8:f4}", "Standard error of constant                 = ", result[8]);
            Console.WriteLine("  {0}{1,8:f4}", "t-value for constant                       = ", result[10]);
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "Analysis of regression table :-");
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "      Source        Sum of squares  D.F.    Mean square     F-value");
            Console.WriteLine(" ");
            Console.Write(" {0}", "Due to regression");
            for (i = 12; i <= 15; i++)
            {
              Console.Write(" {0,11:f3}", result[i - 1]);
            }
            Console.WriteLine(" ");
            Console.Write(" {0}", "About  regression");
            for (i = 16; i <= 18; i++)
            {
              Console.Write(" {0,11:f3}", result[i - 1]);
            }
            Console.WriteLine(" ");
            Console.Write(" {0}", "Total            ");
            for (i = 19; i <= 20; i++)
            {
              Console.Write(" {0,11:f3}", result[i - 1]);
            }
            Console.WriteLine(" ");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write("Exception Raised");
      }
    }
  }
}


g02ca Example Program Results

  Case     Independent     Dependent
 number     variable       variable
   1         1.0000        20.0000
   2         0.0000        15.5000
   3         4.0000        28.3000
   4         7.5000        45.0000
   5         2.5000        24.5000
   6         0.0000        10.0000
   7        10.0000        99.0000
   8         5.0000        31.2000

  Mean of independent variable               =   3.7500
  Mean of   dependent variable               =  34.1875
  Standard deviation of independent variable =   3.6253
  Standard deviation of   dependent variable =  28.2604
  Correlation coefficient                    =   0.9096

  Regression coefficient                     =   7.0905
  Standard error of coefficient              =   1.3224
  t-value for coefficient                    =   5.3620

  Regression constant                        =   7.5982
  Standard error of constant                 =   6.6858
  t-value for constant                       =   1.1365

 Analysis of regression table :-

       Source        Sum of squares  D.F.    Mean square     F-value

 Due to regression    4625.303       1.000    4625.303      28.751
 About  regression     965.245       6.000     160.874
 Total                5590.549       7.000


//      g02cb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02CBE
  {
    static string datafile = "ExampleData/g02cbe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i = 0;
        const int n = 8;
        double[] result = new double[20];
        double[] x = new double[n];
        double[] y = new double[n];
        int ifail;
        Console.WriteLine("g02cb Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        Console.WriteLine(" ");
        Console.WriteLine(" {0}", " Case     Independent     Dependent");
        Console.Write(" {0}", "number     variable       variable");
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          Console.Write("   {0}{1,15:f4}{2,15:f4}", i, x[i - 1], y[i - 1]);
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        //
        G02.g02cb(n, x, y, result, out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02cb failed with ifail = {0,5}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.Write("  {0}{1,5}", "Routine fails, ifail =", ifail);
          }
          else
          {
            Console.WriteLine("  {0}{1,8:f4}", "Mean of independent variable               = ", result[0]);
            Console.WriteLine("  {0}{1,8:f4}", "Mean of   dependent variable               = ", result[1]);
            Console.WriteLine("  {0}{1,8:f4}", "Standard deviation of independent variable = ", result[2]);
            Console.WriteLine("  {0}{1,8:f4}", "Standard deviation of   dependent variable = ", result[3]);
            Console.WriteLine("  {0}{1,8:f4}", "Correlation coefficient                    = ", result[4]);
            Console.WriteLine(" ");
            Console.WriteLine("  {0}{1,8:f4}", "Regression coefficient                     = ", result[5]);
            Console.WriteLine("  {0}{1,8:f4}", "Standard error of coefficient              = ", result[7]);
            Console.WriteLine("  {0}{1,8:f4}", "t-value for coefficient                    = ", result[9]);
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "Analysis of regression table :-");
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "      Source        Sum of squares  D.F.    Mean square     F-value");
            Console.WriteLine(" ");
            Console.Write(" {0}", "Due to regression");
            for (i = 12; i <= 15; i++)
            {
              Console.Write(" {0,11:f3}", result[i - 1]);
            }
            Console.WriteLine(" ");
            Console.Write(" {0}", "About  regression");
            for (i = 16; i <= 18; i++)
            {
              Console.Write(" {0,11:f3}", result[i - 1]);
            }
            Console.WriteLine(" ");
            Console.Write(" {0}", "Total            ");
            for (i = 19; i <= 20; i++)
            {
              Console.Write(" {0,11:f3}", result[i - 1]);
            }
            Console.WriteLine(" ");
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


g02cb Example Program Results

  Case     Independent     Dependent
 number     variable       variable
   1         1.0000        20.0000
   2         0.0000        15.5000
   3         4.0000        28.3000
   4         7.5000        45.0000
   5         2.5000        24.5000
   6         0.0000        10.0000
   7        10.0000        99.0000
   8         5.0000        31.2000

  Mean of independent variable               =   3.7500
  Mean of   dependent variable               =  34.1875
  Standard deviation of independent variable =   3.6253
  Standard deviation of   dependent variable =  28.2604
  Correlation coefficient                    =   0.9096

  Regression coefficient                     =   8.2051
  Standard error of coefficient              =   0.9052
  t-value for coefficient                    =   9.0642

 Analysis of regression table :-

       Source        Sum of squares  D.F.    Mean square     F-value

 Due to regression   13767.805       1.000   13767.805      82.159
 About  regression    1173.025       7.000     167.575
 Total               14940.830       8.000


//      g02cc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02CCE
  {
    static string datafile = "ExampleData/g02cce.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        const int n = 8;
        double xmiss,   ymiss; int i;
        double[] result = new double[21];
        double[] x = new double[n];
        double[] y = new double[n];
        int ifail;
        Console.WriteLine("g02cc Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        Console.WriteLine(" ");
        Console.WriteLine(" {0}", " Case     Independent     Dependent");
        Console.Write(" {0}", "number     variable       variable");
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          Console.Write("   {0}{1,15:f4}{2,15:f4}", i, x[i - 1], y[i - 1]);
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        //
        //      Set up missing values
        //
        xmiss = 0.00e0;
        ymiss = 99.00e0;
        //
        G02.g02cc(n, x, y, xmiss, ymiss, result, out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02cc failed with ifail = {0,5}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.Write("  {0}{1,5}", "Routine fails, ifail =", ifail);
          }
          else
          {
            Console.WriteLine("  {0}{1,8:f4}", "Mean of independent variable               = ", result[0]);
            Console.WriteLine("  {0}{1,8:f4}", "Mean of   dependent variable               = ", result[1]);
            Console.WriteLine("  {0}{1,8:f4}", "Standard deviation of independent variable = ", result[2]);
            Console.WriteLine("  {0}{1,8:f4}", "Standard deviation of   dependent variable = ", result[3]);
            Console.WriteLine("  {0}{1,8:f4}", "Correlation coefficient                    = ", result[4]);
            Console.WriteLine(" ");
            Console.WriteLine("  {0}{1,8:f4}", "Regression coefficient                     = ", result[5]);
            Console.WriteLine("  {0}{1,8:f4}", "Standard error of coefficient              = ", result[7]);
            Console.WriteLine("  {0}{1,8:f4}", "t-value for coefficient                    = ", result[9]);
            Console.WriteLine(" ");
            Console.WriteLine("  {0}{1,8:f4}", "Regression constant                        = ", result[6]);
            Console.WriteLine("  {0}{1,8:f4}", "Standard error of constant                 = ", result[8]);
            Console.WriteLine("  {0}{1,8:f4}", "t-value for constant                       = ", result[10]);
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "Analysis of regression table :-");
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "      Source        Sum of squares  D.F.    Mean square     F-value");
            Console.WriteLine(" ");
            Console.Write(" {0}", "Due to regression");
            for (i = 12; i <= 15; i++)
            {
              Console.Write(" {0,11:f3}", result[i - 1]);
            }
            Console.WriteLine(" ");
            Console.Write(" {0}", "About  regression");
            for (i = 16; i <= 18; i++)
            {
              Console.Write(" {0,11:f3}", result[i - 1]);
            }
            Console.WriteLine(" ");
            Console.Write(" {0}", "Total            ");
            for (i = 19; i <= 20; i++)
            {
              Console.Write(" {0,11:f3}", result[i - 1]);
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.WriteLine("  {0}{1,3:f0}", "Number of cases used = ", result[20]);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


g02cc Example Program Results

  Case     Independent     Dependent
 number     variable       variable
   1         1.0000        20.0000
   2         0.0000        15.5000
   3         4.0000        28.3000
   4         7.5000        45.0000
   5         2.5000        24.5000
   6         0.0000        10.0000
   7        10.0000        99.0000
   8         5.0000        31.2000

  Mean of independent variable               =   4.0000
  Mean of   dependent variable               =  29.8000
  Standard deviation of independent variable =   2.4749
  Standard deviation of   dependent variable =   9.4787
  Correlation coefficient                    =   0.9799

  Regression coefficient                     =   3.7531
  Standard error of coefficient              =   0.4409
  t-value for coefficient                    =   8.5128

  Regression constant                        =  14.7878
  Standard error of constant                 =   2.0155
  t-value for constant                       =   7.3370

 Analysis of regression table :-

       Source        Sum of squares  D.F.    Mean square     F-value

 Due to regression     345.094       1.000     345.094      72.468
 About  regression      14.286       3.000       4.762
 Total                 359.380       4.000

  Number of cases used =   5


//      g02cd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02CDE
  {
    static string datafile = "ExampleData/g02cde.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        const int n = 8;
        double xmiss,   ymiss; int i;
        double[] result = new double[21];
        double[] x = new double[n];
        double[] y = new double[n];
        int ifail;
        Console.WriteLine("g02cd Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        Console.WriteLine(" ");
        Console.WriteLine(" {0}", " Case     Independent     Dependent");
        Console.Write(" {0}", "number     variable       variable");
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          Console.Write("   {0}{1,15:f4}{2,15:f4}", i, x[i - 1], y[i - 1]);
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        //
        //      Set up missing values
        //
        xmiss = 0.00e0;
        ymiss = 99.00e0;
        //
        G02.g02cd(n, x, y, xmiss, ymiss, result, out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02cd failed with ifail = {0,5}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.Write("  {0}{1,5}", "Routine fails, ifail =", ifail);
          }
          else
          {
            Console.WriteLine("  {0}{1,8:f4}", "Mean of independent variable               = ", result[0]);
            Console.WriteLine("  {0}{1,8:f4}", "Mean of   dependent variable               = ", result[1]);
            Console.WriteLine("  {0}{1,8:f4}", "Standard deviation of independent variable = ", result[2]);
            Console.WriteLine("  {0}{1,8:f4}", "Standard deviation of   dependent variable = ", result[3]);
            Console.WriteLine("  {0}{1,8:f4}", "Correlation coefficient                    = ", result[4]);
            Console.WriteLine(" ");
            Console.WriteLine("  {0}{1,8:f4}", "Regression coefficient                     = ", result[5]);
            Console.WriteLine("  {0}{1,8:f4}", "Standard error of coefficient              = ", result[7]);
            Console.WriteLine("  {0}{1,8:f4}", "t-value for coefficient                    = ", result[9]);
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "Analysis of regression table :-");
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "      Source        Sum of squares  D.F.    Mean square     F-value");
            Console.WriteLine(" ");
            Console.Write(" {0}", "Due to regression");
            for (i = 12; i <= 15; i++)
            {
              Console.Write(" {0,11:f3}", result[i - 1]);
            }
            Console.WriteLine(" ");
            Console.Write(" {0}", "About  regression");
            for (i = 16; i <= 18; i++)
            {
              Console.Write(" {0,11:f3}", result[i - 1]);
            }
            Console.WriteLine(" ");
            Console.Write(" {0}", "Total            ");
            for (i = 19; i <= 20; i++)
            {
              Console.Write(" {0,11:f3}", result[i - 1]);
            }
            Console.WriteLine(" ");
            Console.WriteLine(" ");
            Console.WriteLine("  {0}{1,3:f0}", "Number of cases used = ", result[20]);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


g02cd Example Program Results

  Case     Independent     Dependent
 number     variable       variable
   1         1.0000        20.0000
   2         0.0000        15.5000
   3         4.0000        28.3000
   4         7.5000        45.0000
   5         2.5000        24.5000
   6         0.0000        10.0000
   7        10.0000        99.0000
   8         5.0000        31.2000

  Mean of independent variable               =   4.0000
  Mean of   dependent variable               =  29.8000
  Standard deviation of independent variable =   2.4749
  Standard deviation of   dependent variable =   9.4787
  Correlation coefficient                    =   0.9799

  Regression coefficient                     =   6.5833
  Standard error of coefficient              =   0.8046
  t-value for coefficient                    =   8.1816

 Analysis of regression table :-

       Source        Sum of squares  D.F.    Mean square     F-value

 Due to regression    4528.949       1.000    4528.949      66.939
 About  regression     270.631       4.000      67.658
 Total                4799.580       5.000

  Number of cases used =   5


//      g02ce Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02CEE
  {
    static string datafile = "ExampleData/g02cee.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   j;
        const int n = 4;
        const int m = 3;
        double[,] r = new double[n, n];
        double[,] r2 = new double[m, m];
        double[,] ssp = new double[n, n];
        double[,] ssp2 = new double[m, m];
        double[] std = new double[n];
        double[] std2 = new double[m];
        double[] xbar = new double[n];
        double[] xbar2 = new double[m];
        int[] korder = new int[m];
        int ifail;
        Console.WriteLine("g02ce Example Program Results");
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          xbar[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        for (i = 1; i <= n; i++)
        {
          std[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= n; j++)
          {
            ssp[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= n; j++)
          {
            r[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        Console.WriteLine(" ");
        Console.Write(" {0}", "Original vector XBAR :   ");
        for (i = 1; i <= n; i++)
        {
          Console.Write(" {0,11:f4}", xbar[i - 1]);
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        Console.Write(" {0}", "Original vector STD  :   ");
        for (i = 1; i <= n; i++)
        {
          Console.Write(" {0,11:f4}", std[i - 1]);
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        Console.Write(" {0}", "Original matrix SSP  :");
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= n; j++)
          {
            Console.Write(" {0,11:f4}", ssp[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        Console.Write(" {0}", "Original matrix R    :");
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= n; j++)
          {
            Console.Write(" {0,11:f4}", r[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        korder[0] = 4;
        korder[1] = 1;
        korder[2] = 2;
        //
        G02.g02ce(n, xbar, std, ssp, r, m, korder, xbar2, std2, ssp2, r2, out ifail);
        //
        if (ifail != 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02ce failed with ifail = {0,5}", ifail);
        }
        else
        {
          Console.Write(" {0}", "New vector XBAR2 :   ");
          for (i = 1; i <= m; i++)
          {
            Console.Write(" {0,11:f4}", xbar2[i - 1]);
          }
          Console.WriteLine(" ");
          Console.WriteLine(" ");
          Console.Write(" {0}", "New vector STD2  :   ");
          for (i = 1; i <= m; i++)
          {
            Console.Write(" {0,11:f4}", std2[i - 1]);
          }
          Console.WriteLine(" ");
          Console.WriteLine(" ");
          Console.Write(" {0}", "New matrix SSP2  :");
          Console.WriteLine(" ");
          for (i = 1; i <= m; i++)
          {
            for (j = 1; j <= m; j++)
            {
              Console.Write(" {0,11:f4}", ssp2[i - 1, j - 1]);
            }
            Console.WriteLine(" ");
          }
          Console.WriteLine(" ");
          Console.WriteLine(" ");
          Console.Write(" {0,11:f4}", "New matrix R2    :");
          Console.WriteLine(" ");
          for (i = 1; i <= m; i++)
          {
            for (j = 1; j <= m; j++)
            {
              Console.Write(" {0,11:f4}", r2[i - 1, j - 1]);
            }
            Console.WriteLine(" ");
          }
          Console.WriteLine(" ");
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02cf Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02CFE
  {
    static string datafile = "ExampleData/g02cfe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   j;
        const int n = 3;
        double[,] r = new double[n, n];
        double[,] ssp = new double[n, n];
        double[] std = new double[n];
        double[] xbar = new double[n];
        int[] korder = new int[n];
        int ifail;
        Console.WriteLine("g02cf Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          xbar[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        for (i = 1; i <= n; i++)
        {
          std[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= n; j++)
          {
            ssp[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= n; j++)
          {
            r[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        Console.WriteLine(" ");
        Console.Write(" {0}", "Original vector XBAR :   ");
        for (i = 1; i <= n; i++)
        {
          Console.Write(" {0,11:f4}", xbar[i - 1]);
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        Console.Write(" {0}", "Original vector STD  :   ");
        for (i = 1; i <= n; i++)
        {
          Console.Write(" {0,11:f4}", std[i - 1]);
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        Console.Write(" {0,11:f4}", "Original matrix SSP  :");
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= n; j++)
          {
            Console.Write(" {0,11:f4}", ssp[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        Console.Write(" {0}", "Original matrix R    :");
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= n; j++)
          {
            Console.Write(" {0,11:f4}", r[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        korder[0] = 1;
        korder[1] = 3;
        korder[2] = 2;
        //
        G02.g02cf(n, korder, xbar, std, ssp, r, out ifail);
        //
        if (ifail != 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02cf failed with ifail = {0,5}", ifail);
        }
        else
        {
          Console.Write(" {0}", "New vector XBAR :   ");
          for (i = 1; i <= n; i++)
          {
            Console.Write(" {0,11:f4}", xbar[i - 1]);
          }
          Console.WriteLine(" ");
          Console.WriteLine(" ");
          Console.Write(" {0}", "New vector STD  :   ");
          for (i = 1; i <= n; i++)
          {
            Console.Write(" {0,11:f4}", std[i - 1]);
          }
          Console.WriteLine(" ");
          Console.WriteLine(" ");
          Console.Write(" {0}", "New matrix SSP  :");
          Console.WriteLine(" ");
          for (i = 1; i <= n; i++)
          {
            for (j = 1; j <= n; j++)
            {
              Console.Write(" {0,11:f4}", ssp[i - 1, j - 1]);
            }
            Console.WriteLine(" ");
          }
          Console.WriteLine(" ");
          Console.WriteLine(" ");
          Console.Write(" {0}", "New matrix R    :");
          Console.WriteLine(" ");
          for (i = 1; i <= n; i++)
          {
            for (j = 1; j <= n; j++)
            {
              Console.Write(" {0,11:f4}", r[i - 1, j - 1]);
            }
            Console.WriteLine(" ");
          }
          Console.WriteLine(" ");
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write("Exception Raised");
      }
    }
  }
}


//      g02cg Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02CGE
  {
    static string datafile = "ExampleData/g02cge.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        const int k1 = 3;
        const int n = 5;
        const int k = k1 - 1;
        int i,   j; int ifail;
        Console.WriteLine("g02cg Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        double[,] c = new double[k, k];
        double[,] coef = new double[k, 3];
        double[] con = new double[3];
        double[,] r = new double[k1, k1];
        double[] result = new double[13];
        double[,] rinv = new double[k, k];
        double[,] ssp = new double[k1, k1];
        double[] xbar = new double[k1];
        for (i = 1; i <= k1; i++)
        {
          xbar[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        for (i = 1; i <= k1; i++)
        {
          for (j = 1; j <= k1; j++)
          {
            ssp[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        for (i = 1; i <= k1; i++)
        {
          for (j = 1; j <= k1; j++)
          {
            r[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        Console.WriteLine(" ");
        Console.WriteLine(" {0}", "Means:");
        for (i = 1; i <= k1; i++)
        {
          Console.WriteLine(" {0,4}{1,11:f4}", i, xbar[i - 1]);
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        Console.Write(" {0}", "Sums of squares and cross-products about means:\n");
        for (j = 1; j <= k1; j++)
        {
          Console.Write(" {0,10}", j);
        }
        Console.WriteLine(" ");
        for (i = 1; i <= k1; i++)
        {
          Console.Write(" {0,4}", i);
          for (j = 1; j <= k1; j++)
          {
            Console.Write(" {0,11:f4}", ssp[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        Console.Write(" {0}", "Correlation coefficients:\n");
        for (j = 1; j <= k1; j++)
        {
          Console.Write(" {0,10}", j);
        }
        Console.WriteLine(" ");
        for (i = 1; i <= k1; i++)
        {
          Console.Write(" {0,4}", i);
          for (j = 1; j <= k1; j++)
          {
            Console.Write(" {0,11:f4}", r[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        //
        G02.g02cg(n, k1, k, xbar, ssp, r, result, coef, con, rinv, c, out ifail);
        //
        if (ifail != 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02cg failed with ifail = {0,5}", ifail);
        }
        else
        {
          Console.Write(" {0}", "Vble     Coef       Std err      t-value\n\n");
          for (i = 1; i <= k; i++)
          {
            Console.Write(" {0, 3}", i);
            for (j = 1; j <= 3; j++)
            {
              Console.Write(" {0,11:f4}", coef[i - 1, j - 1]);
            }
            Console.WriteLine(" ");
          }
          Console.WriteLine(" ");
          Console.Write(" {0}", "Const");
          for (i = 1; i <= 3; i++)
          {
            Console.Write(" {0,11:f4}", con[i - 1]);
          }
          Console.WriteLine(" ");
          Console.WriteLine(" ");
          Console.Write(" {0}", "Analysis of regression table :-");
          Console.WriteLine(" ");
          Console.Write(" {0}", "      Source        Sum of squares  D.F.    Mean square     F-value");
          Console.WriteLine(" ");
          Console.Write(" {0}", "Due to regression");
          for (i = 1; i <= 4; i++)
          {
            Console.Write(" {0,11:f4}", result[i - 1]);
          }
          Console.WriteLine(" ");
          Console.Write(" {0}", "About  regression");
          for (i = 5; i <= 7; i++)
          {
            Console.Write(" {0,11:f4}", result[i - 1]);
          }
          Console.WriteLine(" ");
          Console.Write(" {0}", "Total            ");
          for (i = 8; i <= 9; i++)
          {
            Console.Write(" {0,11:f4}", result[i - 1]);
          }
          Console.WriteLine(" ");
          Console.WriteLine(" ");
          Console.WriteLine("  {0}{1,8:f4}", "Standard error of estimate =", result[9]);
          Console.WriteLine("  {0}{1,8:f4}", "Multiple correlation (R)   =", result[10]);
          Console.WriteLine("  {0}{1,8:f4}", "Determination (R squared)  =", result[11]);
          Console.WriteLine("  {0}{1,8:f4}", "Corrected R squared        =", result[12]);
          Console.WriteLine(" ");
          Console.WriteLine(" {0}", "Inverse of correlation matrix of independent variables:");
          for (j = 1; j <= k; j++)
          {
            Console.Write(" {0,12}", j);
          }
          Console.WriteLine(" ");
          for (i = 1; i <= k; i++)
          {
            Console.Write(" {0, 4}", i);
            for (j = 1; j <= k; j++)
            {
              Console.Write(" {0,10:f4}", rinv[i - 1, j - 1]);
            }
            Console.WriteLine(" ");
          }
          Console.WriteLine(" ");
          Console.WriteLine(" ");
          Console.Write(" {0}", "Modified inverse matrix:\n");
          for (j = 1; j <= k; j++)
          {
            Console.Write(" {0,12}", j);
          }
          Console.WriteLine(" ");
          for (i = 1; i <= k; i++)
          {
            Console.Write(" {0, 4}", i);
            for (j = 1; j <= k; j++)
            {
              Console.Write(" {0,11:f4}", c[i - 1, j - 1]);
            }
            Console.WriteLine(" ");
          }
          Console.WriteLine(" ");
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02ch Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02CHE
  {
    static string datafile = "ExampleData/g02che.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   j;
        const int k1 = 3;
        const int n = 5;
        const int k = k1 - 1;
        double[,] coef = new double[k, 3];
        double[,] cz = new double[k, k];
        double[] result = new double[13];
        double[,] rz = new double[k1, k1];
        double[,] rznv = new double[k, k];
        double[,] sspz = new double[k1, k1];
        int ifail;
        Console.WriteLine("g02ch Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        for (i = 1; i <= k1; i++)
        {
          for (j = 1; j <= k1; j++)
          {
            sspz[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        for (i = 1; i <= k1; i++)
        {
          for (j = 1; j <= k1; j++)
          {
            rz[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        Console.WriteLine(" ");
        Console.WriteLine(" {0}", "Sums of squares and cross-products about zero:");
        for (j = 1; j <= k1; j++)
        {
          Console.Write(" {0,10}", j);
        }
        Console.WriteLine(" ");
        for (i = 1; i <= k1; i++)
        {
          Console.Write(" {0,4}", i);
          for (j = 1; j <= k1; j++)
          {
            Console.Write(" {0, 10:f4}", sspz[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        Console.WriteLine(" {0}", "Correlation-like coefficients:");
        for (j = 1; j <= k1; j++)
        {
          Console.Write(" {0, 10}", j);
        }
        Console.WriteLine(" ");
        for (i = 1; i <= k1; i++)
        {
          Console.Write(" {0, 4}", i);
          for (j = 1; j <= k1; j++)
          {
            Console.Write(" {0, 10:f4}", rz[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        Console.WriteLine(" ");
        //
        G02.g02ch(n, k1, k, sspz, rz, result, coef, rznv, cz, out ifail);
        //
        if (ifail != 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02ch failed with ifail = {0,5}", ifail);
        }
        else
        {
          Console.WriteLine(" {0}", "Vble     Coef       Std err      t-value");
          for (i = 1; i <= k; i++)
          {
            Console.Write(" {0, 3}", i);
            for (j = 1; j <= 3; j++)
            {
              Console.Write(" {0, 12:f4}", coef[i - 1, j - 1]);
            }
            Console.WriteLine(" ");
          }
          Console.WriteLine(" ");
          Console.WriteLine(" {0}", "Analysis of regression table :-");
          Console.WriteLine(" ");
          Console.WriteLine(" {0}", "      Source        Sum of squares  D.F.    Mean square     F-value");
          Console.WriteLine(" ");
          Console.Write(" {0}", "Due to regression");
          for (i = 1; i <= 4; i++)
          {
            Console.Write(" {0, 12:f4}", result[i - 1]);
          }
          Console.WriteLine(" ");
          Console.Write(" {0}", "About  regression");
          for (i = 5; i <= 7; i++)
          {
            Console.Write(" {0, 12:f4}", result[i - 1]);
          }
          Console.WriteLine(" ");
          Console.Write(" {0}", "Total            ");
          for (i = 8; i <= 9; i++)
          {
            Console.Write(" {0, 12:f4}", result[i - 1]);
          }
          Console.WriteLine(" ");
          Console.WriteLine(" ");
          Console.WriteLine("  {0}{1,8:f4}", "Standard error of estimate =", result[9]);
          Console.WriteLine("  {0}{1,8:f4}", "Multiple correlation (R)   =", result[10]);
          Console.WriteLine("  {0}{1,8:f4}", "Determination (R squared)  =", result[11]);
          Console.WriteLine("  {0}{1,8:f4}", "Corrected R squared        =", result[12]);
          Console.WriteLine(" ");
          Console.WriteLine(" {0}", "Inverse of correlation matrix of independent variables:");
          for (j = 1; j <= k; j++)
          {
            Console.Write(" {0, 10}", j);
          }
          Console.WriteLine(" ");
          for (i = 1; i <= k; i++)
          {
            Console.Write(" {0, 4}", i);
            for (j = 1; j <= k; j++)
            {
              Console.Write(" {0, 10:f4}", rznv[i - 1, j - 1]);
            }
            Console.WriteLine(" ");
          }
          Console.WriteLine(" ");
          Console.WriteLine(" {0}", "Modified inverse matrix:");
          for (j = 1; j <= k; j++)
          {
            Console.Write(" {0, 10}", j);
          }
          Console.WriteLine(" ");
          for (i = 1; i <= k; i++)
          {
            Console.Write(" {0, 4}", i);
            for (j = 1; j <= k; j++)
            {
              Console.Write(" {0, 10:f4}", cz[i - 1, j - 1]);
            }
            Console.WriteLine(" ");
          }
          Console.WriteLine(" ");
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


g02ch Example Program Results

 Sums of squares and cross-products about zero:
          1          2          3
    1   245.0000    99.0000    82.0000
    2    99.0000   271.0000    52.0000
    3    82.0000    52.0000    54.0000

 Correlation-like coefficients:
          1          2          3
    1     1.0000     0.3842     0.7129
    2     0.3842     1.0000     0.4299
    3     0.7129     0.4299     1.0000

 Vble     Coef       Std err      t-value
   1       0.3017       0.1998       1.5098
   2       0.0817       0.1900       0.4299

 Analysis of regression table :-

       Source        Sum of squares  D.F.    Mean square     F-value

 Due to regression      28.9857       2.0000      14.4929       1.7382
 About  regression      25.0143       3.0000       8.3381
 Total                  54.0000       5.0000

  Standard error of estimate =  2.8876
  Multiple correlation (R)   =  0.7326
  Determination (R squared)  =  0.5368
  Corrected R squared        =  0.2280

 Inverse of correlation matrix of independent variables:
          1          2
    1     1.1732    -0.4507
    2    -0.4507     1.1732

 Modified inverse matrix:
          1          2
    1     0.0048    -0.0017
    2    -0.0017     0.0043


//      g02da Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02DAE
  {
    static string datafile = "ExampleData/g02dae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double rss,    tol;  int i,  idf,  ip,  irank,  j,  m,  n;
        bool svd = false;
        string mean = "",
        weight = "";
        int ifail;
        Console.WriteLine("g02da Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        weight = sr.Next();
        mean = sr.Next();
        Console.WriteLine(" ");
        double[] h = new double[n];
        double[] res = new double[n];
        double[] wt = new double[n];
        double[,] x = new double[n, m];
        double[] y = new double[n];
        int[] isx = new int[m];
        if ( n >= 2 && m >=1 )
        {
          if ((weight == "W") || (weight == "w"))
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              wt[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          else
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          sr.Reset();
          for (j = 1; j <= m; j++)
          {
            isx[j - 1] = int.Parse(sr.Next());
          }
          //         Calculate ip
          ip = 0;
          if ((mean == "M") || (mean == "m"))
          {
            ip = ip + 1;
          }
          for (i = 1; i <= m; i++)
          {
            if (isx[i - 1] > 0)
            {
              ip = ip + 1;
            }
          }
          //         Set tolerance
          tol = 0.000010e0;
          //
          double[] b = new double[ip];
          double[] cov = new double[(ip * ip + ip) / 2];
          double[] p = new double[ip * (ip + 2)];
          double[,] q = new double[n, ip + 1];
          double[] se = new double[ip];
          double[] wk = new double[ip*ip + 5*(ip - 1)];
          G02.g02da(mean, weight, n, x, m, isx, ip, y, wt, out rss, out idf, b, se, cov, res, h, q,
          out svd, out irank, p, tol, wk, out ifail);
          //
          if (ifail == 0)
          {
            //
            if (svd)
            {
              Console.Write("  {0}{1,4}", "Model not of full rank, rank = ", irank);
              Console.WriteLine(" ");
            }
            Console.WriteLine("  {0}{1,12:e4}", "Residual sum of squares = ", rss);
            Console.WriteLine("  {0}{1,4}", "Degrees of freedom = ", idf);
            Console.WriteLine(" ");
            Console.WriteLine(" {0} {1}", "Variable   Parameter estimate   ", "Standard error");
            Console.WriteLine(" ");
            for (j = 1; j <= ip; j++)
            {
              Console.WriteLine("  {0,6}{1,20:e4}{2,20:e4}", j, b[j - 1], se[j - 1]);
            }
            Console.WriteLine(" ");
            Console.Write(" {0}", "   Obs          Residuals              H");
            Console.WriteLine(" ");
            for (i = 1; i <= n; i++)
            {
              Console.WriteLine("  {0,6}{1,20:e4}{2,20:e4}", i, res[i - 1], h[i - 1]);
            }
          }
          else
          {
            Console.WriteLine(" ");
            Console.WriteLine("** g02da failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02dc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02DCE
  {
    static string datafile = "ExampleData/g02dce.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double rss,   tol,   wtn,   yn; int i,  idf,  ip,  irank,  ix,  j,  m,  n;
        bool svd = false;
        string mean = "",
        update = "",
        weight = "";
        int ifail;
        Console.WriteLine("g02dc Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        wtn = 0.0;
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        weight = sr.Next();
        mean = sr.Next();
        double[] h = new double[n];
        double[] res = new double[n];
        double[] wt = new double[n];
        double[,] xm = new double[n, m];
        double[] y = new double[n];
        int[] isx = new int[m];
        Console.WriteLine(" ");
        if (n >= 2 && m >= 1)
        {
          if ((weight == "W") || (weight == "w"))
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                xm[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              wt[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          else
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                xm[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          sr.Reset();
          for (j = 1; j <= m; j++)
          {
            isx[j - 1] = int.Parse(sr.Next());
          }
          ip = int.Parse(sr.Next());
          //         Set tolerance
          tol = 0.000010e0;
          //
          //         Fit initial model using g02da
          double[] cov = new double[ip * (ip + 1) / 2];
          double[] b = new double[ip];
          double[] p = new double[ip * (ip + 2)];
          double[,] q = new double[n, ip + 1];
          double[] se = new double[ip];
          double[] wk = new double[5 * (ip - 1) + ip * ip];
          G02.g02da(mean, weight, n, xm, m, isx, ip, y, wt, out rss, out idf, b, se, cov, res, h, q,
          out svd, out irank, p, tol, wk, out ifail);
          //
          if (ifail == 0)
          {
            //
            Console.WriteLine(" {0}", "Results from g02da");
            if (svd)
            {
              Console.WriteLine(" ");
              Console.WriteLine(" {0}", "Model not of full rank");
            }
            Console.WriteLine("  {0}{1,12:e4}", "Residual sum of squares = ", rss);
            Console.WriteLine("  {0}{1,4}", "Degrees of freedom = ", idf);
            Console.WriteLine(" ");
            Console.WriteLine(" {0} {1}", "Variable   Parameter estimate   ", "Standard error");
            Console.WriteLine(" ");
            for (j = 1; j <= ip; j++)
            {
              Console.WriteLine("  {0,6}{1,20:e4}{2,20:e4}", j, b[j - 1], se[j - 1]);
            }
            bool carryon = true;
            while (carryon)
            {
              sr.Reset();
              update = sr.Next();
              ix = 1;
              double[] x = new double[(m-1)*ix+1];
              if ((update != "S") && (update != "s"))
              {
                if ((weight == "W") || (weight == "w"))
                {
                  sr.Reset();
                  for (j = 1; j <= m; j++)
                  {
                    x[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                  }
                  yn = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                  wtn = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }
                else
                {
                  sr.Reset();
                  for (j = 1; j <= m; j++)
                  {
                    x[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                  }
                  yn = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }
                //
                G02.g02dc(update, mean, weight, m, isx, q, ip, x, ix, yn, wtn, ref rss, out ifail);
                if (ifail == 0)
                {
                  //
                  if ((update == "A") || (update == "a"))
                  {
                    Console.WriteLine(" ");
                    Console.WriteLine(" {0}", "Results from adding an observation using g02dc");
                    n = n + 1;
                  }
                  else if ((update == "D") || (update == "d"))
                  {
                    Console.WriteLine(" ");
                    Console.WriteLine(" {0}", "Results from dropping an observation using g02dc");
                    n = n - 1;
                  }
                  //
                  G02.g02dd(n, ip, q, ref rss, out idf, b, se, cov, out svd, out irank, p, tol, out ifail);
                  //
                  if (ifail == 0)
                  {
                    Console.WriteLine("  {0}{1,12:e4}", "Residual sum of squares = ", rss);
                    Console.WriteLine("  {0}{1,4}", "Degrees of freedom = ", idf);
                    Console.WriteLine(" ");
                    Console.WriteLine(" {0} {1}", "Variable   Parameter estimate   ", "Standard error");
                    Console.WriteLine(" ");
                    for (j = 1; j <= ip; j++)
                    {
                      Console.WriteLine("  {0,6}{1,20:e4}{2,20:e4}", j, b[j - 1], se[j - 1]);
                    }
                    continue;
                  }
                  else
                  {
                    Console.WriteLine(" ");
                    Console.WriteLine("** g02dd failed with ifail = {0,5}", ifail);
                    break;
                  }
                }
                else
                {
                  Console.WriteLine(" ");
                  Console.WriteLine("** g02dc failed with ifail = {0,5}", ifail);
                  break;
                }
              }
              else
              {
                carryon=false;
                break;
              }
            }
          }
          else
          {
            Console.WriteLine(" ");
            Console.WriteLine("** g02da failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write("Exception Raised");
      }
    }
  }
}


g02dc Example Program Results

 Results from g02da
  Residual sum of squares =  5.2748e+003
  Degrees of freedom =    8

 Variable   Parameter estimate    Standard error

       1         2.0724e+001         1.3801e+001
       2         1.4085e+001         1.6240e+001
       3         2.6324e+001         1.3801e+001
       4         2.2597e+001         1.3801e+001

 Results from dropping an observation using g02dc
  Residual sum of squares =  2.1705e+001
  Degrees of freedom =    7

 Variable   Parameter estimate    Standard error

       1         3.6003e+001         1.0166e+000
       2         3.7005e+001         1.2451e+000
       3         4.1603e+001         1.0166e+000
       4         3.7877e+001         1.0166e+000

 Results from adding an observation using g02dc
  Residual sum of squares =  2.2227e+001
  Degrees of freedom =    8

 Variable   Parameter estimate    Standard error

       1         3.6003e+001         9.6235e-001
       2         3.7300e+001         9.6235e-001
       3         4.1603e+001         9.6235e-001
       4         3.7877e+001         9.6235e-001


//      g02dd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G02DDE
  {
    static string datafile = "ExampleData/g02dde.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double rss,   tol; int i,  idf,  ip,  irank,  j,  m,  n;
        bool svd = false;
        string weight = "";
        int ifail;
        Console.WriteLine("g02dd Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        int ipmax = m + 1;
        double[,] x = new double[n, m];
        double[] b = new double[ipmax];
        double[] cov = new double[ipmax * (ipmax + 1) / 2];
        double[] p = new double[ipmax * (ipmax + 2)];
        double[,] q = new double[n, ipmax + 2];
        double[] se = new double[ipmax];
        double[] wt = new double[n];
        weight = sr.Next();
        if (n >= 1 && m >= 1)
        {
          if ((weight == "W") || (weight == "w"))
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              q[i - 1, 0] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              wt[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          else
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              q[i - 1, 0] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //         Set tolerance
          tol = 0.0000010e0;
          ip = 0;
          double[] x_slice = new double[n];
          for (i = 1; i <= m; i++)
          {
            //
            //            Fit model using g02de
            for (int xin = 0; xin < n; xin++)
            {
              x_slice[xin] = x[xin, i - 1];
            }
            G02.g02de(weight, n, ip, q, p, wt, x_slice, out rss, tol, out ifail);
            //
            if (ifail == 0)
            {
              ip = ip + 1;
            }
            else if (ifail == 3)
            {
              Console.WriteLine(" {0}", " * New variable not added *");
            }
            else
            {
              Console.WriteLine("");
              Console.WriteLine("** g02de failed with ifail = {0,5}", ifail);
              goto L100;
            }
          }
          rss = 0.00e0;
          //
          G02.g02dd(n, ip, q, ref rss, out idf, b, se, cov, out svd, out irank, p, tol, out ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine("");
            if (svd)
            {
              Console.WriteLine(" {0}", "Model not of full rank");
              Console.WriteLine("");
            }
            Console.WriteLine("  {0}{1,12:e4}", "Residual sum of squares = ", rss);
            Console.WriteLine("  {0}{1,4}", "Degrees of freedom = ", idf);
            Console.WriteLine("");
            Console.WriteLine(" {0}", "Variable   Parameter estimate   Standard error");
            Console.WriteLine("");
            for (j = 1; j <= ip; j++)
            {
              Console.WriteLine("  {0,6}{1,20:e4}{2,20:e4}", j, b[j - 1], se[j - 1]);
            }
          }
          else
          {
            Console.WriteLine("");
            Console.WriteLine("** g02dd failed with ifail = {0,5}", ifail);
          }
        }
        L100: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


g02dd Example Program Results

  Residual sum of squares =  2.2227e+001
  Degrees of freedom =    8

 Variable   Parameter estimate   Standard error

       1         3.6003e+001         9.6235e-001
       2         3.7300e+001         9.6235e-001
       3         4.1603e+001         9.6235e-001
       4         3.7877e+001         9.6235e-001


//      g02de Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G02DEE
  {
    static string datafile = "ExampleData/g02dee.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double rss,   rsst,   tol; int i,  idf,  indx,  ip,  irank,  j,  m,  n;
        bool svd = false;
        string mean = "",
        weight = "";
        int ifail;
        Console.WriteLine("g02de Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        int maxip = m+1;
        weight = sr.Next();
        mean = sr.Next();
        double[] b = new double[maxip];
        double[] cov = new double[maxip * (maxip + 1) / 2];
        double[] p = new double[maxip * (maxip + 2)];
        double[,] q = new double[n, maxip + 1];
        double[] se = new double[maxip];
        double[] wt = new double[n];
        double[,] x = new double[n, m];
        if (n >= 1 && m >= 1)
        {
          if ((weight == "W") || (weight == "w"))
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              q[i - 1, 0] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              wt[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          else
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              q[i - 1, 0] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //         Set tolerance
          tol = 0.0000010e0;
          ip = 0;
          if ((mean == "M") || (mean == "m"))
          {
            double[] x_column = new double[n];
            for (int i_ind = 0; i_ind < n; i_ind++)
            x_column[i_ind] = 1.0;
            //
            //
            G02.g02de(weight, n, ip, q, p, wt, x_column, out rss, tol, out ifail);
            //
            if (ifail < 0)
            {
              Console.WriteLine("");
              Console.WriteLine("** g02de failed with ifail = {0,5}", ifail);
              goto L100;
            }
            else
            {
              ip = 1;
            }
          }
          sr.Reset();
          indx = int.Parse(sr.Next());
          while ( indx > 0)
          {
            //
            double[] x_column = new double[n];
            for (int i_ind = 0; i_ind < n; i_ind++)
            x_column[i_ind] = x[i_ind, indx - 1];
            G02.g02de(weight, n, ip, q, p, wt, x_column, out rss, tol, out ifail);
            //
            if (ifail == 0)
            {
              ip = ip + 1;
              Console.WriteLine("");
              Console.WriteLine("  {0}{1,4}{2}", "Variable", indx, " added");
              rsst = 0.00e0;
              //
              G02.g02dd(n, ip, q, ref rsst, out idf, b, se, cov, out svd, out irank, p, tol,
              out ifail);
              //
              if (ifail == 0)
              {
                if (svd)
                {
                  Console.WriteLine(" {0}", "Model not of full rank");
                  Console.WriteLine("");
                }
                Console.WriteLine("  {0}{1,13:e4}", "Residual sum of squares = ", rsst);
                Console.WriteLine("  {0}{1,4}", "Degrees of freedom = ", idf);
                Console.WriteLine("");
                Console.WriteLine(" {0}", "Variable   Parameter estimate   Standard error");
                Console.WriteLine("");
                for (j = 1; j <= ip; j++)
                {
                  Console.WriteLine("  {0,6}{1,20:e4}{2,20:e4}", j, b[j - 1], se[j - 1]);
                }
              }
              else
              {
                Console.WriteLine("");
                Console.WriteLine("** g02dd failed with ifail = {0,5}", ifail);
                goto L100;
              }
            }
            else if (ifail == 3)
            {
              Console.WriteLine(" {0}", " * New variable not added *");
            }
            else
            {
              Console.WriteLine("");
              Console.WriteLine("** g02de failed with ifail = {0,5}", ifail);
              goto L100;
            }
            sr.Reset();
            indx = int.Parse(sr.Next());
          }
        }
        L100: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


g02de Example Program Results

  Variable   1 added
  Residual sum of squares =   4.0164e+000
  Degrees of freedom =   10

 Variable   Parameter estimate   Standard error

       1         4.4100e+000         4.3756e-001
       2         9.4979e-001         1.0599e-001

  Variable   3 added
  Residual sum of squares =   3.8872e+000
  Degrees of freedom =    9

 Variable   Parameter estimate   Standard error

       1         4.2236e+000         5.6734e-001
       2         1.0554e+000         2.2217e-001
       3        -4.1962e-001         7.6695e-001

  Variable   4 added
  Residual sum of squares =   1.8702e-001
  Degrees of freedom =    8

 Variable   Parameter estimate   Standard error

       1         2.7605e+000         1.7592e-001
       2         1.7057e+000         7.3100e-002
       3         4.4575e+000         4.2676e-001
       4        -1.3006e+000         1.0338e-001

  Variable   2 added
  Residual sum of squares =   8.4066e-002
  Degrees of freedom =    7

 Variable   Parameter estimate   Standard error

       1         3.1440e+000         1.8181e-001
       2         9.0748e-001         2.7761e-001
       3         2.0790e+000         8.6804e-001
       4        -6.1589e-001         2.4530e-001
       5         2.9224e-001         9.9810e-002


//      g02df Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02DFE
  {
    static string datafile = "ExampleData/g02dfe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double rss,   tol; int i,  idf,  indx,  ip,  irank,  j,  m,  n;
        bool svd = false;
        string mean = "",
        weight = "";
        int ifail;
        Console.WriteLine("g02df Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        int ipmax = m + 1;
        weight = sr.Next();
        mean = sr.Next();
        double[] b = new double[5];
        double[] cov = new double[(ipmax * ipmax + ipmax) / 2];
        double[] h = new double[n];
        double[] p = new double[ipmax * (ipmax + 2)];
        double[,] q = new double[n, ipmax + 1];
        double[] res = new double[12];
        double[] se = new double[5];
        double[] wk = new double[5 * (ipmax - 1) + ipmax * ipmax];
        double[] wt = new double[12];
        double[,] x = new double[n, m];
        double[] y = new double[n];
        int[] isx = new int[m];
        if (n >= 2 && m >= 1)
        {
          if ((weight == "W") || (weight == "w"))
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              wt[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          else
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          for (i = 1; i <= m; i++)
          {
            isx[i - 1] = 1;
          }
          ip = (int)m;
          if ((mean == "M") || (mean == "m"))
          {
            ip = ip + 1;
          }
          //         Set tolerance
          tol = 0.000010e0;
          //
          G02.g02da(mean, weight, n, x, m, isx, ip, y, wt, out rss, out idf, b, se, cov, res, h, q,
          out svd, out irank, p, tol, wk, out ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "Results from full model");
            if (svd)
            {
              Console.Write(" {0}", "Model not of full rank");
              Console.WriteLine(" ");
            }
            Console.WriteLine("  {0}{1,13:e4}", "Residual sum of squares = ", rss);
            Console.WriteLine("  {0}{1,4}", "Degrees of freedom = ", idf);
            Console.WriteLine(" ");
            L80: ;
            sr.Reset();
            indx = int.Parse(sr.Next());
            if (indx != 0)
            {
              //
              G02.g02df(ip, q, indx, ref rss, out ifail);
              //
              if (ifail == 0)
              {
                ip = ip - 1;
                if (ip == 0)
                {
                  Console.Write(" {0}", "No terms left in model");
                }
                else
                {
                  Console.WriteLine("  {0}{1,4}{2}", "Variable", indx, " dropped");
                  //
                  G02.g02dd(n, ip, q, ref rss, out idf, b, se, cov, out svd, out irank, p, tol, out ifail);
                  //
                  if (ifail == 0)
                  {
                    Console.WriteLine("  {0}{1,13:e4}", "Residual sum of squares = ", rss);
                    Console.Write("  {0}{1,4}", "Degrees of freedom = ", idf);
                    Console.WriteLine(" ");
                    Console.Write(" {0} {1}", "Parameter estimate   ", "Standard error");
                    Console.WriteLine(" ");
                    for (j = 1; j <= ip; j++)
                    {
                      Console.WriteLine("  {0,15:e4}{1,20:e4}", b[j - 1], se[j - 1]);
                    }
                    goto L80;
                  }
                  else
                  {
                    Console.WriteLine(" ");
                    Console.WriteLine("** g02dd failed with ifail = {0,5}", ifail);
                  }
                }
              }
              else
              {
                Console.WriteLine(" ");
                Console.WriteLine("** g02df failed with ifail = {0,5}", ifail);
              }
            }
          }
          else
          {
            Console.WriteLine(" ");
            Console.WriteLine("** g02da failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write("Exception Raised");
      }
    }
  }
}


g02df Example Program Results

 Results from full model
  Residual sum of squares =   8.4066e-002
  Degrees of freedom =    7

  Variable   2 dropped
  Residual sum of squares =   2.1239e-001
  Degrees of freedom =    8
 Parameter estimate    Standard error
      3.6372e+000         1.5083e-001
      6.1264e-001         2.8007e-002
     -6.0154e-001         4.2335e-001
      1.6709e-001         7.8656e-002
  Variable   4 dropped
  Residual sum of squares =   3.3220e-001
  Degrees of freedom =    9
 Parameter estimate    Standard error
      3.5974e+000         1.7647e-001
      6.2088e-001         3.2706e-002
      2.4247e-001         1.7235e-001


//      g02dg Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02DGE
  {
    static string datafile = "ExampleData/g02dge.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double rss,   tol; int i,  idf,  ip,  irank,  j,  m,  n;
        bool svd = false;
        string mean = "",
        weight = "";
        int ifail;
        Console.WriteLine("g02dg Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        int ipmax = m + 1;
        weight = sr.Next();
        mean = sr.Next();
        double[] b = new double[5];
        double[] cov = new double[ipmax * (ipmax + 1) / 2];
        double[] h = new double[n];
        double[] newy = new double[n];
        double[] p = new double[ipmax * (ipmax + 2)];
        double[,] q = new double[n, ipmax + 1];
        double[] res = new double[n];
        double[] se = new double[5];
        double[] wk = new double[5 * (ipmax - 1) + ipmax * ipmax];
        double[] wt = new double[n];
        double[,] xm = new double[n, m];
        double[] y = new double[n];
        int[] isx = new int[m];
        if ( n >= 2 && m >= 1)
        {
          if ((weight == "W") || (weight == "w"))
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                xm[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              wt[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              newy[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          else
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                xm[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              newy[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          sr.Reset();
          for (j = 1; j <= m; j++)
          {
            isx[j - 1] = int.Parse(sr.Next());
          }
          ip = int.Parse(sr.Next());
          //         Set tolerance
          tol = 0.000010e0;
          //
          //         Fit initial model using g02da
          G02.g02da(mean, weight, n, xm, m, isx, ip, y, wt, out rss, out idf, b, se, cov, res, h, q,
          out svd, out irank, p, tol, wk, out ifail);
          //
          if (ifail == 0)
          {
            Console.Write(" {0}", "Results from g02da");
            Console.WriteLine(" ");
            if (svd)
            {
              Console.Write(" {0}", "Model not of full rank");
              Console.WriteLine(" ");
            }
            Console.WriteLine("  {0}{1,12:e4}", "Residual sum of squares = ", rss);
            Console.Write("  {0}{1,4}", "Degrees of freedom = ", idf);
            Console.WriteLine(" ");
            Console.Write(" {0}", "Variable   Parameter estimate   Standard error");
            Console.WriteLine(" ");
            for (j = 1; j <= ip; j++)
            {
              Console.WriteLine("  {0,6}{1,20:e4}{2,20:e4}", j, b[j - 1], se[j - 1]);
            }
            //
            G02.g02dg(weight, n, wt, ref rss, ip, irank, cov, q, svd, p, newy, b, se, res, wk,
            out ifail);
            //
            if (ifail == 0)
            {
              Console.WriteLine(" ");
              Console.Write(" {0}", "Results for second y-variable using g02dg");
              Console.WriteLine(" ");
              Console.WriteLine("  {0}{1,12:e4}", "Residual sum of squares = ", rss);
              Console.Write("  {0}{1,4}", "Degrees of freedom = ", idf);
              Console.WriteLine(" ");
              Console.Write(" {0} {1}", "Variable   Parameter estimate   ", "Standard error");
              Console.WriteLine(" ");
              for (j = 1; j <= ip; j++)
              {
                Console.WriteLine("  {0,6}{1,20:e4}{2,20:e4}", j, b[j - 1], se[j - 1]);
              }
            }
            else
            {
              Console.WriteLine(" ");
              Console.WriteLine("** g02dg failed with ifail = {0,5}", ifail);
            }
          }
          else
          {
            Console.WriteLine(" ");
            Console.WriteLine("** g02da failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write("Exception Raised");
      }
    }
  }
}


g02dg Example Program Results
 Results from g02da
 Model not of full rank
  Residual sum of squares =  2.2227e+001
  Degrees of freedom =    8
 Variable   Parameter estimate   Standard error
       1         3.0557e+001         3.8494e-001
       2         5.4467e+000         8.3896e-001
       3         6.7433e+000         8.3896e-001
       4         1.1047e+001         8.3896e-001
       5         7.3200e+000         8.3896e-001

 Results for second y-variable using g02dg
  Residual sum of squares =  2.4000e+001
  Degrees of freedom =    8
 Variable   Parameter estimate    Standard error
       1         5.4067e+001         4.0000e-001
       2         1.1267e+001         8.7178e-001
       3         1.2600e+001         8.7178e-001
       4         1.6933e+001         8.7178e-001
       5         1.3267e+001         8.7178e-001


//      g02dk Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02DKE
  {
    static string datafile = "ExampleData/g02dke.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double rss,   tol; int i,  iconst,  idf,  ip,  irank,  j,  m,  n;
        bool svd = false;
        string mean = "",
        weight = "";
        int ifail;
        Console.WriteLine("g02dk Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        int ipmax = m + 1;
        weight = sr.Next();
        mean = sr.Next();
        Console.WriteLine(" ");
        double[] b = new double[ipmax];
        double[,] c = new double[ipmax, ipmax];
        double[] cov = new double[(ipmax * ipmax + ipmax) / 2];
        double[] h = new double[n];
        double[] p = new double[ipmax * (ipmax + 2)];
        double[,] q = new double[n, ipmax + 1];
        double[] res = new double[n];
        double[] se = new double[ipmax];
        double[] wk = new double[4 * ipmax * ipmax + 5 * (ipmax - 1)];
        double[] wt = new double[n];
        double[,] x = new double[n, m];
        double[] y = new double[n];
        int[] isx = new int[m];
        if (n >= 2 && m >= 1)
        {
          if ((weight == "W") || (weight == "w"))
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              wt[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          else
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          sr.Reset();
          for (j = 1; j <= m; j++)
          {
            isx[j - 1] = int.Parse(sr.Next());
          }
          ip = int.Parse(sr.Next());
          //         Set tolerance
          tol = 0.000010e0;
          //
          //         Find initial estimates using g02da
          G02.g02da(mean, weight, n, x, m, isx, ip, y, wt, out rss, out idf, b, se, cov, res, h, q,
          out svd, out irank, p, tol, wk, out ifail);
          //
          if (ifail == 0)
          {
            Console.Write(" {0}", "Estimates from g02da");
            Console.WriteLine(" ");
            Console.WriteLine("  {0}{1,13:e3}", "Residual sum of squares = ", rss);
            Console.WriteLine("  {0}{1,4}", "Degrees of freedom = ", idf);
            Console.WriteLine(" ");
            Console.Write(" {0}", "Variable    Parameter estimate   Standard error");
            Console.WriteLine(" ");
            for (j = 1; j <= ip; j++)
            {
              Console.WriteLine("  {0,6}{1,20:e3}{2,20:e3}", j, b[j - 1], se[j - 1]);
            }
            //            Input constraints and call g02dk
            iconst = ip - irank;
            for (i = 1; i <= ip; i++)
            {
              sr.Reset();
              for (j = 1; j <= iconst; j++)
              {
                c[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
            }
            //
            G02.g02dk(ip, iconst, p, c, b, rss, idf, se, cov, out ifail);
            //
            if (ifail == 0)
            {
              Console.WriteLine(" ");
              Console.Write(" {0}", "Estimates from g02dk using constraints");
              Console.WriteLine(" ");
              Console.Write(" {0}", "Variable    Parameter estimate   Standard error");
              Console.WriteLine(" ");
              for (j = 1; j <= ip; j++)
              {
                Console.WriteLine("  {0,6}{1,20:e3}{2,20:e3}", j, b[j - 1], se[j - 1]);
              }
            }
            else
            {
              Console.WriteLine(" ");
              Console.WriteLine("** g02dk failed with ifail = {0,5}", ifail);
            }
          }
          else
          {
            Console.WriteLine(" ");
            Console.WriteLine("** g02da failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write("Exception Raised");
      }
    }
  }
}


//      g02dn Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02DNE
  {
    static string datafile = "ExampleData/g02dne.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double rss,   sestat,   stat,   t,   tol; int i,  idf,  ip,  irank,  j,  m,  n,  nestfn;
        bool est = false,
        svd = false;
        string mean = "",
        weight = "";
        int ifail;
        Console.WriteLine("g02dn Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        int ipmax = m + 1;
        weight = sr.Next();
        mean = sr.Next();
        double[] b = new double[ipmax];
        double[] cov = new double[(ipmax * ipmax + ipmax) / 2];
        double[] f = new double[ipmax];
        double[] h = new double[n];
        double[] p = new double[ipmax * (ipmax + 2)];
        double[,] q = new double[n, ipmax + 1];
        double[] res = new double[n];
        double[] se = new double[ipmax];
        double[] wk = new double[ipmax * ipmax + 5 * (ipmax - 1)];
        double[] wt = new double[n];
        double[,] x = new double[n, m];
        double[] y = new double[n];
        int[] isx = new int[m];
        if (n >= 2 && m >= 1)
        {
          if ((weight == "W") || (weight == "w"))
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              wt[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          else
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          sr.Reset();
          for (j = 1; j <= m; j++)
          {
            isx[j - 1] = int.Parse(sr.Next());
          }
          ip = int.Parse(sr.Next());
          //         Set tolerance
          tol = 0.000010e0;
          //
          //         Find initial estimates using g02da
          G02.g02da(mean, weight, n, x, m, isx, ip, y, wt, out rss, out idf, b, se, cov, res, h, q,
          out svd, out irank, p, tol, wk, out ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine(" ");
            Console.Write(" {0}", "Estimates from g02da");
            Console.WriteLine(" ");
            Console.WriteLine("  {0}{1,12:e4}", "Residual sum of squares = ", rss);
            Console.WriteLine("  {0}{1,4}", "Degrees of freedom = ", idf);
            Console.WriteLine(" ");
            Console.Write(" {0}", "Variable   Parameter estimate   Standard error");
            Console.WriteLine(" ");
            for (j = 1; j <= ip; j++)
            {
              Console.WriteLine("  {0,6}{1,20:e4}{2,20:e4}", j, b[j - 1], se[j - 1]);
            }
            sr.Reset();
            nestfn = int.Parse(sr.Next());
            for (i = 1; i <= nestfn; i++)
            {
              sr.Reset();
              for (j = 1; j <= ip; j++)
              {
                f[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              //
              G02.g02dn(ip, irank, b, cov, p, f, out est, out stat, out sestat, out t, tol,
              out ifail);
              //
              if ((ifail == 0) || (ifail == 2))
              {
                Console.WriteLine(" ");
                Console.Write("  {0}{1,4}", "Function ", i);
                Console.WriteLine(" ");
                for (j = 1; j <= ip; j++)
                {
                  Console.Write(" {0}", f[j - 1]);
                }
                Console.WriteLine(" ");
                Console.WriteLine(" ");
                if (est)
                {
                  Console.WriteLine("  {0}{1,10:f4}{2}{3,10:f4}{4}{5,10:f4}", "STAT = ", stat, " SE = ", sestat, " T = ", t);
                }
                else
                {
                  Console.WriteLine(" {0}", "Function not estimable");
                }
              }
              else
              {
                Console.WriteLine(" ");
                Console.WriteLine("** g02dn failed with ifail = {0,5}", ifail);
              }
            }
          }
          else
          {
            Console.WriteLine(" ");
            Console.WriteLine("** g02da failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write("Exception Raised");
      }
    }
  }
}


//      g02ef Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02EFE
  {
    static string datafile = "ExampleData/g02efe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        G02.G02EF_MONFUN g02efhG02EFF = new G02.G02EF_MONFUN(g02efh);
        DataReader sr = new DataReader(datafile);
        double fin, fout, rms, rsq, sw, tau;
        int df, i, j, m, monlev, n;
        int ifail;
        Console.WriteLine("g02ef Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        fin = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        fout = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        tau = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        monlev = int.Parse(sr.Next());
        double[] b = new double[m+1];
        double[] c = new double[(m+2)*(m+1)/2];
        double[] se = new double[m+1];
        double[] wmean = new double[m+1];
        double[] wt = new double[1];
        double[,] x = new double[n, m+1];
        int[] isx = new int[m];
        if (n >1 && m >1 )
        {
          sr.Reset();
          for (i = 1; i <= n; i++)
          {
            for (j = 1; j <= m + 1; j++)
            {
              x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          sr.Reset();
          for (j = 1; j <= m; j++)
          {
            isx[j - 1] = int.Parse(sr.Next());
          }
          //
          //         Compute upper-triangular correlation matrix
          G02.g02bu("M", "U", n, m + 1, x, wt, out sw, wmean, c, out ifail);
          //
          if (ifail == 0)
          {
            //            Perform stepwise selection of variables
            G02.g02ef(m, n, wmean, c, sw, isx, fin, fout, tau, b, se, out rsq, out rms, out df, monlev,
            g02efhG02EFF, out ifail);
            //
            if (ifail == 0)
            {
              //               Display summary information for fitted model
              Console.WriteLine(" ");
              Console.WriteLine("  {0}", "Fitted Model Summary");
              Console.WriteLine(" ");
              Console.WriteLine("  {0}", "Term              Estimate   Standard Error");
              Console.WriteLine(" ");
              Console.WriteLine("  {0}        {1,12:e3}          {2,12:e3}", "Intercept:", b[0], se[0]);
              for (i = 0; i < m; i++)
              {
                if ((isx[i] == 1) || (isx[i] == 2))
                {
          Console.WriteLine(" {0} {1,3} {2,12:e3} {3,12:e3}", "Variable:", i+1, b[i+1], se[i+1]);
                }
              }
              Console.WriteLine(" ");
              Console.WriteLine("  {0}  {1,12:e3}", "RMS:", rms);
            }
            else
            {
              Console.WriteLine(" ");
              Console.WriteLine("  {0}{1,5}", " ** g02ef returned with ifail = ", ifail);
            }
          }
          else
          {
            Console.WriteLine(" ");
            Console.WriteLine("  {0}{1,5}", " ** g02bu returned with ifail = ", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    public static void g02efh(string flag, int var, double val)
    {
      switch(flag)
      {
        case "A":
        Console.WriteLine("{0} {1,4} {2}", "Adding variable", var, "to model");
        break;
        case "B":
        Console.WriteLine("{0}", "Backward Selection");
        break;
        case "C":
        Console.WriteLine("{0} {1,4} {2}", "Variable", var, "aliased");
        break;
        case "D":
        Console.WriteLine("{0} {1,4} {2}", "Dropping variable", var, "from model");
        break;
        case "F":
        Console.WriteLine("{0}", "Forward Selection");
        break;
        case "K":
        Console.WriteLine("{0}", "Keeping all current variables");
        break;
        case "S":
        Console.WriteLine("{0}", "Starting Stepwise Selection");
        break;
        case "V":
        Console.WriteLine("{0} {1,4} {2} {3, 12:e3}", "Variable", var,  "Variance ratio =", val);
        break;
        case "X":
        Console.WriteLine("{0}", "Finished Stepwise Selection");
        break;
      }
    }
  }
}


g02ef Example Program Results
Starting Stepwise Selection
Forward Selection
Variable    1 Variance ratio =   1.260e+001
Variable    2 Variance ratio =   2.196e+001
Variable    3 Variance ratio =   4.403e+000
Variable    4 Variance ratio =   2.280e+001
Adding variable    4 to model
Backward Selection
Variable    4 Variance ratio =   2.280e+001
Keeping all current variables
Forward Selection
Variable    1 Variance ratio =   1.082e+002
Variable    2 Variance ratio =   1.725e-001
Variable    3 Variance ratio =   4.029e+001
Adding variable    1 to model
Backward Selection
Variable    1 Variance ratio =   1.082e+002
Variable    4 Variance ratio =   1.593e+002
Keeping all current variables
Forward Selection
Variable    2 Variance ratio =   5.026e+000
Variable    3 Variance ratio =   4.236e+000
Adding variable    2 to model
Backward Selection
Variable    1 Variance ratio =   1.540e+002
Variable    2 Variance ratio =   5.026e+000
Variable    4 Variance ratio =   1.863e+000
Dropping variable    4 from model
Forward Selection
Variable    3 Variance ratio =   1.832e+000
Variable    4 Variance ratio =   1.863e+000
Finished Stepwise Selection

  Fitted Model Summary

  Term              Estimate   Standard Error

  Intercept:          5.258e+001            2.294e+000
 Variable:   1   1.468e+000   1.213e-001
 Variable:   2   6.623e-001   4.585e-002

  RMS:    5.790e+000


//      g02fa Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02FAE
  {
    static string datafile = "ExampleData/g02fae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double rms = 0.0;
        int i,   ip,   j,   n,   nres; int ifail;
        Console.WriteLine("g02fa Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        ip = int.Parse(sr.Next());
        nres = int.Parse(sr.Next());
        rms = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        double[] h = new double[n];
        double[] res = new double[n];
        double[,] sres = new double[nres, 4];
        if (nres > 1 && nres <= n)
        {
          for (i = 1; i <= nres; i++)
          {
            sr.Reset();
            res[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            h[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //
          G02.g02fa(n, ip, nres, res, h, rms, sres, out ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "        Internally    Internally");
            Console.WriteLine(" {0}", "Obs.   standardized  standardized   Cook's D   Atkinson's T");
            Console.WriteLine(" {0}", "         residuals     residuals");
            Console.WriteLine(" ");
            for (i = 1; i <= nres; i++)
            {
              Console.Write(" {0,2}", i);
              for (j = 1; j <= 4; j++)
              {
                Console.Write("{0,13:f3}", sres[i - 1, j - 1]);
              }
              Console.WriteLine("");
            }
          }
          else
          {
            Console.WriteLine("");
            Console.WriteLine("** g02fa failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write("Exception Raised");
      }
    }
  }
}


//      g02fc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02FCE
  {
    static string datafile = "ExampleData/g02fce.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        const int n = 10;
        double d,   pdl,   pdu; int i,  ip;
        double[] res = new double[n];
        int ifail;
        Console.WriteLine("g02fc Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        ip = int.Parse(sr.Next());
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          res[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        //
        //
        G02.g02fc(n, ip, res, out d, out pdl, out pdu, out ifail);
        //
        if (ifail == 0)
        {
          Console.WriteLine(" ");
          Console.Write("  {0}{1,10:f4}", " Durbin-Watson statistic ", d);
          Console.WriteLine(" ");
          Console.WriteLine("  {0}{1,10:f4}{2,10:f4}", " Lower and upper bound ", pdl, pdu);
        }
        else
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02fc failed with ifail = {0,5}", ifail);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


g02fc Example Program Results

   Durbin-Watson statistic     0.9238
   Lower and upper bound     0.0610    0.0060


//      g02ga Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02GAE
  {
    static string datafile = "ExampleData/g02gae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double a,   eps,   rss,   s,   tol; int i,  idf,  ip,  iprint,  irank,  j,  m,  maxit,  n;
        string link = "",
        mean = "",
        offset = "",
        weight = "";
        int ifail;
        Console.WriteLine("g02ga Example Program Results");
        //      Skip heading in data file
        a = 0.0;
        sr.Reset();
        sr.Reset();
        link = sr.Next();
        mean = sr.Next();
        offset = sr.Next();
        weight = sr.Next();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        s = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        iprint = int.Parse(sr.Next());
        double[] wt = new double[n];
        double[,] x = new double[n, m];
        double[] y = new double[n];
        int[] isx = new int[m];
        if (n >= 1 && m >= 1)
        {
          if ((weight == "W") || (weight == "w"))
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              wt[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          else
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          sr.Reset();
          for (j = 1; j <= m; j++)
          {
            isx[j - 1] = int.Parse(sr.Next());
          }
          //         Calculate ip
          ip = 0;
          for (j = 1; j <= m; j++)
          {
            if (isx[j - 1] > 0)
            {
              ip = ip + 1;
            }
          }
          if ((mean == "M") || (mean == "m"))
          {
            ip = ip + 1;
          }
          double[] b = new double[ip];
          double[] cov = new double[(ip * ip + ip) / 2];
          double[] se = new double[ip];
          double[,] v = new double[n, 7 + ip];
          if ((link == "E") || (link == "e"))
          {
            sr.Reset();
            a = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //         Set control parameters
          eps = 0.0000010e0;
          tol = 0.000050e0;
          maxit = 10;
          //
          G02.g02ga(link, mean, offset, weight, n, x, m, isx, ip, y, wt, ref s, a, out rss, out idf, b,
          out irank, se, cov, v, tol, maxit, iprint, eps, out ifail);
          //
          if ((ifail == 0) || (ifail >= (6)))
          {
            Console.WriteLine(" ");
            Console.Write("  {0}{1,12:e4}{2}{3,2}", "Residual sum of squares = ", rss, " Degrees of freedom = ", idf);
            Console.WriteLine(" ");
            Console.Write(" {0}", "      Estimate    Standard error");
            Console.WriteLine(" ");
            for (i = 1; i <= ip; i++)
            {
              Console.WriteLine("  {0,14:f4}{1,14:f4}", b[i - 1], se[i - 1]);
            }
            Console.WriteLine(" ");
            Console.Write(" {0}", "     Y        FV     Residual       H");
            Console.WriteLine(" ");
            for (i = 1; i <= n; i++)
            {
              Console.WriteLine("  {0,7:f1}{1,10:f2}{2,12:f4}{3,10:f3}", y[i - 1], v[i - 1, 1], v[i - 1, 4], v[i - 1, 5]);
            }
          }
          else
          {
            Console.WriteLine(" ");
            Console.WriteLine("** g02ga failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02gb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02GBE
  {
    static string datafile = "ExampleData/g02gbe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double dev,   eps,   tol; int i,  idf,  ip,  iprint,  irank,  j,  m,  maxit,  n;
        string link = "",
        mean = "",
        offset = "",
        weight = "";
        int ifail;
        Console.WriteLine("g02gb Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        link = sr.Next();
        mean = sr.Next();
        offset = sr.Next();
        weight = sr.Next();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        iprint = int.Parse(sr.Next());
        double[] t = new double[n];
        double[] wt = new double[n];
        double[,] x = new double[n, m];
        double[] y = new double[n];
        int[] isx = new int[m];
        if (n >=2 && m >= 1)
        {
          if ((weight == "W") || (weight == "w"))
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              t[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              wt[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          else
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              t[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          sr.Reset();
          for (j = 1; j <= m; j++)
          {
            isx[j - 1] = int.Parse(sr.Next());
          }
          //         Calculate ip
          ip = 0;
          for (j = 1; j <= m; j++)
          {
            if (isx[j - 1] > 0)
            {
              ip = ip + 1;
            }
          }
          if ((mean == "M") || (mean == "m"))
          {
            ip = ip + 1;
          }
          double[] b = new double[ip];
          double[] se = new double[ip];
          double[] cov = new double[(ip*ip + ip)/2];
          double[,] v = new double[n, 7+ip];
          //         Set control parameters
          eps = 0.0000010e0;
          tol = 0.000050e0;
          maxit = 10;
          //
          G02.g02gb(link, mean, offset, weight, n, x, m, isx, ip, y, t, wt, out dev, out idf, b,
          out irank, se, cov, v, tol, maxit, iprint, eps, out ifail);
          //
          if ((ifail == 0) || (ifail >= (7)))
          {
            Console.WriteLine(" ");
            Console.WriteLine("  {0}{1,12:e4}", "Deviance = ", dev);
            Console.WriteLine("  {0}{1,2}", "Degrees of freedom = ", idf);
            Console.WriteLine(" ");
            Console.Write(" {0}", "       Estimate     Standard error");
            Console.WriteLine(" ");
            for (i = 1; i <= ip; i++)
            {
              Console.WriteLine("  {0,14:f4}{1,14:f4}", b[i - 1], se[i - 1]);
            }
            Console.WriteLine(" ");
            Console.Write(" {0}", "       N          Y        FV      Residual      H");
            Console.WriteLine(" ");
            for (i = 1; i <= n; i++)
            {
              Console.WriteLine("  {0,10:f1}{1,10:f1}{2,10:f2}{3,12:f4}{4,10:f3}", t[i - 1], y[i - 1], v[i - 1, 1], v[i - 1, 4], v[i - 1, 5]);
            }
          }
          else
          {
            Console.WriteLine(" ");
            Console.WriteLine("** g02gb failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02gc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02GCE
  {
    static string datafile = "ExampleData/g02gce.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double a,   dev,   eps,   tol; int i,  idf,  ip,  iprint,  irank,  j,  m,  maxit,  n;
        string link = "",
        mean = "",
        offset = "",
        weight = "";
        int ifail;
        Console.WriteLine("g02gc Example Program Results");
        //      Skip heading in data file
        a = 0.0;
        sr.Reset();
        sr.Reset();
        link = sr.Next();
        mean = sr.Next();
        offset = sr.Next();
        weight = sr.Next();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        iprint = int.Parse(sr.Next());
        double[] wt = new double[n];
        double[,] x = new double[n, m];
        double[] y = new double[n];
        int[] isx = new int[m];
        if (n >= 2 && m >= 1)
        {
          if ((weight == "W") || (weight == "w"))
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              wt[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          else
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          sr.Reset();
          for (j = 1; j <= m; j++)
          {
            isx[j - 1] = int.Parse(sr.Next());
          }
          //         Calculate ip
          ip = 0;
          for (j = 1; j <= m; j++)
          {
            if (isx[j - 1] > 0)
            {
              ip = ip + 1;
            }
          }
          if ((mean == "M") || (mean == "m"))
          {
            ip = ip + 1;
          }
          double[] b = new double[ip];
          double[] cov = new double[(ip*ip + ip)/2];
          double[] se = new double[ip];
          double[,] v = new double[n, 7+ip];
          if ((link == "E") || (link == "e"))
          {
            sr.Reset();
            a = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //         Set control parameters
          eps = 0.0000010e0;
          tol = 0.000050e0;
          maxit = 10;
          //
          G02.g02gc(link, mean, offset, weight, n, x, m, isx, ip, y, wt, a, out dev, out idf, b,
          out irank, se, cov, v, tol, maxit, iprint, eps, out ifail);
          //
          if ((ifail == 0) || (ifail >= (7)))
          {
            Console.WriteLine(" ");
            Console.WriteLine("  {0}{1,12:e4}", "Deviance = ", dev);
            Console.WriteLine("  {0}{1,2}", "Degrees of freedom = ", idf);
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "      Estimate     Standard error");
            Console.WriteLine(" ");
            for (i = 1; i <= ip; i++)
            {
              Console.WriteLine("  {0,14:f4}{1,14:f4}", b[i - 1], se[i - 1]);
            }
            Console.WriteLine(" ");
            Console.Write(" {0}", "    Y        FV      Residual       H");
            Console.WriteLine(" ");
            for (i = 1; i <= n; i++)
            {
              Console.WriteLine("  {0,7:f1}{1,10:f2}{2,12:f4}{3,10:f3}", y[i - 1], v[i - 1, 1], v[i - 1, 4], v[i - 1, 5]);
            }
          }
          else
          {
            Console.WriteLine(" ");
            Console.WriteLine("** g02gc failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02gd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02GDE
  {
    static string datafile = "ExampleData/g02gde.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double a,   dev,   eps,   s,   tol; int i,  idf,  ip,  iprint,  irank,  j,  m,  maxit,  n;
        string link = "",
        mean = "",
        offset = "",
        weight = "";
        int ifail;
        Console.WriteLine("g02gd Example Program Results");
        //      Skip heading in data file
        a = 0.0;
        sr.Reset();
        sr.Reset();
        link = sr.Next();
        mean = sr.Next();
        offset = sr.Next();
        weight = sr.Next();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        s = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        iprint = int.Parse(sr.Next());
        double[] wt = new double[n];
        double[,] x = new double[n, m];
        double[] y = new double[n];
        int[] isx = new int[m];
        if (n >=2  && m >= 1)
        {
          if ((weight == "W") || (weight == "w"))
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              wt[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          else
          {
            for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= m; j++)
              {
                x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          sr.Reset();
          for (j = 1; j <= m; j++)
          {
            isx[j - 1] = int.Parse(sr.Next());
          }
          //         Calculate ip
          ip = 0;
          for (j = 1; j <= m; j++)
          {
            if (isx[j - 1] > 0)
            {
              ip = ip + 1;
            }
          }
          if ((mean == "M") || (mean == "m"))
          {
            ip = ip + 1;
          }
          double[] b = new double[ip];
          double[] cov = new double[(ip*ip+ip)/2];
          double[] se = new double[ip];
          double[,] v = new double[n, 7+ip];
          if ((link == "E") || (link == "e"))
          {
            sr.Reset();
            a = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //         Set control parameters
          eps = 0.0000010e0;
          tol = 0.000050e0;
          maxit = 10;
          //
          G02.g02gd(link, mean, offset, weight, n, x, m, isx, ip, y, wt, ref s, a, out dev, out idf, b,
          out irank, se, cov, v, tol, maxit, iprint, eps, out ifail);
          //
          if ((ifail == 0) || (ifail >= (7)))
          {
            Console.WriteLine(" ");
            Console.WriteLine("  {0}{1,12:e4}", "Deviance = ", dev);
            Console.WriteLine("  {0}{1,2}", "Degrees of freedom = ", idf);
            Console.WriteLine(" ");
            Console.Write(" {0}", "     Estimate     Standard error");
            Console.WriteLine(" ");
            for (i = 1; i <= ip; i++)
            {
              Console.WriteLine("  {0,14:f4}{1,14:f4}", b[i - 1], se[i - 1]);
            }
            Console.WriteLine(" ");
            Console.Write(" {0}", "     Y        FV     Residual        H");
            Console.WriteLine(" ");
            for (i = 1; i <= n; i++)
            {
              Console.WriteLine("  {0,7:f1}{1,10:f2}{2,12:f4}{3,10:f3}", y[i - 1], v[i - 1, 1], v[i - 1, 4], v[i - 1, 5]);
            }
          }
          else
          {
            Console.WriteLine(" ");
            Console.WriteLine("** g02gd failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02gk Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02GKE
  {
    static string datafile = "ExampleData/g02gke.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double a,   dev,   eps,   tol; int i,  iconst,  idf,  ip,  iprint,  irank,  j,  m,  maxit,  n;
        int ifail;
        Console.WriteLine("g02gk Example Program Results");
        //      Skip heading in data file
        a = 0.0;
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        iprint = int.Parse(sr.Next());
        double[] b = new double[9];
        double[] wt = new double[n];
        double[,] x = new double[n, m];
        double[] y = new double[n];
        int[] isx = new int[m];
        if (n >= 2 && m >= 1)
        {
          for (i = 1; i <= n; i++)
          {
            sr.Reset();
            for (j = 1; j <= m; j++)
            {
              x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          sr.Reset();
          for (j = 1; j <= m; j++)
          {
            isx[j - 1] = int.Parse(sr.Next());
          }
          ip = int.Parse(sr.Next());
          double[] cov = new double[(ip*ip+ip)/2];
          double[] se = new double[ip];
          double[,] v = new double[n, 7+ip];
          //         Set control parameters
          eps = 0.0000010e0;
          tol = 0.000050e0;
          maxit = 10;
          //
          //         Fit Log-linear model using g02gc
          G02.g02gc("L", "M", "N", "U", n, x, m, isx, ip, y, wt, a, out dev, out idf, b, out irank, se, cov, v, tol, maxit, iprint, eps, out ifail);
          //
          if ((ifail == 0) || (ifail >= (7)))
          {
            Console.WriteLine(" ");
            Console.WriteLine("  {0}{1,12:e4}", "Deviance = ", dev);
            Console.Write("  {0}{1,2}", "Degrees of freedom = ", idf);
            Console.WriteLine(" ");
            //            Input constraints
            iconst = ip - irank;
            double[,] c = new double[ip, iconst];
            for (i = 0; i < ip; i++)
            {
              sr.Reset();
              for (j = 0; j < iconst; j++)
              {
                c[i, j] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
            }
            //
            G02.g02gk(ip, iconst, v, c, b, 1.00e0, se, cov, out ifail);
            //
            if (ifail == 0)
            {
              Console.Write(" {0}", "      Estimate     Standard error");
              Console.WriteLine(" ");
              for (i = 0; i < ip; i++)
              {
                Console.WriteLine("  {0,14:f4}{1,14:f4}", b[i], se[i]);
              }
            }
            else
            {
              Console.WriteLine(" ");
              Console.WriteLine("** g02gk failed with ifail = {0,5}", ifail);
            }
          }
          else
          {
            Console.WriteLine(" ");
            Console.WriteLine("** g02gc failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02gn Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02GNE
  {
    static string datafile = "ExampleData/g02gne.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double a,   dev,   eps,   sestat,   stat,   tol,   z; int i,  idf,  ip,  iprint,  irank,  j,  m,  maxit,  n,  nestfn;
        bool est = false;
        int ifail;
        Console.WriteLine("g02gn Example Program Results");
        //      Skip heading in data file
        a = 0.0;
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        iprint = int.Parse(sr.Next());
        double[] wt = new double[n];
        double[,] x = new double[n, m];
        double[] y = new double[n];
        int[] isx = new int[m];
        if (n >= 2 && m >= 1)
        {
          for (i = 1; i <= n; i++)
          {
            sr.Reset();
            for (j = 1; j <= m; j++)
            {
              x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          sr.Reset();
          for (j = 1; j <= m; j++)
          {
            isx[j - 1] = int.Parse(sr.Next());
          }
          ip = int.Parse(sr.Next());
          double[] b = new double[ip];
          double[] cov = new double[(ip*ip+ip)/2];
          double[] f = new double[ip];
          double[] se = new double[ip];
          double[,] v = new double[n, 7+ip];
          //         Set control parameters
          eps = 0.0000010e0;
          tol = 0.000050e0;
          maxit = 10;
          //
          //         Fit Log-linear model using g02gc
          G02.g02gc("L", "M", "N", "U", n, x, m, isx, ip, y, wt, a, out dev, out idf, b, out irank, se, cov, v, tol, maxit, iprint, eps, out ifail);
          //
          if ((ifail == 0) || (ifail >= (7)))
          {
            Console.WriteLine(" ");
            Console.WriteLine("  {0}{1,12:e4}", "Deviance = ", dev);
            Console.Write("  {0}{1,2}", "Degrees of freedom = ", idf);
            Console.WriteLine(" ");
            Console.Write(" {0}", "      Estimate     Standard error");
            Console.WriteLine(" ");
            for (i = 1; i <= ip; i++)
            {
              Console.WriteLine("  {0,14:f4}{1,14:f4}", b[i - 1], se[i - 1]);
            }
            sr.Reset();
            nestfn = int.Parse(sr.Next());
            for (i = 1; i <= nestfn; i++)
            {
              sr.Reset();
              for (j = 1; j <= ip; j++)
              {
                f[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              //
              G02.g02gn(ip, irank, b, cov, v, f, out est, out stat, out sestat, out z, tol,
              out ifail);
              //
              if ((ifail == 0) || (ifail == 2))
              {
                Console.WriteLine(" ");
                Console.Write("  {0}{1,4}", "Function ", i);
                Console.WriteLine(" ");
                for (j = 1; j <= ip; j++)
                {
                  Console.Write(" {0, 8:f2}{1}", f[j - 1],j%5==0?"\n":"");
                }
                Console.WriteLine(" ");
                Console.WriteLine(" ");
                if (est)
                {
                  Console.WriteLine("  {0}{1,10:f4}{2}{3,10:f4}{4}{5,10:f4}", "STAT = ", stat, " SE = ", sestat, " Z = ", z);
                }
                else
                {
                  Console.WriteLine(" {0}", "Function not estimable");
                }
              }
              else
              {
                Console.WriteLine(" ");
                Console.WriteLine("** g02gn failed with ifail = {0,5}", ifail);
              }
            }
          }
          else
          {
            Console.WriteLine(" ");
            Console.WriteLine("** g02gc failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02gp Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02GPE
  {
    static string datafile = "ExampleData/g02gpe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double a,   eps,   rss,   s,   tol; int i,  idf,  ip,  iprint,  irank,  j,  m,  maxit,  n;
        bool vfobs = false;
        string error = "",
        link = "",
        mean = "",
        offset = "",
        weight = "";
        int ifail;
        Console.WriteLine("g02gp Example Program Results");
        //
        //      Skip headings in data file
        a = 0.0;
        sr.Reset();
        sr.Reset();
        //      Read in training data for model that will be used for prediction
        sr.Reset();
        link = sr.Next();
        mean = sr.Next();
        offset = sr.Next();
        weight = sr.Next();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        s = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        iprint = int.Parse(sr.Next());
        double[] eta = new double[n];
        double[] fwt = new double[n];
        double[] off = new double[n];
        double[] pred = new double[n];
        double[] seeta = new double[n];
        double[] sepred = new double[n];
        double[] t = new double[1];
        double[] wt = new double[n];
        double[,] x = new double[n, m];
        double[] y = new double[n];
        int[] isx = new int[m];
        if (n < 2 || m < 1)
        {
          Console.Write("   ** Problem size is too small.");
          goto L200;
        }
        if ((weight == "W") || (weight == "w"))
        {
          for (i = 1; i <= n; i++)
          {
            sr.Reset();
            for (j = 1; j <= m; j++)
            {
              x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            fwt[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        else
        {
          for (i = 1; i <= n; i++)
          {
            sr.Reset();
            for (j = 1; j <= m; j++)
            {
              x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        sr.Reset();
        for (j = 1; j <= m; j++)
        {
          isx[j - 1] = int.Parse(sr.Next());
        }
        //      Calculate ip
        ip = 0;
        for (j = 1; j <= m; j++)
        {
          if (isx[j - 1] > 0)
          {
            ip = ip + 1;
          }
        }
        if ((mean == "M") || (mean == "m"))
        {
          ip = ip + 1;
        }
        double[] b = new double[ip];
        double[] cov = new double[(ip*ip+ip)/2];
        double[,] v = new double[n, 7 + ip];
        double[] se = new double[ip];
        if ((link == "E") || (link == "e"))
        {
          sr.Reset();
          a = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        //      Set control parameters
        eps = 0.0000010e0;
        tol = 0.000050e0;
        maxit = 10;
        //      Call method to fit model to training data
        G02.g02ga(link, mean, offset, weight, n, x, m, isx, ip, y, fwt, ref s, a, out rss, out idf, b,
        out irank, se, cov, v, tol, maxit, iprint, eps, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g02ga failed with ifail = {0,5}", ifail);
          if (ifail < 6)
          {
            goto L200;
          }
        }
        //      Display parameter estimates for training data
        Console.WriteLine(" ");
        Console.WriteLine("  Residual sum of squares = {0,12:e4} Degrees of freedom = {1,2}", rss, idf);
        Console.WriteLine(" ");
        Console.Write(" {0}", "      Estimate     Standard error");
        Console.WriteLine(" ");
        for (i = 1; i <= ip; i++)
        {
          Console.WriteLine("  {0,14:f4}{1,14:f4}", b[i - 1], se[i - 1]);
        }
        //
        //      Skip second lot of headings in data file
        sr.Reset();
        //      Read in data to predict from and check array sizes
        sr.Reset();
        n = int.Parse(sr.Next());
        vfobs = bool.Parse(sr.Next());
        offset = sr.Next();
        weight = sr.Next();
        if (n < 1)
        {
          Console.Write(" {0}", "n < 1");
          goto L200;
        }
        if ((offset == "Y") && (weight == "W"))
        {
          for (i = 1; i <= n; i++)
          {
            sr.Reset();
            for (j = 1; j <= m; j++)
            {
              x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            off[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            wt[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        else if (offset == "Y")
        {
          for (i = 1; i <= n; i++)
          {
            sr.Reset();
            for (j = 1; j <= m; j++)
            {
              x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            off[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        else if (weight == "W")
        {
          for (i = 1; i <= n; i++)
          {
            sr.Reset();
            for (j = 1; j <= m; j++)
            {
              x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            wt[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        else
        {
          for (i = 1; i <= n; i++)
          {
            sr.Reset();
            for (j = 1; j <= m; j++)
            {
              x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
        }
        //      Using g02ga to fit training model, so error structure is normal
        error = "N";
        //      Call prediction method
        G02.g02gp(error, link, mean, offset, weight, n, x, m, isx, ip, t, off, wt, s, a, b, cov, vfobs,
        eta, seeta, pred, sepred, out ifail);
        // errfn, link, mean, offset, weight, n, x, m, isx, ip, t, off, wt, s, a, b, cov, vfobs, eta, seeta, pred, sepred, out ifail)
        if (ifail != 0)
        {
          Console.WriteLine("** g02gp failed with ifail = {0,5}", ifail);
          if (ifail != 22)
          {
            goto L200;
          }
        }
        //      Display predicted values
        Console.WriteLine(" ");
        Console.Write(" {0} {1}", "  I      ETA         SE(ETA)      Predicted  ",
        " SE(Predicted)");
        Console.WriteLine(" ");
        for (i = 1; i <= n; i++)
        {
          Console.WriteLine("  {0,3}){1,10:f5}        {2,10:f5}        {3,10:f5}        {4,10:f5}        ", i, eta[i - 1], seeta[i - 1], pred[i - 1], sepred[i - 1]);
        }
        //
        L200: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


g02gp Example Program Data
Training Data
'R' 'M' 'N' 'U' 5 1  0.0 0  : LINK,MEAN,OFFSET,WEIGHT,N,M,S,IPRINT
1.0 25.0
2.0 10.0
3.0  6.0
4.0  4.0
5.0  3.0                   : End of X, Y
1                          : ISX
Prediction Data
2  TRUE 'N' 'U'           : N,VFOBS,OFFSET,WEIGHT
32.0
18.0                       : End of X


g02gp Example Program Results

  Residual sum of squares =  3.8717e-001 Degrees of freedom =  3

       Estimate     Standard error
         -0.0239        0.0028
          0.0638        0.0026

   I      ETA         SE(ETA)      Predicted    SE(Predicted)
    1)   2.01807           0.08168           0.49552           0.35981
    2)   1.12472           0.04476           0.88911           0.36098


//      g02ha Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02HAE
  {
    static string datafile = "ExampleData/g02hae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double cpsi,   cucv,   dchi,   h1,   h2,   h3,   sigma,   tol; int i,  indc,  indw,  ipsi,  isigma,  j,  m,  maxit,  n,  nitmon;
        int ifail;
        Console.WriteLine("g02ha Example Program Results");
        //      Skip heading in data file
        indc = 0;
        cpsi = 0.0;
        h1 = 0.0;
        h2 = 0.0;
        h3 = 0.0;
        cucv = 0.0;
        dchi = 0.0;
        sr.Reset();
        //      Read in number of observations and number of x variables
        sr.Reset();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        double[,] c = new double[m, m];
        double[] rs = new double[n];
        double[] theta = new double[m];
        double[] wgt = new double[n];
        double[,] x = new double[n, m];
        double[] y = new double[n];
        double[] stat = new double[4];
        Console.WriteLine(" ");
        if (n > 0 && m > 0)
        {
          //         Read in x and y
          for (i = 1; i <= n; i++)
          {
            sr.Reset();
            for (j = 1; j <= m; j++)
            {
              x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //         Read in control parameters
          sr.Reset();
          indw = int.Parse(sr.Next());
          ipsi = int.Parse(sr.Next());
          isigma = int.Parse(sr.Next());
          //         Read in appropriate weight function parameters.
          if (indw != 0)
          {
            sr.Reset();
            cucv = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            indc = int.Parse(sr.Next());
          }
          if (ipsi > 0)
          {
            if (ipsi == 1)
            {
              sr.Reset();
              cpsi = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            if (ipsi == 2)
            {
              sr.Reset();
              h1 = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              h2 = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              h3 = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            if (isigma > 0)
            {
              sr.Reset();
              dchi = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //         Set values of remaining parameters
          tol = 0.50e-4;
          maxit = 50;
          // Change nitmon to a positive value if monitoring information
          // is required
          nitmon = 0;
          sigma = 1.00e0;
          for (i = 1; i <= m; i++)
          {
            theta[i - 1] = 0.00e0;
          }
          //
          G02.g02ha(indw, ipsi, isigma, indc, n, m, x, y, cpsi, h1, h2, h3, cucv, dchi, theta, ref sigma,

          c, rs, wgt, tol, maxit, nitmon, stat, out ifail);
          //
          if (((ifail != 0)) && ((ifail < 7)))
          {
            Console.WriteLine(" ");
            Console.WriteLine("** g02ha failed with ifail = {0,5}", ifail);
          }
          else
          {
            if (ifail >= (7))
            {
              Console.WriteLine("  {0}{1,5}", "g02ha returned ifail = ", ifail);
              Console.WriteLine(" {0}", "       Some of the following results may be unreliable");
            }
            Console.Write("  {0}{1,10:f4}", "Sigma = ", sigma);
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "       THETA      Standard");
            Console.WriteLine(" {0}", "                   errors");
            for (j = 1; j <= m; j++)
            {
              Console.WriteLine("  {0,12:f4}{1,13:f4}", theta[j - 1], c[j - 1, j - 1]);
            }
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "     Weights     Residuals");
            for (i = 1; i <= n; i++)
            {
              Console.WriteLine("  {0,12:f4}{1,13:f4}", wgt[i - 1], rs[i - 1]);
            }
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02hb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02HBE
  {
    static string datafile = "ExampleData/g02hbe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        G02.G02HB_UCV ucvG02HB = new G02.G02HB_UCV(ucv);
        DataReader sr = new DataReader(datafile);
        double bd,   bl,   tol; int i,  j,  k,  l1,  l2,  m,  maxit,  mm,  n,  nit,  nitmon;
        int ifail;
        Console.WriteLine("g02hb Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        //      Read in the dimensions of X
        sr.Reset();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        double[] a = new double[m*(m+1)/2];
        double[,] x = new double[n, m];
        double[] z = new double[n];
        if (n > 0 && m > 0 && m <= n)
        {
          //         Read in the x matrix
          for (i = 1; i <= n; i++)
          {
            sr.Reset();
            for (j = 1; j <= m; j++)
            {
              x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //         Read in the initial value of A
          mm = (m + 1) * m / 2;
          sr.Reset();
          for (j = 1; j <= mm; j++)
          {
            a[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //         Set the values remaining parameters
          bl = 0.90e0;
          bd = 0.90e0;
          maxit = 50;
          tol = 0.50e-4;
          // Change nitmon to a positive value if monitoring information
          // is required
          nitmon = 0;
          //
          G02.g02hb(ucvG02HB, n, m, x, a, z, bl, bd, tol, maxit, nitmon, out nit, out ifail);
          //
          if (ifail == 0)
          {
            Console.Write("  {0}{1,4}{2}", "g02hb required ", nit, " iterations to converge");
            Console.WriteLine(" ");
            Console.Write(" {0}", "Matrix A");
            Console.WriteLine(" ");
            l2 = 0;
            for (j = 1; j <= m; j++)
            {
              l1 = l2 + 1;
              l2 = l2 + j;
              for (k = l1; k <= l2; k++)
              {
                Console.Write(" {0, 9:f4}", a[k - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "Vector Z");
            for (i = 1; i <= n; i++)
            {
              Console.WriteLine("  {0,9:f4}", z[i - 1]);
            }
            //            Calculate Krasker-Welsch weights
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "Vector of weights");
            for (i = 1; i <= n; i++)
            {
              z[i - 1] = 1.00e0 / z[i - 1];
              Console.WriteLine("  {0,9:f4}", z[i - 1]);
            }
          }
          else
          {
            Console.WriteLine(" ");
            Console.WriteLine("** g02hb failed with ifail = {0,5}", ifail);
          }
          //
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write("Exception Raised");
      }
    }
    //
    public static double ucv(double t)
    {
      const double ucvc = 2.50;
      double ucvValue = 0.0;
      // ucv function for Krasker-Welsch weights
      double pc,   pd,   q,   q2;
      ucvValue = 1.00e0;
      if (t != 0.00e0)
      {
        q = ucvc / t;
        q2 = q * q;
        pc = S.s15ab(q);
        if (q2 < -Math.Log(X02.x02ak()))
        {
          pd = Math.Exp(-q2 / 2.00e0) / Math.Sqrt(X01.x01aa() * 2.00e0);
        }
        else
        {
          pd = 0.00e0;
        }
        ucvValue = (2.00e0 * pc - 1.00e0) * (1.00e0 - q2) + q2 - 2.00e0 * q * pd;
      }
      return ucvValue;
    }
  }
}


//      g02hd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02HDE
  {
    static string datafile = "ExampleData/g02hde.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        G02.G02HD_CHI chiG02HD = new G02.G02HD_CHI(chi);
        G02.G02HD_PSI psiG02HD = new G02.G02HD_PSI(psi);
        DataReader sr = new DataReader(datafile);
        double beta,   eps,   psip0,   sigma,   tol; int i,  indw,  isigma,  j,  k,  m,  maxit,  n,  nit,  nitmon;
        int ifail;
        Console.WriteLine("g02hd Example Program Results");
        //      Skip heading in data file
        beta = 0.0;
        sr.Reset();
        //      Read in the dimensions of X
        sr.Reset();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        double[] rs = new double[n];
        double[] theta = new double[m];
        double[] wgt = new double[n];
        double[,] x = new double[n, m];
        double[] y = new double[n];
        if (n > 0 && m > 0)
        {
          //         Read in the x matrix, the y values and set x[i-1,0] to 1 for the
          //         constant term
          for (i = 1; i <= n; i++)
          {
            sr.Reset();
            for (j = 2; j <= m; j++)
            {
              x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            x[i - 1, 0] = 1.00e0;
          }
          //         Read in weights
          for (i = 1; i <= n; i++)
          {
            sr.Reset();
            wgt[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          betcal(ref n, wgt, ref beta);
          //         Set other parameter values
          maxit = 50;
          tol = 0.50e-4;
          eps = 0.50e-5;
          psip0 = 1.00e0;
          //         Set value of isigma and initial value of sigma
          isigma = 1;
          sigma = 1.00e0;
          //         Set initial value of theta
          for (j = 1; j <= m; j++)
          {
            theta[j - 1] = 0.00e0;
          }
          // Change nitmon to a positive value if monitoring information
          // is required
          nitmon = 0;
          //         Schweppe type regression
          indw = 1;
          //
          G02.g02hd(chiG02HD, psiG02HD, psip0, beta, indw, isigma, n, m, x, y, wgt, theta, out k,
          ref sigma, rs, tol, eps, maxit, nitmon, out nit, out ifail);
          //
          Console.WriteLine(" ");
          if ((ifail != 0) && (ifail != 7))
          {
            Console.WriteLine(" ");
            Console.WriteLine("** g02hd failed with ifail = {0,5}", ifail);
          }
          else
          {
            if (ifail == 7)
            {
              Console.Write("  {0}{1,5}", "g02hd returned ifail = ", ifail);
              Console.Write(" {0}", "Some of the following results may be unreliable");
            }
            Console.WriteLine("  {0}{1,4}{2}", "g02hd required ", nit, " iterations to converge");
            Console.WriteLine("  {0}{1,4}", "                   K = ", k);
            Console.WriteLine("  {0}{1,9:f4}", "               Sigma = ", sigma);
            Console.WriteLine(" {0}", "    THETA");
            for (j = 1; j <= m; j++)
            {
              Console.WriteLine("  {0,9:f4}", theta[j - 1]);
            }
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "  Weights  Residuals");
            for (i = 1; i <= n; i++)
            {
              Console.WriteLine("  {0,9:f4}{1,9:f4}", wgt[i - 1], rs[i - 1]);
            }
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write("Exception Raised");
      }
    }
    //
    public static double psi(double t)
    {
      double psiValue = 0.0;
      double c = 1.5e0;
      if (t <= -c)
      {
        psiValue = -c;
      }
      else if (Math.Abs(t) < c)
      {
        psiValue = t;
      }
      else
      {
        psiValue = c;
      }
      return psiValue;
    }
    public static double chi(double t)
    {
      double chiValue = 0.0;
      double ps = 0.0;
      double dchi = 1.5e0;
      ps = dchi;
      if (Math.Abs(t) < dchi)
      {
        ps = t;
      }
      chiValue = ps * ps / 2.00e0;
      return chiValue;
    }
    //
    public static void betcal(ref int n, double[] wgt, ref double beta)
    {
      //      Calculate beta for Schweppe type regression
      const double dchi = 1.50e0;
      double amaxex,   anormc,   b,   d2,   dc,   dw,   dw2,   pc,   w2; int i;
      amaxex = -Math.Log(X02.x02ak());
      anormc = Math.Sqrt(X01.x01aa() * 2.00e0);
      d2 = dchi * dchi;
      beta = 0.00e0;
      for (i = 1; i <= n; i++)
      {
        w2 = wgt[i - 1] * wgt[i - 1];
        dw = wgt[i - 1] * dchi;
        pc = S.s15ab(dw);
        dw2 = dw * dw;
        dc = 0.00e0;
        if (dw2 < amaxex)
        {
          dc = Math.Exp(-dw2 / 2.00e0) / anormc;
        }
        b = (-dw * dc + pc - 0.50e0) / w2 + (1.00e0 - pc) * d2;
        beta = b * w2 / (double)n + beta;
      }
    }
  }
}


//      g02hf Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02HFE
  {
    static string datafile = "ExampleData/g02hfe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        G02.G02HF_PSI psiG02HF = new G02.G02HF_PSI(psi);
        G02.G02HF_PSP pspG02HF = new G02.G02HF_PSP(psp);
        DataReader sr = new DataReader(datafile);
        double sigma = 0.0;
        int i,   indc,   indw,   j,   k,   m,   n; int ifail;
        Console.WriteLine("g02hf Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        //      Read in the dimensions of X
        sr.Reset();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        double[,] c = new double[m, m];
        double[] rs = new double[n];
        double[] wgt = new double[n];
        double[,] x = new double[n, m];
        double[] diag_d = new double[n];
        double[] diag_p = new double[n];
        Console.WriteLine(" ");
        if (n > 0 && m > 0 && m <= n)
        {
          //         Read in the x matrix
          for (i = 1; i <= n; i++)
          {
            sr.Reset();
            for (j = 1; j <= m; j++)
            {
              x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //         Read in sigma
          sr.Reset();
          sigma = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          //         Read in weights and residuals
          for (i = 1; i <= n; i++)
          {
            sr.Reset();
            wgt[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            rs[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //         Set parameters for Schweppe type regression
          indw = 1;
          indc = 1;
          //
          G02.g02hf(psiG02HF, pspG02HF, indw, indc, sigma, n, m, x, rs, wgt, c, diag_d, diag_p,
                    out ifail);
          //
          if (ifail == 0)
          {
            Console.Write(" {0}", "Covariance matrix\n");
            for (j = 1; j <= m; j++)
            {
              for (k = 1; k <= m; k++)
              {
                Console.Write(" {0,8:f4}", c[j - 1, k - 1]);
              }
              Console.WriteLine(" ");
            }
          }
          else
          {
            Console.WriteLine(" ");
            Console.WriteLine("** g02hf failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
    //
    public static double psi(double t)
    {
      double psiValue = 0.0;
      double c = 1.5e0;
      if (t <= -c)
      {
        psiValue = -c;
      }
      else if (Math.Abs(t) < c)
      {
        psiValue = t;
      }
      else
      {
        psiValue = c;
      }
      return psiValue;
    }
    //
    public static double psp(double t)
    {
      double pspValue = 0.0;
      pspValue = 0.00e0;
      double c = 1.5e0;
      if (Math.Abs(t) < c)
      {
        pspValue = 1.00e0;
      }
      return pspValue;
    }
  }
}


//      g02hk Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02HKE
  {
    static string datafile = "ExampleData/g02hke.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double eps,   tol; int i,  j,  k,  l1,  l2,  m,  maxit,  n,  nit,  nitmon;
        int ifail;
        Console.WriteLine("g02hk Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        //      Read in the dimensions of X
        sr.Reset();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        double[] cov = new double[m*(m+1)/2];
        double[] theta = new double[m];
        double[,] x = new double[n, m];
        if (n > 0 && m > 0 && m <=n)
        {
          //         Read in the x matrix
          for (i = 1; i <= n; i++)
          {
            sr.Reset();
            for (j = 1; j <= m; j++)
            {
              x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //         Read in value of eps
          sr.Reset();
          eps = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          //         Set up remaining parameters
          maxit = 100;
          tol = 0.50e-4;
          //         Set nitmon to positive value for iteration monitoring
          nitmon = 0;
          //
          G02.g02hk(n, m, x, eps, cov, theta, maxit, nitmon, tol, out nit, out ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine(" ");
            Console.Write("  {0}{1,4}{2}", "g02hk required ", nit, " iterations to converge");
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "Covariance matrix\n");
            l2 = 0;
            for (j = 1; j <= m; j++)
            {
              l1 = l2 + 1;
              l2 = l2 + j;
              for (k = l1; k <= l2; k++)
              {
                Console.Write(" {0,10:f3}", cov[k - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "THETA");
            for (j = 1; j <= m; j++)
            {
              Console.WriteLine("  {0,10:f3}", theta[j - 1]);
            }
          }
          else
          {
            Console.WriteLine(" ");
            Console.WriteLine("** g02hk failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


g02hk Example Program Results

  g02hk required   23 iterations to converge
 Covariance matrix

      3.461
     -3.681      5.348
      4.682     -6.645     14.439

 THETA
       5.818
       3.681
      15.037


//      g02hl Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02HLE
  {
    static string datafile = "ExampleData/g02hle.d";
    static double[] ruser = new double[2];
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        G02.G02HL_UCV ucvG02HL = new G02.G02HL_UCV(ucv);
        DataReader sr = new DataReader(datafile);
        double bd,   bl,   tol; int i,  indm,  j,  k,  l1,  l2,  m,  maxit,  mm,  n,  nit,  nitmon;
        int ifail;
        Console.WriteLine("g02hl Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        //      Read in the dimensions of X
        sr.Reset();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        double[] a = new double[m*(m+1)/2];
        double[] cov = new double[m*(m+1)/2];
        double[] theta = new double[m];
        double[] wt = new double[n];
        double[,] x = new double[n, m];
        if (n > 0 && m > 0)
        {
          //         Read in the x matrix
          for (i = 1; i <= n; i++)
          {
            sr.Reset();
            for (j = 1; j <= m; j++)
            {
              x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //         Read in the initial value of A
          mm = (m + 1) * m / 2;
          sr.Reset();
          for (j = 1; j <= mm; j++)
          {
            a[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //         Read in the initial value of theta
          sr.Reset();
          for (j = 1; j <= m; j++)
          {
            theta[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //         Read in the values of the parameters of the ucv functions
          sr.Reset();
          ruser[0] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          ruser[1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          //         Set the values of remaining parameters
          indm = 1;
          bl = 0.90e0;
          bd = 0.90e0;
          maxit = 50;
          tol = 0.50e-4;
          // Change nitmon to a positive value if monitoring information
          // is required *
          nitmon = 0;
          //
          G02.g02hl(ucvG02HL, indm, n, m, x, cov, a, wt, theta, bl, bd, maxit, nitmon, tol, out nit,
          out ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine(" ");
            Console.Write("  {0}{1,4}{2}", "g02hl required ", nit, " iterations to converge");
            Console.WriteLine(" ");
            Console.Write(" {0}", "Robust covariance matrix");
            Console.WriteLine(" ");
            l2 = 0;
            for (j = 1; j <= m; j++)
            {
              l1 = l2 + 1;
              l2 = l2 + j;
              for (k = l1; k <= l2; k++)
              {
                Console.Write(" {0, 10:f3}", cov[k - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "Robust estimates of THETA");
            for (j = 1; j <= m; j++)
            {
              Console.WriteLine("  {0,10:f3}", theta[j - 1]);
            }
          }
          else
          {
            Console.WriteLine(" ");
            Console.WriteLine("** g02hl failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
    //
    //
    public static void ucv(double t, out double u, out double ud, out double w,
    out double wd)
    {
      //      u function and derivative
      double cu,   cw,   t2; cu = ruser[0];
      u = 1.00e0;
      ud = 0.00e0;
      if (t != 0)
      {
        t2 = t * t;
        if (t2 > cu)
        {
          u = cu / t2;
          ud = -2.00e0 * u / t;
        }
      }
      //      w function and derivative
      cw = ruser[1];
      if (t > cw)
      {
        w = cw / t;
        wd = -w / t;
      }
      else
      {
        w = 1.00e0;
        wd = 0.00e0;
      }
    }
  }
}


g02hl Example Program Results

  g02hl required   25 iterations to converge
 Robust covariance matrix
      3.278
     -3.692      5.284
      4.739     -6.409     11.837

 Robust estimates of THETA
       5.700
       3.864
      14.704


//      g02hm Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02HME
  {
    static string datafile = "ExampleData/g02hme.d";
    static double[] ruser = new double[2];
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        G02.G02HM_UCV ucvG02HM = new G02.G02HM_UCV(ucv);
        DataReader sr = new DataReader(datafile);
        double bd,   bl,   tol; int i,  indm,  j,  k,  l1,  l2,  m,  maxit,  mm,  n,  nit,  nitmon;
        int ifail;
        Console.WriteLine("g02hm Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        //      Read in the dimensions of X
        sr.Reset();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        double[] a = new double[m*(m+1)/2];
        double[] cov = new double[m*(m+1)/2];
        double[] theta = new double[m];
        double[] wt = new double[n];
        double[,] x = new double[n, m];
        if (n > 0 && m > 0 && m <= n)
        {
          //         Read in the x matrix
          for (i = 1; i <= n; i++)
          {
            sr.Reset();
            for (j = 1; j <= m; j++)
            {
              x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //         Read in the initial value of A
          mm = ((m + 1) * m) / 2;
          sr.Reset();
          for (j = 1; j <= mm; j++)
          {
            a[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //         Read in the initial value of theta
          sr.Reset();
          for (j = 1; j <= m; j++)
          {
            theta[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //         Read in the values of the parameters of the ucv functions
          sr.Reset();
          ruser[0] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          ruser[1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          //         Set the values remaining parameters
          indm = 1;
          bl = 0.90e0;
          bd = 0.90e0;
          maxit = 50;
          tol = 0.50e-4;
          // Change nitmon to a positive value if monitoring information
          // is required
          nitmon = 0;
          //
          G02.g02hm(ucvG02HM, indm, n, m, x, cov, a, wt, theta, bl, bd, maxit, nitmon, tol, out nit,
          out ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine(" ");
            Console.Write("  {0}{1,4}{2}", "g02hm required ", nit, " iterations to converge");
            Console.WriteLine(" ");
            Console.Write(" {0}", "Robust covariance matrix");
            Console.WriteLine(" ");
            l2 = 0;
            for (j = 1; j <= m; j++)
            {
              l1 = l2 + 1;
              l2 = l2 + j;
              for (k = l1; k <= l2; k++)
              {
                Console.Write(" {0, 10:f3}", cov[k - 1]);
              }
              Console.WriteLine(" ");
            }
            Console.WriteLine(" ");
            Console.WriteLine(" {0}", "Robust estimates of THETA");
            for (j = 1; j <= m; j++)
            {
              Console.WriteLine("  {0,10:f3}", theta[j - 1]);
            }
          }
          else
          {
            Console.WriteLine(" ");
            Console.WriteLine("** g02hm failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
    public static void ucv(double t, out double u, out double w)
    {
      //      u function
      double cu,   cw,   t2; cu = ruser[0];
      u = 1.00e0;
      if (t != 0)
      {
        t2 = t * t;
        if (t2 > cu)
        {
          u = cu / t2;
        }
      }
      //      w function
      cw = ruser[1];
      if (t > cw)
      {
        w = cw / t;
      }
      else
      {
        w = 1.00e0;
      }
    }
  }
}


g02hm Example Program Results

  g02hm required   34 iterations to converge
 Robust covariance matrix
      3.278
     -3.692      5.284
      4.739     -6.409     11.837

 Robust estimates of THETA
       5.700
       3.864
      14.704


//      g02ja Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02JAE
  {
    static string datafile = "ExampleData/g02jae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double reml,   tol; int cwid,  df,  fint,  i,  j,  k,  l,  lb,  maxit,  n,  ncol,  nff,  nfv,  nrf,  nrv,  nv,  nvpr,  rint,  svid,  warn,  yvid;
        //
        int ifail;
        Console.WriteLine("g02ja Example Program Results");
        //
        //
        //      Skip heading in data file
        sr.Reset();
        //
        //      Read in the problem size information
        sr.Reset();
        n = int.Parse(sr.Next());
        ncol = int.Parse(sr.Next());
        nfv = int.Parse(sr.Next());
        nrv = int.Parse(sr.Next());
        nvpr = int.Parse(sr.Next());
        nv = nfv + nrv;
        double[,] dat = new double[n, ncol];
        double[] gamma = new double[nvpr+2];
        int[] fvid = new int[nfv];
        int[] levels = new int[ncol];
        int[] rvid = new int[nrv];
        int[] vpr = new int[nrv];
        //
        //      Check array sizes
        if (ncol < 2 )
        {
          Console.Write(" {0}", "Problem too small");
          goto L200;
        }
        //
        //      Read in number of levels for each variable
        sr.Reset();
        for (i = 1; i <= ncol; i++)
        {
          levels[i - 1] = int.Parse(sr.Next());
        }
        //
        //      Read in model information
        sr.Reset();
        yvid = int.Parse(sr.Next());
        for (i = 1; i <= nfv; i++)
        {
          fvid[i - 1] = int.Parse(sr.Next());
        }
        for (i = 1; i <= nrv; i++)
        {
          rvid[i - 1] = int.Parse(sr.Next());
        }
        svid = int.Parse(sr.Next());
        cwid = int.Parse(sr.Next());
        fint = int.Parse(sr.Next());
        rint = int.Parse(sr.Next());
        //
        //      If no subject specified, then ignore rint
        //      Check remaining array sizes
        if (n < 1 || (nvpr + rint) < 1)
        {
          Console.Write(" {0}", "Problem too small");
          goto L200;
        }
        //
        //      Read in the variance component flag
        sr.Reset();
        for (i = 1; i <= nrv; i++)
        {
          vpr[i - 1] = int.Parse(sr.Next());
        }
        //
        //      Read in the Data matrix
        for (i = 1; i <= n; i++)
        {
          sr.Reset();
          for (j = 1; j <= ncol; j++)
          {
            dat[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        //
        //      Read in the initial values for gamma
        sr.Reset();
        if (svid == 0)
        {
          rint = 0;
        }
        for (i = 1; i <= nvpr + rint; i++)
        {
          gamma[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        //
        //      Read in the maximum number of iterations
        sr.Reset();
        maxit = int.Parse(sr.Next());
        //      Calculate lb
        lb = rint;
        for (i=1; i<=nrv; i++)
        {
          lb += levels[rvid[i-1]-1];
        }
        if (svid != 0)
        {
          lb = lb*levels[svid-1];
        }
        lb += fint;
        for (i = 1; i<=nfv; i++)
        {
          lb += Math.Max(levels[fvid[i-1]-1]-1,1);
        }
        double[] b = new double[lb];
        double[] se = new double[lb];
        //
        //      Run the analysis
        tol = 0.00e0;
        warn = 0;
        G02.g02ja(n, ncol, dat, levels, yvid, cwid, nfv, fvid, fint, nrv, rvid, nvpr, vpr, rint, svid,

        gamma, out nff, out nrf, out df, out reml, b, se, maxit, tol, out warn, out ifail);
        //
        if (ifail == 0)
        {
          //         Output results
          if (warn != 0)
          {
            Console.Write(" {0} {1}", "Warning: At least one variance component was ", "estimated to be negative and then reset to zero");
          }
          Console.Write(" {0}", "Fixed effects (Estimate and Standard Deviation)");
          Console.WriteLine(" ");
          k = 1;
          if (fint == 1)
          {
            Console.WriteLine("  {0}{1,10:f4}{2,10:f4}", "Intercept             ", b[k - 1], se[k - 1]);
            k = k + 1;
          }
          for (i = 1; i <= nfv; i++)
          {
            for (j = 1; j <= levels[fvid[i - 1] - 1]; j++)
            {
              if ((levels[fvid[i - 1] - 1] != 1) && (j == 1))
              {
                goto L40;
              }
              Console.WriteLine("  {0}{1,4}{2}{3,4}{4,10:f4}{5,10:f4}", "Variable", i, " Level", j, b[k - 1], se[k - 1]);
              k = k + 1;
              L40: ;
            }
          }
          //
          Console.WriteLine(" ");
          Console.WriteLine(" {0} {1}", "Random Effects (Estimate and Standard",
          " Deviation)");
          if (svid == 0)
          {
            for (i = 1; i <= nrv; i++)
            {
              for (j = 1; j <= levels[rvid[i - 1] - 1]; j++)
              {
                Console.WriteLine("  {0}{1,4}{2}{3,4}{4,10:f4}{5,10:f4}", "Variable", i, " Level", j, b[k - 1], se[k - 1]);
                k = k + 1;
              }
            }
          }
          else
          {
            for (l = 1; l <= levels[svid - 1]; l++)
            {
              Console.Write("  {0}{1,4}", "Intercept for Subject Level", l);
              if (rint == 1)
              {
                Console.WriteLine("  {0,10:f4}{1,10:f4}", b[k - 1], se[k - 1]);
                k = k + 1;
              }
              for (i = 1; i <= nrv; i++)
              {
                for (j = 1; j <= levels[rvid[i - 1] - 1]; j++)
                {
                  Console.WriteLine("  {0}{1,4}{2}{3,4}{4}{5,4}{6,10:f4}{7,10:f4}", "Subject Level", l, " Variable", i, " Level",
                  j, b[k - 1], se[k - 1]);
                  k = k + 1;
                }
              }
            }
          }
          //
          Console.WriteLine(" ");
          Console.WriteLine(" {0}", " Variance Components");
          for (i = 1; i <= (nvpr + rint); i++)
          {
            Console.WriteLine("  {0,4}{1,10:f4}", i, gamma[i - 1]);
          }
          //
          Console.WriteLine("  {0}{1,10:f4}", "SIGMA^2     = ", gamma[nvpr + rint + 1 - 1]);
          Console.WriteLine("  {0}{1,10:f4}", "-2LOG LIKE  = ", reml);
          Console.WriteLine(" {0} {1}", "DF          = ", df);
        }
        else
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02ja failed with ifail = {0,5}", ifail);
        }
        L200: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


g02ja Example Program Results
 Fixed effects (Estimate and Standard Deviation)
  Intercept                37.0000    4.6674
  Variable   1 Level   2    1.0000    3.5173
  Variable   1 Level   3  -11.0000    3.5173
  Variable   2 Level   2   -8.2500    2.1635
  Variable   3 Level   2    0.5000    3.0596
  Variable   3 Level   3    7.7500    3.0596

 Random Effects (Estimate and Standard  Deviation)
  Intercept for Subject Level   1     10.7631    4.4865
  Subject Level   1 Variable   1 Level   1    3.7276    3.0331
  Subject Level   1 Variable   1 Level   2   -1.4476    3.0331
  Subject Level   1 Variable   1 Level   3    0.3733    3.0331
  Intercept for Subject Level   2     -0.5269    4.4865
  Subject Level   2 Variable   1 Level   1   -3.7171    3.0331
  Subject Level   2 Variable   1 Level   2   -1.2253    3.0331
  Subject Level   2 Variable   1 Level   3    4.8125    3.0331
  Intercept for Subject Level   3     -5.6450    4.4865
  Subject Level   3 Variable   1 Level   1    0.5903    3.0331
  Subject Level   3 Variable   1 Level   2    0.3987    3.0331
  Subject Level   3 Variable   1 Level   3   -2.3806    3.0331
  Intercept for Subject Level   4     -4.5912    4.4865
  Subject Level   4 Variable   1 Level   1   -0.6009    3.0331
  Subject Level   4 Variable   1 Level   2    2.2742    3.0331
  Subject Level   4 Variable   1 Level   3   -2.8052    3.0331

  Variance Components
     1   62.3958
     2   15.3819
  SIGMA^2     =     9.3611
  -2LOG LIKE  =   119.7618
 DF          =  16


//      g02jb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02JBE
  {
    static string datafile = "ExampleData/g02jbe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double ml,   tol; int cwid,  df,  fint,  i,  j,  k,  l,  lb,  maxit,  n,  ncol,  nff,  nfv,  nrf,  nrv,  nv,  nvpr,  rint,  svid,  warn,  yvid;
        //
        int ifail;
        Console.WriteLine("g02jb Example Program Results");
        //
        //      Skip heading in data file
        sr.Reset();
        //
        //      Read in the problem size information
        sr.Reset();
        n = int.Parse(sr.Next());
        ncol = int.Parse(sr.Next());
        nfv = int.Parse(sr.Next());
        nrv = int.Parse(sr.Next());
        nvpr = int.Parse(sr.Next());
        nv = nfv + nrv;
        //        double[] b = new double[lb];
        double[,] dat = new double[n, ncol];
        double[] gamma = new double[nvpr + 2];
        //        double[] se = new double[lb];
        int[] fvid = new int[nfv];
        int[] levels = new int[ncol];
        int[] rvid = new int[nrv];
        int[] vpr = new int[nrv];
        //
        //      Check array sizes
        if (ncol < 2 || nv < 1)
        {
          Console.Write(" {0}", "Problem too small");
          goto L200;
        }
        //
        //      Read in number of levels for each variable
        sr.Reset();
        for (i = 1; i <= ncol; i++)
        {
          levels[i - 1] = int.Parse(sr.Next());
        }
        //
        //      Read in model information
        sr.Reset();
        yvid = int.Parse(sr.Next());
        for (i = 1; i <= nfv; i++)
        {
          fvid[i - 1] = int.Parse(sr.Next());
        }
        for (i = 1; i <= nrv; i++)
        {
          rvid[i - 1] = int.Parse(sr.Next());
        }
        svid = int.Parse(sr.Next());
        cwid = int.Parse(sr.Next());
        fint = int.Parse(sr.Next());
        rint = int.Parse(sr.Next());
        //
        //      If no subject specified, then ignore rint
        //
        //      Check remaining array sizes
        if (n < 2 ||  (nvpr + rint) < 1)
        {
          Console.Write(" {0}", "Problem too large, increase size of arrays");
          goto L200;
        }
        //
        //      Read in the variance component flag
        sr.Reset();
        for (i = 1; i <= nrv; i++)
        {
          vpr[i - 1] = int.Parse(sr.Next());
        }
        //
        //      Read in the Data matrix
        for (i = 1; i <= n; i++)
        {
          sr.Reset();
          for (j = 1; j <= ncol; j++)
          {
            dat[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        //
        //      Read in the initial values for gamma
        sr.Reset();
        for (i = 1; i <= nvpr + rint; i++)
        {
          gamma[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        //
        //      Read in the maximum number of iterations
        sr.Reset();
        maxit = int.Parse(sr.Next());
        //      Calculate lb
        lb = rint;
        for (i=1; i<=nrv; i++)
        {
          lb += levels[rvid[i-1]-1];
        }
        if (svid != 0)
        {
          lb = lb*levels[svid-1];
        }
        lb += fint;
        for (i = 1; i<=nfv; i++)
        {
          lb += Math.Max(levels[fvid[i-1]-1]-1,1);
        }
        double[] b = new double[lb];
        double[] se = new double[lb];
        //
        //      Run the analysis
        tol = 0.00e0;
        warn = 0;
        G02.g02jb(n, ncol, dat, levels, yvid, cwid, nfv, fvid, fint, nrv, rvid, nvpr, vpr, rint, svid,

        gamma, out nff, out nrf, out df, out ml, b, se, maxit, tol, out warn, out ifail);
        //
        if (ifail == 0)
        {
          //         Output results
          if (warn != 0)
          {
            Console.Write(" {0} {1}", "Warning: At least one variance component was ", "estimated to be negative and then reset to zero");
          }
          Console.Write(" {0}", "Fixed effects (Estimate and Standard Deviation)");
          Console.WriteLine(" ");
          k = 1;
          if (fint == 1)
          {
            Console.WriteLine("  {0}{1,10:f4}{2,10:f4}", "Intercept             ", b[k - 1], se[k - 1]);
            k = k + 1;
          }
          for (i = 1; i <= nfv; i++)
          {
            for (j = 1; j <= levels[fvid[i - 1] - 1]; j++)
            {
              if ((levels[fvid[i - 1] - 1] != 1) && (j == 1))
              {
                goto L40;
              }
              Console.WriteLine("  {0}{1,4}{2}{3,4}{4,10:f4}{5,10:f4}", "Variable", i, " Level", j, b[k - 1], se[k - 1]);
              k = k + 1;
              L40: ;
            }
          }
          //
          Console.WriteLine(" ");
          Console.WriteLine(" {0} {1}", "Random Effects (Estimate and Standard",
          " Deviation)");
          if (svid == 0)
          {
            for (i = 1; i <= nrv; i++)
            {
              for (j = 1; j <= levels[rvid[i - 1] - 1]; j++)
              {
                Console.WriteLine("  {0}{1,4}{2}{3,4}{4,10:f4}{5,10:f4}", "Variable", i, " Level", j, b[k - 1], se[k - 1]);
                k = k + 1;
              }
            }
          }
          else
          {
            for (l = 1; l <= levels[svid - 1]; l++)
            {
              if (rint == 1)
              {
                Console.WriteLine("  {0}{1,4}{2}{3,10:f4}{4,10:f4}", "Intercept for Subject Level", l, "", b[k - 1], se[k - 1]);
                k = k + 1;
              }
              for (i = 1; i <= nrv; i++)
              {
                for (j = 1; j <= levels[rvid[i - 1] - 1]; j++)
                {
                  Console.WriteLine("  {0}{1,4}{2}{3,4}{4}{5,4}{6,10:f4}{7,10:f4}", "Subject Level", l, " Variable", i, " Level", j, b[k - 1], se[k - 1]);
                  k = k + 1;
                }
              }
            }
          }
          //
          Console.WriteLine(" ");
          Console.WriteLine(" {0}", " Variance Components");
          for (i = 1; i <= (nvpr + rint); i++)
          {
            Console.WriteLine("  {0,4}{1,10:f4}", i, gamma[i - 1]);
          }
          //
          Console.WriteLine("  {0}{1,10:f4}", "SIGMA^2     = ", gamma[nvpr + rint + 1 - 1]);
          Console.WriteLine("  {0}{1,10:f4}", "-2LOG LIKE  = ", ml);
          Console.WriteLine(" {0} {1}", "DF          = ", df);
        }
        else
        {
          Console.WriteLine(" ");
          Console.WriteLine("** g02jb failed with ifail = {0,5}", ifail);
        }
        L200: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write("Exception Raised");
      }
    }
  }
}


g02jb Example Program Results
 Fixed effects (Estimate and Standard Deviation)
  Intercept                37.0000    4.0421
  Variable   1 Level   2    1.0000    3.0461
  Variable   1 Level   3  -11.0000    3.0461
  Variable   2 Level   2   -8.2500    1.8736
  Variable   3 Level   2    0.5000    2.6497
  Variable   3 Level   3    7.7500    2.6497

 Random Effects (Estimate and Standard  Deviation)
  Intercept for Subject Level   1   10.7631    3.8855
  Subject Level   1 Variable   1 Level   1    3.7276    2.6268
  Subject Level   1 Variable   1 Level   2   -1.4476    2.6268
  Subject Level   1 Variable   1 Level   3    0.3733    2.6268
  Intercept for Subject Level   2   -0.5269    3.8855
  Subject Level   2 Variable   1 Level   1   -3.7171    2.6268
  Subject Level   2 Variable   1 Level   2   -1.2253    2.6268
  Subject Level   2 Variable   1 Level   3    4.8125    2.6268
  Intercept for Subject Level   3   -5.6450    3.8855
  Subject Level   3 Variable   1 Level   1    0.5903    2.6268
  Subject Level   3 Variable   1 Level   2    0.3987    2.6268
  Subject Level   3 Variable   1 Level   3   -2.3806    2.6268
  Intercept for Subject Level   4   -4.5912    3.8855
  Subject Level   4 Variable   1 Level   1   -0.6009    2.6268
  Subject Level   4 Variable   1 Level   2    2.2742    2.6268
  Subject Level   4 Variable   1 Level   3   -2.8052    2.6268

  Variance Components
     1   46.7969
     2   11.5365
  SIGMA^2     =     7.0208
  -2LOG LIKE  =   141.6877
 DF          =  16


//      g02ka Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02KAE
  {
    static string datafile = "ExampleData/g02kae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double h,   nep,   rss,   tau,   tol; int df,  i,  ip,  j,  m,  n,  niter,  opt,  optloo,  orig;
        int ifail;
        Console.WriteLine("g02ka Example Program Results");
        //
        //      Skip heading in data file
        sr.Reset();
        //      Read in data and check array limits
        sr.Reset();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        h = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        opt = int.Parse(sr.Next());
        tol = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        niter = int.Parse(sr.Next());
        orig = int.Parse(sr.Next());
        optloo = int.Parse(sr.Next());
        double[] perr = new double[5];
        double[] res = new double[n];
        double[,] x = new double[n, m];
        double[] y = new double[n];
        int[] isx = new int[m];
        if (n < 1 || m > n)
        {
          Console.WriteLine("   ** Problem size is too small.");
          goto L40;
        }
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          for (j = 1; j <= m; j++)
          {
            x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        sr.Reset();
        for (j = 1; j <= m; j++)
        {
          isx[j - 1] = int.Parse(sr.Next());
        }
        //
        //      Total number of variables.
        ip = 0;
        for (j = 1; j <= m; j++)
        {
          if (isx[j - 1] == 1)
          {
            ip = ip + 1;
          }
        }
        //
        //      Tolerance for setting singular values of H to zero.
        tau = 0.00e0;
        df = 0;
        int blength = ip + 1;
        double[] b = new double[blength];
        double[] vif = new double[ip];
        //
        //      Call function.
        G02.g02ka(n, m, x, isx, ip, tau, y, ref h, opt, ref niter, tol, out nep, orig, b, vif, res,
        out rss, out df, optloo, perr, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g02ka failed with ifail = {0,5}", ifail);
          if (ifail != -1)
          {
            goto L40;
          }
        }
        //      Print results:
        Console.WriteLine("");
        Console.WriteLine("{0}  {1,10:f4}", "Value of ridge parameter:", h);
        Console.WriteLine("");
        Console.WriteLine("{0}  {1,10:e4}", "Sum of squares of residuals:", rss);
        Console.WriteLine("{0}  {1,5}", "Degrees of freedom: ", df);
        Console.WriteLine("{0}  {1,10:f4}", "Number of effective parameters:", nep);
        Console.WriteLine("");
        printArrays(blength,1,b,"Parameter estimates" );
        Console.WriteLine("");
        Console.WriteLine(" {0} {1}", "Number of iterations:", niter);
        Console.WriteLine("");
        if (opt == 1)
        {
          Console.WriteLine(" {0}", "Ridge parameter minimises GCV");
        }
        else if (opt == 2)
        {
          Console.WriteLine(" {0}", "Ridge parameter minimises UEV");
        }
        else if (opt == 3)
        {
          Console.WriteLine(" {0}", "Ridge parameter minimises FPE");
        }
        else if (opt == 4)
        {
          Console.WriteLine(" {0}", "Ridge parameter minimises BIC");
        }
        Console.WriteLine("");
        Console.WriteLine(" {0}", "Estimated prediction errors:");
        Console.WriteLine("{0}  {1,10:f4}", "GCV    =", perr[0]);
        Console.WriteLine("{0}  {1,10:f4}", "UEV    =", perr[1]);
        Console.WriteLine("{0}  {1,10:f4}", "FPE    =", perr[2]);
        Console.WriteLine("{0}  {1,10:f4}", "BIC    =", perr[3]);
        if (optloo == 2)
        {
          Console.WriteLine("{0}  {1,10:f4}", "LOO CV =", perr[4]);
        }
        Console.WriteLine("");
        printArrays(n, 1, res, "Residuals" );
        Console.WriteLine("");
        //
        printArrays(ip, 1, vif, "Variance inflation factors"  );
        L40: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write("Exception Raised");
      }
    }
    internal static void printArrays(int m, int n, double[] array ,string title)
    {
      Console.WriteLine(title);
      Console.WriteLine("{0}\t{1,8}", " ", 1);
      for (int bindex = 0; bindex < m; bindex++)
      {
        Console.WriteLine("{0}\t{1,8:f4}", bindex + 1, array[bindex]);
      }
    }
  }
}


//      g02kb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02KBE
  {
    static string datafile = "ExampleData/g02kbe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   ip,   ip1,   j,   lh,   lpec,   m,   n,   pl,   wantb,   wantvf;
        int ldb, tdb, ldpe, tdpe, ldvf, tdvf;
        //
        int ifail;
        Console.WriteLine("g02kb Example Program Results");
        //
        //      Skip heading in data file
        sr.Reset();
        //
        //      Read in the problem size information
        sr.Reset();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        lh = int.Parse(sr.Next());
        lpec = int.Parse(sr.Next());
        wantb = int.Parse(sr.Next());
        wantvf = 1;
        ldpe = 5;
        double[] h = new double[lh];
        double[] nep = new double[lh];
        double[,] x = new double[n, m];
        double[] y = new double[n];
        int[] isx = new int[m];
        string[] pec = new string[lpec];
        //
        //      Check array sizes
        if (n < 1 || m > n || lh < 1 || ldpe < lpec)
        {
          Console.Write("   ** Problem size is too small or inconsistent");
          goto L160;
        }
        //
        //      Read in the data
        if (lpec > 0)
        {
          sr.Reset();
          for (i = 1; i <= lpec; i++)
          {
            pec[i - 1] = sr.Next();
          }
        }
        for (i = 1; i <= n; i++)
        {
          sr.Reset();
          for (j = 1; j <= m; j++)
          {
            x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        //
        //      Read in the isx flags
        sr.Reset();
        for (i = 1; i <= m; i++)
        {
          isx[i - 1] = int.Parse(sr.Next());
        }
        //
        //      Read in the ridge coefficients
        sr.Reset();
        for (i = 1; i <= lh; i++)
        {
          h[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        //
        //      Total number of variables
        ip = 0;
        for (j = 1; j <= m; j++)
        {
          if (isx[j - 1] == 1)
          {
            ip = ip + 1;
          }
        }
        if (wantb != 0)
        {
          ldb = ip + 1;
          tdb = lh;
        }
        else
        {
          ldb = 1;
          tdb = 1;
        }
        if (wantvf != 0)
        {
          ldvf = ip;
          tdvf = lh;
        }
        else
        {
          ldvf = 0;
          tdvf = 0;
        }
        if (lpec>0)
        {
          ldpe = lpec;
          tdpe = lh;
        }
        else
        {
          ldpe = 0;
          tdpe = 0;
        }
        double[,] pe = new double[ldpe, tdpe];
        double[,] vf = new double[ldvf, tdvf];
        double[,] b = new double[ldb, tdb];
        //
        //      Output the variance inflation factors and parameter estimates
        //      (original scalings)
        //
        //      Run the analysis
        G02.g02kb(  n, m, x, isx, ip, y, lh ,h, nep, wantb, b, wantvf, vf, lpec,pec, pe, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g02kb failed with ifail = {0,5}", ifail);
          goto L160;
        }
        //      Output results
        ip1 = ip - 1;
        //
        //      Summaries
        Console.WriteLine("{0}{1,10}", "Number of parameters used = ", ip + 1);
        Console.WriteLine(" {0}", "Effective number of parameters (NEP):");
        Console.WriteLine(" {0}", "   Ridge   ");
        Console.WriteLine(" {0} {1}", "   Coeff.  ", "NEP");
        for (i = 1; i <= lh; i++)
        {
          Console.WriteLine("{0,10:f4}{1,10:f4}", h[i - 1], nep[i - 1]);
        }
        //
        //      Parameter estimates
        if (wantb != 0)
        {
          Console.WriteLine(" ");
          if (wantb == 1)
          {
            Console.WriteLine(" {0}", "Parameter Estimates (Original scalings)");
          }
          else
          {
            Console.WriteLine(" {0}", "Parameter Estimates (Standarised)");
          }
          pl = Math.Min(ip, 4);
          Console.WriteLine(" {0}", "  Ridge  ");
          Console.WriteLine(" ");
          Console.Write(" {0}", "   Coeff.  ");
          Console.Write(" {0}", " Intercept ");
          for (i = 1; i <= pl; i++)
          {
            Console.Write(" {0}", i);
          }
          Console.WriteLine(" ");
          if (pl < ip1)
          {
            for (i = pl + 1; i <= ip1; i++)
            {
              Console.Write(" {0}", i);
            }
            Console.WriteLine(" ");
          }
          pl = Math.Min(ip + 1, 5);
          for (i = 1; i <= lh; i++)
          {
            Console.Write(" {0, 10:f4}", h[i - 1]);
            for (j = 1; j <= pl; j++)
            {
              Console.Write(" {0, 10:f4}", b[j - 1, i - 1]);
            }
            Console.WriteLine(" ");
            if (pl < ip)
            {
              for (j = pl + 1; j <= ip; j++)
              {
                Console.Write(" {0, 10:f4}", b[j - 1, i - 1]);
              }
              Console.WriteLine(" ");
            }
          }
        }
        //
        //      Variance inflation factors
        if (wantvf != 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine(" {0}", "Variance Inflation Factors");
          pl = Math.Min(ip, 5);
          Console.Write(" {0}", "  Ridge  ");
          Console.WriteLine(" ");
          Console.Write(" {0}", "  Coeff.  ");
          for (i = 1; i <= pl; i++)
          {
            Console.Write(" {0, 10}", i);
          }
          Console.WriteLine(" ");
          if (pl < ip)
          {
            for (i = pl + 1; i <= ip; i++)
            {
              Console.Write(" {0, 10}", i);
            }
            Console.WriteLine(" ");
          }
          for (i = 1; i <= lh; i++)
          {
            Console.Write(" {0, 10:f4}", h[i - 1]);
            for (j = 1; j <= pl; j++)
            {
              Console.Write(" {0, 10:f4}", vf[j - 1, i - 1]);
            }
            Console.WriteLine(" ");
            if (pl < ip)
            {
              for (j = pl + 1; j <= ip; j++)
              {
                Console.Write(" {0, 10:f4}", vf[j - 1, i - 1]);
              }
              Console.WriteLine(" ");
            }
          }
        }
        //
        //      Prediction error criterion
        if (lpec > 0)
        {
          Console.WriteLine(" ");
          Console.WriteLine(" {0}", "Prediction error criterion");
          pl = Math.Min(lpec, 5);
          Console.Write(" {0}", "  Ridge  ");
          Console.WriteLine(" ");
          Console.Write(" {0}", "  Coeff.  ");
          for (i = 1; i <= pl; i++)
          {
            Console.Write(" {0, 10}", i);
          }
          Console.WriteLine(" ");
          if (pl < lpec)
          {
            for (i = pl + 1; i <= lpec; i++)
            {
              Console.Write(" {0, 10}", i);
            }
            Console.WriteLine(" ");
          }
          for (i = 1; i <= lh; i++)
          {
            Console.Write(" {0, 10:f4}", h[i - 1]);
            for (j = 1; j <= pl; j++)
            {
              Console.Write(" {0, 10:f4}", pe[j - 1, i - 1]);
            }
            Console.WriteLine(" ");
            if (pl < ip)
            {
              for (j = pl + 1; j <= ip; j++)
              {
                Console.Write(" {0, 10:f4}", pe[j - 1, i - 1]);
              }
              Console.WriteLine(" ");
            }
          }
          Console.WriteLine(" ");
          Console.WriteLine(" {0}", "Key:");
          for (i = 1; i <= lpec; i++)
          {
            if (pec[i - 1] == "L")
            {
              Console.WriteLine("  {0,5}  {1}", i, "Leave one out cross-validation");
            }
            else if (pec[i - 1] == "G")
            {
              Console.WriteLine("  {0,5}  {1}", i, "Generalised cross-validation");
            }
            else if (pec[i - 1] == "U")
            {
              Console.WriteLine("  {0,5}  {1}", i, "Unbiased estimate of variance");
            }
            else if (pec[i - 1] == "F")
            {
              Console.WriteLine("  {0,5}  {1}", i, "Final prediction error");
            }
            else if (pec[i - 1] == "B")
            {
              Console.WriteLine("  {0,5}  {1}", i, "Bayesian information criterion");
            }
          }
        }
        //
        L160: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02la Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02LAE
  {
    static string datafile = "ExampleData/g02lae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   ip,   iscale,   j,   maxfac,   mx,   my,   n; int ifail;
        Console.WriteLine("g02la Example Program Results");
        //      Skip header in data file.
        sr.Reset();
        //      Read data values.
        sr.Reset();
        n = int.Parse(sr.Next());
        mx = int.Parse(sr.Next());
        my = int.Parse(sr.Next());
        iscale = int.Parse(sr.Next());
        maxfac = int.Parse(sr.Next());
        double[,] x = new double[n, mx];
        double[,] y = new double[n, my];
        int[] isx = new int[mx];
        //      Check array limits
        if (n <= 1 || mx <1  || my < 1)
        {
          Console.Write("   ** Problem size is too small.");
          goto L80;
        }
        //      Read data values.
        for (i = 1; i <= n; i++)
        {
          sr.Reset();
          for (j = 1; j <= mx; j++)
          {
            x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          for (j = 1; j <= my; j++)
          {
            y[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        sr.Reset();
        for (j = 1; j <= mx; j++)
        {
          isx[j - 1] = int.Parse(sr.Next());
        }
        ip = 0;
        for (j = 1; j <= mx; j++)
        {
          if (isx[j - 1] == 1)
          {
            ip = ip + 1;
          }
        }
        double[,] c = new double[my, maxfac];
        double[,] p = new double[ip, maxfac];
        double[,] t = new double[n, maxfac];
        double[,] u = new double[n, maxfac];
        double[,] w = new double[ip, maxfac];
        double[] xbar = new double[ip];
        double[] xcv = new double[maxfac];
        double[,] xres = new double[n, ip];
        double[] xstd = new double[ip];
        double[] ybar = new double[my];
        double[,] ycv = new double[maxfac, maxfac];
        double[,] yres = new double[n, my];
        double[] ystd = new double[my];
        //      Fit a pls model.
        G02.g02la(n, mx, x, isx, ip, my, y, xbar, ybar, iscale, xstd, ystd, maxfac, xres, yres, w, p, t,
        c, u, xcv, ycv, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g02la failed with ifail = {0,5}", ifail);
          goto L80;
        }
        X04.x04ca("G", "X", ip, maxfac, p, "x-loadings, P", out ifail);
        X04.x04ca("G", "X", n, maxfac, t, "x-scores, T", out ifail);
        X04.x04ca("G", "X", my, maxfac, c, "y-loadings, C", out ifail);
        X04.x04ca("G", "X", n, maxfac, u, "y-scores, U", out ifail);
        Console.WriteLine(" ");
        Console.WriteLine(" {0}", "Explained Variance");
        Console.WriteLine("  {0,12}        {1,24}", "Model effects", "Dependent variable(s)");
        for (i = 1; i <= maxfac; i++)
        {
          Console.Write(" {0, 12:f6}             ", xcv[i - 1]);
          for (j = 1; j <= my; j++)
          {
            Console.Write(" {0, 12:f6}", ycv[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        //
        L80: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02lb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02LBE
  {
    static string datafile = "ExampleData/g02lbe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double tau = 0.0;
        int i,   ip,   iscale,   j,   maxfac,   maxit,   mx,   my,   n; int ifail;
        Console.WriteLine("g02lb Example Program Results");
        //      Skip header in data file.
        sr.Reset();
        //      Read data values.
        sr.Reset();
        n = int.Parse(sr.Next());
        mx = int.Parse(sr.Next());
        my = int.Parse(sr.Next());
        iscale = int.Parse(sr.Next());
        maxfac = int.Parse(sr.Next());
        double[,] x = new double[n, mx];
        double[,] y = new double[n, my];
        int[] isx = new int[mx];
        //      Check array sizes
        if (n <= 1 || mx <= 1 || my < 1)
        {
          Console.Write("   ** Problem size is too small");
          goto L80;
        }
        maxit = 200;
        tau = 1.00e-4;
        //      Read data values.
        for (i = 1; i <= n; i++)
        {
          sr.Reset();
          for (j = 1; j <= mx; j++)
          {
            x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          for (j = 1; j <= my; j++)
          {
            y[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        sr.Reset();
        for (j = 1; j <= mx; j++)
        {
          isx[j - 1] = int.Parse(sr.Next());
        }
        ip = 0;
        for (j = 1; j <= mx; j++)
        {
          if (isx[j - 1] == 1)
          {
            ip = ip + 1;
          }
        }
        double[,] c = new double[my, maxfac];
        double[,] p = new double[ip, maxfac];
        double[,] t = new double[n, maxfac];
        double[,] u = new double[n, maxfac];
        double[,] w = new double[ip, maxfac];
        double[] xbar = new double[ip];
        double[] xcv = new double[maxfac];
        double[,] xres = new double[n, ip];
        double[] xstd = new double[ip];
        double[] ybar = new double[3];
        double[,] ycv = new double[maxfac, maxfac];
        double[,] yres = new double[n, ip];
        double[] ystd = new double[my];
        //      Fit a pls model.
        G02.g02lb(n, mx, x, isx, ip, my, y, xbar, ybar, iscale, xstd, ystd, maxfac, maxit, tau, xres,
        yres, w, p, t, c, u, xcv, ycv, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g02lb failed with ifail = {0,5}", ifail);
          goto L80;
        }
        X04.x04ca("G", "X", ip, maxfac, p, "x-loadings, P", out ifail);
        X04.x04ca("G", "X", n, maxfac, t, "x-scores, T", out ifail);
        X04.x04ca("G", "X", my, maxfac, c, "y-loadings, C", out ifail);
        X04.x04ca("G", "X", n, maxfac, u, "y-scores, U", out ifail);
        Console.WriteLine(" ");
        Console.WriteLine(" {0}", "Explained Variance");
        Console.WriteLine("  {0,12}        {1,21}", "Model effects", "Dependent variable(s)");
        for (i = 1; i <= maxfac; i++)
        {
          Console.Write(" {0, 12:f6}", xcv[i - 1]);
          for (j = 1; j <= my; j++)
          {
            Console.Write(" {0, 12:f6}", ycv[i - 1, j - 1]);
          }
          Console.WriteLine(" ");
        }
        //
        L80: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02lc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02LCE
  {
    static string datafile = "ExampleData/g02lce.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double rcond = 0.0;
        int i,   ip,   iscale,   j,   maxfac,   my,   nfact,   orig,   vipopt; int ifail;
        Console.WriteLine("g02lc Example Program Results");
        //      Skip header in data file
        sr.Reset();
        //      Read data values
        sr.Reset();
        ip = int.Parse(sr.Next());
        my = int.Parse(sr.Next());
        maxfac = int.Parse(sr.Next());
        nfact = int.Parse(sr.Next());
        orig = int.Parse(sr.Next());
        iscale = int.Parse(sr.Next());
        vipopt = int.Parse(sr.Next());
        double[,] b = new double[ip, my];
        double[,] c = new double[my, maxfac];
        double[,] ob = new double[ip+1, my];
        double[,] p = new double[ip, maxfac];
        double[,] vip = new double[ip, vipopt];
        double[,] w = new double[ip, maxfac];
        double[] xbar = new double[ip];
        double[] xstd = new double[ip];
        double[] ybar = new double[my];
        double[,] ycv = new double[nfact, my];
        double[] ystd = new double[my];
        //
        if (ip <= 1 || my < 1 || maxfac>ip)
        {
          Console.Write("   ** Problem size is too small.");
          goto L20;
        }
        //      Read P
        for (i = 1; i <= ip; i++)
        {
          sr.Reset();
          for (j = 1; j <= maxfac; j++)
          {
            p[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        //      Read C
        for (i = 1; i <= my; i++)
        {
          sr.Reset();
          for (j = 1; j <= maxfac; j++)
          {
            c[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        //      Read W
        for (i = 1; i <= ip; i++)
        {
          sr.Reset();
          for (j = 1; j <= maxfac; j++)
          {
            w[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        //      Read ycv
        for (i = 1; i <= nfact; i++)
        {
          for (j = 1; j <= my; j++)
          {
            ycv[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        //      Read means
        if (orig == 1)
        {
          sr.Reset();
          for (j = 1; j <= ip; j++)
          {
            xbar[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          sr.Reset();
          for (j = 1; j <= my; j++)
          {
            ybar[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          if (iscale != -1)
          {
            sr.Reset();
            for (j = 1; j <= ip; j++)
            {
              xstd[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            sr.Reset();
            for (j = 1; j <= my; j++)
            {
              ystd[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
        }
        //      Calculate predictions
        rcond = -1.00e0;
        G02.g02lc(ip, my, maxfac, nfact, p, c, w, rcond, b, orig, xbar, ybar, iscale, xstd, ystd, ob,
        vipopt, ycv, vip, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g02lc failed with ifail = {0,5}", ifail);
          goto L20;
        }
        X04.x04ca("G", "X", ip, my, b, "B", out ifail);
        if (orig == 1)
        {
          X04.x04ca("G", "X", ip + 1, my, ob, "OB", out ifail);
        }
        if (vipopt != 0)
        {
          X04.x04ca("G", "X", ip, vipopt, vip, "VIP", out ifail);
        }
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02ld Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G02LDE
  {
    static string datafile = "ExampleData/g02lde.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   ip,   iscale,   j,   l,   my,   mz,   n,   orig;
        int ifail;
        Console.WriteLine("g02ld Example Program Results");
        //      Skip header in data file.
        sr.Reset();
        //      Read data values.
        sr.Reset();
        ip = int.Parse(sr.Next());
        my = int.Parse(sr.Next());
        orig = int.Parse(sr.Next());
        iscale = int.Parse(sr.Next());
        n = int.Parse(sr.Next());
        mz = int.Parse(sr.Next());
        double[] ybar = new double[my];
        double[,] yhat = new double[n, my];
        double[] ystd = new double[my];
        double[,] z = new double[n, mz];
        int[] isz = new int[mz];
        double[] xbar = new double[ip];
        double[] xstd = new double[ip];
        //      Read prediction x-data
        for (i = 1; i <= n; i++)
        {
          sr.Reset();
          for (j = 1; j <= mz; j++)
          {
            z[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        //      Read elements of isz
        sr.Reset();
        for (j = 1; j <= mz; j++)
        {
          isz[j - 1] = int.Parse(sr.Next());
        }
        //      Read parameter estimates
        l = (int)ip;
        if (orig != -1)
        {
          l = l + 1;
        }
        double[,] b = new double[l, my];
        for (j = 1; j <= l; j++)
        {
          sr.Reset();
          for (i = 1; i <= my; i++)
          {
            b[j - 1, i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        //      Read means
        sr.Reset();
        for (j = 1; j <= ip; j++)
        {
          xbar[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        sr.Reset();
        for (l = 1; l <= my; l++)
        {
          ybar[l - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        if (((orig == -1)) && ((iscale != -1)))
        {
          sr.Reset();
          for (j = 1; j <= ip; j++)
          {
            xstd[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          sr.Reset();
          for (l = 1; l <= my; l++)
          {
            ystd[l - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        //      Calculate predictions
        G02.g02ld(ip, my, orig, xbar, ybar, iscale, xstd, ystd, b, n, mz, isz, z, yhat, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g02ld failed with ifail = {0,5}", ifail);
        }
        else
        {
          X04.x04ca("G", "X", n, my, yhat, "YHAT", out ifail);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.Write( "Exception Raised");
      }
    }
  }
}


//      g02qf Example Program Text
//      C# version, NAG Copyright 2012
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{

    public class G02QFE
    {

        static string datafile = "ExampleData/g02qfe.d";
        // Specify data file as a command line argument.
        // It defaults to the named file specified below otherwise.
        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                  datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
        {
            try
            {
                DataReader sr = new DataReader(datafile);
                //      g02qf Example Program Text
                //      Mark 24 Release. NAG Copyright 2012.
           double df;
                int i = 0,
                ifail = 0,
                j = 0,
                l = 0,
                m = 0,
                n = 0,
                ntau = 0;
                double[,] b;
                double[,] bl;
                double[,] bu;
                double[] tau;
                double[,] x;
                double[] y;
                int[] info;
                Console.WriteLine(" {0}", "G02QFF Example Program Results");
                Console.WriteLine("");
                //      Skip heading in data file
                sr.Reset();
                //      Read in the problem size
                sr.Reset();
                n = int.Parse(sr.Next());
                m = int.Parse(sr.Next());
                ntau = int.Parse(sr.Next());
        b = new double[ntau, m];
        info = new int[ntau];
        bl = new double[ntau,m];
        bu= new double[ntau,m];

        x= new double[n,m];
        y= new double[n];
        tau = new double[ntau];

                //      Read in the data
                // allocate
                sr.Reset();
                for (i = 1; i <= n; i++)
                { for (j = 1; j <= m; j++)
                {
                    x[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }
                 y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }
                //      Read in the quantiles required
                sr.Reset();
        for (j = 1; j <= ntau; j++)
                {
                tau[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }

                //      Allocate memory for output arrays
                // allocate
                //      Call the model fitting routine
                ifail = -1;
                G02.g02qf(n, m, x, y, ntau, tau, out df, b, bl, bu, info, out ifail);
                if (ifail != 0)
                {
                    if (ifail == 111)
                    {for (j = 1; j <= ntau; j++)
                {
                        Console.WriteLine(" {0} {1}", "Additional error information (INFO): ", info[j  - 1]);
        }
                    }
                    else
                    {
                        goto L100;
                    }
                }
                //      Display the parameter estimates
                for (l = 1; l <= ntau; l++)
                {
                    Console.WriteLine("  {0}{1,6:f3}", "Quantile: ", tau[l - 1]);
                    Console.WriteLine("");
                    Console.WriteLine(" {0}", "        Lower   Parameter   Upper");
                    Console.WriteLine(" {0}", "        Limit   Estimate    Limit");
                    for (j = 1; j <= m; j++)
                    {
                        Console.WriteLine("  {0,3}      {1,7:f3}      {2,7:f3}      {3,7:f3}", j, bl[l - 1, j - 1], b[l - 1, j - 1], bu[l - 1, j - 1]);
                    }
                    Console.WriteLine("");
                    Console.WriteLine("");
                }
            L100: ;

            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
                Console.WriteLine("Exception Raised");
            }
        }
    }
}


 G02QFF Example Program Results

  Quantile:  0.100

         Lower   Parameter   Upper
         Limit   Estimate    Limit
    1       74.946      110.142      145.337
    2        0.370        0.402        0.433

  Quantile:  0.250

         Lower   Parameter   Upper
         Limit   Estimate    Limit
    1       64.232       95.483      126.735
    2        0.446        0.474        0.502

  Quantile:  0.500

         Lower   Parameter   Upper
         Limit   Estimate    Limit
    1       55.399       81.482      107.566
    2        0.537        0.560        0.584

  Quantile:  0.750

         Lower   Parameter   Upper
         Limit   Estimate    Limit
    1       41.372       62.396       83.421
    2        0.625        0.644        0.663

  Quantile:  0.900

         Lower   Parameter   Upper
         Limit   Estimate    Limit
    1       26.829       67.351      107.873
    2        0.650        0.686        0.723


//      g02qg Example Program Text
//      C# version, NAG Copyright 2012
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{

    public class G02QGE
    {
        static string datafile = "ExampleData/g02qge.d";
        // Specify data file as a command line argument.
        // It defaults to the named file specified below otherwise.
        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
        {
            try
            {
                DataReader sr = new DataReader(datafile);
                int lseed = 1;
                double df;
                int genid = 0,
                i = 0,
                ifail = 0,
                ip = 0,
                j = 0,
                l = 0,
                ldbl = 0,
                lddat = 0,
                ldres = 0,
                lstate = 0,
                lwt = 0,
                m = 0,
                n = 0,
                ntau = 0,
                sorder = 0,
                subid = 0,
                tdch = 0;
                int c1 = 0;
                string weight = "";
                string cvalue = "",
                semeth = "";
                double[,] b;
                double[,] bl;
                double[,] bu;
                double[, ,] ch;
                double[,] dat;
                double[,] res;
                double[] tau;
                double[] wt;
                double[] y;
                int[] info;
                int[] isx;
                int[] state;
                int[] seed = new int[lseed];

                Console.WriteLine(" {0}", "G02QGF Example Program Results");
                Console.WriteLine("");
                //      Skip heading in data file
                sr.Reset();
                //      Read in the problem size
                sr.Reset();

                sorder = int.Parse(sr.Next());

                c1 = int.Parse(sr.Next());

                weight = sr.Next();

                n = int.Parse(sr.Next());

                m = int.Parse(sr.Next());
                ntau = int.Parse(sr.Next());

                //      Read in the data
                if ((weight == "W") || (weight == "w"))
                {
                    lwt = (int)n;
                }
                else
                {
                    lwt = 0;
                }

                y = new double[n];
                isx = new int[m];
                tau = new double[ntau];
                wt = new double[lwt];

                // allocate
                if (sorder == 1)
                {
                    //        DAT(N,M)
                    lddat = (int)n;
                    dat = new double[n, m];
                    // allocate
                    if (lwt == 0)
                    {
                        sr.Reset();
                        for (i = 1; i <= n; i++)
                        {
                            for (j = 1; j <= m; j++)
                            {
                                dat[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                                y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                            }
                        }
                    }
                    else
                    {
                        sr.Reset();
                        for (i = 1; i <= n; i++)
                        {
                            for (j = 1; j <= m; j++)
                            {
                                dat[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                                y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                                wt[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                            }
                        }
                    }
                }
                else
                {
                    //        DAT(M,N)
                    lddat = (int)m;
                    dat = new double[m, n];
                    // allocate
                    if (lwt == 0)
                    {
                        sr.Reset();
                        for (i = 1; i <= n; i++)
                        {
                            for (j = 1; j <= m; j++)
                            {
                                dat[j - 1, i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                                y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                            }
                        }
                    }
                    else
                    {
                        sr.Reset();
                        for (i = 1; i <= n; i++)
                        {
                            for (j = 1; j <= m; j++)
                            {
                                dat[j - 1, i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                                y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                                wt[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                            }
                        }
                    }
                }

                //      Read in variable inclusion flags
                sr.Reset();
                for (j = 1; j <= m; j++)
                {
                    isx[j - 1] = int.Parse(sr.Next());
                }
                //      Calculate IP
                ip = 0;
                for (j = 1; j <= m; j++)
                {
                    if (isx[j - 1] == 1) { ip++; }
                }

                if (c1 == 1)
                {
                    ip++;
                }

                //      Read in the quantiles required
                sr.Reset();
                for (j = 1; j <= ntau; j++)
                {
                    tau[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }
                // allocate
                //      Initialize the optional argument array
                ifail = 0;

                G02.g02qgOptions options = new G02.g02qgOptions();
                /*
                // Begin commented out block
                    while (true)
                    {
                        //        Read in any optional arguments. Reads in to the end of
                        //        the input data, or until a blank line is reached
                string opstr;
                       try{
                sr.Reset();
                optstr = sr.Next();
                //        Set the supplied option

                options.Set(opstr);

                   }
                catch {
                         break;
                       }
                     }
               // end commented out block
                */
             //   options.Set(sr);
                options.Set("Return Residuals = Yes");
                options.Set("Matrix Returned = Covariance");
                options.Set("Interval Method = IID");

                //      Assume that no intervals or output matrices are required
                //      unless the optional argument state differently
                ldbl = 0;
                tdch = 0;
                ldres = 0;
                lstate = 0;
                G05.G05State g05State;

                //      Query the optional arguments to see what output is required

                options.Get("INTERVAL METHOD", ref semeth);

                String matrix_returned = "";
                options.Get("MATRIX RETURNED", ref matrix_returned);

                Console.WriteLine("SEMETH {0}", semeth);
                Console.WriteLine("**************");
                if (semeth != "NONE")
                {
                    //        Require the intervals to be output
                    ldbl = (int)ip;
                    if (semeth == "BOOTSTRAP XY")
                    {
                        //          Need to find the length of the state array for the random
                        //          number generator
                        //          Read in the generator ID and a seed
                        sr.Reset();
                        genid = int.Parse(sr.Next());
                        subid = int.Parse(sr.Next());
                        seed[0] = int.Parse(sr.Next());

                        //      Initialise the generator to a repeatable sequence
                        g05State = new G05.G05State(genid, subid, seed, out ifail);
                    }
                    ifail = 0;

                    if (matrix_returned == "COVARIANCE")
                    {
                        tdch = (int)ntau;

                    }
                    else if (matrix_returned == "H INVERSE")
                    {
                        if ((semeth == "BOOTSTRAP XY") || (semeth == "IID"))
                        {
                            //            NB: If we are using bootstrap or IID errors then any request for
                            //            H INVERSE is ignored
                            tdch = 0;

                        }
                        else
                        {
                            tdch = ntau + 1;

                        }
                    }
                    ifail = 0;
                    options.Get("RETURN RESIDUALS", ref cvalue);
                    if (cvalue == "YES")
                    {
                        ldres = (int)n;
                    }
                }
                //      Allocate memory for output arrays
                // allocate

                if (lstate > 0)
                {

                    //        Doing bootstrap, so initialise the RNG
                    ifail = 0;

                    g05State = new G05.G05State(genid, subid, seed, out ifail);
                }
                else {
                    // initializing state as a fallback case, is not used
                    seed[0] = 1;
                    g05State = new G05.G05State(1, subid, seed, out ifail);
                }
                //      Call the model fitting routine
                ifail = -1;

                b = new double[ntau, ip];
                info = new int[ntau];
                bl = new double[ntau, ldbl];
                bu = new double[ntau, ldbl];

                ch = new double[tdch, ldbl, ldbl];
                state = new int[lstate];
                res = new double[ldres, ntau];

                G02.g02qg(sorder, c1, n, m, dat, isx, ip, y, wt, ntau, tau, out df, b, bl, bu, ch, res, options, g05State, info, out ifail);

                if (ifail != 0)
                {
                    if (ifail == 231)
                    {
                        for (j = 1; j <= ntau; j++)
                        {
                            Console.WriteLine(" {0} {1}", "Additional error information (INFO): ", info[j - 1]);
                        }
                    }
                    else
                    {
                        goto L100;
                    }
                }
                //      Display the parameter estimates
                for (l = 1; l <= ntau; l++)
                {
                    Console.WriteLine("  {0}{1,6:f3}", "Quantile: ", tau[l - 1]);
                    Console.WriteLine("");
                    if (ldbl > 0)
                    {
                        Console.WriteLine(" {0}", "            Lower       Parameter   Upper");
                        Console.WriteLine(" {0}", "            Limit       Estimate    Limit");
                    }
                    else
                    {
                        Console.WriteLine(" {0}", "      Parameter");
                        Console.WriteLine(" {0}", "      Estimate");
                    }
                    for (j = 1; j <= ip; j++)
                    {
                        if (ldbl > 0)
                        {
                            Console.WriteLine("  {0,3}      {1,7:f3}      {2,7:f3}      {3,7:f3}", j, bl[l - 1, j - 1], b[l - 1, j - 1], bu[l - 1, j - 1]);
                        }
                        else
                        {
                            Console.WriteLine("  {0,3}      {1,7:f3}      ", j, b[l - 1, j - 1]);
                        }
                    }
                    Console.WriteLine("");
                    if (tdch == ntau)
                    {
                        Console.WriteLine(" {0}", "Covariance matrix");
                        for (i = 1; i <= ip; i++)
                        {
                            Console.WriteLine("");
                            for (j = 1; j <= i; j++)
                            {
                                Console.Write("  {0,10:e3}      ", ch[l - 1, i - 1, j - 1]);
                            }
                        }
                        Console.WriteLine("");
                    }
                    else if (tdch == ntau + 1)
                    {
                        Console.WriteLine(" {0}", "J");
                        for (i = 1; i <= ip; i++)
                        {
                            for (j = 1; j <= i; j++)
                            {
                                Console.WriteLine("  {0,10:e3}      ", ch[j - 1, i - 1, 0]);
                            }
                        }
                        Console.WriteLine("");
                        Console.WriteLine(" {0}", "H inverse");
                        for (i = 1; i <= ip; i++)
                        {
                            for (j = 1; j <= i; j++)
                            {
                                Console.WriteLine("  {0,10:e3}      ", ch[j - 1, i - 1, l + 1 - 1]);
                            }
                        }
                        Console.WriteLine("");
                    }
                    Console.WriteLine("");
                }
                if (ldres > 0)
                {
                    Console.WriteLine(" {0}", "First 10 Residuals");
                    Console.Write(" {0}\r\n  ", "Obs                           Quantile\r\n");
                    for (j = 1; j <= ntau; j++)
                    {
                        Console.Write("     {0,6:f3}   ", tau[j - 1]);
                    }
                    Console.WriteLine("");
                    for (i = 1; i <= Math.Min(n, 10); i++)
                    {
                        Console.Write("\r\n{0,3}",i);
                        for (j = 1; j <= ntau; j++)
                        {
                            Console.Write("  {0,10:f5}  ", res[i - 1, j - 1]);
                        }
                    }
                }
                else
                {
                    Console.WriteLine(" {0}", "Residuals not returned");
                }
                Console.WriteLine("");
            L100: ;

            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
                Console.WriteLine("Exception Raised");
            }
        }
    }
}


//      g03aa Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G03AAE
  {
    static string datafile = "ExampleData/g03aae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,  j,  m,  n,  nvar; string matrix="",  std="",  weight="";
        int ifail;
        Console.WriteLine("g03aa Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        matrix = sr.Next();
        std = sr.Next();
        weight = sr.Next();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        double[] s = new double[m];
        double[] wt = new double[n];
        double[,] x = new double[n, m];
        int[] isx = new int[m];
        if ( n >= 2 && m >= 1 )
        {
          if ((weight == "U") || (weight == "u"))
          {
            for (i = 1 ; i <= n ; i++)
            {
              sr.Reset();
              for (j = 1 ; j <= m ; j++)
              {
                x[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
            }
          }
          else
          {
            for (i = 1 ; i <= n ; i++)
            {
              sr.Reset();
              for (j = 1 ; j <= m ; j++)
              {
                x[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              wt[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          sr.Reset();
          for (j = 1 ; j <= m ; j++)
          {
            isx[j - 1] = int.Parse(sr.Next());
          }
          nvar = int.Parse(sr.Next());
          double[,] e = new double[nvar, 6];
          double[,] p = new double[nvar, nvar];
          double[,] v = new double[n, nvar];
          if ((matrix == "S") || (matrix == "s"))
          {
            sr.Reset();
            for (j = 1 ; j <= m ; j++)
            {
              s[j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //
          G03.g03aa(matrix, std, weight, n, m, x, isx, s, wt, nvar, e, p, v, out ifail);
          //
          if (ifail == 0)
          {
            Console.WriteLine("");
            Console.WriteLine(" {0}","Eigenvalues  Percentage  Cumulative     Chisq      DF     Sig");
            Console.WriteLine(" {0}","              variation   variation");
            Console.WriteLine("");
            for (i = 1 ; i <= nvar ; i++)
            {
              for (j = 1 ; j <= 6 ; j++)
              {
                Console.Write("{0, 12:f4}", e[i - 1 , j - 1]);
              }
              Console.WriteLine();
            }
            Console.WriteLine("");
            Console.WriteLine(" {0}","Principal component loadings");
            Console.WriteLine("");
            for (i = 1 ; i <= nvar ; i++)
            {
              for (j = 1 ; j <= nvar ; j++)
              {
                Console.Write("{0, 9:f4}", p[i - 1 , j - 1]);
              }
              Console.WriteLine();
            }
            Console.WriteLine("");
            Console.WriteLine("{0}","Principal component scores");
            Console.WriteLine("");
            for (i = 1 ; i <= n ; i++)
            {
              Console.Write(" {0}",  i);
              for (j = 1 ; j <= nvar ; j++)
              {
                Console.Write("{0, 9:f3}", v[i - 1 , j - 1]);
              }
              Console.WriteLine();
            }
          }
          else
          {
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,5}"," ** g03aa returned with ifail = ",ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g05kh Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05KHE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=3;
        const int nv=5;
        int genid,   i,   j,   subid;
        double[] x = new double[nv];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05kh Example Program Results");
        Console.WriteLine("");
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Prepare N streams
        G05.G05State[] g05State = new G05.G05State[n];
        for (i = 1 ; i <= n ; i++)
        {
          //         Initialise the generator to a repeatable sequence
          g05State[i-1] = new G05.G05State(genid, subid, seed, out ifail);
          if (ifail != 0)
          {
            Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
            goto L60;
          }
          //         Prepare the I'th out of N streams
          G05.g05kh(n, i, g05State[i-1], out ifail);
          if (ifail != 0)
          {
            Console.WriteLine("** g05kh failed with ifail = {0,5}", ifail);
            goto L60;
          }
        }
        //      Generate a nv variates from a uniform distribution, from each stream
        for (i = 1; i <= n  ; i++)
        {
          Console.WriteLine(" {0} {1}", "Stream    ", i);
          G05.g05sa(nv, g05State[i-1], x,out ifail);
          if (ifail != 0)
          {
            Console.WriteLine("** g05sa failed with ifail = {0,5}", ifail);
            goto L60;
          }
          //         Display the variates
          for (j = 1 ; j <= nv ; j++)
          {
            Console.WriteLine(" {0,8:f4}", x[j - 1]); ;
          }
          Console.WriteLine("");
          Console.WriteLine("");
        }
        //
        L60: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05kh Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
3  5              :: N,NV


//      g05kj Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05KJE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=50;
        const int nv=5;
        int genid,   i,   subid;
        double[] x = new double[nv];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05kj Example Program Results");
        Console.WriteLine("");
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Advance the sequence N places
        G05.g05kj(n, g05State, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05kj failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate a nv variates from a uniform distribution
        G05.g05sa(nv, g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05sa failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= nv ; i++)
        {
          Console.WriteLine(" {0,8:f4}", x[i - 1]); ;
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05kj Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
50  5             :: N,NV


//      g05kk Example Program Text
//      Mark 23 Release. NAG Copyright 2011.
//      C# version, NAG Copyright 2012
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
    public class G05KKE
    {
        static string datafile = "ExampleData/g05kke.d";
        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }
        public static int StartExample()
        {
            try
            {
                int genid = 0,

                subid = 0;
                int[] seed = new int[1];
                int ifail;
                DataReader sr = new DataReader(datafile);
                Console.WriteLine("g05kk Example Program Results");
                Console.WriteLine("");

                //      Read data from a file
                //      Skip heading
                sr.Reset();
                sr.Reset();
                //      Read in initial parameters

                // Read in the base generator information and seed

                genid = int.Parse(sr.Next());
                subid = int.Parse(sr.Next());
                seed[0] = int.Parse(sr.Next());

                //
                //      Initialise the generator to a repeatable sequence
                G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);

                int n = int.Parse(sr.Next());
                int nv = int.Parse(sr.Next());

                double[] x = new double[nv];

                //    Advance the sequence 2**N places

                G05.g05kk(n, g05State, out ifail);

                //  Generate a NV variates from a uniform distribution

                G05.g05sa(nv, g05State, x, out ifail);

                //  Display the variates

                for (int i = 0; i < nv; i++)
                {

                    Console.WriteLine("{0,6:f4}", x[i]);
                }
                return 0;

            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
                Console.WriteLine("Exception Raised");
                return 0;
            }

        }
    }
}


g05kk Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
17  5             :: N,NV


//      g05nc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05NCE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=8;
        int genid,   i,   j,   lseed,   m,   subid; int[] index = new int[n];
        lseed = mseed;
        int[] seed = new int[lseed];
        int ifail;
        Console.WriteLine("g05nc Example Program Results");
        Console.WriteLine("");
        //      Number of permutations
        m = 10;
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L60;
        }
        //
        Console.WriteLine("  {0,2}{1}{2,1}{3}",m," Permutations of first ",n," integers");
        Console.WriteLine("");
        //      Permutate M times
        for (j = 1 ; j <= m ; j++)
        {
          //         Set up the index vector
          Console.Write("\t");
          for (i = 1 ; i <= n ; i++)
          {
            index[i - 1] = i;
          }
          //         Call the permutation method
          G05.g05nc(index,n, g05State, out ifail);
          if (ifail != 0)
          {
            Console.WriteLine("** g05nc failed with ifail = {0,5}", ifail);
            goto L60;
          }
          //         Display the results
          for (i = 1 ; i <= n ; i++)
          {
            Console.Write(" {0}", index[i - 1]);
          }
          Console.WriteLine("");
        }
        //
        L60: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05nc Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
8  10             :: N,NPERM


//      g05nd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05NDE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=8;
        int genid,   i,   m,   subid; int[] ipop = new int[n];
        int[] isampl = new int[n];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05nd Example Program Results");
        Console.WriteLine("");
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L60;
        }
        //
        Console.WriteLine("  {0}{1,1}{2}"," Samples from the first ",n," integers");
        Console.WriteLine("");
        Console.WriteLine(" {0}", " Sample size\tValues" + "\r\n");
        //      Initialise the population
        for (i = 1 ; i <= n ; i++)
        {
          ipop[i - 1] = i;
        }
        //      Generate samples of different sizes
        for (m = 1 ; m <= n ; m++)
        {
          G05.g05nd(ipop, n, isampl, m, g05State, out ifail);
          if (ifail != 0)
          {
            Console.WriteLine("** g05nd failed with ifail = {0,5}", ifail);
            goto L60;
          }
          //         Display the results
          Console.Write("\t {0}",  m+"\t");
          for (i = 1 ; i <= m ; i++)
          {
            Console.Write(" {0}", isampl[i - 1]);
          }
          Console.WriteLine("");
        }
        //
        L60: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05nd Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
8                 :: N
1                 :: List of sample sizes (M)
2
3
4
5
6
7
8


g05nd Example Program Results

   Samples from the first 8 integers

  Sample size	Values

     1	 2
     2	 3 6
     3	 1 5 7
     4	 2 6 7 8
     5	 1 2 3 4 8
     6	 1 3 4 5 6 7
     7	 1 3 4 5 6 7 8
     8	 1 2 3 4 5 6 7 8


//      g05pg Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05PDE
  {
    const int mseed=1;
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int num=10;
        const int ip=0;
        const int iq=3;
        double gamma=0.0;
        int df,   genid,   i,   subid;
        bool fcall=false;
        string dist="";
        double[] et = new double[num];
        double[] ht = new double[num];
        double[] r = new double[2*(ip+iq+2)];
        double[] theta = new double[ip+iq+1];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05pd Example Program Results");
        Console.WriteLine("");
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L60;
        }
        //      Set up the parameters for the series being generated
        dist = "N";
        gamma =  -0.40e0;
        theta[0] = 0.80e0;
        theta[1] = 0.60e0;
        theta[2] = 0.20e0;
        theta[3] = 0.10e0;
        df = 0;
        fcall =  true ;
        //      Generate the first realisation
        G05.g05pd(dist, num, ip, iq, theta, gamma, df, ht, et, fcall, r,  g05State, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05pd failed with ifail = {0,5}", ifail);
          goto L60;
        }
        //      Display the results
        Console.WriteLine("");
        Console.WriteLine(" {0}"," Realisation Number 1");
        Console.WriteLine(" {0}","   I            HT(I)            ET(I)");
        Console.WriteLine(" {0}","  --------------------------------------");
        for (i = 1 ; i <= num ; i++)
        {
          Console.WriteLine("  {0,5}  {1,16:f4}  {2,16:f4}",i,ht[i - 1],et[i - 1]);
        }
        //      Generate a second realisation
        fcall =  false ;
        G05.g05pd(dist, num, ip, iq, theta, gamma, df, ht, et, fcall, r,  g05State, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05pd failed with ifail = {0,5}", ifail);
          goto L60;
        }
        //      Display the results
        Console.WriteLine("");
        Console.WriteLine(" {0}"," Realisation Number 2");
        Console.WriteLine(" {0}","   I            HT(I)            ET(I)");
        Console.WriteLine(" {0}","  --------------------------------------");
        for (i = 1 ; i <= num ; i++)
        {
          Console.WriteLine("  {0,5}  {1,16:f4}  {2,16:f4}",i,ht[i - 1],et[i - 1]);
        }
        //
        L60: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05pd Example Program Data
1  1  1762543      :: GENID,SUBID,SEED(1)
10  2              :: NUM,NREAL
0  3               :: IP,IQ
'N'
0.8  0.6  0.2  0.1 :: THETA
-0.4               :: GAMMA


// g05pe Example Program Text
// C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05PEE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int num=10;
        const int ip=1;
        const int iq=1;
        double gamma=0.0;
        int df,   genid,   i,   subid; bool fcall=false;
        string dist="";
        double[] et = new double[num];
        double[] ht = new double[num];
        double[] r = new double[2*(iq+ip+2)];
        double[] theta = new double[ip+iq+1];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05pe Example Program Results");
        Console.WriteLine("");
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L60;
        }
        //      Set up the parameters for the series being generated
        dist = "N";
        theta[0] = 0.080e0;
        theta[1] = 0.20e0;
        theta[2] = 0.70e0;
        gamma =  -0.40e0;
        df = 0;
        fcall =  true ;
        //      Generate the first realisation
        G05.g05pe(dist, num, ip, iq, theta, gamma, df, ht, et, fcall, r,  g05State, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05pe failed with ifail = {0,5}", ifail);
          goto L60;
        }
        //      Display the results
        Console.WriteLine("");
        Console.WriteLine(" {0}"," Realisation Number 1");
        Console.WriteLine(" {0}","   I            HT(I)            ET(I)");
        Console.WriteLine(" {0}","  --------------------------------------");
        for (i = 1 ; i <= num ; i++)
        {
          Console.WriteLine("  {0,5}  {1,16:f4}  {2,16:f4}",i,ht[i - 1],et[i - 1]);
        }
        //      Generate a second realisation
        fcall =  false ;
        G05.g05pe(dist, num, ip, iq, theta, gamma, df, ht, et, fcall, r,  g05State, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05pe failed with ifail = {0,5}", ifail);
          goto L60;
        }
        //      Display the results
        Console.WriteLine("");
        Console.WriteLine(" {0}"," Realisation Number 2");
        Console.WriteLine(" {0}","   I            HT(I)            ET(I)");
        Console.WriteLine(" {0}","  --------------------------------------");
        for (i = 1 ; i <= num ; i++)
        {
          Console.WriteLine("  {0,5}  {1,16:f4}  {2,16:f4}",i,ht[i - 1],et[i - 1]);
        }
        //
        L60: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05pe Example Program Data
1  1  1762543      :: GENID,SUBID,SEED(1)
10  2              :: NUM,NREAL
1  1               :: IP,IQ
'N'
0.08 0.2 0.7       :: THETA
-0.4               :: GAMMA


// g05pf Example Program Text
// C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05PFE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int num=10;
        const int ip=1;
        const int iq=1;
        double gamma=0.0;
        int df,   genid,   i,  subid;
        bool fcall=false;
        string dist="";
        double[] et = new double[num];
        double[] ht = new double[num];
        double[] r = new double[2*(iq+ip+2)];
        double[] theta = new double[ip+iq+1];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05pf Example Program Results");
        Console.WriteLine("");
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L60;
        }
        //      Set up the parameters for the series being generated
        dist = "N";
        theta[0] = 0.40e0;
        theta[1] = 0.10e0;
        theta[2] = 0.70e0;
        gamma = 0.10e0;
        df = 0;
        fcall =  true ;
        //      Generate the first realisation
        G05.g05pf(dist, num, ip, iq, theta, gamma, df, ht, et, fcall, r, g05State, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05pf failed with ifail = {0,5}", ifail);
          goto L60;
        }
        //      Display the results
        Console.WriteLine("");
        Console.WriteLine(" {0}"," Realisation Number 1");
        Console.WriteLine(" {0}","   I            HT(I)            ET(I)");
        Console.WriteLine(" {0}","  --------------------------------------");
        for (i = 1 ; i <= num ; i++)
        {
          Console.WriteLine("  {0,5}  {1,16:f4}  {2,16:f4}",i,ht[i - 1],et[i - 1]);
        }
        //      Generate a second realisation
        fcall =  false ;
        G05.g05pf(dist, num, ip, iq, theta, gamma, df, ht, et, fcall, r, g05State, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05pf failed with ifail = {0,5}", ifail);
          goto L60;
        }
        //      Display the results
        Console.WriteLine("");
        Console.WriteLine(" {0}"," Realisation Number 2");
        Console.WriteLine(" {0}","   I            HT(I)            ET(I)");
        Console.WriteLine(" {0}","  --------------------------------------");
        for (i = 1 ; i <= num ; i++)
        {
          Console.WriteLine("  {0,5}  {1,16:f4}  {2,16:f4}",i,ht[i - 1],et[i - 1]);
        }
        //
        L60: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05pf Example Program Data
1  1  1762543      :: GENID,SUBID,SEED(1)
10 2               :: NUM,NREAL
1  1               :: IP,IQ
'N'
0.4 0.1 0.7        :: THETA
0.1                :: GAMMA


// g05pg Example Program Text
// C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05PGE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int num=10;
        const int ip=1;
        const int iq=1;
        int df,   genid,   i,   subid;
        bool fcall=false;
        string dist="";
        double[] et = new double[num];
        double[] ht = new double[num];
        double[] r = new double[2*(2*iq+ip+2)];
        double[] theta = new double[2*iq+ip+1];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05pg Example Program Results");
        Console.WriteLine("");
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L60;
        }
        //      Set up the parameters for the series being generated
        dist = "N";
        theta[0] = 0.10e0;
        theta[1] =  -0.30e0;
        theta[2] = 0.10e0;
        theta[3] = 0.90e0;
        df = 0;
        fcall =  true ;
        //      Generate the first realisation
        G05.g05pg(dist, num, ip, iq, theta, df, ht, et, fcall, r,  g05State, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05pg failed with ifail = {0,5}", ifail);
          goto L60;
        }
        //      Display the results
        Console.WriteLine("");
        Console.WriteLine(" {0}"," Realisation Number 1");
        Console.WriteLine(" {0}","   I            HT(I)            ET(I)");
        Console.WriteLine(" {0}","  --------------------------------------");
        for (i = 1 ; i <= num ; i++)
        {
          Console.WriteLine("  {0,5}  {1,16:f4}  {2,16:f4}",i,ht[i - 1],et[i - 1]);
        }
        //      Generate a second realisation
        fcall =  false ;
        G05.g05pg(dist, num, ip, iq, theta, df, ht, et, fcall, r,  g05State, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05pg failed with ifail = {0,5}", ifail);
          goto L60;
        }
        //      Display the results
        Console.WriteLine("");
        Console.WriteLine(" {0}"," Realisation Number 2");
        Console.WriteLine(" {0}","   I            HT(I)            ET(I)");
        Console.WriteLine(" {0}","  --------------------------------------");
        for (i = 1 ; i <= num ; i++)
        {
          Console.WriteLine("  {0,5}  {1,16:f4}  {2,16:f4}",i,ht[i - 1],et[i - 1]);
        }
        //
        L60: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05pg Example Program Data
1  1  1762543      :: GENID,SUBID,SEED(1)
10 2               :: NUM,NREAL
1  1               :: IP,IQ
'N'
0.1 -0.3 0.1 0.9   :: THETA


// g05ph Example Program Text
// C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05PHE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int ip=2;
        const int iq=0;
        const int n=10;
        const int mseed=1;
        double avar,   var,   xmean; int genid,  i,  subid;
        double[] phi = new double[ip];
        double[] r = new double[ip+iq+6+ip];
        double[] theta = new double[iq];
        double[] x = new double[n];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05ph Example Program Results");
        Console.WriteLine("");
        //      Set the ARMA model parameters
        xmean = 0.00e0;
        phi[0] = 0.40e0;
        phi[1] = 0.20e0;
        avar = 1.00e0;
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L40;
        }
        //      Set up the reference vector and generate the N realisations
        //      Choose mode = 2
        G05.g05ph(2, n, xmean, ip, phi,iq,theta, avar,r,  g05State, out var, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05ph failed with ifail = {0,5}", ifail);
          goto L40;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine("  {0,12:f4}",x[i - 1]);
        }
        //
        L40: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05ph Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
10                :: N
2  0              :: IP,IQ
0.0               :: XMEAN
0.4  0.2          :: PHI
1.0               :: AVAR


// g05pj Example Program Text
// C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05PJE
  {
    static string datafile = "ExampleData/g05pje.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        const int mseed=1;

        int genid,   i,   ii,   ip,   iq,   j,   k,   l,   n,   subid; int ifail;
        Console.WriteLine("g05pj Example Program Results");
        Console.WriteLine("");
        //      Read data from a file
        //      Skip heading
        sr.Reset();
        //      Read in initial parameters
        sr.Reset();
        k = int.Parse(sr.Next());
        ip = int.Parse(sr.Next());
        iq = int.Parse(sr.Next());
        n = int.Parse(sr.Next());
        int rn = Math.Max(ip, iq); l = k*(k+1)/2;
        int k2 = k*k;
        if (ip>0)
        {
          l = l + (ip-1)*k2;
        }
        double[] phi = new double[ip*k*k];
        int lr;
        if (k>=6)
        {
          lr = (5*rn*rn+1)*k2 + (4*rn+3) + 4;
        }
        else
        {
          lr = ((ip+iq)*(ip+iq)+1)*k2 + (4*(ip+iq)+3)*k +
          Math.Max(k*rn*(k*rn+2),k2*(ip+iq)*(ip+iq)+l*(l+3)+k2*(iq+1)) + 4;
        }
        double[] theta = new double[iq*k*k];
        double[,] var = new double[k, k];
        double[,] x = new double[k, n];
        double[] xmean = new double[k];
        int[] seed = new int[mseed];
        double[] r = new double[lr];
        //      Check the specified array limits
        if (k <= 0 || ip < 0 || iq < 0 || n <= 0)
        {
          Console.WriteLine("   ** Problem size is too small.");
          goto L160;
        }
        //      Read in the AR parameters
        for (l = 1 ; l <= ip ; l++)
        {
          for (i = 1 ; i <= k ; i++)
          {
            ii = (l - 1) * k * k + i;
            sr.Reset();
            for (j = 1 ; j <= k ; j++)
            {
              phi[ii + k * (j - 1) - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
        }
        //      Read in the MA parameters
        for (l = 1 ; l <= iq ; l++)
        {
          for (i = 1 ; i <= k ; i++)
          {
            ii = (l - 1) * k * k + i;
            sr.Reset();
            for (j = 1 ; j <= k ; j++)
            {
              theta[ii + k * (j - 1) - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
        }
        //      Read in the means
        sr.Reset();
        for (i = 1 ; i <= k ; i++)
        {
          xmean[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        //      Read in the variance / covariance matrix
        for (i = 1 ; i <= k ; i++)
        {
          sr.Reset();
          for (j = 1 ; j <= i ; j++)
          {
            var[i - 1 , j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L160;
        }
        //      Generate the first realisation
        //      Use mode = 2 to set up R and generate values

        G05.g05pj(2, n, k, xmean, ip, phi, iq, theta, var, r,  g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05pj failed with ifail = {0,5}", ifail);
          goto L160;
        }
        //      Display the results
        Console.WriteLine("");
        Console.WriteLine(" {0:0.000}"," Realisation Number 1");
        for (i = 1 ; i <= k ; i++)
        {
          Console.WriteLine("\n  {0}{1,3}","  Series number ",i);
          Console.WriteLine(" {0}","  -------------");
          Console.WriteLine("");
          for (j = 1 ; j <= n ; j++)
          {
            Console.Write(" {0,8:f3}{1}", x[i - 1 , j - 1],j%8==0||j==n?"\n":"");
          }
          Console.WriteLine("");
        }
        //      Generate a second realisation
        //      Use mode = 3 to reset the series and generate values
        G05.g05pj(3, n, k, xmean, ip, phi, iq, theta, var,  r,  g05State, x,   out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05pj failed with ifail = {0,5}", ifail);
          goto L160;
        }
        //      Display the results
        Console.WriteLine("");
        Console.WriteLine(" {0}"," Realisation Number 2");
        for (i = 1 ; i <= k ; i++)
        {
          Console.WriteLine("\n  {0}{1,3}","  Series number ",i);
          Console.WriteLine(" {0}","  -------------");
          Console.WriteLine("");
          for (j = 1 ; j <= n ; j++)
          {
            Console.Write(" {0,8:f3}{1}", x[i - 1 , j - 1],j%8==0||j==n?"\n":"");
          }
          Console.WriteLine("");
        }
        //
        L160: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


// g05pm Example Program Text
// C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05PME
  {
    static string datafile = "ExampleData/g05pme.d";
    const double one=1.00e0;
    const double two=2.00e0;
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double ad, alpha, dv, tmp, var, z;
        int en, genid, i, itype, ival, j, k=0, mode, n, nf, nsim, p, smode, subid;
        int[] seed = new int[1];
        int ifail;
        Console.WriteLine("g05pm Example Program Results");
        //      Initialise the seed to a repeatable sequence
        seed[0] = 1762543;
        //      genid and subid identify the base generator.
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("   ** Generator initialisation returned with ifail = {0,5}",ifail);
          goto L140;
        }
        //      Skip headings in data file
        sr.Reset();
        //      Read in the initial arguments and check array sizes
        sr.Reset();
        mode = int.Parse(sr.Next());
        itype = int.Parse(sr.Next());
        n = int.Parse(sr.Next());
        nf = int.Parse(sr.Next());
        nsim = int.Parse(sr.Next());
        alpha = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        double[,] blim = new double[2, nf];
        double[,] bsim = new double[nsim, nf];
        double[] e = new double[1];
        double[] fse = new double[nf];
        double[] fv = new double[nf];
        double[,] glim = new double[2, nf];
        double[,] gsim = new double[nsim, nf];
        double[] param = new double[4];
        double[] q = new double[2];
        double[] res = new double[n];
        double[] tsim1 = new double[n];
        double[] tsim2 = new double[n];
        double[] y = new double[n];
        double[] yhat = new double[n];
        if (n < 1  || nsim < 1)
        {
          Console.WriteLine("   ** Problem size is too small.");
          goto L140;
        }
        sr.Reset();
        for (i = 1 ; i <= n ; i++)
        {
          y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        //      Read in the itype dependent arguments (skipping headings)
        if (itype == 1)
        {
          sr.Reset();
          param[0] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          p = 0;
          ival = 1;
        }
        else if (itype == 2)
        {
          sr.Reset();
          param[0] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          param[1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          p = 0;
          ival = 2;
        }
        else if (itype == 3)
        {
          sr.Reset();
          param[0] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          param[1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          param[2] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          p = 0;
          ival = 2;
        }
        else
        {
          sr.Reset();
          param[0] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          param[1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          param[2] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          param[3] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          p = int.Parse(sr.Next());
          ival = p + 2;
        }
        double[] init = new double[ival];
        double[] r = new double[p+13];
        //      Read in the mode dependent arguments (skipping headings)
        if (mode == 0)
        {
          //         User supplied initial values
          sr.Reset();
          for (i = 1 ; i <= ival ; i++)
          {
            init[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        else if (mode == 1)
        {
          //         Continuing from a previously saved R
          sr.Reset();
          for (i = 1 ; i <= p + 13 ; i++)
          {
            r[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        else if (mode == 2)
        {
          //         Initial values calculated from first K observations
          sr.Reset();
          k = int.Parse(sr.Next());
        }
        //
        //      Fit a smoothing model (parameter r in G05.g05PMF and state in G13.g13amf
        //      are in the same format)
        G13.g13am(mode, itype, p, param, n, y, k, init, nf, fv, fse, yhat, res, out dv,out ad, r,
        out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("   ** g13am returned with ifail = {0,5}",ifail);
          goto L140;
        }
        //
        //      Simulate forecast values from the model, and don't update R
        smode = 2;
        var = dv * dv;
        en = (int)n;
        //      Simulate nsim forecasts
        for (i = 1 ; i <= nsim ; i++)
        {
          //         Simulations assuming gaussian errors
          G05.g05pm(smode, nf, itype, p, param, init, var, r, g05State, e, 0, tsim1, out ifail);
          if (ifail != 0)
          {
            Console.WriteLine("   ** G05.g05pm returned with ifail = {0,5}",ifail);
            goto L140;
          }
          //         Bootstrapping errors
          G05.g05pm(smode, nf, itype, p, param, init, 0.00e0, r, g05State, res, en, tsim2,
          out ifail);
          if (ifail != 0)
          {
            Console.WriteLine("   ** G05.g05pm returned with ifail = {0,5}",ifail);
            goto L140;
          }
          //         Copy and transpose the simulated values
          for (j = 1 ; j <= nf ; j++)
          {
            gsim[i - 1 , j - 1] = tsim1[j - 1];
            bsim[i - 1 , j - 1] = tsim2[j - 1];
          }
        }
        //
        //      Calculate ci based on the quantiles for each simulated forecast
        q[0] = alpha / two;
        q[1] = one - q[0];
        double [] gsim_vec = new double[nsim];
        double [] glim_vec = new double[nsim];
        double [] bsim_vec = new double[nsim];
        double [] blim_vec = new double[nsim];
        for (i = 1 ; i <= nf ; i++)
        {
          for (j = 1; j<= nsim; j++)
          {
            gsim_vec[j-1] = gsim[j-1, i-1];
            bsim_vec[j-1] = bsim[j-1, i-1];
          }
          G01.g01am(nsim, gsim_vec, 2, q, glim_vec, out ifail);
          if (ifail != 0)
          {
            Console.WriteLine("   ** g01am returned with ifail = {0,5}",ifail);
            goto L140;
          }
          G01.g01am(nsim, bsim_vec, 2, q, blim_vec, out ifail);
          if (ifail != 0)
          {
            Console.WriteLine("   ** g01am returned with ifail = {0,5}",ifail);
            goto L140;
          }
          for (j = 1; j<= 2; j++)
          {
            glim[j-1, i-1] = glim_vec[j-1];
            blim[j-1, i-1] = blim_vec[j-1];
          }
        }
        //
        //      Display the forecast values and associated prediction intervals
        Console.WriteLine("");
        Console.WriteLine(" {0}","Initial values used:");
        for (i = 1 ; i <= ival ; i++)
        {
          Console.WriteLine("{0,4}  {1,12:f3}  ",i,init[i - 1]);
        }
        Console.WriteLine("");
        Console.WriteLine("{0}{1,12:e4}","Mean Deviation     = ",dv);
        Console.WriteLine("{0}{1,12:e4}","Absolute Deviation = ",ad);
        Console.WriteLine("");
        Console.WriteLine(" {0}","         Observed      1-Step");
        Console.WriteLine(" {0}"," Period   Values      Forecast      Residual");
        Console.WriteLine("");
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine("{0,4}  {1,12:f3}  {2,12:f3}  {3,12:f3}",i,y[i - 1],yhat[i - 1],res[i - 1]);
        }
        Console.WriteLine("");
        Console.WriteLine(" {0}",("") + ("      Simulated CI         Simulated CI"));
        Console.WriteLine(" {0}",("Obs.  Forecast      Estimated CI   ") + ("     (Gaussian Errors)    (Bootstrap Errors)"));
        z = G01.g01fa("L", q[1], out ifail);
        for (i = 1 ; i <= nf ; i++)
        {
          tmp = z * fse[i - 1];
          Console.WriteLine("{0,3}  {1,10:f3}  {2,10:f3}  {3,10:f3}  {4,10:f3}  {5,10:f3}  {6,10:f3}  {7,10:f3}",n + i,fv[i - 1],fv[i - 1] - tmp,fv[i - 1] + tmp,glim[0 , i - 1],glim[1 , i - 1],blim[0 , i - 1],blim[1 , i - 1]);
        }
        Console.WriteLine("  {0,5:f1}{1}",100.00e0 * (one - alpha),"% CIs were produced");
        //
        L140: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


// g05px Example Program Text
// C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05PXE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int n=4;
        const int m=4;
        const int mseed=1;
        int genid,   i,   j,   subid;
        double[,] a = new double[m, n];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05px Example Program Results");
        Console.WriteLine("");
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L40;
        }
        //      Generate the random orthogonal matrix
        G05.g05px("Right", "Initialize", m, n, g05State, a,  out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05kp failed with ifail = {0,5}", ifail);
          goto L40;
        }
        //      Display the results
        for (i = 1 ; i <= m ; i++)
        {
          for (j = 1 ; j <= n ; j++)
          {
            Console.Write(" {0,8:f3}", a[i - 1 , j - 1]);
          }
          Console.WriteLine("");
        }
        //
        L40: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05px Example Program Data
1  1  1762543      :: GENID,SUBID,SEED(1)
4  4               :: N,M
'R'  'I'           :: SIDE,INIT


// g05py Example Program Text
// C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05PYE
  {
    static string datafile = "ExampleData/g05pye.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        DataReader sr = new DataReader(datafile);
        double eps=0.0;
        int genid,   i,   j,   n,  subid;
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05py Example Program Results");
        Console.WriteLine("");
        //      Read data from a file
        //      Skip heading
        sr.Reset();
        //      Read in initial parameters
        sr.Reset();
        n = int.Parse(sr.Next());
        double[,] c = new double[n, n];
        double[] d = new double[n];
        //      Check the specified array limits
        if (n < 0)
        {
          Console.WriteLine("   ** Problem size is too small.");
          goto L40;
        }
        //      Read in the eigenvalues
        sr.Reset();
        for (i = 1 ; i <= n ; i++)
        {
          d[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        //      Set the size of C and tolerance
        eps = 0.000010e0;
        //      Initialise the seed
        seed[0] = 1762543;
        // genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L40;
        }
        //      Generate the correlation matrix
        G05.g05py(n, d, eps, g05State, c, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05py failed with ifail = {0,5}", ifail);
          goto L40;
        }
        //      Display the results
        for (i = 1 ; i <= n ; i++)
        {
          for (j = 1 ; j <= n ; j++)
          {
            Console.Write(" {0,8:f3}", c[i - 1 , j - 1]);
          }
          Console.WriteLine("");
        }
        //
        L40: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05py Example Program Data
3
0.7 0.9 1.4


// g05pz Example Program Text
// C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05PZE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int lrow=4;
        const int ncol=3;
        const int mseed=1;
        const int lr=60;
        int genid,   i,   j,   rctot,   subid; double[] r = new double[lr];
        int[] seed = new int[mseed];
        int[] totc = new int[ncol];
        int[] totr = new int[lrow];
        int[,] x = new int[lrow, ncol];
        int ifail;
        Console.WriteLine("g05pz Example Program Results");
        Console.WriteLine("");Console.WriteLine("");
        //      Set the table row and column totals
        totr[0] = 9;
        totr[1] = 11;
        totr[2] = 7;
        totr[3] = 23;
        totc[0] = 16;
        totc[1] = 17;
        totc[2] = 17;
        rctot = 50;
        //      Initialise the seed
        seed[0] = 1762543;
        // genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L40;
        }
        //      Generate the random table
        //      Choose mode = 2
        G05.g05pz(2, lrow, ncol, totr, totc,r,  g05State, x,  out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05pz failed with ifail = {0,5}", ifail);
          goto L40;
        }
        //      Display the results
        for (i = 1 ; i <= lrow ; i++)
        {
          for (j = 1 ; j <= ncol ; j++)
          {
            Console.Write("{0,3}", x[i - 1 , j - 1]);
          }
          Console.Write("{0,3} ",  "   |    "+totr[i - 1]);
          Console.WriteLine("");
        }
        Console.WriteLine("{0}", "------------+------");
        for (j = 1 ; j <= ncol ; j++)
        {
          Console.Write("{0,3}", totc[j - 1]);
        }
        Console.Write("{0,3} ", "   |    " + rctot);
        Console.WriteLine("");
        //
        L40: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05pz Example Program Data
1  1  1762543      :: GENID,SUBID,SEED(1)
4  3               :: NROW,NCOL
9   11   7   23    :: TOTR
16  17  17         :: TOTC


// g05rc Example Program Text
// C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05RCE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        int df,   genid,   i,   j,   m,   mode,   n,   subid;
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05rc Example Program Results");
        Console.WriteLine("");
        //      Set the number of variables and variates
        m = 4;
        n = 10;
        double[,] x = new double[n, m];
        double[,] c = new double[m, m];
        double[] r = new double[m*(m+1)+2];
        //      Input the upper triangle portion of the covariance matrix
        c[0 , 0] = 1.690e0;
        c[0 , 1] = 0.390e0;
        c[0 , 2] =  -1.860e0;
        c[0 , 3] = 0.070e0;
        c[1 , 0] = 0.390e0;
        c[1 , 1] = 98.010e0;
        c[1 , 2] =  -7.070e0;
        c[1 , 3] =  -0.710e0;
        c[2 , 0] =  -1.860e0;
        c[2 , 1] =  -7.070e0;
        c[2 , 2] = 11.560e0;
        c[2 , 3] = 0.030e0;
        c[3 , 0] = 0.070e0;
        c[3,  1] =  -0.710e0;
        c[3 , 2] = 0.030e0;
        c[3 , 3] = 0.010e0;
        //      Set the degrees of freedom
        df = 10;
        //      Initialise the seed
        seed[0] = 1762543;
        //      Choose the random generator to use
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L40;
        }
        //      Set up reference vector and generate variates
        //      Choose mode = 2
        mode = 2;
        G05.g05rc(mode, n, df, m, c, r,  g05State, x,  out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05rc failed with ifail = {0,5}", ifail);
          goto L40;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          for (j = 1 ; j <= m ; j++)
          {
            Console.Write("{0,10:f4}", x[i - 1 , j - 1]);
          }
          Console.WriteLine(""); ;
        }
        //
        L40: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


// g05rd Example Program Text
// C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05RDE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        int genid,   i,   j,   m,   mode,   n,   subid;
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05rd Example Program Results");
        Console.WriteLine("");
        //      Set the number of variables and variates
        m = 4;
        n = 10;
        double[] r = new double[m*(m+1)+1];
        double[,] x = new double[n, m];
        double[,] c = new double[m, m];
        //      Input the upper triangle portion of the covariance matrix
        c[0 , 0] = 1.690e0;
        c[0 , 1] = 0.390e0;
        c[0 , 2] =  -1.860e0;
        c[0 , 3] = 0.070e0;
        c[1 , 0] = 0.390e0;
        c[1 , 1] = 98.010e0;
        c[1 , 2] =  -7.070e0;
        c[1 , 3] =  -0.710e0;
        c[2 , 0] =  -1.860e0;
        c[2 , 1] =  -7.070e0;
        c[2 , 2] = 11.560e0;
        c[2 , 3] = 0.030e0;
        c[3 , 0] = 0.070e0;
        c[3,  1] =  -0.710e0;
        c[3 , 2] = 0.030e0;
        c[3 , 3] = 0.010e0;
        //      Initialise the seed
        seed[0] = 1762543;
        //      Choose the random generator to use
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L40;
        }
        //      Set up reference vector and generate variates
        //      Choose mode = 2
        mode = 2;
        G05.g05rd(mode, n, m, c,  r,  g05State, x , out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05rd failed with ifail = {0,5}", ifail);
          goto L40;
        }
        //      Display the results
        for (i = 1 ; i <= n ; i++)
        {
          for (j = 1 ; j <= m ; j++)
          {
            Console.Write(" {0, 10:f4}", x[i - 1 , j - 1]);
          }
          Console.WriteLine("");
        }
        //
        L40: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


// g05ry Example Program Text
// C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05RYE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        int df,   genid,   i,   j,   m,   mode,   n,   subid; m = 4;
        n = 10;
        double[,] c = new double[m, m];
        double[] r = new double[m*(m+1)+2];
        double[,] x = new double[n, m];
        double[] xmu = new double[m];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05ry Example Program Results");
        Console.WriteLine("");Console.WriteLine("");
        //      Set the number of variables and variates
        //      Input the upper triangle portion of the covariance matrix
        c[0 , 0] = 1.690e0;
        c[0 , 1] = 0.390e0;
        c[0 , 2] =  -1.860e0;
        c[0 , 3] = 0.070e0;
        c[1 , 0] = 0.390e0;
        c[1 , 1] = 98.010e0;
        c[1 , 2] =  -7.070e0;
        c[1 , 3] =  -0.710e0;
        c[2 , 0] =  -1.860e0;
        c[2 , 1] =  -7.070e0;
        c[2 , 2] = 11.560e0;
        c[2 , 3] = 0.030e0;
        c[3 , 0] = 0.070e0;
        c[3,  1] =  -0.710e0;
        c[3 , 2] = 0.030e0;
        c[3 , 3] = 0.010e0;
        //      Input the means
        xmu[0] = 1.00e0;
        xmu[1] = 2.00e0;
        xmu[2] =  -3.00e0;
        xmu[3] = 0.00e0;
        //      Set the degrees of freedom
        df = 10;
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L40;
        }
        //      Set up reference vector and generate N numbers
        //      Choose mode = 2
        mode = 2;
        //        int order = 2;
        G05.g05ry(mode, n, df, m, xmu, c,r,  g05State, x,   out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05ry failed with ifail = {0,5}", ifail);
          goto L40;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          for (j = 1 ; j <= m ; j++)
          {
            Console.Write(" {0, 10:f4}", x[i - 1 , j - 1]);
          }
          Console.WriteLine("");
        }
        //
        L40: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


// g05rz Example Program Text
// C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05RZE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        int genid,   i,   j,   m,   mode,   n,   subid;
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05rz Example Program Results");
        Console.WriteLine("");
        //      Set the number of variables and variates
        m = 4;
        n = 10;
        double[] r = new double[m*(m+1)+1];
        double[,] x = new double[n, m];
        double[] xmu = new double[m];
        double[,] c = new double[m, m];
        //      Input the upper triangle portion of the covariance matrix
        c[0 , 0] = 1.690e0;
        c[0 , 1] = 0.390e0;
        c[0 , 2] =  -1.860e0;
        c[0 , 3] = 0.070e0;
        c[1 , 0] = 0.390e0;
        c[1 , 1] = 98.010e0;
        c[1 , 2] =  -7.070e0;
        c[1 , 3] =  -0.710e0;
        c[2 , 0] =  -1.860e0;
        c[2 , 1] =  -7.070e0;
        c[2 , 2] = 11.560e0;
        c[2 , 3] = 0.030e0;
        c[3 , 0] = 0.070e0;
        c[3,  1] =  -0.710e0;
        c[3 , 2] = 0.030e0;
        c[3 , 3] = 0.010e0;
        //      Input the means
        xmu[0] = 1.00e0;
        xmu[1] = 2.00e0;
        xmu[2] =  -3.00e0;
        xmu[3] = 0.00e0;
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L40;
        }
        //      Set up reference vector and generate N numbers
        //      Choose mode = 2
        mode = 2;
        G05.g05rz(mode, n, m, xmu, c,r,  g05State, x,  out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05rz failed with ifail = {0,5}", ifail);
          goto L40;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          for (j = 1 ; j <= m ; j++)
          {
            Console.Write(" {0,8:f4}  ", x[i - 1 , j - 1]);
          }
          Console.WriteLine("");
        }
        //
        L40: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g05sa Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05SAE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=5;
        int genid,   i,   subid; double[] x = new double[n];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05sa Example Program Results");
        Console.WriteLine(" ");
        Console.WriteLine(" ");
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate the variates
        G05.g05sa(n, g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05sa failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0,8:f4}", x[i - 1]);
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05sa Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
5                 :: N


//      g05sb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05SBE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=5;
        double a,   b;
        int genid,  i,  subid;
        double[] x = new double[n];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05sb Example Program Results");
        Console.WriteLine(" ");
        //      Set the distribution parameters A and B
        a = 2.00e0;
        b = 2.00e0;
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate the variates
        G05.g05sb(n, a, b, g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05sb failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0,8:f4}", x[i - 1]);
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05sb Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
5                 :: N
2.0 2.0           :: A,B


//      g05sc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05SCE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=5;
        double semiqr,   xmed; int genid,  i,  subid;
        double[] x = new double[n];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05sc Example Program Results");
        Console.WriteLine(" ");
        //      Set the distribution parameters xmed and semiqr
        xmed = 1.00e0;
        semiqr = 2.00e0;
        //      Initialise the seed to a repeatable sequence
        seed[0] = 1762543;
        //      genid and subid identify the base generator.
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate the variates
        G05.g05sc(n, xmed, semiqr, g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05sc failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0,8:f4} ", x[i - 1]);
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05sc Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
5                 :: N
1.0 2.0           :: XMED,SEMIQR


//      g05sd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05SDE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=5;
        int df,   genid,   i,   subid; double[] x = new double[n];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05sd Example Program Results");
        Console.WriteLine("");
        //      Set the distribution parameter df
        df = 5;
        //      Initialise the seed to a repeatable sequence
        seed[0] = 1762543;
        //      genid and subid identify the base generator.
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate the variates
        G05.g05sd(n, df, g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05sd failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0,8:f4} ", x[i - 1]);
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05sd Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
5                 :: N
5                 :: DF


//      g05se Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05SEE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=5;
        const int m=4;
        int genid,   i,   j,   subid;
        double[] a = new double[m];
        double[,] x = new double[n, m];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05se Example Program Results");
        Console.WriteLine("");Console.WriteLine("");
        //      Set the distribution parameters A
        for (i = 1 ; i <= m ; i++)
        {
          a[i - 1] = 2.00e0;
        }
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L60;
        }
        //      Generate the variates
        G05.g05se(n, m, a, g05State, x,   out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05se failed with ifail = {0,5}", ifail);
          goto L60;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          for (j = 1 ; j <= m ; j++)
          {
            Console.Write(" {0,8:f4}", x[i - 1 , j - 1]);
          }
          Console.WriteLine("");
        }
        //
        L60: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05se Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
5 4               :: N,M
2.0 2.0 2.0 2.0   :: A


//      g05sf Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05SFE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=5;
        double a=0.0;
        int genid,   i, subid;
        double[] x = new double[n];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05sf Example Program Results");
        Console.WriteLine("");
        //      Set the distribution parameter A
        a = 1.00e0;
        //      Initialise the seed to a repeatable sequence
        seed[0] = 1762543;
        //      genid and subid identify the base generator.
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate the variates
        G05.g05sf(n, a, g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05sf failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0:0.0000} ", x[i - 1]);
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05sf Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
5                 :: N
1.0               :: A


//      g05sg Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05SGE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=5;
        const int nmix=3;
        int genid,   i,   subid;
        double[] a = new double[nmix];
        double[] wgt = new double[nmix];
        double[] x = new double[n];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05sg Example Program Results");
        Console.WriteLine("");Console.WriteLine("");
        //      Set the distribution parameters a and wgt
        a[0] = 1.00e0;
        a[1] = 5.00e0;
        a[2] = 2.00e0;
        wgt[0] = 0.50e0;
        wgt[1] = 0.30e0;
        wgt[2] = 0.20e0;
        //      Initialise the seed to a repeatable sequence
        seed[0] = 1762543;
        //      genid and subid identify the base generator.
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate the variates
        G05.g05sg(n, nmix, a, wgt, g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05sg failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0,8:f4}", x[i - 1]);
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g05sh Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05SHE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=5;
        int df1,   df2,   genid,   i,   subid;
        double[] x = new double[n];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05sh Example Program Results");
        Console.WriteLine("");
        //      Set the distribution parameters df1 and df2
        df1 = 2;
        df2 = 3;
        //      Initialise the seed to a repeatable sequence
        seed[0] = 1762543;
        //      genid and subid identify the base generator.
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate the variates
        G05.g05sh(n, df1, df2, g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05sh failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0,8:f4} ", x[i - 1]);
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05sh Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
5 3               :: N,NMIX
2 3               :: DF1,DF2


//      g05sj Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05SJE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=5;
        double a,   b; int genid,  i,  subid;
        double[] x = new double[n];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05sj Example Program Results");
        Console.WriteLine("");
        //      Set the distribution parameters A and B
        a = 5.00e0;
        b = 1.00e0;
        //      Initialise the seed to a repeatable sequence
        seed[0] = 1762543;
        //      genid and subid identify the base generator.
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate the variates
        G05.g05sj(n, a, b, g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05sj failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0,8:f4}", x[i - 1]);
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05sj Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
5 3               :: N,NMIX
5.0 1.0           :: A,B


//      g05sk Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05SKE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=5;
        double var,    xmu; int genid,   i,   subid;
        double[] x = new double[n];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05sk Example Program Results");
        Console.WriteLine("");Console.WriteLine("");
        //      Set the distribution parameters xmu and var
        xmu = 1.00e0;
        var = 1.50e0;
        //      Initialise the seed to a repeatable sequence
        seed[0] = 1762543;
        //      genid and subid identify the base generator.
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate the variates
        G05.g05sk(n, xmu, var, g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05sk failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0,8:f4}", x[i - 1]);
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05sk Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
5                 :: N
1.0 1.5           :: XMU,VAR


//      g05sl Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05SLE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=5;
        double a,   b; int genid,  i,  subid;
        double[] x = new double[n];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05sl Example Program Results");
        Console.WriteLine("");Console.WriteLine("");
        //      Set the distribution parameters A and B
        a = 1.00e0;
        b = 2.00e0;
        //      Initialise the seed to a repeatable sequence
        seed[0] = 1762543;
        //      genid and subid identify the base generator.
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate the variates
        G05.g05sl(n, a, b, g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05sl failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0,8:f4}", x[i - 1]);
          //       Math.Mo
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05sl Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
5 3               :: N,NMIX
1.0 2.0           :: A,B


//      g05sm Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05SME
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=5;
        double var,   xmu;
        int genid,  i,  subid;
        double[] x = new double[n];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05sm Example Program Results");
        Console.WriteLine("");Console.WriteLine("");
        //      Set the distribution parameters xmu and var
        xmu = 1.00e0;
        var = 2.00e0;
        //      Initialise the seed to a repeatable sequence
        seed[0] = 1762543;
        //      genid and subid identify the base generator.
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate the variates
        G05.g05sm(n, xmu, var, g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05sm failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0,8:f4}", x[i - 1]);
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05sm Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
5 3               :: N,NMIX
1.0 2.0           :: XMU,VAR


//      g05sn Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05SNE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=5;
        int df,   genid,   i,   subid;
        double[] x = new double[n];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05sn Example Program Results");
        Console.WriteLine("");Console.WriteLine("");
        //      Set the distribution parameter df
        df = 5;
        //      Initialise the seed to a repeatable sequence
        seed[0] = 1762543;
        //      genid and subid identify the base generator.
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate the variates
        G05.g05sn(n, df, g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05sn failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0,8:f4}", x[i - 1]);
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05sn Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
5 3               :: N,NMIX
5                 :: DF


//      g05sp Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05SPE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=5;
        double xmax,   xmed,   xmin;
        int genid,  i,  subid;
        double[] x = new double[n];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05sp Example Program Results");
        Console.WriteLine("");
        //      Set the distribution parameters xmin,xmax and xmed
        xmin =  -1.00e0;
        xmax = 1.00e0;
        xmed = 0.50e0;
        //      Initialise the seed to a repeatable sequence
        seed[0] = 1762543;
        //      genid and subid identify the base generator.
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate the variates
        G05.g05sp(n, xmin, xmed, xmax, g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05sp failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0,8:f4}", x[i - 1]);
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05sp Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
5 3               :: N,NMIX
-1.0 0.5 1.0      :: XMIN,XMED,XMAX


//      g05sq Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05SQE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=5;
        double a,   b;
        int genid,  i,  subid;
        double[] x = new double[n];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05sq Example Program Results");
        Console.WriteLine("");
        //      Set the distribution parameters A and B
        a =  -1.00e0;
        b = 1.00e0;
        //      Initialise the seed to a repeatable sequence
        seed[0] = 1762543;
        //      genid and subid identify the base generator.
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate the variates
        G05.g05sq(n, a, b, g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05sq failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0,8:f4}", x[i - 1]);
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05sq Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
5 3               :: N,NMIX
-1.0 1.0          :: A,B


//      g05sr Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05SRE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=5;
        double vk=0.0;
        int genid,   i,   subid;
        double[] x = new double[n];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05sr Example Program Results");
        Console.WriteLine("");
        //      Set the distribution parameters vk
        vk = 1.00e0;
        //      Initialise the seed to a repeatable sequence
        seed[0] = 1762543;
        //      genid and subid identify the base generator.
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate the variates
        G05.g05sr(n, vk, g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05sr failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0,8:f4}", x[i - 1]);
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05sr Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
5 3               :: N,NMIX
1.0               :: VK


//      g05ss Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05SSE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=5;
        double a,   b;
        int genid,  i,  subid;
        double[] x = new double[n];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05ss Example Program Results");
        Console.WriteLine("");
        //      Set the distribution parameters A and B
        a = 1.00e0;
        b = 2.00e0;
        //      Initialise the seed to a repeatable sequence
        seed[0] = 1762543;
        //      genid and subid identify the base generator.
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate the variates
        G05.g05ss(n, a, b, g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05ss failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0,8:f4}", x[i - 1]);
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05ss Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
5 3               :: N,NMIX
1.0 2.0           :: A,B


//      g05ta Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05TAE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=20;
        double p=0.0;
        int genid,   i,   m,   subid;
        double[] r = new double[6007];
        int[] seed = new int[mseed];
        int[] x = new int[n];
        int ifail;
        Console.WriteLine("g05ta Example Program Results");
        Console.WriteLine("");
        //      Set the distribution parameters P and M
        p = 0.80e0;
        m = 6000;
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate the variates
        //      Choose mode = 2
        G05.g05ta(2, n, m, p,r,  g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05ta failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0}", x[i - 1]);
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05ta Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
20                :: N
0.8 6000          :: P,M


//      g05tb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05TBE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=20;
        double p=0.0;
        int genid,   i,   subid;
        int[] seed = new int[mseed];
        bool[] x = new bool[n];
        int ifail;
        Console.WriteLine("g05tb Example Program Results");
        Console.WriteLine("");
        //      Set the distribution parameters P
        p = 0.50e0;
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate the variates
        G05.g05tb(n, p, g05State,  x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05tb failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0,8:f4}", x[i - 1]);
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05tb Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
20                :: N
0.5               :: P


g05tb Example Program Results

    False
     True
    False
    False
     True
     True
     True
    False
     True
    False
     True
     True
    False
     True
    False
     True
     True
    False
    False
    False


//      g05tc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05TCE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=10;
        double p=0.0;
        int genid,   i,   subid;
        double[] r = new double[40000];
        int[] seed = new int[mseed];
        int[] x = new int[n];
        int ifail;
        Console.WriteLine("g05tc Example Program Results");
        Console.WriteLine("");Console.WriteLine("");
        //      Set the distribution parameter P
        p = 0.0010e0;
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate the variates
        //      Choose mode = 3 because P is close to 0
        G05.g05tc(3, n, p,r,  g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05tc failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0,5}", x[i - 1]);
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05tc Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
10                :: N
0.001             :: P


//      g05td Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05TDE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int np=11;
        const int mseed=1;
        const int n=20;
        int genid,   i,   ip1,   itype,   subid;
        double[] p = new double[np] {0.010e0, 0.020e0, 0.040e0, 0.080e0, 0.20e0, 0.30e0,
        0.20e0, 0.080e0, 0.040e0, 0.020e0, 0.010e0};
        double[] r = new double[10+(int)Math.Ceiling(1.4*np)];
        int[] seed = new int[mseed];
        int[] x = new int[n];
        int ifail;
        Console.WriteLine("g05td Example Program Results");
        Console.WriteLine("");Console.WriteLine("");
        //      Set the lowest value for the distribution
        ip1 =  -5;
        //      P is a PDF
        itype = 1;
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate the variates
        //      Choose mode = 2
        G05.g05td(2, n, p, np, ip1, itype,r,  g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05td failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0,5}", x[i - 1]);
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g05te Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05TEE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=20;
        const int lr=200;
        int genid,   i,   m,   np,   ns,   subid;
        double[] r = new double[lr];
        int[] seed = new int[mseed];
        int[] x = new int[n];
        int ifail;
        Console.WriteLine("g05te Example Program Results");
        Console.WriteLine("");
        //      Set the distribution parameters ns, np, m
        ns = 500;
        m = 900;
        np = 1000;
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate the variates
        //      Choose mode = 2
        G05.g05te(2, n, ns, np, m, r, g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05te failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0,5}", x[i - 1]);
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g05tf Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05TFE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=10;
        const int lr=1;
        double a=0.0;
        int genid,   i,   subid;
        double[] r = new double[lr];
        int[] seed = new int[mseed];
        int[] x = new int[n];
        int ifail;
        Console.WriteLine("g05tf Example Program Results");
        Console.WriteLine("");
        //      Set the distribution parameter A
        a = 0.99990e0;
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate the variates
        //      Use mode=3 because a > 0.95
        G05.g05tf(3, n, a, r, g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05tf failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0,5}", x[i - 1]);
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05tf Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
10                :: N
0.9999            :: A


g05tf Example Program Results

     6
    23
  2765
    30
     3
     1
   299
   968
   166
     4


//      g05tg Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05TGE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        int genid, i, j, m, subid;
        int n=20;
        int k=4;
        int lr=6007;
        double[] p = new double[k];
        double[] r = new double[lr];
        int[] seed = new int[1];
        int[,] x = new int[n, k];
        int ifail;
        Console.WriteLine("g05tg Example Program Results");
        Console.WriteLine("");
        //      Set the distribution parameters P and M
        p[0] = 0.080e0;
        p[1] = 0.10e0;
        p[2] = 0.80e0;
        p[3] = 0.020e0;
        m = 6000;
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("   ** Generator initialisation returned with ifail = {0,5}",ifail);
          goto L40;
        }
        //      Generate the variates
        //      Choose mode = 2
        G05.g05tg(2, n, m, k, p,r,  g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("   ** G05.g05tg returned with ifail = {0,5}",ifail);
          goto L40;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          for (j = 1 ; j <= k ; j++)
          {
            Console.Write(" {0,8}", x[i - 1 , j - 1]);
          }
          Console.WriteLine("");
        }
        //
        L40: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g05th Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05THE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=20;
        const int lr=1;
        double p=0.0;
        int genid,   i,   m,   subid;
        double[] r = new double[lr];
        int[] seed = new int[mseed];
        int[] x = new int[n];
        int ifail;
        Console.WriteLine("g05th Example Program Results");
        Console.WriteLine("");Console.WriteLine("");
        //      Set the distribution parameter P
        p = 0.9990e0;
        m = 60;
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate the variates
        //      Choose mode = 3 because p close to 1
        G05.g05th(3, n, m, p,r,  g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05th failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0,10}", x[i - 1]);
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05th Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
20                :: N
0.999  60         :: P,M


//      g05tj Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05TJE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=10;
        const int lr=120;
        double lambda=0.0;
        int genid,   i,   subid; double[] r = new double[lr];
        int[] seed = new int[mseed];
        int[] x = new int[n];
        int ifail;
        Console.WriteLine("g05tj Example Program Results");
        Console.WriteLine("");
        //      Set the distribution parameter lambda
        lambda = 20.00e0;
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Generate the variates
        //      Choose mode = 2
        G05.g05tj(2, n, lambda,r,  g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05tj failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0,10}", x[i - 1]);
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05tj Example Program Data
1  1  1762543     :: GENID,SUBID,SEED(1)
10                :: N
20.0              :: LAMBDA


g05tj Example Program Results

         21
         15
         23
         24
         14
         20
         19
         23
         20
         22


//      g05tk Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05TKE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int m=5;
        const int n=10;
        int genid,   i,   j,   subid;
        double[] lambda = new double[m];
        int[] seed = new int[mseed];
        int[] x = new int[n];
        int ifail;
        Console.WriteLine("g05tk Example Program Results");
        Console.WriteLine("");
        //      Set the distribution parameter lambda
        lambda[0] = 0.50e0;
        lambda[1] = 5.00e0;
        lambda[2] = 1.00e1;
        lambda[3] = 5.00e2;
        lambda[4] = 1.00e3;
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L40;
        }
        //      Generate N sets of the M variates
        for (i = 1 ; i <= n ; i++)
        {
          G05.g05tk(m, lambda, g05State, x, out ifail);
          if (ifail != 0)
          {
            Console.WriteLine("** g05tk failed with ifail = {0,5}", ifail);
            goto L40;
          }
          //         Display the variates
          Console.Write(" {0,3}",  i);
          for (j = 1 ; j <= m ; j++)
          {
            Console.Write(" {0,10}", x[j - 1]);
          }
          Console.WriteLine("");
        }
        //
        L40: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


//      g05tl Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05TLE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int mseed=1;
        const int n=5;
        int a,   b,   genid,   i,   subid; int[] seed = new int[mseed];
        int[] x = new int[n];
        int ifail;
        Console.WriteLine("g05tl Example Program Results");
        Console.WriteLine("");Console.WriteLine("");
        //      Initialise the seed
        seed[0] = 1762543;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L20;
        }
        a =  -5;
        b = 5;
        //      Generate the variates
        G05.g05tl(n, a, b, g05State, x, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05tl failed with ifail = {0,5}", ifail);
          goto L20;
        }
        //      Display the variates
        for (i = 1 ; i <= n ; i++)
        {
          Console.WriteLine(" {0,5}", x[i - 1]);
        }
        Console.WriteLine("");
        //
        L20: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05tl Example Program Data
1  1  1762543           :: GENID,SUBID,SEED(1)
5                       :: N
-5 5                    :: A,B


g05tl Example Program Results

     2
    -4
     3
     3
    -4


//      g05ym Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05YME
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int n=200;
        const int midim=8;
        const int ordrc=1;
        const int liref=32 * midim + 7;
        double sum,   tmp,   vsbl; int d,  genid,  i,  idim,  iskip,  j;
        int[] iref = new int[liref];
        int ifail;
        Console.WriteLine("g05ym Example Program Results");
        idim = midim;
        double[,] quas = new double[idim, n];
        //      Skip the first few variates in the sequence
        iskip = 1000;
        //      Initialise the Sobol generator
        genid = 1;
        G05.g05yl(genid, idim, iref,  iskip, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05yl failed with ifail = {0,5}", ifail);
          goto L80;
        }
        //      Generate N quasi-random variates
        G05.g05ym(n, ordrc, quas, iref, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05ym failed with ifail = {0,5}", ifail);
          goto L80;
        }
        //      Evaluate the function, and sum
        sum = 0.00e0;
        for (i = 1 ; i <= n ; i++)
        {
          tmp = 1.00e0;
          for (d = 1 ; d <= idim ; d++)
          {
            tmp = tmp * Math.Abs(4.00e0 * quas[d - 1 , i - 1] - 2.00e0);
          }
          sum = sum + tmp;
        }
        //      Convert sum to mean value
        vsbl = sum / (double)n;
        Console.WriteLine("  ");
        Console.WriteLine("  {0}{1,8:f4}","Value of integral = ",vsbl);
        //      Dump the first 10 variates
        Console.WriteLine("  ");
        Console.WriteLine("  {0}","First 10 variates");
        Console.WriteLine("");
        for (i = 1 ; i <= 10 ; i++)
        {
          Console.Write(" {0,3}  ",  i);
          for (j = 1 ; j <= idim ; j++)
          {
            Console.Write(" {0,8:f4}", quas[j - 1 , i - 1]);
          }
          Console.WriteLine("");
        }
        //
        L80: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05ym Example Program Data
1                 :: GENID
200  8  1000      :: N,IDIM,ISKIP
5                 :: DN


//      g05yn Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
using System.IO;
namespace NagDotNetExamples
{
  public class G05YNE
  {
    const int mn=200;
    const int midim=8;
    const int ordrc=1;
    const int ldquas=midim;
    const int tdquas=mn;
    const int liref=32 * midim + 7;
    const int mseed=1;
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        double sum,   tmp,   vsbl; int d,  i,  idim,  iskip,  j,  n,  nsdigi,  pgenid,  psubid,  stype;
        int[] iref = new int[liref];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g05yn Example Program Results");
        //      Initialise the psuedo-random generator used in the
        //      scrambling to a repeatable sequence
        seed[0] = 1762543;
        pgenid = 1;
        psubid = 1;
        G05.G05State g05State = new G05.G05State(pgenid, psubid, seed, out  ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L80;
        }
        //      Problem size
        idim = 8;
        n = mn;
        double[,] quas = new double[idim, n];
        //      Skip the first few variates in the sequence
        iskip = 1000;
        //      Initialise the Sobol generator
        //      Use Owen type scrambling
        stype = 1;
        //      Use the default value for nsdigi
        nsdigi = 0;
        //      Call the initialiser for the quasi-random sequence
        G05.g05yn(pgenid, stype, idim, iref,  iskip, nsdigi, g05State, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05yn failed with ifail = {0,5}", ifail);
          goto L80;
        }
        //      Generate N quasi-random variates
        G05.g05ym(n, ordrc, quas,   iref, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g05ym failed with ifail = {0,5}", ifail);
          goto L80;
        }
        //      Evaluate the function, and sum
        sum = 0.00e0;
        for (i = 1 ; i <= n ; i++)
        {
          tmp = 1.00e0;
          for (d = 1 ; d <= idim ; d++)
          {
            tmp = tmp * Math.Abs(4.00e0 * quas[d - 1 , i - 1] - 2.00e0);
          }
          sum = sum + tmp;
        }
        //      Convert sum to mean value
        vsbl = sum / (double)n;
        Console.WriteLine("  ");
        Console.WriteLine("  {0}{1,8:f4}","Value of integral = ",vsbl);
        //      Dump the first 10 variates
        Console.WriteLine("  ");
        Console.WriteLine("  {0}","First 10 variates");
        Console.WriteLine("");
        for (i = 1 ; i <= 10 ; i++)
        {
          Console.Write(" {0,3}  ",  i);
          for (j = 1 ; j <= idim ; j++)
          {
            Console.Write(" {0,6:f4}", quas[j - 1 , i - 1]);
          }
          Console.WriteLine("");
        }
        //
        L80: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine( "Exception Raised");
      }
    }
  }
}


g05yn Example Program Data
1  1  1762543     :: PGENID,PSUBID,SEED(1)
1  1  0           :: GENID,STYPE,NSDIGI
200  8  1000      :: N,IDIM,ISKIP
5                 :: DN


//      g07ga Example Program Text
//      Mark 23 Release. NAG Copyright 2011.
//      C# version, NAG Copyright 2012
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
    public class G07GAE
    {
        static string datafile = "ExampleData/g07gae.d";
        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }
        public static int StartExample()
        {
            try
            {

                DataReader sr = new DataReader(datafile);

                double mean,
                                   var;

                int i = 0,
                                   ifail = 0,
                                   ldiff = 0,
                                   n = 0,
                                   niout = 0,
                                   p = 0;

                Console.WriteLine(" {0}", "g07ga Example Program Results");

                Console.WriteLine("");

                //      Skip heading in data file
                sr.Reset();

                //      Read in the problem size
                sr.Reset();
                n = int.Parse(sr.Next());
                p = int.Parse(sr.Next());
                ldiff = int.Parse(sr.Next());

                // allocate
                double[] y = new double[n];
                int[] iout = new int[n];
                double[] diff = new double[ldiff];
                double[] llamb = new double[ldiff];

                //      Read in data
                sr.Reset();
                for (i = 0; i < y.Length; i++)
                {
                    y[i] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }

                //      Let routine calculate mean and variance
                mean = 0.00e0;

                var = 0.00e0;

                //      Get a list of potential outliers
                G07.g07ga(n, p, y, mean, var, iout, out niout, ldiff, diff, llamb, out ifail);

                //      Display results
                Console.WriteLine(" {0} {1}", "Number of potential outliers:", niout);

                if (ldiff > 0)
                {

                    Console.WriteLine(" {0}", "  No.  Index     Value       Diff    ln(lambda^2)");

                }
                else
                {
                    Console.WriteLine(" {0}", "  No.  Index     Value");

                }

                for (i = 1; i <= niout; i++)
                {

                    if (i > ldiff)
                    {

                        Console.WriteLine(" {0,4}   {1,4} {2,10:f2}", i, iout[i - 1], y[iout[i - 1] - 1]);

                    }
                    else
                    {
                        Console.WriteLine(" {0,4}   {1,4} {2,10:f2}  {3,10:f2}  {4,10:f2}", i, iout[i - 1], y[iout[i - 1] - 1], diff[i - 1], llamb[i - 1]);

                    }

                }

                return 0;
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
                Console.WriteLine("Exception Raised");
                return 0;
            }

        }
    }
}


 g07ga Example Program Results

 Number of potential outliers: 2
   No.  Index     Value       Diff    ln(lambda^2)
    1     13      -1.40        0.31       -0.30
    2     11       1.01


//      g07gb Example Program Text
//      Mark 23 Release. NAG Copyright 2011.
//      C# version, NAG Copyright 2012
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
    public class G07GBE
    {
        static string datafile = "ExampleData/g07gbe.d";
        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }
        public static int StartExample()
        {
            try
            {

                DataReader sr = new DataReader(datafile);

                double e,
                                   lx,
                                   ux,
                                   var1,
                                   var2,
                                   x;

                int ifail = 0,
                                   n = 0;

                bool outlier = false;

                Console.WriteLine(" {0}", "g07gb Example Program Results");

                Console.WriteLine("");

                //      Skip heading in data file
                sr.Reset();

                while (true)
                {
                    //        Read in the sample size, variances and value to test

                    try
                    {
                        sr.Reset();
                        n = int.Parse(sr.Next());
                        e = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                        var1 = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                        var2 = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                    }
                    catch
                    {
                        break;
                    }

                    if (ifail != 0)
                    {
                        break;
                    }

                    //        Check whether E is a potential outlier
                    ifail = 0;

                    outlier = G07.g07gb(n, e, var1, var2, out x, out lx, out ux, out ifail);

                    //        Display results
                    Console.WriteLine("  {0}  {1,10}", "Sample size                              :", n);
                    Console.WriteLine("  {0}  {1,10:f3}", "Largest absolute residual (E)            :", e);
                    Console.WriteLine("  {0}  {1,10:f3}", "Variance for whole sample                :", var1);
                    Console.WriteLine("  {0}  {1,10:f3}", "Variance excluding E                     :", var2);
                    Console.WriteLine("  {0}  {1,10:f3}", "Estimate for cutoff (X)                  :", x);
                    Console.WriteLine("  {0}  {1,10:f3}", "Lower limit for cutoff (LX)              :", lx);
                    Console.WriteLine("  {0}  {1,10:f3}", "Upper limit for cutoff (UX)              :", ux);

                    if (outlier)
                    {

                        Console.WriteLine(" {0}", "E is a potential outlier");

                    }
                    else
                    {
                        Console.WriteLine(" {0}", "E does not appear to be an outlier");

                    }

                    Console.WriteLine("");

                }

                return 0;
            }
            catch (Exception e)
            {
                Console.WriteLine(e.Message);
                Console.WriteLine("Exception Raised");
                return 0;
            }

        }
    }
}


 g07gb Example Program Results

  Sample size                              :          15
  Largest absolute residual (E)            :      -1.400
  Variance for whole sample                :       0.303
  Variance excluding E                     :       0.161
  Estimate for cutoff (X)                  :       0.000
  Lower limit for cutoff (LX)              :       0.000
  Upper limit for cutoff (UX)              :       0.000
 E is a potential outlier

  Sample size                              :          14
  Largest absolute residual (E)            :       1.010
  Variance for whole sample                :       0.161
  Variance excluding E                     :       0.103
  Estimate for cutoff (X)                  :       0.105
  Lower limit for cutoff (LX)              :       0.100
  Upper limit for cutoff (UX)              :       0.110
 E is a potential outlier

  Sample size                              :          13
  Largest absolute residual (E)            :       0.630
  Variance for whole sample                :       0.103
  Variance excluding E                     :       0.080
  Estimate for cutoff (X)                  :       1.059
  Lower limit for cutoff (LX)              :       1.011
  Upper limit for cutoff (UX)              :       1.155
 E does not appear to be an outlier


//      g13aa Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13AAE
  {
    static string datafile = "ExampleData/g13aae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   nd,   nds,   ns,   nx,   nxd; int ifail;
        Console.WriteLine("g13aa Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        nx = int.Parse(sr.Next());
        nd = int.Parse(sr.Next());
        nds = int.Parse(sr.Next());
        ns = int.Parse(sr.Next());
        double[] x = new double[nx];
        double[] xd = new double[nx];
        if (nx > 0)
        {
          sr.Reset();
          for (i = 1; i <= nx; i++)
          {
            x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,1}{2}", "Non-seasonal differencing of order ", nd, " and seasonal differencing");
          Console.WriteLine("  {0}{1,1}{2}{3,1}{4}", "of order ", nds, " with seasonality ", ns, " are applied");
          //
          G13.g13aa(x, nx, nd, nds, ns, xd, out nxd, out ifail);
          //
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,2}{2}{3,2}{4}", "The output array holds ", nx, " values, of which the first ", nxd, " are differenced values");
          Console.WriteLine("");
          for (i = 1; i <= nx; i++)
          {
            Console.Write(" {0, 9:f1}{1}", xd[i - 1], i%5==0?"\n":"");
          }
          Console.WriteLine("");
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


g13aa Example Program Results

  Non-seasonal differencing of order 2 and seasonal differencing
  of order 1 with seasonality 4 are applied

  The output array holds 20 values, of which the first 14 are differenced values

     -11.0     -10.0      -8.0       4.0      12.0
      -2.0      18.0       9.0      -4.0      -6.0
      -5.0      -2.0     -12.0       5.0       2.0
     -10.0     -13.0      17.0       6.0     105.0


//      g13ab Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13ABE
  {
    static string datafile = "ExampleData/g13abe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double stat,   xm,   xv; int i,  nk,  nx;
        int ifail;
        Console.WriteLine("g13ab Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        nx = int.Parse(sr.Next());
        nk = int.Parse(sr.Next());
        double[] r = new double[nk];
        double[] x = new double[nx];
        Console.WriteLine("");
        if (nk > 0 && nx > 0)
        {
          sr.Reset();
          for (i = 1; i <= nx; i++)
          {
            x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          Console.WriteLine("  {0}{1,2}{2}", "The first ", nk, " coefficients are required");
          //
          G13.g13ab(x, nx, nk, out xm, out xv, r, out stat, out ifail);
          //
          Console.WriteLine("  {0}{1,12:f4}", "The input array has sample mean ", xm);
          Console.WriteLine("  {0}{1,12:f4}", "The input array has sample variance ", xv);
          Console.WriteLine(" {0}", "The sample autocorrelation coefficients are");
          Console.WriteLine("");
          Console.WriteLine(" {0}", "     Lag  Coeff           Lag  Coeff");
          Console.WriteLine("     ");
          for (i = 1; i <= nk; i++)
          {
            Console.Write("{0,3}{1,8:f4}          {2}", i, r[i - 1], i % 2 == 0 || i == 10 ? "\n     " : "");
          }
          Console.WriteLine(""); ;
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,12:f4}", "The value of STAT is ", stat);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


g13ab Example Program Results

  The first 10 coefficients are required
  The input array has sample mean      37.4180
  The input array has sample variance    1002.0301
 The sample autocorrelation coefficients are

      Lag  Coeff           Lag  Coeff

  1  0.8004            2  0.4355
       3  0.0328            4 -0.2835
       5 -0.4505            6 -0.4242
       7 -0.2419            8  0.0550
       9  0.3783           10  0.5857

  The value of STAT is      92.1231


//      g13ac Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13ACE
  {
    static string datafile = "ExampleData/g13ace.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   nk,   nl,   nvl; int ifail;
        Console.WriteLine("g13ac Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        nk = int.Parse(sr.Next());
        nl = int.Parse(sr.Next());
        double[] ar = new double[nl];
        double[] p = new double[nl];
        double[] r = new double[nk];
        double[] v = new double[nl];
        Console.WriteLine("");
        if (nl > 0 && nk > 0)
        {
          sr.Reset();
          for (i = 1; i <= nk; i++)
          {
            r[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //
          G13.g13ac(r, nk, nl, p, v, ar, out nvl, out ifail);
          //
          if (ifail < 0)
          {
            Console.WriteLine("");
            Console.WriteLine("** g13ac failed with ifail = {0,5}", ifail);
          }
          else
          {
            if (ifail != 0)
            {
              Console.WriteLine("  {0}{1,5}", "g13ac fails. ifail = ", ifail);
              Console.WriteLine("");
            }
            if (ifail == 3)
            {
              Console.WriteLine("  {0}{1,2}{2}", "   Only", nvl, "valid sets were generated");
              Console.WriteLine("");
            }
            if ((ifail == 0) || (ifail == 3))
            {
              Console.WriteLine(" {0}", "Lag  Partial    Predictor error  Autoregressive");
              Console.WriteLine(" {0}", ("     autocorrn  variance ratio") + ("   parameter"));
              Console.WriteLine("");
              for (i = 1; i <= nvl; i++)
              {
                Console.Write(" {0}{1,10:f3}{2,15:f3}{3,15:f3}\r\n", i, p[i - 1], v[i - 1], ar[i - 1]);
              }
              Console.WriteLine("");
            }
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


g13ac Example Program Results

 Lag  Partial    Predictor error  Autoregressive
      autocorrn  variance ratio   parameter

 1     0.800          0.359          1.108
 2    -0.571          0.242         -0.290
 3    -0.239          0.228         -0.193
 4    -0.049          0.228         -0.014
 5    -0.032          0.228         -0.032


//      g13ad Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13ADE
  {
    static string datafile = "ExampleData/g13ade.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double rv,   xv; int i,  nk,  npar;
        int ifail;
        Console.WriteLine("g13ad Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        nk = int.Parse(sr.Next());
        sr.Reset();
        xv = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        double[] r = new double[nk];
        int[] isf = new int[4];
        int[] mr = new int[7];
        Console.WriteLine("");
        if (nk > 0)
        {
          sr.Reset();
          for (i = 1; i <= nk; i++)
          {
            r[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          sr.Reset();
          for (int mrlenindex = 0; mrlenindex < 7; mrlenindex++)
          {
            mr[mrlenindex] = int.Parse(sr.Next());
          }
          npar = mr[0] + mr[2] + mr[3] + mr[5];
          double[] par = new double[npar];
          if (nk >= Math.Max(mr[0]+mr[2], mr[6]*(mr[3]+mr[5])))
          {
            //
            G13.g13ad(mr, r, nk, xv, par, out rv, isf, out ifail);
            //
            if (ifail < 0)
            {
              Console.WriteLine("");
              Console.WriteLine("** g13ad failed with ifail = {0,5}", ifail);
            }
            else
            {
              if (ifail != 0)
              {
                Console.WriteLine("  {0}{1,5}", "g13ad fails. ifail = ", ifail);
                Console.WriteLine("");
              }
              if ((ifail == 0) || (ifail >= (7)))
              {
                Console.Write(" {0}", "Parameter estimation success/failure indicator");
                for (i = 1; i <= 4; i++)
                {
                  Console.Write(" {0}", isf[i - 1]);
                }
                Console.WriteLine("");
                Console.WriteLine("");
                Console.Write(" {0}", "ARIMA model parameter values ");
                for (i = 1; i <= npar; i++)
                {
                  Console.Write(" {0, 10:f5}", par[i - 1]);
                }
                Console.WriteLine("");
                Console.WriteLine("");
                Console.WriteLine("  {0}{1,10:f5}", "Residual variance", rv);
              }
            }
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


g13ad Example Program Results

 Parameter estimation success/failure indicator 0 1 0 1

 ARIMA model parameter values     0.37390    0.51237

  Residual variance   0.00148


//      g13af Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13AFE
  {
    static string datafile = "ExampleData/g13afe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double c,   s; int i,  ipd,  iqd,  ires,  itc,  j,  kfc,  kpiv,  ndf,  nit,  npar,  nppc,  nres,  nst,  nx;
        int[] isf = new int[4];
        int[] mr = new int[7];
        int ifail;
        Console.WriteLine("g13af Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        nx = int.Parse(sr.Next());
        double[] st = new double[nx];
        double[] x = new double[nx];
        for (i = 1; i <= 7; i++)
        {
          mr[i - 1] = int.Parse(sr.Next());
        }
        Console.WriteLine("");
        if (nx > 0)
        {
          sr.Reset();
          for (i = 1; i <= nx; i++)
          {
            x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          npar = mr[0] + mr[2] + mr[3] + mr[5];
          double[] par = new double[npar];
          if (npar > 0)
          {
            for (i = 1; i <= npar; i++)
            {
              par[i - 1] = 0.00e0;
            }
            kfc = 1;
            c = 0.00e0;
            nppc = npar + kfc;
            double[,] cm = new double[nppc, nppc];
            double[] sd = new double[nppc];
            //            * Set kpiv to 1 to obtain monitoring information *
            kpiv = 0;
            nit = 50;
            iqd = mr[5] * mr[6] + mr[2];
            ipd = mr[3] * mr[6] + mr[0];
            ires = 15 * iqd + 11 * nx + 13 * nppc + 8 * ipd + 12 + 2 * ((iqd + nppc)) * ((iqd + nppc));
            double[] res = new double[ires];
            if (ires > 0)
            {
              //
              G13.g13af(mr, par, ref c, kfc, x, nx, out s, out ndf, sd, nppc, cm, st, out nst, kpiv,
              nit, out itc, isf, res, out nres, out ifail);
              //
              if (ifail < 0)
              {
                Console.WriteLine("");
                Console.WriteLine("  {0}{1,5}", (" ** g13af returned with") + (" ifail = "), ifail);
              }
              else
              {
                if (ifail != 0)
                {
                  Console.WriteLine("  {0}{1,5}", "g13af fails. ifail = ", ifail);
                }
                if ((ifail == 0) || (ifail >= (7)))
                {
                  Console.WriteLine("  {0}{1,3}{2}", ("Convergence was achieved") + (" after"), itc, " cycles");
                  Console.WriteLine("");
                  Console.WriteLine(" {0}", "Final values of the PAR parameters and the constant are as follows");
                  for (i = 1; i <= npar; i++)
                  {
                    Console.Write(" {0:0.0000}", par[i - 1]);
                  }
                  Console.WriteLine(" {0:0.0000}", c);
                  Console.WriteLine(""); ;
                  Console.WriteLine("");
                  Console.WriteLine("  {0}{1,10:f3}{2}{3,4}{4}", "Residual sum of squares is", s, "  with", ndf, " degrees of freedom\r\n");
                  if ((((ifail == 0) || (ifail == 9))) && (itc > 0))
                  {
                    Console.WriteLine("");
                    Console.WriteLine(" {0:0.0000}", ("The corresponding SD array") + (" holds\r\n"));
                    for (i = 1; i <= nppc; i++)
                    {
                      Console.Write(" {0:0.0000}", sd[i - 1]);
                    }
                    Console.WriteLine(""); ;
                    Console.WriteLine("");
                    Console.WriteLine(" {0}", "The correlation matrix is as follows\r\n");
                    for (i = 1; i <= nppc; i++)
                    {
                      for (j = 1; j <= nppc; j++)
                      {
                        Console.Write(" {0,8:f3}", cm[i - 1, j - 1]);
                      }
                      Console.WriteLine(""); ;
                    }
                  }
                  if ((ifail == 0) || (ifail == 9))
                  {
                    Console.WriteLine("");
                    Console.WriteLine("  {0}{1,4}{2}", "The residuals consist of", nres, " values\r\n");
                    for (i = 1; i <= nres; i++)
                    {
                      Console.Write(" {0,8:f4}{1}", res[i - 1], i % 5 == 0 || i == nres ? "\n" : " ");
                    }
                    Console.WriteLine(""); ;
                    Console.WriteLine("");
                    Console.WriteLine("  {0}{1,3}{2}", "The state set consists of", nst, " values\r\n");
                    for (i = 1; i <= nst; i++)
                    {
                      Console.Write(" {0:0.000}  ", st[i - 1]);
                      if (i % 5 == 0)
                      {
                        Console.WriteLine(""); ;
                      }
                    }
                    Console.WriteLine(""); ;
                  }
                }
              }
            }
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13ag Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13AGE
  {
    static string datafile = "ExampleData/g13age.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double c = 0.0;
        int i,   npar,   nst,   nuv;
        int[] mr = new int[7];
        int ifail;
        Console.WriteLine("g13ag Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        nuv = int.Parse(sr.Next());
        double[] anexr = new double[nuv];
        double[] anx = new double[nuv];
        sr.Reset();
        for (i = 1; i <= 7; i++)
        {
          mr[i - 1] = int.Parse(sr.Next());
        }
        npar = mr[0] + mr[2] + mr[3] + mr[5];
        double[] par = new double[npar];
        nst = mr[3] * mr[6] + mr[4] * mr[6] + mr[1] + mr[2] + Math.Max(mr[0],
        mr[5] * mr[6]);
        double[] st = new double[nst];
        if (nuv > 0 && npar > 0 && nst > 0)
        {
          sr.Reset();
          for (i = 1; i <= npar; i++)
          {
            par[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          c = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          sr.Reset();
          for (i = 1; i <= nst; i++)
          {
            st[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          sr.Reset();
          for (i = 1; i <= nuv; i++)
          {
            anx[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //
          G13.g13ag(st, nst, mr, par, c, anx, nuv, anexr, out ifail);
          //
          Console.WriteLine("");
          Console.WriteLine(" {0}", "The updated state set array now holds the values\r\n");
          for (i = 1; i <= nst; i++)
          {
            Console.Write(" {0, 8:f4}{1}", st[i - 1], i%8==0?"\n":"");
          }
          Console.WriteLine(""); ;
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,3}", "The residuals corresponding to the", nuv);
          Console.WriteLine(" {0}", "values used to update the system are\r\n");
          for (i = 1; i <= nuv; i++)
          {
            Console.Write(" {0, 8:f4}{1}", anexr[i - 1], i%8==0?"\n":"");
          }
          Console.WriteLine(""); ;
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13ah Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13AHE
  {
    static string datafile = "ExampleData/g13ahe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double c,   rms; int i,  nfv,  npar,  nst,  nwa;
        int[] mr = new int[7];
        int ifail;
        Console.WriteLine("g13ah Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        nfv = int.Parse(sr.Next());
        double[] fsd = new double[nfv];
        double[] fva = new double[nfv];
        sr.Reset();
        for (i = 1; i <= 7; i++)
        {
          mr[i - 1] = int.Parse(sr.Next());
        }
        npar = mr[0] + mr[2] + mr[3] + mr[5];
        nst = mr[3] * mr[6] + mr[4] * mr[6] + mr[1] + mr[2] + Math.Max(mr[0],
        mr[5] * mr[6]);
        nwa = 4 * npar + 3 * nst;
        double[] par = new double[npar];
        double[] st = new double[nst];
        if (nfv > 0 && npar > 0 && nst > 0)
        {
          sr.Reset();
          for (i = 1; i <= npar; i++)
          {
            par[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          c = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          sr.Reset();
          for (i = 1; i <= nst; i++)
          {
            st[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          sr.Reset();
          rms = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          //
          G13.g13ah(st, nst, mr, par, c, rms, nfv, fva, fsd, out ifail);
          //
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,3}{2}", "The required", nfv, " forecast values are as follows\r\n");
          for (i = 1; i <= nfv; i++)
          {
            Console.Write(" {0, 8:f4}{1}", fva[i - 1], i%8==0?"\n":"");
          }
          Console.WriteLine(""); ;
          Console.WriteLine("");
          Console.WriteLine(" {0}", "The standard deviations corresponding to the forecasts are\r\n");
          for (i = 1; i <= nfv; i++)
          {
            Console.Write(" {0, 8:f4}{1}", fsd[i - 1], i%8==0?"\n":"");
          }
          Console.WriteLine(""); ;
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13aj Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13AJE
  {
    static string datafile = "ExampleData/g13aje.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double c,   rms; int i,  ifv,  ist,  kfc,  nfv,  npar,  nst,  nx;
        int[] isf = new int[4];
        int[] mr = new int[7];
        int ifail;
        Console.WriteLine("g13aj Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        nx = int.Parse(sr.Next());
        double[] x = new double[nx];
        for (i = 1; i <= 7; i++)
        {
          mr[i - 1] = int.Parse(sr.Next());
        }
        nfv = int.Parse(sr.Next());
        npar = mr[0] + mr[2] + mr[3] + mr[5];
        double[] par = new double[npar];
        if (nx > 0 && npar > 0)
        {
          sr.Reset();
          for (i = 1; i <= nx; i++)
          {
            x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          sr.Reset();
          for (i = 1; i <= npar; i++)
          {
            par[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          sr.Reset();
          kfc = int.Parse(sr.Next());
          c = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          ist = mr[3] + mr[6] + mr[1] + mr[4] + mr[2] + Math.Max(mr[0], mr[5] * mr[6]);
          ifv = Math.Max(1, nfv);
          double[] fva = new double[ifv];
          double[] fsd = new double[ifv];
          double[] st = new double[ist];
          //
          G13.g13aj(mr, par, c, kfc, x, nx, out rms, st, out nst, nfv, fva, fsd, isf,
          out ifail);
          //
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,9:f2}", "The residual mean square is ", rms);
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,1}{2}", "The state set consists of ", nst, " values\r\n");
          for (i = 1; i <= nst; i++)
          {
            Console.Write(" {0:0.0000}", st[i - 1]);
            if (i % 5 == 0)
            {
              Console.WriteLine(""); ;
            }
          }
          Console.WriteLine(""); ;
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,2}{2}", "The ", nfv, " forecast values and standard errors are -\r\n");
          for (i = 1; i <= nfv; i++)
          {
            Console.WriteLine(" {0, 10:f2}{1,10:f2}", fva[i - 1], fsd[i - 1]);
          }
          Console.WriteLine(""); ;
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


g13aj Example Program Results

  The residual mean square is    375.91

  The state set consists of 4 values

 64.0000 -30.9807 -20.4495 -2.7212

  The  5 forecast values and standard errors are -

      60.59     19.39
      69.50     34.99
      79.54     54.25
      89.51     67.87
      99.50     79.20


//      g13am Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13AME
  {
    static string datafile = "ExampleData/g13ame.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double ad,   dv; int i,  itype,  ival,  k,  mode,  n,  nf,  p;
        int ifail;
        Console.WriteLine("g13am Example Program Results");
        //
        //      Skip headings in data file
        k = 0;
        sr.Reset();
        //      Read in the initial arguments and check array sizes
        sr.Reset();
        mode = int.Parse(sr.Next());
        itype = int.Parse(sr.Next());
        n = int.Parse(sr.Next());
        nf = int.Parse(sr.Next());
        double[] fse = new double[nf];
        double[] fv = new double[nf];
        double[] param = new double[4];
        double[] res = new double[n];
        double[] y = new double[n];
        double[] yhat = new double[n];
        if (n < 1 || nf < 1 )
        {
          Console.WriteLine("   ** Problem size is too small.");
          goto L80;
        }
        sr.Reset();
        for (i = 1; i <= n; i++)
        {
          y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        //      Read in the itype dependent arguments (skipping headings)
        if (itype == 1)
        {
          sr.Reset();
          param[0] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          p = 0;
          ival = 1;
        }
        else if (itype == 2)
        {
          sr.Reset();
          param[0] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          param[1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          p = 0;
          ival = 2;
        }
        else if (itype == 3)
        {
          sr.Reset();
          param[0] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          param[1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          param[2] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          p = 0;
          ival = 2;
        }
        else
        {
          sr.Reset();
          param[0] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          param[1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          param[2] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          param[3] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          p = int.Parse(sr.Next());
          ival = p + 2;
          if (p < 1)
          {
            Console.WriteLine("Problem size is too small.");
            goto L80;
          }
        }
        //      Read in the mode dependent arguments (skipping headings)
        double[] init = new double[ival];
        double[] r = new double[p+13];
        if (mode == 0)
        {
          //         User supplied initial values
          sr.Reset();
          for (i = 1; i <= ival; i++)
          {
            init[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        else if (mode == 1)
        {
          //         Continuing from a previously saved R
          sr.Reset();
          for (i = 1; i <= p + 13; i++)
          {
            r[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        else if (mode == 2)
        {
          //         Initial values calculated from first K observations
          sr.Reset();
          k = int.Parse(sr.Next());
        }
        //
        //      Call the library method
        G13.g13am(mode, itype, p, param, n, y, k, init, nf, fv, fse, yhat, res, out dv, out ad, r,
        out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g13am failed with ifail = {0,5}", ifail);
          goto L80;
        }
        //      Display the output
        Console.WriteLine("");
        Console.WriteLine(" {0}", "Initial values used:");
        for (i = 1; i <= ival; i++)
        {
          Console.WriteLine("{0,4}  {1,12:f3}  ", i, init[i - 1]);
        }
        Console.WriteLine("");
        Console.WriteLine("{0}{1,12:e4}", "Mean Deviation     = ", dv);
        Console.WriteLine("{0}{1,12:e4}", "Absolute Deviation = ", ad);
        Console.WriteLine("");
        Console.WriteLine(" {0}", "         Observed      1-Step");
        Console.WriteLine(" {0}", " Period   Values      Forecast      Residual");
        Console.WriteLine("");
        for (i = 1; i <= n; i++)
        {
          Console.WriteLine("{0,4}  {1,12:f3}  {2,12:f3}  {3,12:f3}", i, y[i - 1], yhat[i - 1], res[i - 1]);
        }
        Console.WriteLine("");
        Console.WriteLine(" {0}", "         Forecast     Standard");
        Console.WriteLine(" {0}", " Period   Values       Errors");
        Console.WriteLine("");
        for (i = 1; i <= nf; i++)
        {
          Console.WriteLine("{0,4}  {1,12:f3}  {2,12:f3}  ", n + i, fv[i - 1], fse[i - 1]);
        }
        //
        L80: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13as Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13ASE
  {
    static string datafile = "ExampleData/g13ase.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double c,   chi,   s,   siglev; int i,  idf,  ishow,  itc,  kfc,  kpiv,  m,
        n,  ndf,  nit,  npar,  nppc,  nst,  nx;
        int ifail;
        int[] mr = new int[7];
        int[] isf = new int[4];
        Console.WriteLine("g13as Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        nx = int.Parse(sr.Next());
        double[] x = new double[nx];
        double[] st = new double[nx];
        sr.Reset();
        for (i = 1; i <= nx; i++)
        {
          x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        sr.Reset();
        for (i = 1; i <= 7; i++)
        {
          mr[i - 1] = int.Parse(sr.Next());
        }
        kfc = 1;
        c = 0.00e0;
        npar = mr[0] + mr[2] + mr[3] + mr[5];
        nppc = npar + kfc;
        int pp = mr[0] + mr[3]*mr[6];
        int qp = mr[2] + mr[5]*mr[6];
        int ires = 15*qp + 11*nx + 13*nppc + 8*pp + 12 + 2*(qp+nppc)*(qp+nppc);
        double[] par = new double[npar];
        double[] sd = new double[nppc];
        double[] v = new double[ires];
        nppc = npar + kfc;
        for (i = 1; i <= npar; i++)
        {
          par[i - 1] = 0.00e0;
        }
        double[,] cm = new double[nppc, nppc];
        //            * Set kpiv to 1 to obtain monitoring information *
        kpiv = 0;
        nit = 50;
        //
        G13.g13af(mr, par, ref c, kfc, x, nx, out s, out ndf, sd, nppc, cm, st, out nst, kpiv,
        nit, out itc, isf, v, out n, out ifail);
        //
        if (ifail < 0)
        {
          Console.WriteLine("");
          Console.WriteLine("** g13af failed with ifail = {0,5}", ifail);
        }
        else
        {
          if (ifail != 0)
          {
            Console.WriteLine("  {0}{1,5}", ("g13af fails.") + (" ifail ="), ifail);
          }
          //
          if ((ifail == 0) || (ifail == 9))
          {
            m = 10;
            ishow = 1;
            double[] r = new double[m];
            double[,] rcm = new double[m, m];
            //
            G13.g13as(n, v, mr, m, par, ishow, r, rcm, out chi, out idf, out siglev,
            out ifail);
            //
            if (ifail != 0)
            {
              Console.WriteLine("  {0}{1,5}", "g13as fails. ifail =", ifail);
            }
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13au Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13AUE
  {
    static string datafile = "ExampleData/g13aue.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   m,   n,   ngrps;
        int ifail;
        Console.WriteLine("g13au Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        n = int.Parse(sr.Next());
        m = int.Parse(sr.Next());
        double[] mean = new double[50];
        double[] z = new double[n];
        if (n >= m && m >= 1)
        {
          sr.Reset();
          for (i = 1; i <= n; i++)
          {
            z[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          Console.WriteLine("");
          Console.WriteLine(" {0}", "                                 Range-mean plot");
          Console.WriteLine("");
          ngrps = n / m;
          double[] y = new double[ngrps];
          int[] isort = new int[ngrps];
          //
          G13.g13au(n, z, m, ngrps, "RANGE", y, mean, out ifail);
          //
          //         Print Mean and Range
          Console.WriteLine("Group       Mean              Range");
          for (i=0; i<ngrps; i++)
          {
            Console.WriteLine ("{0, 3}   {1, 10:f2}         {2, 10:f2}", i, mean[i], y[i]);
          }
        }
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13ba Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13BAE
  {
    static string datafile = "ExampleData/g13bae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double a1,   a2,   cx,   cy,   rms; int i,  idd,  ii,  ij,  iqxd,  j,  k,  n,  nb,  ni,  nmr,  npar,  nparx,  nst,  nwa,  nx,  ny;
        int[] mr = new int[14];
        int[] mrx = new int[7];
        int ifail;
        Console.WriteLine("g13ba Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        nx = int.Parse(sr.Next());
        double[] x = new double[nx];
        if (nx > 0)
        {
          sr.Reset();
          for (i = 1; i <= nx; i++)
          {
            x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //         Read univariate ARIMA for series
          sr.Reset();
          for (i = 1; i <= 7; i++)
          {
            mrx[i - 1] = int.Parse(sr.Next());
          }
          sr.Reset();
          cx = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          nparx = mrx[0] + mrx[2] + mrx[3] + mrx[5];
          double[] b = new double[320];
          double[] parx = new double[nparx];
          double[] wa = new double[2200];
          int[] isf = new int[4];
          if (nparx > 0)
          {
            sr.Reset();
            for (i = 1; i <= nparx; i++)
            {
              parx[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            //            Read model by which to filter series
            sr.Reset();
            for (i = 1; i <= 7; i++)
            {
              mr[i - 1] = int.Parse(sr.Next());
            }
            npar = mr[0] + mr[2] + mr[3] + mr[5];
            if (npar > 0)
            {
              double[] par = new double[npar+nparx];
              sr.Reset();
              for (i = 1; i <= npar; i++)
              {
                par[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              // Initially backforecast qy values
              // Reverse series in situ
              n = nx / 2;
              ni = (int)nx;
              for (i = 1; i <= n; i++)
              {
                a1 = x[i - 1];
                a2 = x[ni - 1];
                x[i - 1] = a2;
                x[ni - 1] = a1;
                ni = ni - 1;
              }
              idd = mrx[1] + mrx[4];
              //               (2) Possible sign reversal for ARIMA constant
              if ((idd % 2) != 0)
              {
                cx = -cx;
              }
              //               (3) Calculate number of backforecasts required
              iqxd = mrx[2] + mrx[5] * mrx[6];
              ny = nx + iqxd;
              double[] y = new double[ny];
              if (iqxd != 0)
              {
                //                  (4) Set up parameter list for call to forecast
                //                  method g13aj
                //
                int ifv;
                int  ist = mrx[3] + mrx[6] + mrx[1] + mrx[4] + mrx[2] +
                Math.Max(mrx[0],mrx[5]*mrx[6]);
                double[] st = new double[ist];
                ifv = Math.Max(1, iqxd);
                double [] fva = new double[ifv];
                double [] fsd = new double[ifv];
                G13.g13aj(mrx, parx, cx, 1, x, nx, out rms, st, out nst, iqxd, fva, fsd, isf,
                out ifail);
                //
                j = (int)iqxd;
                for (i = 1; i <= iqxd; i++)
                {
                  y[i - 1] = fva[j - 1];
                  j = j - 1;
                }
                //                  Move series into Y
                j = iqxd + 1;
                k = (int)nx;
                for (i = 1; i <= nx; i++)
                {
                  if (j > ny)
                  {
                    goto L160;
                  }
                  y[j - 1] = x[k - 1];
                  j = j + 1;
                  k = k - 1;
                }
              }
              //               Move ARIMA for series into mr
              for (i = 1; i <= 7; i++)
              {
                mr[7 + i - 1] = mrx[i - 1];
              }
              //               Move parameters of ARIMA for y into par
              for (i = 1; i <= nparx; i++)
              {
                par[npar + i - 1] = parx[i - 1];
              }
              npar = npar + nparx;
              //               Move constant and reset sign reversal
              cy = (double)cx;
              if ((idd % 2) != 0)
              {
                cy = -cy;
              }
              //               Set parameters for call to filter method g13ba
              nmr = 14;
              nwa = mr[2] + mr[5] * mr[6] + mr[7] + mr[8] + (mr[10] + mr[11]) * mr[13];
              nwa = nwa * (nwa + 2);
              nb = ny+  Math.Max(mr[2] + mr[5] * mr[6],
              mr[0] + mr[1] + (mr[3] + mr[4]) * mr[6]);
              if (nb > 1)
              {
                //                  Filter series by call to g13ba
                G13.g13ba(y, ny, mr, nmr, par, cy, b, out ifail);
                //
                Console.WriteLine("");
                Console.WriteLine(" {0}", "                 Original        Filtered");
                Console.WriteLine(" {0}", "Backforecasts    y-series         series");
                if (iqxd != 0)
                {
                  ij = -iqxd;
                  for (i = 1; i <= iqxd; i++)
                  {
                    Console.WriteLine("  {0,8}{1,17:f4}{2,15:f4}", ij, y[i - 1], b[i - 1]);
                    ij = ij + 1;
                  }
                }
                Console.WriteLine("");
                Console.WriteLine(" {0}", "\t\tFiltered\t\tFiltered\t\tFiltered\t\tFiltered");
                Console.WriteLine(" {0}", "\t\tseries\t\t\tseries\t\t\tseries\t\t\tseries");
                Console.WriteLine("");
                for (i = iqxd + 1; i <= ny; i += 4)
                {
                  for (ii = i; ii <= Math.Min(ny, i + 3); ii++)
                  {
                    Console.Write("       {0, 5}{1, 9:f4}", ii - iqxd, b[ii - 1]);
                  }
                  Console.WriteLine(""); ;
                }
              }
            }
          }
        }
        L160: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13bb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13BBE
  {
    static string datafile = "ExampleData/g13bbe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double a1,   a2,   cx,   cy,   rms; int i,  idd,  ii,  ij,  iqxd,  iwa,  j,  k,  n,  nb,  ni,  nmr,  npar,  nparx,  nst,  nx,  ny;
        int[] isf = new int[4];
        int[] mrx = new int[7];
        int ifail;
        Console.WriteLine("g13bb Example Program Results");
        //      Skip heading in data file
        iqxd = 0;
        idd = 0;
        sr.Reset();
        sr.Reset();
        nx = int.Parse(sr.Next());
        double[] x = new double[nx];
        Console.WriteLine("");
        if (nx > 0)
        {
          sr.Reset();
          for (i = 1; i <= nx; i++)
          {
            x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //         Read univariate ARIMA for series
          sr.Reset();
          for (i = 1; i <= 7; i++)
          {
            mrx[i - 1] = int.Parse(sr.Next());
          }
          sr.Reset();
          cx = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          nparx = mrx[0] + mrx[2] + mrx[3] + mrx[5];
          iqxd = mrx[2] + mrx[5] * mrx[6];
          int ifv = Math.Max(1, iqxd); ny = nx + iqxd;
          int ist = mrx[4-1] + mrx[7-1] + mrx[2-1] + mrx[5-1] + mrx[3-1] +
          Math.Max(mrx[1-1],mrx[6-1]*mrx[7-1]);
          double[] st = new double[ist];
          double [] y = new double[ny];
          double [] fva = new double[ifv];
          double [] fsd = new double[ifv];
          double[] parx = new double[nparx];
          if (iqxd != 0)
          {
            nmr = 10;
          }
          else
          {
            nmr = 3;
          }
          int[] mr = new int[nmr];
          if (nparx > 0)
          {
            sr.Reset();
            for (i = 1; i <= nparx; i++)
            {
              parx[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            //            Read model by which to filter series
            sr.Reset();
            for (i = 1; i <= 3; i++)
            {
              mr[i - 1] = int.Parse(sr.Next());
            }
            npar = mr[1] + mr[2] + 1;
            double [] par = new double[npar+nparx];
            if (npar > 0)
            {
              sr.Reset();
              for (i = 1; i <= npar; i++)
              {
                par[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
              //  Initially backforecast qy values
              //  Reverse series in situ
              n = nx / 2;
              ni = (int)nx;
              for (i = 1; i <= n; i++)
              {
                a1 = x[i - 1];
                a2 = x[ni - 1];
                x[i - 1] = a2;
                x[ni - 1] = a1;
                ni = ni - 1;
              }
              idd = mrx[1] + mrx[4];
              // Possible sign reversal for ARIMA constant
              if ((idd % 2) != 0)
              {
                cx = -cx;
              }
              //               (3) Calculate number of backforecasts required
              if (iqxd != 0)
              {
                G13.g13aj(mrx, parx, cx, 0, x, nx, out rms, st, out nst, iqxd, fva, fsd, isf,
                out ifail);
              }
              //               Move backforecasts to start of Y array
              j = (int)iqxd;
              for (i = 1; i <= iqxd; i++)
              {
                y[i - 1] = fva[j - 1];
                j = j - 1;
              }
              //               Move series into Y
              j = iqxd + 1;
              k = (int)nx;
              for (i = 1; i <= nx; i++)
              {
                if (j > ny)
                {
                  goto L160;
                }
                y[j - 1] = x[k - 1];
                j = j + 1;
                k = k - 1;
              }
            }
            // Move ARIMA for series into mr
            for (i = 1; i <= 7; i++)
            {
              mr[3 + i - 1] = mrx[i - 1];
            }
            // Move parameters of ARIMA for y into par
            for (i = 1; i <= nparx; i++)
            {
              par[npar + i - 1] = parx[i - 1];
            }
            npar = npar + nparx;
            //            Move constant and reset sign reversal
            cy = (double)cx;
            if ((idd % 2) != 0)
            {
              cy = -cy;
            }
            //            Set parameters for call to filter method g13bb
            iwa = mr[2] + mr[3] + mr[4] + (mr[6] + mr[7]) * mr[9];
            iwa = npar + iwa * (iwa + 2);
            nb = ny + Math.Max(mr[0] + mr[1], mr[2]);
            double[] b = new double[nb];
            if (nb > 1)
            {
              //
              //               Filter series by call to g13bb
              G13.g13bb(y, ny, mr, nmr, par, cy, b, out ifail);
              //
              Console.WriteLine(" {0}", "                  Original        Filtered");
              Console.WriteLine(" {0}", " Backforecasts    y-series         series");
              if (iqxd != 0)
              {
                ij = -iqxd;
                for (i = 1; i <= iqxd; i++)
                {
                  Console.WriteLine("  {0,8}{1,17:f1}{2,16:f1}", ij, y[i - 1], b[i - 1]);
                  ij = ij + 1;
                }
                Console.WriteLine("");
                Console.WriteLine(" {0}", "        Filtered        Filtered        Filtered        Filtered");
                Console.WriteLine(" {0}", "         series          series          series          series");
                Console.WriteLine("");
                for (i = iqxd + 1; i <= ny; i += 4)
                {
                  for (ii = i; ii <= Math.Min(ny, i + 3); ii++)
                  {
                    Console.Write(" {0}{1, 10:f1}{2}", ii - iqxd, b[ii - 1], i%4==0?"\n":"");
                  }
                  Console.WriteLine(""); ;
                }
              }
            }
          }
        }
        L160: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13bc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13BCE
  {
    static string datafile = "ExampleData/g13bce.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double r0xy,   r0yx,   statxy,   statyx,   sxy,   syx; int i,  nl,  nxy;
        int ifail;
        Console.WriteLine("g13bc Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        //      Read series length and number of lags
        sr.Reset();
        nxy = int.Parse(sr.Next());
        nl = int.Parse(sr.Next());
        double[] rxy = new double[nl];
        double[] ryx = new double[nl];
        double[] x = new double[nxy];
        double[] y = new double[nxy];
        if (nxy > 2 && nl > 0)
        {
          //         Read series
          sr.Reset();
          for (i = 1; i <= nxy; i++)
          {
            x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          sr.Reset();
          for (i = 1; i <= nxy; i++)
          {
            y[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //         Call method to calculate cross correlations between x and y
          //
          G13.g13bc(x, y, nxy, nl, out sxy, out r0xy, rxy, out statxy, out ifail);
          //
          //
          //         Call method to calculate cross correlations between y and x
          G13.g13bc(y, x, nxy, nl, out syx, out r0yx, ryx, out statyx, out ifail);
          //
          Console.WriteLine("");
          Console.WriteLine(" {0}", "                           Between        Between");
          Console.WriteLine(" {0}", "                           x and y        y and x");
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,10:f4}{2,15:f4}", "Standard deviation ratio", sxy, syx);
          Console.WriteLine("");
          Console.WriteLine(" {0}", " Cross correlation at lag\r\n");
          Console.WriteLine("{0}\t{1,8:f4}\t{2,8:f4}", "\t\t\t\t 0", r0xy, r0yx);
          for (i = 1; i <= nl; i++)
          {
            Console.Write("\t\t\t\t{0,2}\t{1,8:f4}\t{2,8:f4}", i, rxy[i - 1], ryx[i - 1]);
            Console.WriteLine(""); ;
          }
          Console.WriteLine(""); ;
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,10:f4}{2,15:f4}", "Test statistic          ", statxy, statyx);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13bd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13BDE
  {
    static string datafile = "ExampleData/g13bde.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double r0,   s; int i,  iwa,  nl,  nwds;
        int[] isf = new int[2];
        int[] nna = new int[3];
        int ifail;
        Console.WriteLine("g13bd Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        nl = int.Parse(sr.Next());
        sr.Reset();
        r0 = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        double[] r = new double[nl];
        if (nl > 0)
        {
          sr.Reset();
          for (i = 1; i <= nl; i++)
          {
            r[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          sr.Reset();
          for (i = 1; i <= 3; i++)
          {
            nna[i - 1] = int.Parse(sr.Next());
          }
          sr.Reset();
          s = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          nwds = nna[1] + nna[2] + 1;
          iwa = nna[2] * (nna[2] + 1);
          double[] wds = new double[nwds];
          if (nwds > 0 )
          {
            //
            G13.g13bd(r0, r, nl, nna, s, nwds, wds, isf, out ifail);
            //
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,4}{2,4}", "Success/failure indicator", isf[0], isf[1]);
            Console.WriteLine("");
            Console.Write(" {0}", "Transfer function model B, Q, P =");
            for (i = 1; i <= 3; i++)
            {
              Console.Write(" {0}", nna[i - 1]);
            }
            Console.WriteLine(""); ;
            Console.WriteLine("");
            Console.WriteLine(" {0}", "Parameter initial estimates\r\n");
            for (i = 1; i <= nwds; i++)
            {
              Console.Write(" {0:0.0000}", wds[i - 1]);
            }
            Console.WriteLine(""); ;
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


g13bd Example Program Results

  Success/failure indicator   1   1

 Transfer function model B, Q, P = 3 2 1

 Parameter initial estimates

 -0.5575 0.3166 0.4626 0.6169


//      g13be Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13BEE
  {
    static string datafile = "ExampleData/g13bee.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double d,   s; int dp,  i,   inc,  itc,   j,   kef,   kfc,   kpriv,   kzef,   kzsp,
        mx,  ncd,  nce,  ncf,  ndf,   ndv,   nit,   npara,   ncg,  nser,   nsttf,
        nxxy, qp, qx, smx ;
        double[] zsp = new double[4];
        int[] mr = new int[7];
        int ifail;
        Console.WriteLine("g13be Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        kzef = int.Parse(sr.Next());
        kfc = int.Parse(sr.Next());
        nxxy = int.Parse(sr.Next());
        nser = int.Parse(sr.Next());
        kef = int.Parse(sr.Next());
        nit = int.Parse(sr.Next());
        kzsp = int.Parse(sr.Next());
        int[,] mt = new int[4, nser];
        if (nxxy > 0 && nser > 0)
        {
          if (kzsp != 0)
          {
            sr.Reset();
            for (int zsplen = 0; zsplen < zsp.Length; zsplen++)
            {
              zsp[zsplen] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          sr.Reset();
          for (i = 1; i <= 7; i++)
          {
            mr[i - 1] = int.Parse(sr.Next());
          }
          for (i = 1; i <= 4; i++)
          {
            sr.Reset();
            for (j = 1; j <= nser; j++)
            {
              mt[i - 1, j - 1] = int.Parse(sr.Next());
            }
          }
          npara = 0;
          ncg = 0;
          qx = 0;
          smx = 0;
          ncf = nser;
          inc = 1;
          for ( i = 1; i<= nser-1; i++)
          {
            npara = npara + mt[2-1,i-1] + mt[3-1,i-1];
            if (mt[4-1,i-1]>1)
            {
              ncg = ncg +  mt[0,i-1]+ mt[1,i-1]+ mt[2,i-1];
              if (mt[4-1,i-1]==3)
              {
                mx = Math.Max(mt[1-1,i-1]+mt[2-1,i-1],mt[3-1,i-1]);
                qx = Math.Max(qx,mx);
                smx = smx + mx;
              }
            }
            else if (mt[4-1,i-1]==1 && kef==3)
            {
              if (mt[3-1,i-1]>0)
              {
                ncf = ncf + 1;
              }
              inc = inc + 1;
            }
          }
          npara = npara + mr[0] + mr[2] + mr[3] + mr[5] + nser;
          //      Calculate size of arrays
          int isttf = mr[4-1]*mr[7-1] + mr[2-1] + mr[5-1]*mr[7-1] + mr[3-1] +
          Math.Max(mr[1-1],mr[6-1]*mr[7-1]) + ncg;
          qp = mr[3-1] + mr[6-1]*mr[7-1];
          dp = mr[2-1] + mr[5-1]*mr[7-1];
          if (mr[3-1]>0 && kef>1)
          {
            inc = inc + 1;
          }
          if (kfc>0 && kef==3)
          {
            inc = inc + 1;
          }
          qx = qp;
          ncd = npara + kfc + smx;
          if (mr[1-1]>0)
          {
            ncf = ncf + inc;
          }
          if (mr[3-1]>0)
          {
            ncf = ncf + inc;
          }
          if (mr[4-1]>0)
          {
            ncf = ncf + inc;
          }
          if (mr[6-1]>0)
          {
            ncf = ncf + inc;
          }
          if (qx>0)
          {
            ncf = ncf + 1;
          }
          if (kfc>0)
          {
            ncf = ncf + 1;
          }
          ncd = ncd + qx;
          nce = nxxy + dp + 6*qx;
          double[,] cm = new double[npara, npara];
          double[] para = new double[npara];
          double[] res = new double[nxxy];
          double[] sd = new double[npara];
          double[] sttf = new double[isttf];
          double[,] xxy = new double[nxxy, nser];
          if (npara > 0)
          {
            sr.Reset();
            for (i = 1; i <= npara; i++)
            {
              para[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            for (i = 1; i <= nxxy; i++)
            {
              sr.Reset();
              for (j = 1; j <= nser; j++)
              {
                xxy[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
            }
            // Set kpriv to 1 to obtain monitoring information *
            kpriv = 0;
            //
            G13.g13be(mr, nser, mt, para, npara, kfc, nxxy, xxy, kef, nit, kzsp, zsp, out itc, sd, cm,
            out s, out d, out ndf, kzef, res, sttf, out nsttf, kpriv, out ifail);
            //
            if (ifail != 0)
            {
              Console.WriteLine("");
              Console.WriteLine("  {0}{1,4}", "g13be fails. ifail =", ifail);
            }
            if ((((ifail == 0) || (ifail == 8)) || (ifail == 9)) || (ifail == 11))
            {
              Console.WriteLine("");
              Console.WriteLine("  {0}{1,4}", "The number of iterations carried out is", itc);
              Console.WriteLine("");
              Console.WriteLine(" {0}", "Final values of the parameters and their standard deviations");
              Console.WriteLine("");
              Console.WriteLine(" {0}", "   I            PARA(I)                 SD");
              Console.WriteLine("");
              for (i = 1; i <= npara; i++)
              {
                Console.WriteLine("  {0,4}{1,20:f6}{2,20:f6}", i, para[i - 1], sd[i - 1]);
              }
              Console.WriteLine("");
              Console.WriteLine(" {0}", "The correlation matrix is");
              Console.WriteLine("");
              for (i = 1; i <= npara; i++)
              {
                for (j = 1; j <= npara; j++)
                {
                  Console.Write(" {0, 10:f4}", cm[i - 1, j - 1]);
                }
                Console.WriteLine(""); ;
              }
              Console.WriteLine(""); ;
              Console.WriteLine("");
              Console.WriteLine(" {0}", "The residuals and the z and n values are");
              Console.WriteLine("");
              Console.WriteLine(" {0}", "   I         RES(I)          z(t)           n(t)");
              Console.WriteLine("");
              ndv = nxxy - mr[1] - mr[4] * mr[6];
              for (i = 1; i <= nxxy; i++)
              {
                if (i <= ndv)
                {
                  Console.Write(" {0,4}", i);
                  Console.Write(" {0, 15:f3}", res[i - 1]);
                  for (j = 1; j <= nser; j++)
                  {
                    Console.Write(" {0, 15:f3}", xxy[i - 1, j - 1]);
                  }
                  Console.WriteLine(""); ;
                }
                else
                {
                  Console.WriteLine(" {0, 4}", i);
                  for (j = 1; j <= nser; j++)
                  {
                    Console.Write(" {0, 15:f3}", xxy[i - 1, j - 1]);
                  }
                  Console.WriteLine(""); ;
                }
              }
              if ((mr[1] != 0) || (mr[4] != 0))
              {
                Console.WriteLine("");
                Console.WriteLine(" {0}", "** Note that the residuals relate to differenced values **");
              }
              Console.WriteLine("");
              Console.WriteLine("  {0}{1,4}{2}", "The state set consists of", nsttf, " values");
              Console.WriteLine("");
              for (i = 1; i <= nsttf; i++)
              {
                Console.Write(" {0, 10:f4}", sttf[i - 1] );
              }
              Console.WriteLine(""); ;
              Console.WriteLine("");
              Console.WriteLine("  {0}{1,4}", "The number of degrees of freedom is", ndf);
            }
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13bg Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13BGE
  {
    static string datafile = "ExampleData/g13bge.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   j,   kzef,   nnv,   npara,   nser,   nsttf; int ifail;
        int[] mr = new int[7];
        Console.WriteLine("g13bg Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        nsttf = int.Parse(sr.Next());
        nser = int.Parse(sr.Next());
        nnv = int.Parse(sr.Next());
        kzef = int.Parse(sr.Next());
        double[] res = new double[nnv];
        double[] sttf = new double[nsttf];
        double[,] xxyn = new double[nnv, nser];
        int[,] mt = new int[4, nser];
        if (nsttf > 0 && nser > 0 && nnv > 0)
        {
          sr.Reset();
          for (i = 1; i <= 7; i++)
          {
            mr[i - 1] = int.Parse(sr.Next());
          }
          for (i = 1; i <= 4; i++)
          {
            sr.Reset();
            for (j = 1; j <= nser; j++)
            {
              mt[i - 1, j - 1] = int.Parse(sr.Next());
            }
          }
          npara = 0;
          for (i = 1; i <= nser; i++)
          {
            npara = npara + mt[1, i - 1] + mt[2, i - 1];
          }
          npara = npara + mr[0] + mr[2] + mr[3] + mr[5] + nser;
          double[] para = new double[10];
          sr.Reset();
          for (i = 1; i <= nsttf; i++)
          {
            sttf[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          if (npara > 0)
          {
            sr.Reset();
            for (i = 1; i <= npara; i++)
            {
              para[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            for (i = 1; i <= nnv; i++)
            {
              sr.Reset();
              for (j = 1; j <= nser; j++)
              {
                xxyn[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
            }
            //
            G13.g13bg(sttf, nsttf, mr, nser, mt, para, npara, nnv, xxyn, kzef, res, out ifail);
            //
            Console.WriteLine("");
            Console.WriteLine(" {0}", "The updated state set\r\n");
            for (i = 1; i <= nsttf; i++)
            {
              Console.Write("{0, 8:f4}{1}", sttf[i - 1], i % 6 == 0 ? "\n" : " ");
            }
            Console.WriteLine(""); ;
            Console.WriteLine("");
            Console.WriteLine(" {0}", "The residuals (after differencing)");
            for (i = 1; i <= nnv; i++)
            {
              Console.WriteLine("  {0,4}{1,10:f4}", i, res[i - 1]);
            }
            Console.WriteLine("");
            Console.WriteLine(" {0}", "The values of z(t) and n(t)\r\n");
            for (i = 1; i <= nnv; i++)
            {
              Console.Write(" {0, 4}", i);
              for (j = 1; j <= nser; j++)
              {
                Console.Write(" {0,10:f4}", xxyn[i - 1, j - 1]);
              }
              Console.WriteLine(""); ;
            }
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13bj Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13BJE
  {
    static string datafile = "ExampleData/g13bje.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   isttf,  j,   kfc,   kzef,   ldparx,  n,   ncf=0,  nev,   nfv,   npara,   nparx,  nser,   nsttf; int[] mr = new int[7];
        int ifail;
        Console.WriteLine("g13bj Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        kfc = int.Parse(sr.Next());
        nev = int.Parse(sr.Next());
        nfv = int.Parse(sr.Next());
        nser = int.Parse(sr.Next());
        kzef = int.Parse(sr.Next());
        double[] fsd = new double[nfv];
        double[] fva = new double[nfv];
        double[] rmsxy = new double[nser];
        int[,] mrx = new int[7, nser];
        int[,] mt = new int[4, nser];
        if (nser > 0 && nfv > 0 && nev > 0)
        {
          sr.Reset();
          for (i = 1; i <= 7; i++)
          {
            mr[i - 1] = int.Parse(sr.Next());
          }
          for (i = 1; i <= 4; i++)
          {
            sr.Reset();
            for (j = 1; j <= nser; j++)
            {
              mt[i - 1, j - 1] = int.Parse(sr.Next());
            }
          }
          npara = 0;
          for (i = 1; i <= nser-1; i++)
          {
            npara = npara + mt[1, i - 1] + mt[2, i - 1];
          }
          npara = npara + mr[0] + mr[2] + mr[3] + mr[5] + nser;
          double [] para = new double[npara];
          for(i = 1; i<=nser-1; i++)
          {
            if (mt[4-1,i-1]>1)
            {
              ncf = mt[0, i-1] + mt[1, i-1] + mt[2,i-1];
            }
          }
          isttf = mr[1-1]*mr[7-1] + mr[2-1] + mr[5-1]*mr[7-1] + mr[3-1] +
          Math.Max(mr[1-1],mr[6-1]*mr[7-1]) + ncf;
          double [] sttf = new double [isttf];
          if (npara > 0)
          {
            sr.Reset();
            for (i = 1; i <= npara; i++)
            {
              para[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            n = nev + nfv;
            double [, ] xxy = new double[n,  nser]; for (i = 1; i <= n; i++)
            {
              sr.Reset();
              for (j = 1; j <= nser; j++)
              {
                xxy[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
            }
            sr.Reset();
            for (i = 1; i <= nser; i++)
            {
              rmsxy[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            for (i = 1; i <= 7; i++)
            {
              sr.Reset();
              for (j = 1; j <= nser; j++)
              {
                mrx[i - 1, j - 1] = int.Parse(sr.Next());
              }
            }
            ldparx = 0;
            for (i=1; i<=nser-1; i++)
            {
              if (rmsxy[i-1] != 0.0E0)
              {
                nparx = mrx[1-1,i-1] + mrx[3-1,i-1] + mrx[4-1,i-1] + mrx[6-1,i-1];
                ldparx = Math.Max(ldparx,nparx);
              }
            }
            double[,] parx = new double[ldparx, nser];
            for (i = 1; i <= 5; i++)
            {
              sr.Reset();
              for (j = 1; j <= nser; j++)
              {
                parx[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
            }
            //
            G13.g13bj(mr, nser, mt, para, npara, kfc, nev, nfv, xxy, kzef, rmsxy, mrx, parx, fva, fsd,
            sttf, out nsttf, out ifail);
            //
            Console.WriteLine("");
            if (ifail < 0)
            {
              Console.WriteLine("");
              Console.WriteLine("** g13bj failed with ifail = {0,5}", ifail);
            }
            else
            {
              if (ifail != 0)
              {
                Console.WriteLine("  {0}{1,3}", ("g13bj fails.") + (" ifail ="), ifail);
              }
              if ((((ifail == 0) || (ifail == 8)) || (ifail == 9)) || (ifail == 11))
              {
                Console.WriteLine("  {0}{1,3}{2}", "After processing", nev, " sets of observations");
                Console.WriteLine("  {0,3}{1}", nsttf, " values of the state set are derived");
                Console.WriteLine("");
                for (i = 1; i <= nsttf; i++)
                {
                  Console.Write(" {0, 8:f4}", sttf[i - 1], i % 7 == 0 || i == nsttf ? "\n" : " ");
                }
                Console.WriteLine(""); ;
                Console.WriteLine("");
                Console.WriteLine(" {0}", ("The residual mean square for the") + (" output"));
                Console.WriteLine("  {0}{1,10:f4}", "series is also derived and its value is", rmsxy[nser - 1]);
                Console.WriteLine("");
                Console.WriteLine(" {0}", "The forecast values and their standard errors are");
                Console.WriteLine("");
                Console.WriteLine(" {0}", "   I       FVA       FSD");
                Console.WriteLine("");
                for (i = 1; i <= nfv; i++)
                {
                  Console.WriteLine("  {0,4}{1,10:f3}{2,10:f4}", i, fva[i - 1], fsd[i - 1]);
                }
                Console.WriteLine("");
                Console.WriteLine(" {0}", "The values of z(t) and n(t) are");
                Console.WriteLine("");
                Console.WriteLine(" {0}", "  I          z1            z2            z3            z4           z5             n");
                Console.WriteLine("");
                for (i = 1; i <= n; i++)
                {
                  Console.Write(" {0,3}", i);
                  for (j = 1; j <= nser; j++)
                  {
                    Console.Write("    {0,10:f3}", xxy[i - 1, j - 1]);
                  }
                  Console.WriteLine(""); ;
                }
              }
            }
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13ca Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13CAE
  {
    static string datafile = "ExampleData/g13cae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double px = 0.0;
        int i,   ic,   iw,   kc,   l,   lg,   mtx,   mw,   nc,   ng,   nx,  nxg; int ifail;
        Console.WriteLine("g13ca Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        nx = int.Parse(sr.Next());
        nc = int.Parse(sr.Next());
        mtx = 1;
        px = 0.10e0;
        iw = 4;
        mw = 100;
        ic = 0;
        kc = 360;
        l = 200;
        lg = 0;
        double[] c = new double[nc];
        double[] stats = new double[4];
        if (ic==0)
        {
          nxg = Math.Max(kc,l);
        }
        else
        {
          nxg = l;
        }
        int lxg = Math.Max(nxg, nx); double[] xg = new double[lxg];
        if (nx > 0 && nx <= nxg && nc > 0)
        {
          sr.Reset();
          for (i = 1; i <= nx; i++)
          {
            xg[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //
          G13.g13ca(nx, mtx, px, iw, mw, ic, nc, c, kc, l, lg, xg, out ng, stats, out ifail);
          //
          Console.WriteLine("");
          if (ifail < 0)
          {
            Console.WriteLine("");
            Console.WriteLine("** g13ca failed with ifail = {0,5}", ifail);
          }
          else
          {
            if (ifail != 0)
            {
              Console.WriteLine("  {0}{1,5}", "g13ca fails. ifail =", ifail);
              Console.WriteLine("");
            }
            if ((ifail == 0) || (ifail >= (4)))
            {
              Console.WriteLine(" {0}", "Covariances\r\n");
              for (i = 1; i <= nc; i++)
              {
                Console.Write("  {0,11:f4}{1}", c[i - 1], i % 6 == 0 || i == nc ? "\n" : " ");
              }
              Console.WriteLine(""); ;
              Console.WriteLine("");
              Console.WriteLine("  {0}{1,4:f1}{2}{3,7:f4}", "Degrees of freedom =", stats[0], "      Bandwidth =", stats[3]);
              Console.WriteLine("");
              Console.WriteLine("  {0}{1,7:f4}{2}{3,7:f4}", "95 percent confidence limits -     Lower =", stats[1], "  Upper =", stats[2]);
              Console.WriteLine("");
              Console.WriteLine(" {0}", "      Spectrum       Spectrum       Spectrum       Spectrum");
              Console.WriteLine(" {0}", "      estimate       estimate       estimate       estimate");
              Console.WriteLine("");
              for (i = 1; i <= ng; i++)
              {
                Console.Write(" {0,3}{1,10:f4}{2}", i, xg[i - 1], i % 4 == 0 || i == ng ? "\n" : " ");
              }
              Console.WriteLine(""); ;
            }
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13cb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13CBE
  {
    static string datafile = "ExampleData/g13cbe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double pw,   px; int i,  kc,  l,  lg,  mtx,  mw,  ng,  nx;
        double[] stats = new double[4];
        int ifail;
        Console.WriteLine("g13cb Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        nx = int.Parse(sr.Next());
        mtx = 1;
        px = 0.20e0;
        mw = (int)nx;
        pw = 0.50e0;
        kc = 400;
        l = 100;
        lg = 1;
        int lxg = Math.Max(kc, nx); double[] xg = new double[lxg];
        double[] xh = new double[lxg];
        if (nx > 0)
        {
          sr.Reset();
          for (i = 1; i <= nx; i++)
          {
            xh[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          L20: ;
          try
          {
            sr.Reset();
            mw = int.Parse(sr.Next());
          }
          catch
          {
            goto L60;
          }
          if ((mw > 0) && (mw <= nx))
          {
            for (i = 1; i <= nx; i++)
            {
              xg[i - 1] = xh[i - 1];
            }
            //
            G13.g13cb(nx, mtx, px, mw, pw, l, kc, lg, xg, out ng, stats, out ifail);
            //
            if (mw == nx)
            {
              Console.WriteLine(" {0}", "No smoothing");
            }
            else
            {
              Console.WriteLine("  {0}{1,5}", "Frequency width of smoothing window = 1/", mw);
            }
            Console.WriteLine("");
            if (ifail < 0)
            {
              Console.WriteLine("");
              Console.WriteLine("** g13cb failed with ifail = {0,5}", ifail);
            }
            else
            {
              if (ifail != 0)
              {
                Console.WriteLine("  {0}{1,5}", "g13cb fails. ifail =", ifail);
                Console.WriteLine("");
              }
              if ((ifail == 0) || (ifail >= (4)))
              {
                Console.WriteLine("  {0}{1,4:f1}{2}{3,7:f4}", "Degrees of freedom =", stats[0], "      Bandwidth =", stats[3]);
                Console.WriteLine("");
                Console.WriteLine("  {0}{1,7:f4}{2}{3,7:f4}", "95 percent confidence limits -     Lower =", stats[1], "  Upper =", stats[2]);
                Console.WriteLine("");
                Console.WriteLine(" {0}", "          Spectrum            Spectrum           Spectrum          Spectrum");
                Console.WriteLine(" {0}", "          estimate            estimate           estimate          estimate");
                Console.WriteLine("");
                for (i = 1; i <= ng; i++)
                {
                  Console.Write("  {0,3}   {1,10:f4}{2}", i, xg[i - 1], i % 4 == 0 || i == ng ? "\n" : " ");
                }
                Console.WriteLine(""); ;
              }
            }
            goto L20;
          }
        }
        L60: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13cc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13CCE
  {
    static string datafile = "ExampleData/g13cce.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double pxy = 0.0;
        int i,   ic,   ii,   ish,   iw,   kc,   l,   mtxy,   mw,   nc,   ng,   nxy; int ifail;
        Console.WriteLine("g13cc Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        nxy = int.Parse(sr.Next());
        nc = int.Parse(sr.Next());
        ic = int.Parse(sr.Next());
        mtxy = 1;
        pxy = 0.10e0;
        //         Parzen window and zero covariance at lag 35
        iw = 4;
        mw = 35;
        //         Alignment shift of 3, 50 covariances to be calculated
        ish = 3;
        kc = 350;
        l = 80;
        int nxyg;
        if (ic==0)
        {
          nxyg = Math.Max(kc,l);
        }
        else
        {
          nxyg = l;
        }
        int lxg = Math.Max(nxyg,  nxy); int lyg = Math.Max(nxyg, nxy);
        double[] cxy = new double[nc];
        double[] cyx = new double[nc];
        double[] xg = new double[lxg];
        double[] yg = new double[lyg];
        if (nxy > 0 && nxy <= nxyg && nc > 0)
        {
          if (ic == 0)
          {
            sr.Reset();
            for (i = 1; i <= nxy; i++)
            {
              xg[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            sr.Reset();
            for (i = 1; i <= nxy; i++)
            {
              yg[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          else
          {
            sr.Reset();
            for (i = 1; i <= nc; i++)
            {
              cxy[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            sr.Reset();
            for (i = 1; i <= nc; i++)
            {
              cyx[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
          //         Set parameters for call to g13cc
          //         Mean correction and 10 percent taper
          //
          G13.g13cc(nxy, mtxy, pxy, iw, mw, ish, ic, nc, cxy, cyx, kc, l, xg, yg, out ng, out ifail);
          //
          Console.WriteLine("");
          Console.WriteLine(" {0}", "                  Returned cross covariances");
          Console.WriteLine("");
          Console.WriteLine(" {0}", "Lag     XY         YX   Lag     XY       YX     Lag     XY         YX");
          Console.WriteLine("");
          for (i = 1; i <= nc; i += 3)
          {
            for (ii = i; ii <= Math.Min(i + 2, nc); ii++)
            {
              Console.Write("{0,3}  {1,8:f4}   {2,8:f4}", ii - 1, cxy[ii - 1], cyx[ii - 1]);
            }
            Console.WriteLine(""); ;
          }
          Console.WriteLine("");
          Console.WriteLine(" {0}", "                      Returned sample spectrum");
          Console.WriteLine("");
          Console.WriteLine(" {0}", "       Real   Imaginary       Real   Imaginary         Real     Imaginary");
          Console.WriteLine(" {0}", "Lag    part     part   Lag    part     part     Lag    part        part");
          Console.WriteLine("");
          for (i = 1; i <= ng; i += 3)
          {
            for (ii = i; ii <= Math.Min(i + 2, ng); ii++)
            {
              Console.Write("{0,3}  {1,8:f4}   {2,8:f4}", ii - 1, xg[ii - 1], yg[ii - 1]);
            }
            Console.WriteLine(""); ;
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13cd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13CDE
  {
    static string datafile = "ExampleData/g13cde.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double pw,   pxy; int i,  ish,  j,  kc, m, mtxy,  mw,  ng,  nxy;
        int ifail;
        Console.WriteLine("g13cd Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        nxy = int.Parse(sr.Next());
        int l = 80;
        mtxy = 1;
        pxy = 0.10e0;
        //         Window shape parameter and zero covariance at lag 16
        pw = 0.50e0;
        mw = 16;
        //         Alignment shift of 3
        ish = 3;
        m = (int)Math.Ceiling(Math.Log(2.0*(double)nxy/(double)l) /Math.Log(2.0));
        kc = (int)Math.Pow(2, m)*l;
        double[] xg = new double[kc];
        double[] yg = new double[kc];
        if (nxy > 0)
        {
          sr.Reset();
          for (i = 1; i <= nxy; i++)
          {
            xg[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          sr.Reset();
          for (i = 1; i <= nxy; i++)
          {
            yg[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //         Set parameters for call to g13cd
          //         Mean correction and 10 percent taper
          //
          G13.g13cd(nxy, mtxy, pxy, mw, ish, pw, l, kc, xg, yg, out ng, out ifail);
          if (ifail != 0)
          {
            Console.WriteLine("");
            Console.WriteLine("** g13cd failed with ifail = {0,5}", ifail);
            return;
          }
          //
          Console.WriteLine("");
          Console.WriteLine(" {0}", "                      Returned sample spectrum");
          Console.WriteLine("");
          Console.WriteLine(" {0}", "      Real       Imaginary       Real     Imaginary       Real     Imaginary");
          Console.WriteLine(" {0}", "      part         part         part        part          part       part");
          Console.WriteLine("");
          for (j = 1; j <= ng; j++)
          {
            Console.Write("{0,3}  {1,8:f4}   {2,8:f4}{3}", j, xg[j - 1], yg[j - 1], j % 3 == 0 || j == ng ? "\n" : " ");
          }
          Console.WriteLine(""); ;
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13ce Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13CEE
  {
    static string datafile = "ExampleData/g13cee.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double t = 0.0;
        int i,   j,   ng; int ifail;
        Console.WriteLine("g13ce Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        ng = int.Parse(sr.Next());
        double[] stats = new double[4];
        double[] ca = new double[ng];
        double[] calw = new double[ng];
        double[] caup = new double[ng];
        double[] sc = new double[ng];
        double[] sclw = new double[ng];
        double[] scup = new double[ng];
        double[] xg = new double[ng];
        double[] xyig = new double[ng];
        double[] xyrg = new double[ng];
        double[] yg = new double[ng];
        sr.Reset();
        for (i = 1; i <= 4; i++)
        {
          stats[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        sr.Reset();
        for (i = 1; i <= ng; i++)
        {
          xg[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          yg[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          xyrg[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          xyig[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        //
        G13.g13ce(xg, yg, xyrg, xyig, ng, stats, ca, calw, caup, out t, sc, sclw, scup,
        out ifail);
        //
        Console.WriteLine("");
        if (ifail >= 0)
        {
          if (ifail != 0)
          {
            Console.WriteLine("  {0}{1,3}", "g13ce fails. ifail =", ifail);
            Console.WriteLine("");
          }
          if (ifail != 1)
          {
            Console.WriteLine(" {0}", "      Cross amplitude spectrum");
            Console.WriteLine("");
            Console.WriteLine(" {0}", "                    Lower     Upper");
            Console.WriteLine(" {0}", "          Value     bound     bound");
            Console.WriteLine("");
            for (j = 1; j <= ng; j++)
            {
              Console.WriteLine("  {0,5}{1,10:f4}{2,10:f4}{3,10:f4}", j - 1, ca[j - 1], calw[j - 1], caup[j - 1]);
            }
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,12:f4}", "Squared coherency test statistic =", t);
            Console.WriteLine("");
            Console.WriteLine(" {0}", "         Squared coherency");
            Console.WriteLine("");
            Console.WriteLine(" {0}", "                    Lower     Upper");
            Console.WriteLine(" {0}", "          Value     bound     bound");
            Console.WriteLine("");
            for (j = 1; j <= ng; j++)
            {
              Console.WriteLine("  {0,5}{1,10:f4}{2,10:f4}{3,10:f4}", j - 1, sc[j - 1], sclw[j - 1], scup[j - 1]);
            }
          }
        }
        else
        {
          Console.WriteLine("** g13ce failed with ifail = {0,5}", ifail);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13cf Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13CFE
  {
    static string datafile = "ExampleData/g13cfe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   j,   ng; int ifail;
        Console.WriteLine("g13cf Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        ng = int.Parse(sr.Next());
        double[] gn = new double[ng];
        double[] gnlw = new double[ng];
        double[] gnup = new double[ng];
        double[] ph = new double[ng];
        double[] phlw = new double[ng];
        double[] phup = new double[ng];
        double[] stats = new double[4];
        double[] xg = new double[ng];
        double[] xyig = new double[ng];
        double[] xyrg = new double[ng];
        double[] yg = new double[ng];
        if (ng > 0)
        {
          sr.Reset();
          for (i = 1; i <= 4; i++)
          {
            stats[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          sr.Reset();
          for (i = 1; i <= ng; i++)
          {
            xg[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            yg[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            xyrg[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            xyig[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //
          G13.g13cf(xg, yg, xyrg, xyig, ng, stats, gn, gnlw, gnup, ph, phlw, phup, out ifail);
          //
          Console.WriteLine("");
          if (ifail >= 0)
          {
            if (ifail != 0)
            {
              Console.WriteLine("  {0}{1,3}", "g13cf fails. ifail =", ifail);
              Console.WriteLine("");
            }
            if (ifail != 1)
            {
              Console.WriteLine(" {0}", "              The gain");
              Console.WriteLine("");
              Console.WriteLine(" {0}", "                    Lower     Upper");
              Console.WriteLine(" {0}", "          Value     bound     bound");
              Console.WriteLine("");
              for (j = 1; j <= ng; j++)
              {
                Console.WriteLine("  {0,5}{1,10:f4}{2,10:f4}{3,10:f4}", j - 1, gn[j - 1], gnlw[j - 1], gnup[j - 1]);
              }
              Console.WriteLine("");
              Console.WriteLine(" {0}", "             The phase");
              Console.WriteLine("");
              Console.WriteLine(" {0}", "                    Lower     Upper");
              Console.WriteLine(" {0}", "          Value     bound     bound");
              Console.WriteLine("");
              for (j = 1; j <= ng; j++)
              {
                Console.WriteLine("  {0,5}{1,10:f4}{2,10:f4}{3,10:f4}", j - 1, ph[j - 1], phlw[j - 1], phup[j - 1]);
              }
            }
          }
          else
          {
            Console.WriteLine("** g13cf failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13cg Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13CGE
  {
    static string datafile = "ExampleData/g13cge.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double erlw,   erup,   rfse; int i,  j,  l,  n,  ng;
        int ifail;
        Console.WriteLine("g13cg Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        ng = int.Parse(sr.Next());
        l = int.Parse(sr.Next());
        n = int.Parse(sr.Next());
        double[] er = new double[ng];
        double[] rf = new double[l];
        double[] stats = new double[4];
        double[] xg = new double[ng];
        double[] xyig = new double[ng];
        double[] xyrg = new double[ng];
        double[] yg = new double[ng];
        if (ng > 0 && l > 0)
        {
          sr.Reset();
          for (i = 1; i <= 4; i++)
          {
            stats[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          sr.Reset();
          for (i = 1; i <= ng; i++)
          {
            xg[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            yg[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            xyrg[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            xyig[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
          //
          G13.g13cg(xg, yg, xyrg, xyig, ng, stats, l, n, er, out erlw, out erup, rf, out rfse,
          out ifail);
          //
          Console.WriteLine("");
          if (ifail >= 0)
          {
            if (ifail != 0)
            {
              Console.WriteLine("  {0}{1,3}", "g13cg fails. ifail =", ifail);
              Console.WriteLine("");
            }
            if (ifail != 1)
            {
              Console.WriteLine(" {0}", "           Noise spectrum");
              for (j = 1; j <= ng; j++)
              {
                Console.WriteLine("  {0,5}{1,16:f4}", j - 1, er[j - 1]);
              }
              Console.WriteLine("");
              Console.WriteLine(" {0}", "Noise spectrum bounds multiplying factors");
              Console.WriteLine("  {0}{1,10:f4}{2}{3,10:f4}", "Lower =", erlw, "     Upper =", erup);
              Console.WriteLine("");
              Console.WriteLine(" {0}", "Impulse response function");
              Console.WriteLine("");
              for (j = 1; j <= l; j++)
              {
                Console.WriteLine("  {0,5}{1,16:f4}", j - 1, rf[j - 1]);
              }
              Console.WriteLine("");
              Console.WriteLine("  {0}{1,10:f4}", "Impulse response function standard error =", rfse);
            }
          }
          else
          {
            Console.WriteLine("** g13cg failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13dd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13DDE
  {
    static string datafile = "ExampleData/g13dde.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double cgetol,   rlogl; int i,  ip,  iprint,  iq,  ishow,  j,  k,  maxcal,  n,  niter,  npar;
        bool exact = false,
        mean = false;
        int ifail;
        Console.WriteLine("g13dd Example Program Results");
        //
        //      Skip heading in data file
        //
        sr.Reset();
        sr.Reset();
        k = int.Parse(sr.Next());
        ip = int.Parse(sr.Next());
        iq = int.Parse(sr.Next());
        n = int.Parse(sr.Next());
        mean = bool.Parse(sr.Next());
        npar = (ip + iq) * k * k;
        if (mean)
        {
          npar = npar + k;
        }
        double[] par = new double[npar];
        double[,] cm = new double[npar, npar];
        double[] g = new double[npar];
        double[,] qq = new double[k, k];
        double[,] v = new double[k, n];
        double[,] w = new double[k, n];
        bool[] parhld = new bool[npar];
        //
        //
        Console.WriteLine("");
        //
        if (k <= 0 || ip < 0 || iq < 0 )
        {
          Console.WriteLine("   ** Problem size is too small.");
          goto L100;
        }
        //
        for (i = 1; i <= npar; i++)
        {
          par[i - 1] = 0.00e0;
          parhld[i - 1] = false;
        }
        //
        //      Set all elements of Q to zero to use the covariance matrix
        //      between the K time series as the initial estimate of the
        //      covariance matrix
        for (j = 1; j <= k; j++)
        {
          for (i = j; i <= k; i++)
          {
            qq[i - 1, j - 1] = 0.00e0;
          }
        }
        //
        for (i = 1; i <= k; i++)
        {
          sr.Reset();
          for (j = 1; j <= n; j++)
          {
            w[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        //
        parhld[2] = true;
        exact = true;
        //
        // Set iprint > 0 to obtain intermediate output
        //
        iprint = -1;
        cgetol = 0.00010e0;
        maxcal = 40 * npar * (npar + 5);
        ishow = 2;
        G13.g13dd(k, n, ip, iq, mean, par, qq, w, parhld, exact, iprint, cgetol, maxcal, ishow,
        out niter, out rlogl, v, g, cm, out ifail);
        if (ifail != 0)
        {
          Console.WriteLine("** g13dd failed with ifail = {0,5}", ifail);
        }
        //
        L100: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13dj Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13DJE
  {
    static string datafile = "ExampleData/g13dje.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double cgetol,   rlogl; int i,  i2,  idmax,  idmin,  ip,  iprint,  iq,  ishow,  j,  k,  l,  l2,  lmax,  loop,  lpar,  maxcal,  n,  nd,  niter;
        bool exact = false,
        meanl = false;
        string mean = "";
        int ifail;
        Console.WriteLine("g13dj Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        k = int.Parse(sr.Next());
        n = int.Parse(sr.Next());
        ip = int.Parse(sr.Next());
        iq = int.Parse(sr.Next());
        mean = sr.Next();
        lmax = int.Parse(sr.Next());
        lpar = (ip + iq) * k * k;
        meanl = false;
        string[] tr = new string[k];
        if ((mean == "M") || (mean == "m"))
        {
          lpar = lpar + k;
          meanl = true;
        }
        double[] par = new double[lpar];
        double[,] qq = new double[k, k];
        double[,] v = new double[k, n];
        double[,] z = new double[k, n];
        int[] id = new int[k];
        bool[] parhld = new bool[lpar];
        //        if ((((((k > 0  && (n >= 1)) ) && ((lpar) >= (1))) ) && ((lmax) >= (1))) )
        if (k > 0  && n >= 1 && lpar >= 1 && lmax >= 1)
        {
          sr.Reset();
          for (i = 1; i <= k; i++)
          {
            id[i - 1] = int.Parse(sr.Next());
          }
          idmin = 0;
          idmax = 0;
          for (i = 1; i <= k; i++)
          {
            idmin = Math.Min(id[i - 1], idmin);
            idmax = Math.Max(id[i - 1], idmax);
          }
          double[,] delta = new double[k, Math.Max(idmax,1)];
          double[,] cm = new double[lpar, lpar];
          double[] g = new double[lpar];
          double[,] predz = new double[k, lmax];
          double[,] sefz = new double[k, lmax];
          double[,] w = new double[k, n];
          //
          if (idmin >= 0)
          {
            for (i = 1; i <= k; i++)
            {
              sr.Reset();
              for (j = 1; j <= n; j++)
              {
                z[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
              }
            }
            sr.Reset();
            for (i = 1; i <= k; i++)
            {
              tr[i - 1] = sr.Next();
            }
            //
            if (idmax > 0)
            {
              for (i = 1; i <= k; i++)
              {
                sr.Reset();
                for (j = 1; j <= id[i - 1]; j++)
                {
                  delta[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }
              }
            }
            //
            G13.g13dl(k, n, z, tr, id, delta, w, out nd, out ifail);
            //
            for (i = 1; i <= lpar; i++)
            {
              par[i - 1] = 0.00e0;
              parhld[i - 1] = false;
            }
            for (i = 1; i <= k; i++)
            {
              for (j = 1; j <= i; j++)
              {
                qq[i - 1, j - 1] = 0.00e0;
              }
            }
            parhld[2] = true;
            exact = true;
            // Set iprint < 0 for no monitoring
            iprint = -1;
            cgetol = 0.00010e0;
            maxcal = 40 * lpar * (lpar + 5);
            // Set ishow = 0 for no printing of results from g13dd
            ishow = 0;
            //
            G13.g13dd(k, nd, ip, iq, meanl, par, qq, w, parhld, exact, iprint, cgetol, maxcal, ishow,
            out niter, out rlogl, v, g, cm, out  ifail);
            //
            double[] refn = new double[(lmax-1)*k*k + 2*k*lmax + k];
            if ((ifail == 0) || (ifail >= (4)))
            {
              //
              G13.g13dj(k, n, z, tr, id, delta, ip, iq, mean, par, qq, v, lmax, predz, sefz, refn,
              out ifail);
              //
              Console.WriteLine("");
              Console.WriteLine(" {0}", " FORECAST SUMMARY TABLE");
              Console.WriteLine(" {0}", " ----------------------");
              Console.WriteLine("");
              Console.WriteLine("  {0}{1,4}", " Forecast origin is set at t = ", n);
              Console.WriteLine("");
              loop = lmax / 5;
              if ((lmax % 5) != 0)
              {
                loop = loop + 1;
              }
              for (j = 1; j <= loop; j++)
              {
                i2 = (j - 1) * 5;
                l2 = Math.Min(i2 + 5, lmax);
                Console.WriteLine("");
                Console.Write(" {0}", "Lead Time \t\t   ");
                for (i = i2 + 1; i <= l2; i++)
                {
                  Console.Write("  {0,8}", i);
                }
                Console.WriteLine(""); ;
                Console.WriteLine("");
                i = 1;
                Console.Write(" {0}", "Series ");
                Console.Write(" {0}", i);
                Console.Write(" {0}", " : Forecast    ");
                for (l = i2 + 1; l <= l2; l++)
                {
                  Console.Write("  {0,8:f2}", predz[0, l - 1]);
                }
                Console.WriteLine(""); ;
                Console.Write(" {0}", "           : Standard Error");
                for (l = i2 + 1; l <= l2; l++)
                {
                  Console.Write("{0,8:f2}  ", sefz[0, l - 1]);
                }
                Console.WriteLine(""); ;
                for (i = 2; i <= k; i++)
                {
                  Console.Write(" {0}", "Series ");
                  Console.Write(" {0}", i);
                  Console.Write(" {0}", " : Forecast    ");
                  for (l = i2 + 1; l <= l2; l++)
                  {
                    Console.Write("  {0,8:f2}", predz[i - 1, l - 1]);
                  }
                  Console.WriteLine(""); ;
                  Console.Write(" {0}", "           : Standard Error");
                  for (l = i2 + 1; l <= l2; l++)
                  {
                    Console.Write("{0,8:f2}  ", sefz[i - 1, l - 1]);
                  }
                  Console.WriteLine(""); ;
                }
                Console.WriteLine("");
              }
            }
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


g13dj Example Program Results

  FORECAST SUMMARY TABLE
  ----------------------

   Forecast origin is set at t =   48

 Lead Time 		            1         2         3         4         5

 Series  1  : Forecast          7.82      7.28      6.77      6.33      5.95
            : Standard Error    1.72      2.23      2.51      2.68      2.79
 Series  2  : Forecast         10.31      9.25      8.65      8.30      8.10
            : Standard Error    2.32      2.68      2.78      2.82      2.83


//      g13dk Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13DKE
  {
    static string datafile = "ExampleData/g13dke.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double cgetol,   rlogl; int i,  idmax,  idmin,  ip,  iprint,  iq,  ishow,  j,  k,  lmax,  lpar,  m,  maxcal,  mlast,  n,  nd,  niter;
        bool exact = false,
        meanl = false;
        string mean = "";
        int[] id = new int[3];
        int ifail;
        Console.WriteLine("g13dk Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        k = int.Parse(sr.Next());
        n = int.Parse(sr.Next());
        ip = int.Parse(sr.Next());
        iq = int.Parse(sr.Next());
        mean = sr.Next();
        lmax = int.Parse(sr.Next());
        meanl = false;
        lpar = (ip + iq) * k * k;
        if ((mean == "M") || (mean == "m"))
        {
          lpar = lpar + k;
          meanl = true;
        }
        double[,] cm = new double[lpar, lpar];
        double[] g = new double[lpar];
        double[] par = new double[lpar];
        double[,] predz = new double[k, lmax];
        double[,] qq = new double[k, k];
        int lref = (lmax - 1) * k * k + 2 * k * lmax + k;
        double[] refn = new double[lref];
        double[,] sefz = new double[k, lmax];
        double[,] v = new double[k, n];
        double[,] w = new double[k, n];
        bool[] parhld = new bool[lpar];
        sr.Reset();
        for (i = 1; i <= k; i++)
        {
          id[i - 1] = int.Parse(sr.Next());
        }
        idmax = 0;
        idmin = 0;
        for (i = 1; i <= k; i++)
        {
          idmin = Math.Min(id[i - 1], idmin);
          idmax = Math.Max(id[i - 1], idmax);
        }
        double[,] z = new double[k, n];
        for (i = 1; i <= k; i++)
        {
          sr.Reset();
          for (j = 1; j <= n; j++)
          {
            z[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        string[] tr = new string[k];
        sr.Reset();
        for (i = 1; i <= k; i++)
        {
          tr[i - 1] = sr.Next();
        }
        double[,] delta = new double[k, Math.Max(idmax,1)];
        if (idmax > 0)
        {
          for (i = 1; i <= k; i++)
          {
            sr.Reset();
            for (j = 1; j <= id[i - 1]; j++)
            {
              delta[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
        }
        //
        G13.g13dl(k, n, z, tr, id, delta, w, out nd, out ifail);
        //
        for (i = 1; i <= lpar; i++)
        {
          par[i - 1] = 0.00e0;
          parhld[i - 1] = false;
        }
        for (j = 1; j <= k; j++)
        {
          for (i = j; i <= k; i++)
          {
            qq[i - 1, j - 1] = 0.00e0;
          }
        }
        parhld[2] = true;
        exact = true;
        // Set iprint > 0 for no intermediate monitoring
        iprint = -1;
        cgetol = 0.00010e0;
        maxcal = 40 * lpar * (lpar + 5);
        // Set ishow = 0 for no results from g13dd
        ishow = 0;
        //
        G13.g13dd(k, nd, ip, iq, meanl, par, qq, w, parhld, exact, iprint, cgetol, maxcal, ishow,
        out  niter, out rlogl, v, g, cm, out ifail);
        //
        if ((ifail == 0) || (ifail >= (4)))
        {
          //
          G13.g13dj(k, n, z, tr, id, delta, ip, iq, mean, par, qq, v, lmax, predz, sefz, refn,
          out ifail);
          //
          fprint(ref k, n, ref lmax, predz, sefz, k);
          m = 1;
          mlast = 0;
          z[0, 0] = 8.10e0;
          z[1, 0] = 10.20e0;
          //
          G13.g13dk(k, lmax, m, ref mlast, z, refn, v, predz, sefz, out ifail);
          //
          fprint(ref k, n + mlast, ref lmax, predz, sefz, k);
          m = 1;
          // Leave mlast unchanged from last call
          z[0, 0] = 8.50e0;
          z[1, 0] = 10.00e0;
          //
          G13.g13dk(k, lmax, m, ref mlast, z, refn, v, predz, sefz, out ifail);
          //
          fprint(ref k, n + mlast, ref lmax, predz, sefz, k);
        }
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    public static void fprint(ref int k, int nm, ref int lmax, double[,] predz, double[,
    ] sefz, int ldsefz)
    {
      int i,   i2,   j,   l,   l2,   loop; Console.WriteLine("");
      Console.WriteLine(" {0}", " FORECAST SUMMARY TABLE");
      Console.WriteLine(" {0}", " ----------------------");
      Console.WriteLine("");
      Console.WriteLine("  {0}{1,4}", " Forecast origin is set at t = ", nm);
      Console.WriteLine("");
      loop = lmax / 5;
      if ((lmax % 5) != 0)
      {
        loop = loop + 1;
      }
      for (j = 1; j <= loop; j++)
      {
        i2 = (j - 1) * 5;
        l2 = Math.Min(i2 + 5, lmax);
        Console.Write(" {0}", "Lead Time \t\t   ");
        for (i = i2 + 1; i <= l2; i++)
        {
          Console.Write("  {0,8}", i);
        }
        Console.WriteLine("");
        Console.WriteLine("");
        i = 1;
        Console.Write(" {0}", "Series ");
        Console.Write(" {0}", i);
        Console.Write(" {0}", " : Forecast    ");
        for (l = i2 + 1; l <= l2; l++)
        {
          Console.Write("  {0,8:f2}", predz[0, l - 1]);
        }
        Console.WriteLine(""); ;
        Console.Write(" {0}", "           : Standard Error");
        for (l = i2 + 1; l <= l2; l++)
        {
          Console.Write("{0,8:f2}  ", sefz[0, l - 1]);
        }
        Console.WriteLine("");
        for (i = 2; i <= k; i++)
        {
          Console.Write(" {0}", "Series ");
          Console.Write(" {0}", i);
          Console.Write(" {0}", " : Forecast    ");
          for (l = i2 + 1; l <= l2; l++)
          {
            Console.Write("  {0,8:f2}", predz[i - 1, l - 1]);
          }
          Console.WriteLine("");
          Console.Write(" {0}", "           : Standard Error");
          for (l = i2 + 1; l <= l2; l++)
          {
            Console.Write("{0,8:f2}  ", sefz[i - 1, l - 1]);
          }
          Console.WriteLine("");
        }
        Console.WriteLine("");
      }
      //
    }
  }
}


//      g13dl Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13DLE
  {
    static string datafile = "ExampleData/g13dle.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   j,   k,   maxd,   mind,   n,   nd; int ifail;
        Console.WriteLine("g13dl Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        k = int.Parse(sr.Next());
        n = int.Parse(sr.Next());
        double[,] w = new double[k, n];
        double[,] z = new double[k, n];
        int[] id = new int[k];
        string[] tr = new string[k];
        sr.Reset();
        for (i = 1; i <= k; i++)
        {
          id[i - 1] = int.Parse(sr.Next());
        }
        mind = 0;
        maxd = 0;
        for (i = 1; i <= k; i++)
        {
          mind = Math.Min(mind, id[i - 1]);
          maxd = Math.Max(maxd, id[i - 1]);
        }
        for (i = 1; i <= k; i++)
        {
          sr.Reset();
          for (j = 1; j <= n; j++)
          {
            z[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
          }
        }
        sr.Reset();
        for (i = 1; i <= k; i++)
        {
          tr[i - 1] = sr.Next();
        }
        double[,] delta = new double[k, Math.Max(maxd,1)];
        if (maxd > 0)
        {
          for (i = 1; i <= k; i++)
          {
            sr.Reset();
            for (j = 1; j <= id[i - 1]; j++)
            {
              delta[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
          }
        }
        //
        G13.g13dl(k, n, z, tr, id, delta, w, out nd, out ifail);
        //
        Console.WriteLine("");
        Console.WriteLine(" {0}", " Transformed/Differenced series");
        Console.WriteLine(" {0}", " ------------------------------");
        for (i = 1; i <= k; i++)
        {
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,2}", " Series ", i);
          Console.WriteLine(" {0}", " -----------");
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,6}", " Number of differenced values = ", nd);
          Console.WriteLine("");
          for (j = 1; j <= nd; j++)
          {
            Console.Write(" {0,8:f3}{1}", w[i - 1, j - 1],j % 8 == 0||j==nd ? "\n":" ");
          }
          Console.WriteLine(""); ;
        }
        //
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13dx Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13DXE
  {
    static string datafile = "ExampleData/g13dxe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        int i,   ip,   k,   npar; int ifail;
        Console.WriteLine("g13dx Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        k = int.Parse(sr.Next());
        ip = int.Parse(sr.Next());
        // Read the AR (or MA) parameters
        npar = ip * k * k;
        double[] par = new double[npar];
        sr.Reset();
        for (i = 1; i <= npar; i++)
        {
          par[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        }
        //
        double[] ri = new double[k*ip];
        double[] rmod = new double[k*ip];
        double[] rr = new double[k*ip];
        G13.g13dx(k, ip, par, rr, ri, rmod, out ifail);
        //
        Console.WriteLine("");
        Console.WriteLine(" {0}", "        Eigenvalues       Moduli");
        Console.WriteLine(" {0}", "        -----------       ------");
        //
        for (i = 1; i <= k * ip; i++)
        {
          if ((ri[i - 1]) >= (0.00e0))
          {
            Console.WriteLine("{0,10:f3}  + {1,6:f3} i  {2,8:f3}", rr[i - 1], ri[i - 1], rmod[i - 1]);
          }
          else
          {
            Console.WriteLine("{0,10:f3}  - {1,6:f3} i  {2,8:f3}", rr[i - 1], -ri[i - 1], rmod[i - 1]);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13fa Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13FAE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        const int num = 1500;
        const int mseed = 1;
        const int nregmx = 10;
        const int mnmx = 1;
        const double zero = 0.00e0;
        const int ipmax = 3;
        const int iqmax = 3;
        double fac1,   gamma,   hp,   lgf,   mean,   tol,   xterm; int d,  df,  genid,  i,  ip,  iq,  isym,  j,  k,  maxit,  mn,  npar,  npar2,  nreg,  nt,  subid;
        bool fcall = false;
        string dist = "";
        int[] seed = new int[mseed];
        bool[] copts = new bool[2];
        int ifail;
        double[] param = new double[ipmax+iqmax+1];
        double[,] x = new double[num, Math.Max(nregmx+mnmx,1)];
        double[] yt = new double[num];
        double[] etm = new double[num];
        double[] htm = new double[num];
        double[] ht = new double[num];
        double[] rvec = new double[2*(ipmax+iqmax+1)];
        double[] bx = new double[nregmx];
        Console.WriteLine("g13fa Example Program Results");
        Console.WriteLine("");
        df = 0;
        hp = 0.0;
        //      Initialise the seed
        seed[0] = 111;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        //
        //      Initialise the time dependent, exogenous, variables
        bx[0] = 1.50e0;
        bx[1] = 2.50e0;
        bx[2] = 3.00e0;
        for (i = 1; i <= num; i++)
        {
          fac1 = (double)i * 0.010e0;
          x[i - 1, 0] = 0.010e0 + 0.70e0 * Math.Sin(fac1);
          x[i - 1, 1] = 0.50e0 + fac1 * 0.10e0;
          x[i - 1, 2] = 1.00e0;
        }
        //
        //      Show two examples, normally distributed errors,
        //      and student t errors
        for (d = 1; d <= 2; d++)
        {
          if (d == 1)
          {
            //            Errors distributed as a normal distribution
            Console.WriteLine("");
            Console.WriteLine(" {0}", "Normal distribution");
            Console.WriteLine("");
            dist = "N";
            //            Initialise the series parameters required
            //            for generation of some test data
            mean = 3.00e0;
            mn = 1;
            nreg = 0;
            isym = 1;
            gamma = -0.40e0;
            ip = 0;
            iq = 3;
            param[0] = 0.80e0;
            param[1] = 0.60e0;
            param[2] = 0.20e0;
            param[3] = 0.10e0;
          }
          else
          {
            //            Errors distributed as a students t distribution
            Console.WriteLine("");
            Console.WriteLine(" {0}", "Students T distribution");
            Console.WriteLine("");
            dist = "T";
            //            Initialise the series parameters required
            //            for generation of some test data
            df = 4;
            mean = 3.00e0;
            mn = 1;
            nreg = 2;
            ip = 1;
            iq = 1;
            isym = 1;
            gamma = -0.20e0;
            param[0] = 0.10e0;
            param[1] = 0.20e0;
            param[2] = 0.30e0;
          }
          //
          //         Start of data generation
          //         Generate the errors
          fcall = true;
          G05.g05pd(dist, num, ip, iq, param, gamma, df, ht, yt, fcall, rvec, g05State, out ifail);
          //         Calculate the observed data
          for (i = 1; i <= num; i++)
          {
            xterm = zero;
            for (k = 1; k <= nreg; k++)
            {
              xterm = xterm + x[i - 1, k - 1] * bx[k - 1];
            }
            if (mn == 1)
            {
              yt[i - 1] = mean + xterm + yt[i - 1];
            }
            else
            {
              yt[i - 1] = xterm + yt[i - 1];
            }
          }
          //         End of data generation
          //
          //         Calculate the number of parameters
          npar = 1 + iq + ip;
          npar2 = npar + isym + mn + nreg;
          if (dist == "T")
          {
            npar2 = npar2 + 1;
          }
          double[] theta = new double[npar2];
          double[] sc = new double[npar2];
          double[] se = new double[npar2];
          double[,] covr = new double[npar2, npar2];
          //
          //         Set the model fitting options
          copts[0] = true;
          copts[1] = true;
          maxit = 200;
          tol = 1.00e-5;
          //
          //         Generate initial values for the alpha_i and beta_j parameters
          for (i = 1; i <= npar; i++)
          {
            theta[i - 1] = param[i - 1] * 0.50e0;
          }
          //         Generate initial values for the asymmetry parameter, gamma
          j = npar + 1;
          if (isym == 1)
          {
            theta[j - 1] = gamma * 0.50e0;
            j = j + 1;
          }
          // Generate initial values for df estimate
          if (dist == "T")
          {
            theta[j - 1] = df * 0.650e0;
            j = j + 1;
          }
          //         Generate the initial values for b_0
          if (mn == 1)
          {
            theta[j - 1] = mean * 0.50e0;
            j = j + 1;
          }
          //         Generate the initial values for the linear regression
          //         coefficients b_i, if required
          if (!(copts[1]))
          {
            for (i = 1; i <= nreg; i++)
            {
              theta[i + j - 1 - 1] = bx[i - 1] * 0.50e0;
            }
          }
          //
          //         Call the analysis method
          G13.g13fa(dist, yt, x, num, ip, iq, nreg, mn, isym, npar2, theta, se, sc, covr, ref hp, etm,
          htm, out lgf, copts, maxit, tol, out ifail);
          //
          //         Output the results
          Console.WriteLine(" {0} {1}", "          Parameter       Standard        ", "Correct");
          Console.WriteLine(" {0} {1}", "          estimates       errors          ", "values");
          //         Output the coefficient alpha_0
          Console.WriteLine("  {0,16:f4}{1,16:f4}{2,16:f4}", theta[0], se[0], param[0]);
          //         Output the coefficients alpha_i
          for (i = 2; i <= iq; i++)
          {
            Console.WriteLine("  {0,16:f4}{1,16:f4}{2,16:f4}", theta[i - 1], se[i - 1], param[i - 1]);
          }
          //         Output the coefficients beta_j
          for (i = iq + 1; i <= npar; i++)
          {
            Console.WriteLine("  {0,16:f4}{1,16:f4}{2,16:f4}", theta[i - 1], se[i - 1], param[i - 1]);
          }
          //         Output the estimated asymmetry parameter, gamma
          j = npar + 1;
          if (isym == 1)
          {
            Console.WriteLine("  {0,16:f4}{1,16:f4}{2,16:f4}", theta[j - 1], se[j - 1], gamma);
            j = j + 1;
          }
          //         Output the estimated degrees of freedom, df
          if (dist == "T")
          {
            Console.WriteLine("  {0,16:f4}{1,16:f4}{2,16:f4}", theta[j - 1], se[j - 1], (double)df);
            j = j + 1;
          }
          //         Output the estimated mean term, b_0
          if (mn == 1)
          {
            Console.WriteLine("  {0,16:f4}{1,16:f4}{2,16:f4}", theta[j - 1], se[j - 1], mean);
            j = j + 1;
          }
          //         Output the estimated linear regression coefficients, b_i
          for (i = 1; i <= nreg; i++)
          {
            Console.WriteLine("  {0,16:f4}{1,16:f4}{2,16:f4}", theta[i + j - 1 - 1], se[i + j - 1 - 1], bx[i - 1]);
          }
          //
          //         Calculate the volatility forecast
          nt = 4;
          double[] cvar = new double[nt];
          G13.g13fb(num, nt, ip, iq, theta, gamma, cvar, htm, etm, out ifail);
          //         Display the volatility forecast
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,12:f4}", "Volatility forecast = ", cvar[nt - 1]);
          Console.WriteLine("");
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13fc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13FCE
  {
    const int ipmax = 3;
    const int iqmax = 3;
    const int nregmx = 10;
    const int mnmx = 1;
    const int num = 1500;
    const int mseed = 1;
    const double zero = 0.00e0;
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        double fac1,   gamma,   hp,   lgf,   mean,   tol,   xterm; int d,  df,  genid,  i,  ip,  iq,  j,  k,  maxit,  mn,  npar,  npar2,  nreg,  nt,  subid;
        bool fcall = false;
        string dist = "";
        double[] bx = new double[nregmx];
        double[] param = new double[ipmax+iqmax+1];
        double[,] x = new double[num, num];
        double[] yt = new double[num];
        int[] seed = new int[mseed];
        bool[] copts = new bool[2];
        double[] etm = new double[num];
        double[] ht = new double[num];
        double[] htm = new double[num];
        double[] rvec = new double[2*(ipmax+iqmax+1)];
        int ifail;
        Console.WriteLine("g13fc Example Program Results");
        Console.WriteLine("");
        df = 0;
        hp = 0.0;
        //      Initialise the seed
        seed[0] = 111;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        //
        //      Initialise the time dependent, exogenous, variables
        bx[0] = 1.50e0;
        bx[1] = 2.50e0;
        bx[2] = 3.00e0;
        for (i = 1; i <= num; i++)
        {
          fac1 = (double)i * 0.010e0;
          x[i - 1, 0] = 0.010e0 + 0.70e0 * Math.Sin(fac1);
          x[i - 1, 1] = 0.50e0 + fac1 * 0.10e0;
          x[i - 1, 2] = 1.00e0;
        }
        //
        //      Show two examples, normally distributed errors,
        //      and student t errors
        for (d = 1; d <= 2; d++)
        {
          if (d == 1)
          {
            //            Errors distributed as a normal distribution
            Console.WriteLine("");
            Console.WriteLine(" {0}", "Normal distribution");
            Console.WriteLine("");
            dist = "N";
            //            Initialise the series parameters required
            //            for generation of some test data
            mean = 3.00e0;
            mn = 1;
            nreg = 2;
            gamma = -0.40e0;
            ip = 1;
            iq = 1;
            param[0] = 0.080e0;
            param[1] = 0.20e0;
            param[2] = 0.70e0;
          }
          else
          {
            //            Errors distributed as a students t distribution
            Console.WriteLine("");
            Console.WriteLine(" {0}", "Students T distribution");
            Console.WriteLine("");
            dist = "T";
            //            Initialise the series parameters required
            //            for generation of some test data
            df = 4;
            mean = 3.00e0;
            mn = 1;
            nreg = 2;
            gamma = -0.40e0;
            ip = 1;
            iq = 1;
            param[0] = 0.10e0;
            param[1] = 0.10e0;
            param[2] = 0.80e0;
          }
          //
          //         Start of data generation
          //         Generate the errors
          fcall = true;
          G05.g05pe(dist, num, ip, iq, param, gamma, df, ht, yt, fcall, rvec, g05State, out ifail);
          //         Calculate the observed data
          for (i = 1; i <= num; i++)
          {
            xterm = zero;
            for (k = 1; k <= nreg; k++)
            {
              xterm = xterm + x[i - 1, k - 1] * bx[k - 1];
            }
            if (mn == 1)
            {
              yt[i - 1] = mean + xterm + yt[i - 1];
            }
            else
            {
              yt[i - 1] = xterm + yt[i - 1];
            }
          }
          //         End of data generation
          //
          //         Calculate the number of parameters
          npar = iq + ip + 1;
          npar2 = npar + mn + nreg + 1;
          if (dist == "T")
          {
            npar2 = npar2 + 1;
          }
          double[] theta = new double[npar2];
          double[,] covr = new double[npar2, npar2];
          double[] sc = new double[npar2];
          double[] se = new double[npar2];
          //
          //         Set the model fitting options
          copts[0] = true;
          copts[1] = true;
          maxit = 50;
          tol = 1.00e-5;
          //
          //         Generate initial values for the alpha_i and beta_j parameters
          for (i = 1; i <= npar; i++)
          {
            theta[i - 1] = param[i - 1] * 0.50e0;
          }
          //         Generate initial values for the asymmetry parameter, gamma
          theta[npar + 1 - 1] = gamma * 0.50e0;
          //  Generate initial values for df estimate
          j = npar + 2;
          if (dist == "T")
          {
            theta[j - 1] = df * 0.650e0;
            j = j + 1;
          }
          //         Generate the initial values for b_0
          if (mn == 1)
          {
            theta[j - 1] = mean * 0.50e0;
            j = j + 1;
          }
          //         Generate the initial values for the linear regression
          //         coefficients b_i, if required
          if (!(copts[1]))
          {
            for (i = 1; i <= nreg; i++)
            {
              theta[i + j - 1 - 1] = bx[i - 1] * 0.50e0;
            }
          }
          //
          //         Call the analysis method
          G13.g13fc(dist, yt, x, num, ip, iq, nreg, mn, npar2, theta, se, sc, covr, ref hp, etm, htm,
          out lgf, copts, maxit, tol, out ifail);
          //
          //         Output the results
          Console.WriteLine(" {0} {1}", "          Parameter       Standard", "        Correct");
          Console.WriteLine(" {0} {1}", "          estimates       errors  ", "        values");
          //         Output the coefficient alpha_0
          Console.WriteLine("  {0,16:f4}{1,16:f4}{2,16:f4}", theta[0], se[0], param[0]);
          //         Output the coefficients alpha_i
          for (i = 2; i <= iq; i++)
          {
            Console.WriteLine("  {0,16:f4}{1,16:f4}{2,16:f4}", theta[i - 1], se[i - 1], param[i - 1]);
          }
          //         Output the coefficients beta_j
          for (i = iq + 1; i <= npar; i++)
          {
            Console.WriteLine("  {0,16:f4}{1,16:f4}{2,16:f4}", theta[i - 1], se[i - 1], param[i - 1]);
          }
          //         Output the estimated asymmetry parameter, gamma
          Console.WriteLine("  {0,16:f4}{1,16:f4}{2,16:f4}", theta[npar + 1 - 1], se[npar + 1 - 1], gamma);
          j = npar + 2;
          //         Output the estimated degrees of freedom, df
          if (dist == "T")
          {
            Console.WriteLine("  {0,16:f4}{1,16:f4}{2,16:f4}", theta[j - 1], se[j - 1], (double)df);
            j = j + 1;
          }
          //         Output the estimated mean term, b_0
          if (mn == 1)
          {
            Console.WriteLine("  {0,16:f4}{1,16:f4}{2,16:f4}", theta[j - 1], se[j - 1], mean);
            j = j + 1;
          }
          //         Output the estimated linear regression coefficients, b_i
          for (i = 1; i <= nreg; i++)
          {
            Console.WriteLine("  {0,16:f4}{1,16:f4}{2,16:f4}", theta[i + j - 1 - 1], se[i + j - 1 - 1], bx[i - 1]);
          }
          //
          //         Calculate the volatility forecast
          nt = 4;
          double[] cvar = new double[nt];
          G13.g13fd(num, nt, ip, iq, theta, gamma, cvar, htm, etm, out ifail);
          //         Display the volatility forecast
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,12:f4}", "Volatility forecast = ", cvar[nt - 1]);
          Console.WriteLine("");
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13fe Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13FEE
  {
    const int ipmax = 10;
    const int iqmax = 10;
    const int num = 2000;
    const int mseed = 1;
    const int nregmx = 10;
    const int mnmx = 1;
    const double zero = 0.00e0;
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        double fac1,   gamma,   hp,   lgf,   mean,   tol,   xterm; int d,  df,  genid,  i,  ip,  iq,  j,  k,  maxit,  mn,  npar,  npar2,  nreg,  nt,  subid;
        bool fcall = false;
        string dist = "";
        double[] bx = new double[nregmx];
        double[] etm = new double[num];
        double[] ht = new double[num];
        double[] htm = new double[num];
        double[] param = new double[ipmax+iqmax+1];
        double[,] x = new double[num, Math.Max(1, nregmx+mnmx)];
        double[] yt = new double[num];
        double[] rvec = new double[2*(ipmax+ipmax+2)];
        int[] seed = new int[mseed];
        bool[] copts = new bool[2];
        int ifail;
        Console.WriteLine("g13fe Example Program Results");
        Console.WriteLine("");
        df = 0;
        hp = 0.0;
        df = 0;
        hp = 0.0;
        //      Initialise the seed
        seed[0] = 111;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        //
        if (ifail != 0)
        {
          goto L200;
        }
        //
        //      Initialise the time dependent, exogenous, variables
        gamma = 0.10e0;
        bx[0] = 1.50e0;
        bx[1] = 2.50e0;
        bx[2] = 3.00e0;
        for (i = 1; i <= num; i++)
        {
          fac1 = (double)i * 0.010e0;
          x[i - 1, 1] = 0.010e0 + 0.70e0 * Math.Sin(fac1);
          x[i - 1, 0] = 0.50e0 + fac1 * 0.10e0;
          x[i - 1, 2] = 1.00e0;
        }
        //
        for (d = 1; d <= 2; d++)
        {
          if (d == 1)
          {
            //            Errors distributed as a normal distribution
            Console.WriteLine("");
            Console.WriteLine(" {0}", "Normal distribution");
            Console.WriteLine("");
            dist = "N";
            //            Initialise the series parameters required
            //            for generation of some test data
            mean = 4.00e0;
            mn = 1;
            nreg = 2;
            gamma = 0.10e0;
            ip = 1;
            iq = 1;
            param[0] = 0.40e0;
            param[1] = 0.10e0;
            param[2] = 0.70e0;
          }
          else
          {
            //            Errors distributed as a students t distribution
            Console.WriteLine("");
            Console.WriteLine(" {0}", "Students T distribution");
            Console.WriteLine("");
            dist = "T";
            //            Initialise the series parameters required
            //            for generation of some test data
            mean = 3.00e0;
            df = 5;
            mn = 1;
            nreg = 2;
            gamma = 0.090e0;
            ip = 1;
            iq = 1;
            param[0] = 0.050e0;
            param[1] = 0.10e0;
            param[2] = 0.80e0;
          }
          //
          //         Start of data generation
          //         Generate the errors
          fcall = true;
          G05.g05pf(dist, num, ip, iq, param, gamma, df, ht, yt, fcall, rvec, g05State, out ifail);
          //
          //         Calculate the observed data
          for (i = 1; i <= num; i++)
          {
            xterm = zero;
            for (k = 1; k <= nreg; k++)
            {
              xterm = xterm + x[i - 1, k - 1] * bx[k - 1];
            }
            if (mn == 1)
            {
              yt[i - 1] = mean + xterm + yt[i - 1];
            }
            else
            {
              yt[i - 1] = xterm + yt[i - 1];
            }
          }
          //         End of data generation
          //
          //         Calculate the number of parameters
          npar = iq + ip + 1;
          npar2 = npar + mn + nreg + 1;
          if (dist == "T")
          {
            npar2 = npar2 + 1;
          }
          double[] theta = new double[npar2];
          double[,] covr = new double[npar2, npar2];
          double[] sc = new double[npar2];
          double[] se = new double[npar2];
          //
          //         Set the model fitting options
          copts[0] = true;
          copts[1] = true;
          maxit = 55;
          tol = 1.00e-5;
          //
          //         Generate initial values for the alpha_i and beta_j parameters
          for (i = 1; i <= npar; i++)
          {
            theta[i - 1] = param[i - 1] * 0.50e0;
          }
          //         Generate initial values for the asymmetry parameter, gamma
          theta[npar + 1 - 1] = gamma * 0.50e0;
          //         Generate initial values for df estimate
          j = npar + 2;
          if (dist == "T")
          {
            theta[j - 1] = df * 0.650e0;
            j = j + 1;
          }
          //         Generate the initial values for b_0
          if (mn == 1)
          {
            theta[j - 1] = mean * 0.50e0;
            j = j + 1;
          }
          //         Generate the initial values for the linear regression
          //         coefficients b_i, if required
          if (!(copts[1]))
          {
            for (i = 1; i <= nreg; i++)
            {
              theta[i + j - 1 - 1] = bx[i - 1] * 0.50e0;
            }
          }
          //
          //         Call the analysis method
          G13.g13fe(dist, yt, x, num, ip, iq, nreg, mn, npar2, theta, se, sc, covr, ref hp, etm, htm,
          out lgf, copts, maxit, tol, out ifail);
          //
          //         Output the results
          Console.WriteLine(" {0} {1}", "          Parameter       Standard", "        Correct");
          Console.WriteLine(" {0} {1}", "          estimates       errors  ", "        values");
          //         Output the coefficient alpha_0
          Console.WriteLine("  {0,16:f4}{1,16:f4}{2,16:f4}", theta[0], se[0], param[0]);
          //         Output the coefficients alpha_i
          for (i = 2; i <= iq; i++)
          {
            Console.WriteLine("  {0,16:f4}{1,16:f4}{2,16:f4}", theta[i - 1], se[i - 1], param[i - 1]);
          }
          //         Output the coefficients beta_j
          for (i = iq + 1; i <= npar; i++)
          {
            Console.WriteLine("  {0,16:f4}{1,16:f4}{2,16:f4}", theta[i - 1], se[i - 1], param[i - 1]);
          }
          //         Output the estimated asymmetry parameter, gamma
          Console.WriteLine("  {0,16:f4}{1,16:f4}{2,16:f4}", theta[npar + 1 - 1], se[npar + 1 - 1], gamma);
          j = npar + 2;
          //         Output the estimated degrees of freedom, df
          if (dist == "T")
          {
            Console.WriteLine("  {0,16:f4}{1,16:f4}{2,16:f4}", theta[j - 1], se[j - 1], (double)df);
            j = j + 1;
          }
          //         Output the estimated mean term, b_0
          if (mn == 1)
          {
            Console.WriteLine("  {0,16:f4}{1,16:f4}{2,16:f4}", theta[j - 1], se[j - 1], mean);
            j = j + 1;
          }
          //         Output the estimated linear regression coefficients, b_i
          for (i = 1; i <= nreg; i++)
          {
            Console.WriteLine("  {0,16:f4}{1,16:f4}{2,16:f4}", theta[i + j - 1 - 1], se[i + j - 1 - 1], bx[i - 1]);
          }
          //         Calculate the volatility forecast
          nt = 4;
          double[] cvar = new double[nt];
          G13.g13ff(num, nt, ip, iq, theta, gamma, cvar, htm, etm, out ifail);
          //         Display the volatility forecast
          Console.WriteLine("");
          Console.WriteLine("  {0}{1,12:f4}", "Volatility forecast = ", cvar[nt - 1]);
          Console.WriteLine("");
        }
        //
        L200: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      g13fg Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class G13FGE
  {
    const int ipmax = 5;
    const int iqmax = 5;
    const int num = 1500;
    const int mseed = 1;
    const int nregmx = 10;
    const int mnmx = 1;
    const double zero = 0.00e0;
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        double fac1,   hp,   lgf,   mean,   tol,   xterm; int d,  df,  genid,  i,  ip,  iq,  j,  k,
        maxit,  mn,  npar,  npar2,  nreg,  nt,  subid;
        bool copts = false,
        fcall = false;
        string dist = "";
        double[] bx = new double[nregmx];
        double[] etm = new double[num];
        double[] ht = new double[num];
        double[] htm = new double[num];
        double[] param = new double[2*iqmax+ipmax+1];
        double[] rvec = new double[2*(ipmax + 2*iqmax +2)];
        double[,] x = new double[num, Math.Max(nregmx+mnmx, 1)];
        double[] yt = new double[num];
        int[] seed = new int[mseed];
        int ifail;
        Console.WriteLine("g13fg Example Program Results");
        Console.WriteLine("");
        df = 0;
        hp = 0.0;
        //      Initialise the seed
        seed[0] = 111;
        //      genid and subid identify the base generator
        genid = 1;
        subid = 1;
        //      Initialise the generator to a repeatable sequence
        G05.G05State g05State = new G05.G05State(genid, subid, seed, out ifail);
        //
        if (ifail != 0)
        {
          Console.WriteLine("** Generator initialisation failed with ifail = {0,5}", ifail);
          goto L200;
        }
        //
        //      Initialise the time dependent, exogenous, variables
        bx[0] = 1.50e0;
        bx[1] = 2.50e0;
        bx[2] = 3.00e0;
        for (i = 1; i <= num; i++)
        {
          fac1 = (double)i * 0.010e0;
          x[i - 1, 1] = 0.010e0 + 0.70e0 * Math.Sin(fac1);
          x[i - 1, 0] = 0.50e0 + fac1 * 0.10e0;
          x[i - 1, 2] = 1.00e0;
        }
        //
        for (d = 1; d <= 2; d++)
        {
          if (d == 1)
          {
            //            Errors distributed as a normal distribution
            Console.WriteLine("");
            Console.WriteLine(" {0}", "Normal distribution");
            Console.WriteLine("");
            dist = "N";
            //            Initialise the series parameters required
            //            for generation of some test data
            mean = 3.00e0;
            mn = 1;
            nreg = 2;
            ip = 1;
            iq = 1;
            param[0] = 0.10e0;
            param[1] = -0.30e0;
            param[2] = 0.10e0;
            param[3] = 0.90e0;
          }
          else
          {
            //            Errors distributed as a students t distribution
            Console.WriteLine("");
            Console.WriteLine(" {0}", "Students T distribution");
            Console.WriteLine("");
            dist = "T";
            //            Initialise the series parameters required
            //            for generation of some test data
            mean = 3.00e0;
            df = 5;
            mn = 1;
            nreg = 2;
            ip = 1;
            iq = 2;
            param[0] = 0.10e0;
            param[1] = -0.30e0;
            param[2] = -0.10e0;
            param[3] = 0.10e0;
            param[4] = 0.30e0;
            param[5] = 0.70e0;
          }
          //
          //         Start of data generation
          //         Generate the errors
          fcall = true;
          G05.g05pg(dist, num, ip, iq, param, df, ht, yt, fcall, rvec, g05State, out ifail);
          //         Calculate the observed data
          for (i = 1; i <= num; i++)
          {
            xterm = zero;
            for (k = 1; k <= nreg; k++)
            {
              xterm = xterm + x[i - 1, k - 1] * bx[k - 1];
            }
            if (mn == 1)
            {
              yt[i - 1] = mean + xterm + yt[i - 1];
            }
            else
            {
              yt[i - 1] = xterm + yt[i - 1];
            }
          }
          //         End of data generation
          //
          //         Calculate the number of parameters
          npar = 1 + 2 * iq + ip;
          npar2 = npar + mn + nreg;
          if (dist == "T")
          {
            npar2 = npar2 + 1;
          }
          double[,] covr = new double[npar2, npar2];
          double[] sc = new double[npar2];
          double[] se = new double[npar2];
          double[] theta = new double[npar2];
          //
          //         Set the model fitting options
          copts = true;
          maxit = 50;
          tol = 1.00e-5;
          //
          //         Generate initial values for the alpha_i and beta_j parameters
          for (i = 1; i <= npar; i++)
          {
            theta[i - 1] = param[i - 1] * 0.50e0;
          }
          //         Generate initial values for df estimate
          j = npar + 1;
          if (dist == "T")
          {
            theta[j - 1] = df * 0.650e0;
            j = j + 1;
          }
          //         Generate the initial values for b_0
          if (mn == 1)
          {
            theta[j - 1] = mean * 0.50e0;
            j = j + 1;
          }
          //         Generate the initial values for the linear regression
          //         coefficients b_i, if required
          if (!(copts))
          {
            for (i = 1; i <= nreg; i++)
            {
              theta[i + j - 1 - 1] = bx[i - 1] * 0.50e0;
            }
          }
          //
          //         Call the analysis method
          G13.g13fg(dist, yt, x, num, ip, iq, nreg, mn, npar2, theta, se, sc, covr, ref hp, etm, htm,
          out lgf, copts, maxit, tol, out ifail);
          //
          if (ifail == 0)
          {
            //            Output the results
            Console.WriteLine(" {0}", "          Parameter       Standard        Correct");
            Console.WriteLine(" {0}", "          estimates       errors          values");
            //            Output the coefficient alpha_0
            Console.WriteLine("  {0,16:f3}{1,16:f3}{2,16:f3}", theta[0], se[0], param[0]);
            //            Output the coefficients alpha_i
            for (i = 2; i <= iq; i++)
            {
              Console.WriteLine("  {0,16:f3}{1,16:f3}{2,16:f3}", theta[i - 1], se[i - 1], param[i - 1]);
            }
            //            Output the coefficients beta_j
            for (i = iq + 1; i <= npar; i++)
            {
              Console.WriteLine("  {0,16:f3}{1,16:f3}{2,16:f3}", theta[i - 1], se[i - 1], param[i - 1]);
            }
            j = npar + 1;
            //            Output the estimated degrees of freedom, df
            if (dist == "T")
            {
              Console.WriteLine("  {0,16:f3}{1,16:f3}{2,16:f3}", theta[j - 1], se[j - 1], (double)df);
              j = j + 1;
            }
            //            Output the estimated mean term, b_0
            if (mn == 1)
            {
              Console.WriteLine("  {0,16:f3}{1,16:f3}{2,16:f3}", theta[j - 1], se[j - 1], mean);
              j = j + 1;
            }
            //            Output the estimated linear regression coefficients, b_i
            for (i = 1; i <= nreg; i++)
            {
              Console.WriteLine("  {0,16:f3}{1,16:f3}{2,16:f3}", theta[i + j - 1 - 1], se[i + j - 1 - 1], bx[i - 1]);
            }
            //
            //            Calculate the volatility forecast
            nt = 4;
            double[] cvar = new double[nt];
            G13.g13fh(num, nt, ip, iq, theta, cvar, htm, etm, out ifail);
            //            Display the volatility forecast
            Console.WriteLine("");
            Console.WriteLine("  {0}{1,12:f3}", "Volatility forecast = ", cvar[nt - 1]);
            Console.WriteLine("");
          }
        }
        //
        L200: ;
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      h02bb Example Program Text
//      C# version, NAG Copyright 2012
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
    public class H02BBE
    {
     // Specify data file as a command line argument.
     // It defaults to the named file specified below otherwise.
     static string datafile = "ExampleData/h02bbe.d";

        const int liwork = 1000;
        const int lrwork = 1000;

        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
        {
            DataReader sr = new DataReader(datafile);
            double bigbnd = 0.0,
            objmip = 0.0,
            tolfes = 0.0,
            toliv = 0.0;
            int i = 0,
            intfst = 0,
            itmax = 0,
            j = 0,
            m = 0,
            maxdpt = 0,
            maxnod = 0,
            msglvl = 0,
            n = 0;

            double[] rwork = new double[1000];
            int[] iwork = new int[1000];
            Console.WriteLine("h02bb Example Program Results");
            //      Skip heading in data file
            sr.Reset();
            sr.Reset();
            n = int.Parse(sr.Next());
            m = int.Parse(sr.Next());
            double[,] a = new double[m, n];
            double[] x = new double[n];
            double[] bl = new double[n + m];
            double[] bu = new double[n + m];
            double[] cvec = new double[n];
            int[] intvar = new int[n];

            //
            //         Read ITMAX, MSGLVL, MAXNOD, INTFST, MAXDPT, TOLFES, TOLIV,
            //         CVEC, A, BIGBND, BL, BU, INTVAR and X from data file
            //
            sr.Reset();
            itmax = int.Parse(sr.Next());
            msglvl = int.Parse(sr.Next());
            sr.Reset();
            maxnod = int.Parse(sr.Next());
            sr.Reset();
            intfst = int.Parse(sr.Next());
            maxdpt = int.Parse(sr.Next());
            sr.Reset();
            tolfes = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            toliv = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            sr.Reset();
            for (i = 1; i <= n; i++)
            {
                cvec[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            sr.Reset();
            for (i = 1; i <= m; i++)
            {
                for (j = 1; j <= n; j++)
                {
                    a[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }
            }
            sr.Reset();
            bigbnd = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            sr.Reset();
            for (i = 1; i <= n + m; i++)
            {
                bl[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            sr.Reset();
            for (i = 1; i <= n + m; i++)
            {
                bu[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            sr.Reset();
            for (i = 1; i <= n; i++)
            {
                intvar[i - 1] = int.Parse(sr.Next());
            }
            sr.Reset();
            for (i = 1; i <= n; i++)
            {
                x[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            }
            //
            //         Solve the IP problem
            //
            int ifail;
            H.h02bbOptions options = new H.h02bbOptions();
            H.h02bb(ref itmax, msglvl, n, m, a, bl, bu, intvar, cvec, maxnod, intfst, maxdpt, ref toliv,
                    ref tolfes, ref bigbnd, x, out objmip, iwork, rwork, options, out ifail);
            //

        }
    }
}


H02BB Example Program Data
  2  3                                           :Values of N and M
  0  10                                          :Values of ITMAX and MSGLVL
  0                                              :Value of MAXNOD
  0  4                                           :Values of INTFST and MAXDPT
  0.0   0.0                                      :Values of TOLFES and TOLIV
 -3.0  -4.0                                      :End of CVEC
  2.0   5.0
  2.0  -2.0
  3.0   2.0                                      :End of matrix A
  1.0e+20                                        :Value of BIGBND
  0.0      0.0      -1.0e+20  -1.0e+20  5.0      :End of BL
  1.0e+20  1.0e+20  15.0       5.0      1.0e+20  :End of BU
  1     1                                        :End of INTVAR
  1.0   1.0                                      :End of X


h02bb Example Program Results

 *** H02BBF

 Parameters
 ----------

 Linear constraints......         3        First integer solution..       OFF
 Variables...............         2        Max depth of the tree...         4

 Feasibility tolerance...  1.05E-08        Print level.............        10
 Infinite bound size.....  1.00E+20        EPS (machine precision).  1.11E-16

 Integer feasibility tol.  1.00E-05        Iteration limit.........        50
 Max number of nodes.....      NONE

 ** Workspace provided with MAXDPT =     4: LRWORK =  1000  LIWORK =  1000
 ** Workspace required with MAXDPT =     4: LRWORK =    84  LIWORK =   137

   *** Optimum LP solution ***   -17.50000

 Varbl State     Value     Lower Bound   Upper Bound    Lagr Mult   Residual

 V  1    FR    3.92857       0.00000         None        0.000       3.929
 V  2    FR    1.42857       0.00000         None        0.000       1.429

 L Con State     Value     Lower Bound   Upper Bound    Lagr Mult   Residual

 L  1    UL    15.0000         None        15.0000     -1.0000       0.000
 L  2    UL    5.00000         None        5.00000     -0.5000     -8.8818E-16
 L  3    FR    14.6429       5.00000         None        0.000       9.643

   *** Start of tree search ***

  Node  Parent   Obj       Varbl  Value      Lower      Upper      Value   Depth
   No    Node   Value      Chosen Before     Bound      Bound      After
    2     1   No Feas Soln    1    3.93       4.00       None       4.00       1
    3     1    -16.2          1    3.93       0.00       3.00       3.00       1
    4     3    -15.5          2    1.80       2.00       None       2.00       2
    5     3    -13.0          2    1.80       0.00      1.000      1.000       2
      *** Integer solution ***

  Node  Parent   Obj       Varbl  Value      Lower      Upper      Value   Depth
   No    Node   Value      Chosen Before     Bound      Bound      After
    6     4   No Feas Soln    1    2.50       3.00       3.00       3.00       3
    7     4    -14.8          1    2.50       0.00       2.00       2.00       3
    8     7    -12.0     CO   2    2.20       3.00       None       3.00       4
    9     7    -14.0          2    2.20       2.00       2.00       2.00       4
      *** Integer solution ***

     *** End of tree search ***

 Total of     9 nodes investigated.

 Exit H02BBF - Optimum IP solution found.

 Final IP objective value =   -14.00000

 Varbl State     Value     Lower Bound   Upper Bound    Lagr Mult   Residual

 V  1    UL    2.00000       0.00000       2.00000      -3.000       0.000
 V  2    EQ    2.00000       2.00000       2.00000      -4.000       0.000

 L Con State     Value     Lower Bound   Upper Bound    Lagr Mult   Residual

 L  1    FR    14.0000         None        15.0000       0.000      1.0000
 L  2    FR    0.00000         None        5.00000       0.000       5.000
 L  3    FR   10.00000       5.00000         None        0.000       5.000


//      h02cb Example Program Text
//      Mark 20 Revised. NAG Copyright 2001.
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
    public class H02CBE
    {
     // Specify data file as a command line argument.
     // It defaults to the named file specified below otherwise.
     static string datafile = "ExampleData/h02cbe.d";

        const int nin = 5;
        const int lintvr = 1;
        const int nmax = 10;
        const int ncmax = 10;
        const int lda = ncmax;
        const int ldh = nmax;
        const int liwrk = 1000;
        const int lwrk = 10000;
        const int mdepth = 30;

        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
        {
            H.H02CB_QPHESS e04nfuH02CBF = new H.H02CB_QPHESS(H.h02cbv);
            H.H02CB_MONIT h02cbuH02CBF = new H.H02CB_MONIT(H.h02cbu);
            DataReader sr = new DataReader(datafile);
            double obj = 0.0;
            int i = 0,
            j = 0,
            n = 0,
            nclin = 0,
            strtgy = 0;
            double[,] a = new double[lda, nmax];
            double[] ax = new double[10];
            double[] bl = new double[20];
            double[] bu = new double[20];
            double[] clamda = new double[20];
            double[] cvec = new double[10];
            double[,] h = new double[ldh, nmax];
            double[] wrk = new double[10000];
            double[] xs = new double[20];
            int[] intvar = new int[1];
            int[] istate = new int[20];
            int[] iwrk = new int[1000];
            int ifail;
            Console.WriteLine("h02cb Example Program Results");
            //      Skip heading in data file
            sr.Reset();
            sr.Reset();
            n = int.Parse(sr.Next());
            nclin = int.Parse(sr.Next());
            if ((n <= nmax) && (nclin <= ncmax))
            {
                //
                //         Read CVEC, A, BL, BU, XS and H from data file
                //
                sr.Reset();
                for (i = 1; i <= n; i++)
                {
                    cvec[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }
                sr.Reset();
                for (i = 1; i <= nclin; i++)
                {
                    for (j = 1; j <= n; j++)
                    {
                        a[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                    }
                }
                sr.Reset();
                for (i = 1; i <= n + nclin; i++)
                {
                    bl[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }
                sr.Reset();
                for (i = 1; i <= n + nclin; i++)
                {
                    bu[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }
                sr.Reset();
                for (i = 1; i <= n; i++)
                {
                    xs[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }
                sr.Reset();
                for (i = 1; i <= n; i++)
                {
                    for (j = 1; j <= n; j++)
                    {
                        h[i - 1, j - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                    }
                }
                //
                strtgy = 2;
                intvar[0] = 4;

                //         Solve the problem
                //
                //
                H.h02cbOptions options = new H.h02cbOptions();
                options.Set("Print Level = 0");
                H.h02cb(n, nclin, a, bl, bu, cvec, h, e04nfuH02CBF, intvar,  mdepth, istate, xs, out obj, ax,
                        clamda, strtgy, h02cbuH02CBF, options, out ifail);
         //
                //         Print out the best integer solution found
                //
                Console.Write(" Optimal Integer Value is = ");
                Console.Write(" {0}", obj);
                Console.WriteLine();
                Console.WriteLine(" Components are ");
                for (i = 1; i <= n; i++)
                {
                    // nested do in write
                    Console.Write("X({0})=", i);
                    Console.Write(xs[i - 1]);
                    Console.WriteLine();
                }
                Console.WriteLine();
                //
            }
            //

        }
    }
}


//      h02ce Example Program Text
//      C# version, NAG Copyright 2012
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
    public class H02CEE
    {
     // Specify data file as a command line argument.
     // It defaults to the named file specified below otherwise.
     static string datafile = "ExampleData/h02cee.d";

        const int nmax = 100;
        const int mmax = 100;
        const int nnzmax = 100;
        const int leniz = 100000;
        const int lenz = 100000;
        const int lintvr = 10;
        const int mdepth = 2000;

        static void Main(String[] args)
        {
            if (args.Length == 1)
            {
                datafile = args[0];
            }
            StartExample();
        }

        public static void StartExample()
        {
            H.H02CE_QPHX qphxH02CEF = new H.H02CE_QPHX(qphx);
            H.H02CE_MONIT monitH02CEF = new H.H02CE_MONIT(monit);
            DataReader sr = new DataReader(datafile);
            double obj = 0.0;
            int i = 0,
            icol = 0,
            iobj = 0,
            j = 0,
            jcol = 0,
            m = 0,
            miniz = 0,
            minz = 0,
            n = 0,
            ncolh = 0,
            nname = 0,
            nnz = 0,
            ns = 0,
            strtgy = 0;
            string start = "";
            double[] a = new double[100];
            double[] bl = new double[200];
            double[] bu = new double[200];
            double[] clamda = new double[200];
            double[] xs = new double[200];
            double[] z = new double[100000];
            int[] ha = new int[100];
            int[] intvar = new int[10];
            int[] istate = new int[200];
            int[] iz = new int[100000];
            int[] ka = new int[101];
            string[] crname = new string[200];
            string[] names = new string[5];
            Console.WriteLine("h02ce Example Program Results");
            //      Skip heading in data file.
            sr.Reset();
            sr.Reset();
            n = int.Parse(sr.Next());
            m = int.Parse(sr.Next());
            int ifail = 0;
            if ((n <= nmax) && (m <= mmax))
            {
                //
                //         Read NNZ, IOBJ, NCOLH, START and NNAME from data file.
                //
                sr.Reset();
                nnz = int.Parse(sr.Next());
                iobj = int.Parse(sr.Next());
                ncolh = int.Parse(sr.Next());
                start = sr.Next();
                nname = int.Parse(sr.Next());
                //
                //         Read NAMES and CRNAME from data file.
                //
                sr.Reset();
                for (i = 1; i <= 5; i++)
                {
                    names[i - 1] = sr.Next();
                }
                sr.Reset();
                for (i = 1; i <= nname; i++)
                {
                    crname[i - 1] = sr.Next();
                }
                //
                //         Read the matrix A from data file. Set up KA.
                //
                jcol = 1;
                ka[jcol - 1] = 1;
                for (i = 1; i <= nnz; i++)
                {
                    //
                    //            Element ( HA( I ), ICOL ) is stored in A( I ).
                    //
                    sr.Reset();
                    a[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                    ha[i - 1] = int.Parse(sr.Next());
                    icol = int.Parse(sr.Next());
                    //
                    if (icol == jcol + 1)
                    {
                        //
                        //               Index in A of the start of the ICOL-th column equals I.
                        //
                        ka[icol - 1] = i;
                        jcol = (int)icol;
                    }
                    else if (icol > jcol + 1)
                    {
                        //
                        //               Index in A of the start of the ICOL-th column equals I,
                        //               but columns JCOL+1,JCOL+2,...,ICOL-1 are empty. Set the
                        //               corresponding elements of KA to I.
                        //
                        for (j = jcol + 1; j <= icol - 1; j++)
                        {
                            ka[j - 1] = i;
                        }
                        ka[icol - 1] = i;
                        jcol = (int)icol;
                    }
                }
                ka[n + 1 - 1] = nnz + 1;
                //
                //         Read BL, BU, ISTATE and XS from data file.
                //
                sr.Reset();
                for (i = 1; i <= n + m; i++)
                {
                    bl[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }
                sr.Reset();
                for (i = 1; i <= n + m; i++)
                {
                    bu[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }
                sr.Reset();
                for (i = 1; i <= n; i++)
                {
                    istate[i - 1] = int.Parse(sr.Next());
                }
                sr.Reset();
                for (i = 1; i <= n; i++)
                {
                    xs[i - 1] = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
                }
                //
                strtgy = 3;
                intvar[0] = 2;
                intvar[1] = 3;
                intvar[2] = 4;
                intvar[3] = 5;
                intvar[4] = 6;
                intvar[5] = 7;
                intvar[6] = -1;
                //
                H.h02ceOptions options = new H.h02ceOptions();

                options.Set("NoList");

                options.Set("Print Level = 0"); ;
                //
                //         Solve the QP problem.
                //
                //

                H.h02ce(n, m, nnz, iobj, ncolh, qphxH02CEF, a, ha, ka, bl, bu, start, names, nname, crname,
                        ref ns, xs, intvar, lintvr, mdepth, istate, out miniz, out minz, out obj, clamda, strtgy,
                        iz, z,
                        monitH02CEF, options, out ifail);
                //
                //         Print out the best integer solution found
                //

                Console.WriteLine();
                Console.WriteLine("Optimal Integer Value is {0:G10}", obj);
                Console.WriteLine();
                Console.WriteLine("Components are:");

                for (i = 0; i < n; i++)
                {
                    Console.WriteLine("x[{0}]={1:G10}", i, xs[i]);

                }

            }

        }
        //
        public static void qphx(int nstate, int ncolh, double[] x, double[] hx)
        {
            //
            //      Routine to compute H*x. (In this version of QPHX, the Hessian
            //      matrix H is not referenced explicitly.)
            //
            const double two = 2.00e+0;
            hx[0] = two * x[0];
            hx[1] = two * x[1];
            hx[2] = two * (x[2] + x[3]);
            hx[3] = hx[2];
            hx[4] = two * x[4];
            hx[5] = two * (x[5] + x[6]);
            hx[6] = hx[5];
            //
        }
        //
        public static void monit(int intfnd, int nodes, int depth, double obj, double[] x,
                                  ref double bstval, double[] bstsol, double[] bl, double[] bu, int n, ref bool halt, ref int count)
        {
            const double cutoff = -1847510.00e+0;
            if (intfnd == 0)
            {
                bstval = cutoff;
            }
            //
        }
    }
}


h02ce Example Program Results

Optimal Integer Value is -1847518

Components are:
x[0]=0
x[1]=355
x[2]=645
x[3]=164
x[4]=410
x[5]=275
x[6]=151


// sum_tuple declaration

let sum_tuple (a,b) = a + b;;

// sum_curried declaration

let sum_curried a  b = a + b;;

// sum_ref declaration

let sum_ref (a,b,r) = r := a + b;;

// sum_byref declaration

let sum_byref (a,b,r:byref<int>) = r <- a + b;;

// Simple sum examples

let r1 = sum_tuple (1,2);;

let r2 = sum_curried 1 2;;

let rr3 = ref 0;;

sum_ref (1,2,rr3);;

let r3 = !rr3;;

let mutable r4 = 0;;

sum_byref(1,2,&r4);;

printfn "r4=%i" r4;;

// composing sum examples (functional)

let c1=sum_tuple (sum_tuple(1,1),sum_tuple(2,2));;

let c2=sum_curried (sum_curried 1 1) (sum_curried 2 2);;

// composing sum examples (imperative)

let r3a = ref 0;;

let r3b = ref 0;;

let r3c = ref 0;;

sum_ref (1,1,r3a);;

sum_ref (2,2,r3b);;

sum_ref (!r3a,!r3b,r3c);;

let c3 = !r3c;;

let mutable r4a = 0;;

let mutable r4b = 0;;

let mutable c4 = 0;;

sum_byref (1,1,&r4a);;

sum_byref (2,2,&r4b);;

sum_byref (r4a,r4b,&c4);;

printfn "c4=%i" c4;;

// mysum declaration and use

let  mysum a b =
   let r = ref 0
   sum_ref(a,b,r)
   !r ;;

let c5=mysum(mysum 1 1) (mysum 2 2);;

// NAG Library reference for fsi

#if INTERACTIVE
#I @"c:\Program Files\NAG\NAG Library for .NET"
#r "NagLibrary32.dll"
#endif
open System
open NagLibrary

// a00ac example

printfn "Have a NAG licence: %b" (A00.a00ac())

// d01ah example: direct call

let if1 = ref 0
let mutable npts=0
let relerr= ref 0.0
let f x = Math.Sin(x:double)
let nlimit=1000
let ff= D01.D01AH_F(f)
let result1 = D01.d01ah(0.0,Math.PI,0.01,&npts,relerr,ff,nlimit, if1);;

printfn "!if1=%i" !if1;;

printfn "npts=%i" npts;;

printfn "!relerr=%f" !relerr;

// d01ah example: returning a tuple

let (result2,if2) = D01.d01ah(0.0,Math.PI,0.01,&npts, relerr,(fun x -> f x),nlimit);;

printfn "npts=%i" npts;;

printfn "!relerr=%f" !relerr;;

// declaration of myd01ah: curried, returning a record

type d01ahresults = { result: float ; npts: int ; relerr: float; ifail: int }

let myd01ah f interval epsr nlimit =
    let ff=D01.D01AH_F(f)
    let (a,b) = interval
    let npts = ref 0
    let relerr = ref 0.0
    let ifl = ref 0
    let result = D01.d01ah(a,b,epsr,npts,relerr,ff,nlimit,ifl)
    {result= result; npts= !npts;relerr= !relerr;ifail= !ifl} ;;

// using myd01ah

let _ = myd01ah Math.Sin (0.0,Math.PI) 0.01 1000 ;;

// declaration of mye04ab: curried, returning a record

type  e04abresults = { minimum: float ; x: float; bounds: (float*float);
                       iter: int; ifail: int }

let mye04ab f interv  e1 e2  mc =
    let a,b = interv
    let ra = ref a
    let rb = ref b
    let fx = ref 0.0
    let x = ref 0.0
    let mcr = ref mc
    let ifr = ref 0
    E04.e04ab((fun x res -> res <- f x ), ref e1, ref e2, ra, rb, mcr ,x, fx ,ifr)
    {minimum = !fx; x = !x;bounds = (!ra,!rb); iter= !mcr; ifail = !ifr} ;;

// using mye04ab

let _ = mye04ab (fun x ->  (Math.Sin x) / x) (3.0,5.0) 0.0 0.0 30 ;;


// This example of calling the NAG Library for .NET  by David carlisle,
// based on an example form application from the F# sample distribution
// carrying the notice:

// Copyright (c) Microsoft Corporation 2005-2006.
// This sample code is provided "as is" without warranty of any kind.
// We disclaim all warranties, either express or implied, including the
// warranties of merchantability and fitness for a particular purpose.

# light
#if INTERACTIVE
#I @"c:\Program Files\NAG\DTW02"
#r "NagLibrary32.dll"
#endif
open System
open System.Windows.Forms
open NagLibrary

// first form example

// declaration of  mye04cb
let mye04cb n x tolf tolx func monit maxcal =
    let ffunc = new E04.E04CB_FUNCT(fun n xc (res:byref<float>) -> res <- func xc)
    let fmonit = new E04.E04CB_MONIT(monit)
    let ifl = ref 0
    let rf = ref 0.0
    E04.e04cb(n,x,rf,tolx,tolf,ffunc,fmonit,maxcal,ifl)
    (x,!rf)

// object function for e04cb example
let mutable e04cbf = fun (xc: float[]) ->
    Math.Exp(xc.[0]) * (4.00e0 * xc.[0] * (xc.[0] + xc.[1]) + 2.00e0 * xc.[1] * (xc.[1] + 1.00e0) + 1.00e0);
(*
// Update e04cb object function
e04cbf <- fun (xc: float[]) -> 1.0;;
*)

// e04cb example bounds
let mutable e04cbx = [|-1.0;1.0|]

// second form example

// declaration of mye04xa
let mye04xa mlevel n epsrf x mode objfun hforw =
    let objf = ref 0.0
    let objgrd :float array = Array.zeroCreate n
    let hcntrl :float array = Array.zeroCreate n
    let h :float [,] = Array2D.zeroCreate n n
    let info : int array = Array.zeroCreate n
    let mref = ref mode
    let objfref = ref 0.0
    let warnref = ref 0
    let ifailref = ref 0
    let objfund = E04.E04XA_OBJFUN(fun (a:byref<int>) b c (d:byref<float>) e f ->
                    d <- objfun a b c d e f
                    )
    E04.e04xa (mlevel,n,epsrf,x,mref,objfund,hforw,objfref,objgrd,hcntrl,h,warnref,info,ifailref)
    (!objfref,objgrd,hcntrl,h,!warnref)

let e04xaobjfun int n (x: float array) objf objgrd nstate =
  let a = x.[0] + 10.0*x.[1]
  let b = x.[2] - x.[3]
  let c = x.[1] - 2.0*x.[2]
  let d = x.[0] - x.[3]
  a*a + 5.0*b*b + c*c*c*c + 10.0*d*d*d*d

// form setup

let form = new Form()
form.Width  <- 900
form.Height <- 300
form.Visible <- true
form.Text <- "NAG Example Form"

// Menu bar, menus
let mMain = form.Menu <- new MainMenu()
let mFile = form.Menu.MenuItems.Add("Choose &Example")
let miRun1  = new MenuItem("Run example &1 : e04cb")
let _ = mFile.MenuItems.Add(miRun1)
let miRun2  = new MenuItem("Run example &2 : e04xa")
let _ = mFile.MenuItems.Add(miRun2)
let miRun3  = new MenuItem("Run example &3 : e04xa (error)")
let _ = mFile.MenuItems.Add(miRun3)
let miQuit  = new MenuItem("&Quit")
let _ = mFile.MenuItems.Add(miQuit)

// RichTextView
let textB = new RichTextBox()
textB.Dock <- DockStyle.Fill
textB.Font <- new System.Drawing.Font("Courier New", 7.0F)
form.Controls.Add(textB)
// RichTextView
let textB2 = new RichTextBox()
textB2.Dock <- DockStyle.Left
form.Controls.Add(textB2)

// e04cb monit function
let e04cbmonitor  fmin fmax sim n ncall se vr =
        textB.Text <- ( textB.Text + (sprintf "  There have been %d function calls\n" ncall))

// run the e04cb example
let runexmpl1 () =
       textB.BackColor<- Drawing.Color.White
       textB.Text <- "monitor\n"
       textB2.Text <- sprintf "The final function value is ...\n"
       let (interv,vl) = mye04cb  2 e04cbx (Math.Sqrt(X02.x02aj()))
                                 (Math.Sqrt(Math.Sqrt(X02.x02aj())))
                                  e04cbf
                                  e04cbmonitor
                                  100
       textB2.Text <- ( textB2.Text + (sprintf "  %f \n" vl))

// end first eample
//second example

// run the e04xa example
// make mode a parameter just so we can force an error to occur
// in the 3rd example on the menu.
// 10 is not a valid input value for mode.
let runexmpl2 (mode) =
       textB.BackColor<- Drawing.Color.White
       textB.Text <- "monitor\n"
       textB2.Text <- sprintf "The final function value is ...\n"
 // Beta 2 code needed to redirect Console.Out
 // Now we can use PrintManager properties.
 //     let oldOut = Console.Out
 //      let strWriter = new IO.StringWriter()
 //      Console.SetOut(strWriter);
       PrintManager.Message <- (fun s -> textB.Text <- textB.Text + s  + "\n")
       PrintManager.Warning <- (fun s ->
                                 textB.BackColor<- Drawing.Color.Red
                                 textB.Text <- textB.Text + "\nError:\n" + s   + "\n")
       let (objf,z1,z2,z3,z4)=
           mye04xa
             (*mlevel*) 10
             (*n*) 4
             (*epsrf*) 0.0
             (*x*) [|3.0;-1.0;0.0;1.0|]
             (*mode*)  mode
             (*objfun*) e04xaobjfun
             (*hforw*) [|-1.0;-1.0;-1.0;-1.0|]
       textB2.Text <- ( textB2.Text + (sprintf "  %f \n" objf))

 //      Console.SetOut(oldOut)
 //      textB.Text <- strWriter.ToString()
 //      textB2.Text <- ( textB2.Text + (sprintf "  %f \n" objf))

// callbacks
miQuit.Click.Add(fun _ -> form.Close())
miRun1.Click.Add(fun _ -> runexmpl1 ())
miRun2.Click.Add(fun _ -> runexmpl2 (0))
miRun3.Click.Add(fun _ -> runexmpl2 (10))

#if COMPILED
// Run the main code. The attribute marks the startup application thread as "Single
// Thread Apartment" mode, which is necessary for GUI applications.
[<STAThread>]
do Application.Run(form)
#endif


// Learn more about F# at http://fsharp.net

open System
open NagLibrary

let n: int = 4;;
let nclin: int = 1;;
let ncnln: int = 2;;

let  a = Array2D.create 1 4 1.0;;

let bl = [| 1.0; 1.0; 1.0; 1.0; -1.0e25; -1.0e25; 25.0|];;
let bu = [| 5.0; 5.0; 5.0; 5.0; 20.0;40.0; 1.0e25 |];;
let x =[|1.0; 5.0; 5.0; 1.0|];;

let c = Array.create ncnln 0.0;;
let cjac = Array2D.create ncnln n 0.0;;
let clamda = Array.create 7 0.0;;
let objgrd = Array.create n 0.0;;
let r = Array2D.create n n 0.0;;
let work = Array.create nclin 0.0;;
let istate = Array.create 7 0;;
let ifail = ref 0;;
let objf = ref 0.0;;
let iter = ref 0;;
let one: double =  1.00e0;;
let two: double =  2.00e0;;
let options = new E04.e04ucOptions();

options.Set("List");;
options.Set("Print level = 10");;

let objfunE04UCA = new E04.E04UC_OBJFUN(fun (mode:byref<int>) (n) (x) (objf: byref<float>) (objgrd) (nstate) ->
            if ((mode = 0) || (mode = 2)) then
                objf <- x.[0] * x.[3] * (x.[0] + x.[1] + x.[2]) + x.[2]
            if ((mode = 1) || (mode = 2) ) then
                objgrd.[0] <- x.[3] * (two * x.[0] + x.[1] + x.[2])
                objgrd.[1] <- x.[0] * x.[3]
                objgrd.[2] <- x.[0] * x.[3] + one
                objgrd.[3] <- x.[0] * (x.[0] + x.[1] + x.[2]));;

let confunE04UCA = new E04.E04UC_CONFUN(fun (mode:byref<int>) (ncnln) (n) (needc) (x) (c) (cjac) (nstate) ->
            if (nstate = 1) then
                for j = 1 to n-1 do
                    for i = 1 to ncnln-1 do
                        cjac.[i - 1, j - 1] <- 0.0;
                    done
                done
            if (needc.[0] > 0) then
                if (mode = 0 || mode = 2) then
                    c.[0] <- x.[0]**2.0  + x.[1]**2.0 + x.[2]**2.0 + x.[3]**2.0
                if (mode = 1 || mode = 2) then
                    cjac.[0, 0] <- two * x.[0]
                    cjac.[0, 1] <- two * x.[1]
                    cjac.[0, 2] <- two * x.[2]
                    cjac.[0, 3] <- two * x.[3]
            if (needc.[1] > 0) then
                if (mode = 0 || mode = 2) then
                    c.[1] <- x.[0] * x.[1] * x.[2] * x.[3]
                if (mode = 1 || mode = 2) then
                    cjac.[1, 0] <- x.[1] * x.[2] * x.[3]
                    cjac.[1, 1] <- x.[0] * x.[2] * x.[3]
                    cjac.[1, 2] <- x.[0] * x.[1] * x.[3]
                    cjac.[1, 3] <- x.[0] * x.[1] * x.[2]);;

E04.e04uc(n,nclin,ncnln, a, bl, bu, confunE04UCA, objfunE04UCA, iter, istate, c, cjac, clamda, objf , objgrd, r, x, options, ifail);;


//      s01ba Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S01BAE
  {
    static string datafile = "ExampleData/s01bae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {

         PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s01ba Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "       x           y          ifail");
        try
        {
          while (true)
          {
           sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);

           y = S.s01ba(x, out ifail);
            //

            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3} {1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s01ba failed with ifail = {0,5}", ifail);
              break;
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s07aa Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S07AAE
  {
    static string datafile = "ExampleData/s07aae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s07aa Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y         ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s07aa(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s07aa failed with ifail = {0,5}", ifail);
              break;
            }
          }
        }
        catch
        {
          }        //
        }
        catch (Exception e)
        {
          Console.WriteLine(e.Message);
          Console.WriteLine("Exception Raised");
        }
      }
      static void discardmessage(String message)
      {
      }
    }
  }


//      s09aa Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S09AAE
  {
    static string datafile = "ExampleData/s09aae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s09aa Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s09aa(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s09aa failed with ifail = {0,5}", ifail);
            }
          }
        }
        //
        catch
        {
        }
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


s09aa Example Program Data
            -0.5
             0.1
             0.9
             2.0
            -1.5


//      s09ab Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S09ABE
  {
    static string datafile = "ExampleData/s09abe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s09ab Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s09ab(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s09ab failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


s09ab Example Program Data
            -0.5
             0.1
             0.9
             2.0
            -1.5


//      s10aa Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S10AAE
  {
    static string datafile = "ExampleData/s10aae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double x,   y; Console.WriteLine("s10aa Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y");
        Console.WriteLine("");
        try
        {
          while ( true )
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            y = S.s10aa(x);
            //
            Console.WriteLine("  {0,12:e3}{1,12:e3}", x, y);
          }
        }
        catch
        {
        }
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


s10aa Example Program Data
           -20.0
            -5.0
             0.5
             5.0


//      s10ab Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S10ABE
  {
    static string datafile = "ExampleData/s10abe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s10ab Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s10ab(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s10ab failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


s10ab Example Program Data
           -10.0
            -0.5
             0.0
             0.5
            25.0


//      s10ac Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S10ACE
  {
    static string datafile = "ExampleData/s10ace.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s10ac Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s10ac(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s10ac failed with ifail = {0,5}", ifail);
            }
          }
          //
        }
        catch
        {
        }
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


s10ac Example Program Data
           -10.0
            -0.5
             0.0
             0.5
            25.0


//      s11aa Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S11AAE
  {
    static string datafile = "ExampleData/s11aae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s11aa Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s11aa(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s11aa failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s11ab Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S11ABE
  {
    static string datafile = "ExampleData/s11abe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; Console.WriteLine("s11ab Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s11ab(x);
            //
            Console.WriteLine("  {0,12:e3}{1,12:e3}", x, y);
          }
          //
        }
        catch
        {
        }
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


s11ab Example Program Data
            -2.0
            -0.5
             1.0
             6.0


//      s11ac Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S11ACE
  {
    static string datafile = "ExampleData/s11ace.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s11ac Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x            y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s11ac(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s11ac failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


s11ac Example Program Data
             1.00
             2.0
             5.0
            10.0
            -0.5


//      s13aa Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S13AAE
  {
    static string datafile = "ExampleData/s13aae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s13aa Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s13aa(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s13aa failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


s13aa Example Program Data
             2.0
             0.0
            -1.0
         -1000.0


//      s13ac Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S13ACE
  {
    static string datafile = "ExampleData/s13ace.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s13ac Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            y = S.s13ac(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s13ac failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


s13ac Example Program Data
             0.2
             0.4
             0.6
             0.8
             1.0


//      s13ad Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S13ADE
  {
    static string datafile = "ExampleData/s13ade.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double x,   y; Console.WriteLine("s13ad Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s13ad(x);
            //
            Console.WriteLine("  {0,12:e3}{1,12:e3}", x, y);
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


s13ad Example Program Data
             0.0
             0.2
             0.4
             0.6
             0.8
             1.0


//      s14aa Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S14AAE
  {
    static string datafile = "ExampleData/s14aae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,    y; int ifail; Console.WriteLine("s14aa Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s14aa(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s14aa failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s14ab Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S14ABE
  {
    static string datafile = "ExampleData/s14abe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,    y; int ifail; Console.WriteLine("s14ab Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s14ab(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s14ab failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s14ac Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S14ACE
  {
    static string datafile = "ExampleData/s14ace.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double f,   x; int ifail;
        Console.WriteLine("s14ac Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "       x        psi(x)-log(x)    ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            f = S.s14ac(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:f4}{1,15:f4}{2,7}", x, f, ifail);
            }
            else
            {
              Console.WriteLine("** s14ac failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


s14ac Example Program Data
0.1
0.5
3.6
8.0


//      s14ad Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S14ADE
  {
    static string datafile = "ExampleData/s14ade.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x = 0.0;
        int i,   m,   n; int ifail;
        Console.WriteLine("s14ad Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0} {1}", "      x            ans[0]         ans[1]      ",
        "   ans[2]         ans[3]       ifail");
        Console.WriteLine("");
        n = 0;
        m = 4;
        double[] ans = new double[m];
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            S.s14ad(x, n, m, ans, out ifail);
            //
            if (ifail >= 0)
            {
              Console.Write("  {0:0.0000E+00}", x);
              for (i = 1; i <= m; i++)
              {
                Console.Write("\t {0:0.####E+00}", ans[i - 1]);
              }
              Console.WriteLine("{0,7}", ifail);
            }
            else
            {
              Console.WriteLine("** s14ad failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


s14ad Example Program Data
0.1
0.5
3.6
8.0


//      s14ae Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S14AEE
  {
    static string datafile = "ExampleData/s14aee.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int k;
        int ifail;
        Console.WriteLine("s14ae Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "   x     k      (d^k/dx^k)psi(x)            ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            k = int.Parse(sr.Next());
            //
            y = S.s14ae(x, k, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,5:f1}{1,5}          {2,12:e4}      {3,7}", x, k, y, ifail);
            }
            else
            {
              Console.WriteLine("** s14ae failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


s14ae Example Program Data
 2.5   2  : Values of X and K


s14ae Example Program Results

    x     k      (d^k/dx^k)psi(x)            ifail

    2.5    2          -2.3620e-001            0


//      s14ba Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S14BAE
  {
    static string datafile = "ExampleData/s14bae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double a,   p,   q,   tol,   x; int ifail;
        Console.WriteLine("s14ba Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        tol = X02.x02aj();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "         a           x           p           q     ifail");
        try
        {
          while (true)
          {
            sr.Reset();
            a = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            S.s14ba(a, x, tol, out p, out q, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:f4}{1,12:f4}{2,12:f4}{3,12:f4}{4,5}", a, x, p, q, ifail);
            }
            else
            {
              Console.WriteLine("** s14ba failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s15ab Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S15ABE
  {
    static string datafile = "ExampleData/s15abe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double x,   y;
        Console.WriteLine("s15ab Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s15ab(x);
            //
            Console.WriteLine("  {0,12:e3}{1,12:e3}", x, y);
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      s15ac Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S15ACE
  {
    static string datafile = "ExampleData/s15ace.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double x,   y; Console.WriteLine("s15ac Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s15ac(x);
            //
            Console.WriteLine("  {0,12:e3}{1,12:e3}", x, y);
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      s15ad Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S15ADE
  {
    static string datafile = "ExampleData/s15ade.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double x,   y;
        Console.WriteLine("s15ad Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s15ad(x);
            //
            Console.WriteLine("  {0,12:e3}{1,12:e3}", x, y);
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


s15ad Example Program Data
           -10.0
            -1.0
             0.0
             1.0
            10.0


//      s15ae Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S15AEE
  {
    static string datafile = "ExampleData/s15aee.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double x,   y; Console.WriteLine("s15ae Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s15ae(x);
            //
            Console.WriteLine("  {0,12:e3}{1,12:e3}", x, y);
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      s15af Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S15AFE
  {
    static string datafile = "ExampleData/s15afe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double x,   y; Console.WriteLine("s15af Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s15af(x);
            //
            Console.WriteLine("  {0,12:e3}{1,12:e3}", x, y);
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      s15ag Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S15AGE
  {
    static string datafile = "ExampleData/s15age.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s15ag Example Program Results");
        //
        //      Skip heading in data file
        //
        sr.Reset();
        //
        Console.WriteLine("");
        Console.WriteLine(" {0}", "       x          erfcx(x)    ifail");
        Console.WriteLine("");
        //
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            //
            y = S.s15ag(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("    {0,13:e5}  {1,13:e5}  {2,3}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s15ag failed with ifail = {0,5}", ifail);
            }
            //
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s17ac Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S17ACE
  {
    static string datafile = "ExampleData/s17ace.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
      try
      {
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s17ac Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s17ac(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s17ac failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s17ad Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S17ADE
  {
    static string datafile = "ExampleData/s17ade.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s17ad Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s17ad(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s17ad failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s17ae Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S17AEE
  {
    static string datafile = "ExampleData/s17aee.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s17ae Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s17ae(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s17ae failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s17af Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S17AFE
  {
    static string datafile = "ExampleData/s17afe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s17af Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s17af(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s17af failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s17ag Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S17AGE
  {
    static string datafile = "ExampleData/s17age.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s17ag Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s17ag(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s17ag failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s17ah Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S17AHE
  {
    static string datafile = "ExampleData/s17ahe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s17ah Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s17ah(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s17ah failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s17aj Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S17AJE
  {
    static string datafile = "ExampleData/s17aje.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s17aj Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s17aj(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s17aj failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s17ak Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S17AKE
  {
    static string datafile = "ExampleData/s17ake.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s17ak Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s17ak(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s17ak failed with ifail = {0,5}", ifail);
            }
          }
        }
        //
        catch
        {
        }
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s17al Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S17ALE
  {
    static string datafile = "ExampleData/s17ale.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        const double zero = 0.00e+0;
        double a,   rel; int i,  mode,  n;
        double[] x = new double[100];
        int ifail;
        Console.WriteLine("s17al Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        rel = Math.Sqrt(X02.x02aj());
        sr.Reset();
        a = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        n = int.Parse(sr.Next());
        mode = int.Parse(sr.Next());
        //
        S.s17al(a, n, mode, rel, x, out ifail);
        //
        if (ifail >= 0)
        {
          Console.WriteLine(" {0}", "   a   n     mode     ifail          rel");
          Console.WriteLine(" {0}", "                             (machine-dependent)");
          Console.WriteLine("");
          Console.WriteLine("  {0,4:f1}{1,4}{2,7}{3,8}            {4,9:e1}", a, n, mode, ifail, rel);
          Console.WriteLine("");
          if (mode == 1)
          {
            Console.WriteLine(" {0}", "Leading N positive zeros of J");
          }
          else if (mode == 2)
          {
            Console.WriteLine(" {0}", "Leading N positive zeros of Y");
          }
          else if (mode == 3)
          {
            if (a == zero)
            {
              Console.WriteLine(" {0}", "Leading N non-negative zeros of J'");
            }
            else
            {
              Console.WriteLine(" {0}", "Leading N positive zeros of J'");
            }
          }
          else if (mode == 4)
          {
            Console.WriteLine(" {0}", "Leading N positive zeros of Y'");
          }
          Console.WriteLine("");
          for (i = 1; i <= n; i++)
          {
            Console.WriteLine(" x = {0,12:e4}", x[i - 1]);
          }
          Console.WriteLine("");
        }
        else
        {
          Console.WriteLine("** s17al failed with ifail = {0,5}", ifail);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


s17al Example Program Data
 0.0  5  1 : Values of A, N and MODE


s17al Example Program Results

    a   n     mode     ifail          rel
                              (machine-dependent)

   0.0   5      1       0             1.1e-008

 Leading N positive zeros of J

 x =  2.4048e+000
 x =  5.5201e+000
 x =  8.6537e+000
 x =  1.1792e+001
 x =  1.4931e+001


//      s17dg Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S17DGE
  {
    static string datafile = "ExampleData/s17dge.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        Complex ai = new Complex(0.0, 0.0), z = new Complex(0.0, 0.0);
        double xxx = ai.re;
        int nz = 0;
        string deriv = "",
        scal = "";
        int ifail;
        Console.WriteLine("s17dg Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "deriv           z            scal          ai            nz     ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            deriv = sr.Next();
            z = Complex.Parse(sr.Next());
            scal = sr.Next();
            //
            S.s17dg(deriv, z, scal, out ai, out nz, out ifail);
            //
            string formattedZ = String.Format("({0,8:f4},{1,7:f4})", z.re, z.im);
            string formattedAI = String.Format("({0,8:f4},{1,8:f4})", ai.re, ai.im);
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,-5} {1}{2,6}    {3,8}{4,5}{5,7}", deriv, formattedZ, scal, formattedAI, nz, ifail);
            }
            else
            {
              Console.WriteLine("** s17dg failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s17dh Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S17DHE
  {
    static string datafile = "ExampleData/s17dhe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        Complex bi = new Complex(0.0, 0.0),
        z = new Complex(0.0, 0.0);
        string deriv = "",
        scal = "";
        int ifail;
        Console.WriteLine("s17dh Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "deriv           z            scal           bi            ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            deriv = sr.Next();
            z = Complex.Parse(sr.Next());
            scal = sr.Next();
            //
            S.s17dh(deriv, z, scal, out bi, out ifail);
            //
            string formattedZ = String.Format("({0,8:f4},{1,7:f4})", z.re, z.im);
            string formattedBI = String.Format("({0,8:f4},{1,8:f4})", bi.re, bi.im);
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,-5} {1}{2,6}    {3,8} {4,7}", deriv, formattedZ, scal, formattedBI, ifail);
            }
            else
            {
              Console.WriteLine("** s17dh failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s18ac Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S18ACE
  {
    static string datafile = "ExampleData/s18ace.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s18ac Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s18ac(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s18ac failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s18ad Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S18ADE
  {
    static string datafile = "ExampleData/s18ade.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s18ad Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s18ad(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s18ad failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s18ae Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S18AEE
  {
    static string datafile = "ExampleData/s18aee.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s18ae Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s18ae(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s18ae failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s18af Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S18AFE
  {
    static string datafile = "ExampleData/s18afe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s18af Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s18af(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s18af failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s18cc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S18CCE
  {
    static string datafile = "ExampleData/s18cce.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s18cc Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s18cc(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s18cc failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s18cd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S18CDE
  {
    static string datafile = "ExampleData/s18cde.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s18cd Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s18cd(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s18cd failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s18ce Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S18CEE
  {
    static string datafile = "ExampleData/s18cee.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y;
        Console.WriteLine("s18ce Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s18ce(x);
            //
            Console.WriteLine("  {0,12:e3}{1,12:e3}", x, y);
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s18cf Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S18CFE
  {
    static string datafile = "ExampleData/s18cfe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        DataReader sr = new DataReader(datafile);
        double x,   y; Console.WriteLine("s18cf Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s18cf(x);
            //
            Console.WriteLine("  {0,12:e3}{1,12:e3}", x, y);
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      s19aa Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S19AAE
  {
    static string datafile = "ExampleData/s19aae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s19aa Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s19aa(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s19aa failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s19ab Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S19ABE
  {
    static string datafile = "ExampleData/s19abe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s19ab Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s19ab(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s19ab failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s19ac Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S19ACE
  {
    static string datafile = "ExampleData/s19ace.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s19ac Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s19ac(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s19ac failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s19ad Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S19ADE
  {
    static string datafile = "ExampleData/s19ade.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; int ifail;
        Console.WriteLine("s19ad Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y        ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s19ad(x, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,12:e3}{1,12:e3}{2,7}", x, y, ifail);
            }
            else
            {
              Console.WriteLine("** s19ad failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s20ac Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S20ACE
  {
    static string datafile = "ExampleData/s20ace.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; Console.WriteLine("s20ac Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x          y");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s20ac(x);
            //
            Console.WriteLine("  {0,12:e3}{1,12:e3}", x, y);
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s20ad Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S20ADE
  {
    static string datafile = "ExampleData/s20ade.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x,   y; Console.WriteLine("s20ad Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "     x           y");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s20ad(x);
            //
            Console.WriteLine("  {0,12:e3}{1,12:e3}", x, y);
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s21ba Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S21BAE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        double rc,   x,   y; int ix;
        int ifail;
        Console.WriteLine("s21ba Example Program Results");
        Console.WriteLine("");
        Console.WriteLine(" {0}", "    x      y        s21ba  ifail");
        Console.WriteLine("");
        for (ix = 1; ix <= 3; ix++)
        {
          x = ix * 0.50e0;
          y = 1.00e0;
          //
          rc = S.s21ba(x, y, out ifail);
          //
          if (ifail >= 0)
          {
            Console.WriteLine("  {0,7:f2}{1,7:f2}{2,12:f4}{3,5}", x, y, rc, ifail);
          }
          else
          {
            Console.WriteLine("** s21ba failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s21bb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S21BBE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        double rf,   x,   y,   z; int ix;
        int ifail;
        Console.WriteLine("s21bb Example Program Results");
        Console.WriteLine("");
        Console.WriteLine(" {0}", "    x      y      z        s21bb  ifail");
        Console.WriteLine("");
        for (ix = 1; ix <= 3; ix++)
        {
          x = ix * 0.50e0;
          y = (ix + 1) * 0.50e0;
          z = (ix + 2) * 0.50e0;
          //
          rf = S.s21bb(x, y, z, out ifail);
          //
          if (ifail >= 0)
          {
            Console.WriteLine("  {0,7:f2}{1,7:f2}{2,7:f2}{3,12:f4}{4,5}", x, y, z, rf, ifail);
          }
          else
          {
            Console.WriteLine("** s21bb failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s21bc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S21BCE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        double rd,   x,   y,   z; int ix,  iy;
        int ifail;
        Console.WriteLine("s21bc Example Program Results");
        Console.WriteLine("");
        Console.WriteLine(" {0}", "    x      y      z        s21bc  ifail");
        Console.WriteLine("");
        for (ix = 1; ix <= 3; ix++)
        {
          x = ix * 0.50e0;
          for (iy = ix; iy <= 3; iy++)
          {
            y = iy * 0.50e0;
            z = 1.00e0;
            //
            rd = S.s21bc(x, y, z, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,7:f2}{1,7:f2}{2,7:f2}{3,12:f4}{4,5}", x, y, z, rd, ifail);
            }
            else
            {
              Console.WriteLine("** s21bc failed with ifail = {0,5}", ifail);
            }
          }
        }

      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s21bd Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S21BDE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        double r,   rj,   x,   y,   z; int ix,  iy,  iz;
        int ifail;
        Console.WriteLine("s21bd Example Program Results");
        Console.WriteLine("");
        Console.WriteLine(" {0}", "    x      y      z      r        s21bd  ifail");
        Console.WriteLine("");
        for (ix = 1; ix <= 3; ix++)
        {
          x = ix * 0.50e0;
          for (iy = ix; iy <= 3; iy++)
          {
            y = iy * 0.50e0;
            for (iz = iy; iz <= 3; iz++)
            {
              z = iz * 0.50e0;
              r = 2.00e0;
              //
              rj = S.s21bd(x, y, z, r, out ifail);
              //
              if (ifail >= 0)
              {
                Console.WriteLine("  {0,7:f2}{1,7:f2}{2,7:f2}{3,7:f2}{4,12:f4}{5,5}", x, y, z, r, rj, ifail);
              }
              else
              {
                Console.WriteLine("** s21bd failed with ifail = {0,5}", ifail);
              }
            }
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s21be Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S21BEE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        double dm,   f,   phi,   pi; int ix;
        int ifail;
        Console.WriteLine("s21be Example Program Results");
        Console.WriteLine("");
        Console.WriteLine(" {0}", "    phi    dm      s21be   ifail");
        Console.WriteLine("");
        //
        pi = X01.x01aa();
        //
        for (ix = 1; ix <= 3; ix++)
        {
          phi = ix * pi / 6.00e0;
          dm = ix * 0.250e0;
          //
          f = S.s21be(phi, dm, out ifail);
          //
          if (ifail >= 0)
          {
            Console.WriteLine("  {0,7:f2}{1,7:f2}{2,12:f4}{3,5}", phi, dm, f, ifail);
          }
          else
          {
            Console.WriteLine("** s21be failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s21bf Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S21BFE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        double dm,   f,   phi,   pi; int ix;
        int ifail;
        Console.WriteLine("s21bf Example Program Results");
        Console.WriteLine("");
        Console.WriteLine(" {0}", "    phi    dm      s21bf   ifail");
        Console.WriteLine("");
        //
        pi = X01.x01aa();
        //
        for (ix = 1; ix <= 3; ix++)
        {
          phi = ix * pi / 6.00e0;
          dm = ix * 0.250e0;
          //
          f = S.s21bf(phi, dm, out ifail);
          //
          if (ifail >= 0)
          {
            Console.WriteLine("  {0,7:f2}{1,7:f2}{2,12:f4}{3,5}", phi, dm, f, ifail);
          }
          else
          {
            Console.WriteLine("** s21bf failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s21bg Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S21BGE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        double dm,   dn,   f,   phi,   pi; int ix;
        int ifail;
        Console.WriteLine("s21bg Example Program Results");
        Console.WriteLine("");
        Console.WriteLine(" {0}", "    dn     phi    dm      s21bg   ifail");
        Console.WriteLine("");
        //
        pi = X01.x01aa();
        //
        for (ix = 1; ix <= 3; ix++)
        {
          phi = ix * pi / 6.00e0;
          dm = ix * 0.250e0;
          dn = (Math.Pow((-1.00e0), (ix + 1))) * ix * 0.10e0;
          //
          f = S.s21bg(dn, phi, dm, out ifail);
          //
          if (ifail >= 0)
          {
            Console.WriteLine("  {0,7:f2}{1,7:f2}{2,7:f2}{3,12:f4}{4,5}", dn, phi, dm, f, ifail);
          }
          else
          {
            Console.WriteLine("** s21bg failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s21bh Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S21BHE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        double dm,   f; int ix;
        int ifail;
        Console.WriteLine("s21bh Example Program Results");
        Console.WriteLine("");
        Console.WriteLine(" {0}", "    dm      s21bh   ifail");
        Console.WriteLine("");
        //
        for (ix = 1; ix <= 3; ix++)
        {
          dm = ix * 0.250e0;
          //
          f = S.s21bh(dm, out ifail);
          //
          if (ifail >= 0)
          {
            Console.WriteLine("  {0,7:f2}{1,12:f4}{2,5}", dm, f, ifail);
          }
          else
          {
            Console.WriteLine("** s21bh failed with ifail = {0,5}", ifail);
          }
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s21bj Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S21BJE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        double dm,   f; int ix;
        int ifail;
        Console.WriteLine("s21bj Example Program Results");
        Console.WriteLine("");
        Console.WriteLine(" {0}", "    dm      s21bj   ifail");
        Console.WriteLine("");
        //
        for (ix = 1; ix <= 3; ix++)
        {
          dm = ix * 0.250e0;
          //
          f = S.s21bj(dm, out ifail);
          //
          if (ifail >= 0)
          {
            Console.WriteLine("  {0,7:f2}{1,12:f4}{2,5}", dm, f, ifail);
          }
          else
          {
            Console.WriteLine("** s21bj failed with ifail = {0,5}", ifail);
          }
        }
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s21ca Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S21CAE
  {
    static string datafile = "ExampleData/s21cae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double cn,   dn,   m,   sn,   u; int ifail;
        Console.WriteLine("s21ca Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.Write(" {0}", "          u            m           sn           cn           dn");
        Console.WriteLine("         ifail");
        try
        {
          while (true)
          {
            sr.Reset();
            u = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            m = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            S.s21ca(u, m, out sn, out cn, out dn, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("      {0,13:e4}{1,13:e4}{2,13:e4}{3,13:e4}{4,13:e4}{5,5}",
              u, m, sn, cn, dn, ifail);
            }
            else
            {
              Console.WriteLine("** s21ca failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


//      s21cb Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S21CBE
  {
    static string datafile = "ExampleData/s21cbe.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        Complex cn = new Complex(0.0, 0.0),
        dn = new Complex(0.0, 0.0),
        sn = new Complex(0.0, 0.0),
        z = new Complex(0.0, 0.0);
        double ak2 = 0.0;
        int ifail;
        Console.WriteLine("s21cb Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            z = Complex.Parse(sr.Next());
            ak2 = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            S.s21cb(z, ak2, out sn, out cn, out dn, out ifail);
            //
            string formattedZ = String.Format("({0,7:f3},{1,7:f3})", z.re, z.im);
            string formattedSn = String.Format("({0,8:f4},{1,8:f4})", sn.re, sn.im);
            string formattedCn= String.Format("({0,8:f4},{1,8:f4})", cn.re, cn.im);
            string formattedDn = String.Format("({0,8:f4},{1,8:f4})", dn.re,dn.im);
            if (ifail >= 0)
            {
              Console.WriteLine(" {0} {1}", "          Z                      AK2", "  ifail");
              Console.WriteLine(" {0}          {1,10:f2}   {2}              ", formattedZ, ak2, ifail);
              Console.WriteLine("");
              Console.WriteLine(" {0} {1}", "         SN                                CN", "                         DN");
              Console.WriteLine("  {0}\t\t{1}\t\t{2}", formattedSn, formattedCn, formattedDn);
            }
            else
            {
              Console.WriteLine("** s21cb failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


s21cb Example Program Data
 (-2.0, 3.0)  0.25 : Values of Z and AK2


//      s21cc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S21CCE
  {
    static string datafile = "ExampleData/s21cce.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double q,   x,   y; int k;
        int ifail;
        Console.WriteLine("s21cc Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        Console.WriteLine("");
        Console.WriteLine(" {0}", "  k     x     q         y           ifail");
        Console.WriteLine("");
        try
        {
          while (true)
          {
            sr.Reset();
            k = int.Parse(sr.Next());
            x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            q = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
            //
            y = S.s21cc(k, x, q, out ifail);
            //
            if (ifail >= 0)
            {
              Console.WriteLine("  {0,2}    {1,4:f1}    {2,4:f1}    {3,12:e4}{4,6}", k, x, q, y, ifail);
            }
            else
            {
              Console.WriteLine("** s21cc failed with ifail = {0,5}", ifail);
            }
          }
        }
        catch
        {
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


s21cc Example Program Data
 2  0.7  0.4  : Values of K, X and Q


s21cc Example Program Results

   k     x     q         y           ifail

   2     0.7     0.4    -6.9289e-001     0


//      s22aa Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class S22AAE
  {
    static string datafile = "ExampleData/s22aae.d";
    static void Main(String[] args)
    {
      if (args.Length == 1)
      {
        datafile = args[0];
      }
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        PrintManager.Warning = new PrintManager.MessageLogger(discardmessage);
        DataReader sr = new DataReader(datafile);
        double x = 0.0;
        int m,   mode,   n,   nl;
        int ifail;
        Console.WriteLine("s22aa Example Program Results");
        //      Skip heading in data file
        sr.Reset();
        sr.Reset();
        mode = int.Parse(sr.Next());
        x = double.Parse(sr.Next(), CultureInfo.InvariantCulture);
        m = int.Parse(sr.Next());
        nl = int.Parse(sr.Next());
        double[] p = new double[nl+1];
        Console.WriteLine("");
        //
        S.s22aa(mode, x, m, nl, p, out ifail);
        //
        if (ifail >= 0)
        {
          Console.WriteLine(" {0}", "mode           x      m    nl   ifail");
          Console.WriteLine("");
          Console.WriteLine("  {0,3}        {1,5:f1}{2,6}{3,6}{4,6}", mode, x, m, nl, ifail);
          Console.WriteLine("");
          if (mode == 1)
          {
            if (m == 0)
            {
              Console.WriteLine(" {0}", "Unnormalized Legendre function values");
            }
            else
            {
              Console.WriteLine(" {0}", "Unnormalized associated Legendre function values");
            }
          }
          else if (mode == 2)
          {
            if (m == 0)
            {
              Console.WriteLine(" {0}", "Normalized Legendre function values");
            }
            else
            {
              Console.WriteLine(" {0}", "Normalized associated Legendre function values");
            }
          }
          Console.WriteLine(" {0}", " n      P(n)");
          for (n = 0; n <= nl; n++)
          {
            Console.WriteLine("  {0,2}  {1,12:e4}", n, p[n - 0]);
          }
        }
        else
        {
          Console.WriteLine("** s22aa failed with ifail = {0,5}", ifail);
        }
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
    static void discardmessage(String message)
    {
    }
  }
}


s22aa Example Program Data
 1   0.5   2   3  : Values of MODE, X, M and NL


s22aa Example Program Results

 mode           x      m    nl   ifail

    1          0.5     2     3     0

 Unnormalized associated Legendre function values
  n      P(n)
   0   0.0000e+000
   1   0.0000e+000
   2   2.2500e+000
   3   5.6250e+000


PrintManager.MessageLogger Delegate

[image]

NAG Library for .NET Release 2
PrintManager..::..MessageLogger Delegate
PrintManager Class See Also Send Feedback
Delegate type to use for messages.

Syntax

C#
public delegate void MessageLogger(
    string message
)
Visual Basic
Public Delegate Sub MessageLogger ( _
    message As String _
)
Visual C++
public delegate void MessageLogger(
    String^ message
)
F#
type MessageLogger =
    delegate of
        message : string -> unit

Parameters

message
Type: System..::..String
The string to be output

See Also

NagLibrary Namespace
NAG Library Overview

Send comments on this topic to support@nag.co.uk


//      x02bb Example Program Text
//      C# version, NAG Copyright 2014
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class X02AJE
  {
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      Console.WriteLine("x02aj Example Program Results");
      Console.WriteLine("The machine precision = {0}", X02.x02aj());
    }
  }
}


x02aj Example Program Results
The machine precision = 1.11022302462516E-16


//      x04ca Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class X04CAE
  {
    const int nmax=5;
    const int mmax=nmax;
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        int i,  j;
        double[,] a = new double[mmax, nmax];
        int ifail;
        Console.WriteLine("x04ca Example Program Results");
        Console.WriteLine("");
        //      Generate an array of data
        for (j = 1 ; j <= nmax ; j++)
        {
          for (i = 1 ; i <= mmax ; i++)
          {
            a[i - 1 , j - 1] = 10 * i + j;
          }
        }
        //
        //
        //      Print 3 by 5 rectangular matrix
        X04.x04ca("General", "", 3, 5, a, "Example 1:", out ifail);
        //
        Console.WriteLine("");
        //
        //      Print 5 by 5 lower triangular matrix
        X04.x04ca("Lower", "Non-unit", 5, 5, a, "Example 2:", out ifail);
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      x04cb Example Program Text
//      Mark 14 Release. NAG Copyright 1989.
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class X04CBE
  {
    const int nmax=5;
    const int lda=nmax;
     static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
        try
        {
            int i = 0,
            indent = 0,
            j = 0,
            ncols = 0;
            double[,] a = new double[lda, nmax];
            string[] clabs = new string[5] { "Un", "Deux", "Trois", "Quatre", "Cinq" };
            string[] rlabs = new string[5] { "Uno", "Duo", "Tre", "Quattro", "Cinque" };
            int ifail;
            Console.WriteLine("x04cb Example Program Results");
            Console.WriteLine("");
            //      Generate an array of data
            for (j = 1; j <= nmax; j++)
            {
                for (i = 1; i <= lda; i++)
                {
                    a[i - 1, j - 1] = 10 * i + j;
                }
            }
            ncols = 80;
            indent = 0;
            //
            //      Print 3 by 5 rectangular matrix with default format and integer
            //      row and column labels
            X04.x04cb("General", "", 3, 5, a, "", "Example 1:", "Integer", rlabs, "Integer", clabs, ncols, indent, out ifail);
            //
            Console.WriteLine("");
            //
            //      Print 5 by 5 upper triangular matrix with user-supplied format
            //      and row and column labels
            X04.x04cb("Upper", "Non-unit", 5, 5, a, "F8.2", "Example 2:", "Character", rlabs, "Character", clabs, ncols, indent, out ifail);
            //
        }
        catch (Exception e)
        {
            Console.WriteLine(e.Message);
            Console.WriteLine("Exception Raised");
        }
      }
    }

}


//      x04cc Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class X04CCE
  {
    const int nmax=5;
    const int la=(nmax * (nmax + 1)) / 2;
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        int i;
        double[] a = new double[15];
        int ifail;
        Console.WriteLine("x04cc Example Program Results");
        Console.WriteLine("");
        //
        //      Generate an array of data
        for (i = 1 ; i <= la ; i++)
        {
          a[i - 1] = i;
        }
        //
        //
        //      Print order 4 lower triangular matrix
        X04.x04cc("Lower", "Unit", 4, a, "Example 1:", out ifail);
        //
        Console.WriteLine("");
        //
        //      Print order 5 upper triangular matrix
        X04.x04cc("Upper", "Non-unit", 5, a, "Example 2:", out ifail);
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      x04ce Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class X04CEE
  {
    const int nmax=5;
    const int lda=nmax;
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        int i,  j;
        double[,] a = new double[lda, nmax];
        int ifail;
        Console.WriteLine("x04ce Example Program Results");
        Console.WriteLine("");
        //
        //      Generate an array of data
        for (j = 1 ; j <= nmax ; j++)
        {
          for (i = 1 ; i <= lda ; i++)
          {
            a[i - 1 , j - 1] = 10 * i + j;
          }
        }
        //
        //
        //      Print 5 by 5 band matrix with 1 sub-diagonal and 1 super-diagonal
        X04.x04ce(5, 5, 1, 1, a, "Band Matrix:", out ifail);
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


//      x04db Example Program Text
//      C# version, NAG Copyright 2008
using System;
using NagLibrary;
using System.Globalization;
namespace NagDotNetExamples
{
  public class X04DBE
  {
    const int nmax=4;
    const int lda=nmax;
    static void Main(String[] args)
    {
      StartExample();
    }
    public static void StartExample()
    {
      try
      {
        double aa=0.0;
        int i,  indent,  j,  ncols;
        Complex[,] a = new Complex[lda, nmax];
        string[] clabs = new string[4] {"Un", "Deux", "Trois", "Quatre"};
        string[] rlabs = new string[4] {"Uno", "Duo", "Tre", "Quattro"};
        int ifail;
        Console.WriteLine("x04db Example Program Results");
        Console.WriteLine("");
        //      Generate an array of data
        for (j = 1 ; j <= nmax ; j++)
        {
          for (i = 1 ; i <= lda ; i++)
          {
            aa = 10 * i + j;
            a[i - 1 , j - 1] = new Complex(aa,  -aa);
          }
        }
        ncols = 80;
        indent = 0;
        //
        //      Print 3 by 4 rectangular matrix with default format and integer
        //      row and column labels, and bracketed complex elements
        X04.x04db("General", "", 3, 4, a, "Bracketed", "", "Example 1:", "Integer", rlabs, "Integer", clabs, ncols, indent, out ifail);
        //
        Console.WriteLine("");
        //
        //      Print 4 by 4 upper triangular matrix with user-supplied format
        //      and row and column labels, and complex elements with real part
        //      above imaginary part
        X04.x04db("Upper", "Non-unit", 4, 4, a, "Above", "F8.2", "Example 2:", "Character", rlabs, "Character", clabs, ncols, indent, out ifail);
        //
      }
      catch (Exception e)
      {
        Console.WriteLine(e.Message);
        Console.WriteLine("Exception Raised");
      }
    }
  }
}


This is release branch v2.1 of MathJax.