library Subpackage

Package Summary

Interfaces for accessing the NAG Library from Python.

Subpackage Summary

The examples subpackage supplies example scripts for a selection of functions. The subpackage is divided into further subpackages to match the algorithmic subcategorization of the NAG Library, as below.

You may run the examples subpackage as a module by invoking

python -m naginterfaces.library.examples

Submodule Summary

Python interfaces are available for the following algorithmic submodules.

anova - Analysis of Variance (g04)

This module is concerned with methods for analysing the results of designed experiments. The range of experiments covered include:

single factor designs with equal sized blocks such as randomized complete block and balanced incomplete block designs,

row and column designs such as Latin squares, and

complete factorial designs.

Further designs may be analysed by combining the analyses provided by multiple calls to functions or by using general linear model functions provided in submodule correg.

blas - Linear Algebra Support Routines (f06)

This module is concerned with basic linear algebra functions which perform elementary algebraic operations involving scalars, vectors and matrices. It includes functions which conform to the specifications of the BLAS (Basic Linear Algebra Subprograms).

blast - Further Linear Algebra Support Routines (f16)

This module is concerned with basic linear algebra functions which perform elementary algebraic operations involving scalars, vectors and matrices. Most functions for such operations conform either to the specifications of the BLAS (Basic Linear Algebra Subprograms) or to the specifications of the BLAST (Basic Linear Algebra Subprograms Technical) Forum. This module includes functions from the BLAST specifications. Most (BLAS) functions for such operations are available in submodule blas.

blgm - Linear Model Specification (g22)

The functions in this module provide a mechanism for specifying a linear model using a text based modelling language and are intended to be used in conjunction with the model fitting functions from other modules, for example submodule correg.

complex - Complex Arithmetic (a02)

This module provides facilities for arithmetic operations involving complex numbers.

contab - Contingency Table Analysis (g11)

The functions in this module are for the analysis of discrete multivariate data. One suite of functions computes tables while other functions are for the analysis of two-way contingency tables, conditional logistic models and one-factor analysis of binary data.

Functions in submodule correg may be used to fit generalized linear models to discrete data including binary data and contingency tables.

correg - Correlation and Regression Analysis (g02)

This module is concerned with two techniques

  1. correlation analysis and

  2. regression modelling,

both of which are concerned with determining the inter-relationships among two or more variables.

Other modules of the NAG Library which cover similar problems are submodule fit and submodule opt. Submodule fit functions may be used to fit linear models by criteria other than least squares and also for polynomial regression; submodule opt functions may be used to fit nonlinear models and linearly constrained linear models.

det - Determinants (f03)

This module is concerned with the calculation of determinants of square matrices.

dot - Inner Products (x03)

This module is concerned with the calculation of innerproducts required by other functions within the NAG Library.

eigen - Eigenvalues and Eigenvectors (f02)

This module provides functions for various types of matrix eigenvalue problem:

standard eigenvalue problems (finding eigenvalues and eigenvectors of a square matrix );

singular value problems (finding singular values and singular vectors of a rectangular matrix );

generalized eigenvalue problems (finding eigenvalues and eigenvectors of a matrix pencil ).

quadratic eigenvalue problems (finding eigenvalues and eigenvectors of the quadratic ).

Functions are provided for both real and complex data.

The majority of functions for these problems can be found in submodule lapackeig which contains software derived from LAPACK (see Anderson et al. (1999)). However, you should read the F02 Introduction before turning to submodule lapackeig, especially if you are a new user. Submodule sparseig contains functions for large sparse eigenvalue problems, although one such function is also available in this module.

Submodule eigen and submodule lapackeig contain Black Box (or Driver) functions that enable many problems to be solved by a call to a single function, and the decision trees in Decision Trees direct you to the most appropriate functions in submodule eigen and submodule lapackeig. The submodule eigen functions call functions in submodule lapacklin and submodule lapackeig wherever possible to perform the computations, and there are pointers in Decision Trees to the relevant decision trees in submodule lapackeig.

fit - Curve and Surface Fitting (e02)

The main aim of this module 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 function then derives for the coefficients the values which provide the best fit of that particular form. The module 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 functions (some of which are contained in other modules) 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 module also contains functions for evaluating, differentiating and integrating polynomial and spline curves and surfaces, once the numerical values of their coefficients have been determined.

There is also a function for computing a Padé approximant of a mathematical function (see Background to the Problems).

glopt - Global Optimization of a Function (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. Where submodule opt treats local nonlinear optimization problems as well as convex optimization problems (for which local optima are by definition also global), this module tries to handle finding global optima of non-convex nonlinear optimization problems. Such problems can be much harder to solve than local optimization problems 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.

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, see Neumaier (2004). Furthermore, much of the material in the E04 Introduction is also relevant in this context and it is strongly recommended that you read the E04 Introduction.

Some solvers in this module have been integrated in to the NAG optimization modelling suite, which provides an easy-to-use and flexible way of defining optimization problems among numerous solvers of the NAG library. All utility routines from the suite can be used to define a compatible problem to be solved by the integrated solvers; see the E04 Introduction for more details.

ieee - IEEE Arithmetic (x07)

This module provides functions to handle various aspects of IEEE floating-point arithmetic behaviour.

info - Library Identification (a00)

The functions in this module provide information about the NAG Library.

Information about the precise implementation of the NAG Library in use will be needed when communicating with the NAG Technical Support Service (see Support from NAG).

inteq - Integral Equations (d05)

This module is concerned with the numerical solution of integral equations. Provision will be made for most of the standard types of equation (see Background to the Problems). The following are, however, specifically excluded:

  1. Equations arising in the solution of partial differential equations by integral equation methods. In cases where the prime purpose of an algorithm is the solution of a partial differential equation it will normally be included in submodule pde.

  2. Calculation of inverse integral transforms. This problem falls within the scope of submodule sum.

interp - Interpolation (e01)

This module 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 functions provide either an interpolating function or an interpolated value. For some of the interpolating functions, there are supporting NAG Library functions to evaluate, differentiate or integrate them.

lapackeig - Least Squares and Eigenvalue Problems (LAPACK) (f08)

This module provides functions for the solution of linear least squares problems, eigenvalue problems and singular value problems, as well as associated computations. It provides functions 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.

Functions 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 submodule linsys. The decision trees, at the end of submodule linsys, direct you to the most appropriate functions in submodule linsys or submodule lapackeig. Submodule linsys and submodule lapackeig contain Black Box (or driver) functions which enable standard linear least squares problems to be solved by a call to a single function.

For a general introduction to eigenvalue and singular value problems, you should turn first to submodule eigen. The decision trees, at the end of submodule eigen, direct you to the most appropriate functions in submodule eigen or submodule lapackeig. Submodule eigen and submodule lapackeig contain Black Box (or driver) functions which enable standard types of problem to be solved by a call to a single function. Often functions in submodule eigen call submodule lapackeig functions to perform the necessary computational tasks.

The functions in this module (submodule lapackeig) handle only dense, band, tridiagonal and Hessenberg matrices (not matrices with more specialised structures, or general sparse matrices). The tables in Available Functions and the decision trees in Decision Trees direct you to the most appropriate functions in submodule lapackeig.

The functions in this module 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.

lapacklin - Linear Equations (LAPACK) (f07)

This module provides functions for the solution of systems of simultaneous linear equations, and associated computations. It provides functions 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.

Functions 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 the F04 Introduction. The decision trees, in the F04 Introduction, direct you to the most appropriate functions in submodule linsys or submodule lapacklin for solving your particular problem. In particular, submodule linsys and submodule lapacklin contain Black Box (or driver) functions which enable some standard types of problem to be solved by a call to a single function. Where possible, functions in submodule linsys call submodule lapacklin functions to perform the necessary computational tasks.

There are two types of driver functions in this module: 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 functions in this module (submodule lapacklin) handle only dense and band matrices (not matrices with more specialised structures, or general sparse matrices).

The functions in this module 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.

linsys - Simultaneous Linear Equations (f04)

This module is concerned with the solution of the matrix equation , where may be a single vector or a matrix of multiple right-hand sides. The matrix may be real, complex, symmetric, Hermitian, positive definite, positive definite Toeplitz or banded. It may also be rectangular, in which case a least squares solution is obtained.

Much of the functionality of this module has been superseded by functions from submodule lapacklin and submodule lapackeig (LAPACK routines) as those modules have grown and have included driver and expert driver functions.

For a general introduction to sparse systems of equations, see the F11 Introduction, which provides functions for large sparse systems. Some functions for sparse problems are also included in this module; they are described in Sparse Matrix Functions.

machine - Machine Constants (x02)

This module 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 NAG Library to another, but within the context of a single implementation they are constants.

The parameters are intended for use primarily by other functions in the NAG Library, but users of the NAG Library may sometimes need to refer to them directly.

math - Mathematical Constants (x01)

This module is concerned with the provision of mathematical constants required by other functions within the NAG Library.

matop - Matrix Operations, Including Inversion (f01)

This module provides facilities for four types of problem:

  1. matrix inversion;

  2. matrix factorizations;

  3. matrix arithmetic and manipulation;

  4. matrix functions.

See Background to the Problems where these problems are discussed.

mesh - Mesh Generation (d06)

This module is concerned with automatic mesh generation

with line segments, over the boundary of a closed two-dimensional connected polygonal domain;

with triangles, over a given two-dimensional region using only its boundary mesh.

mip - Operations Research (h)

This module provides functions to solve certain integer programming, transportation and shortest path problems. Additionally ‘best subset’ functions are included.

mv - Multivariate Methods (g03)

This module 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 module 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 submodule correg.

nonpar - Nonparametric Statistics (g08)

The functions in this module perform nonparametric statistical tests which are based on distribution-free methods of analysis. For convenience, the module contents are divided into five types of test: tests of location, tests of dispersion, tests of distribution, tests of association and correlation, and tests of randomness. There are also functions to fit linear regression models using the ranks of the observations.

The emphasis in this module is on testing; if you wish to compute nonparametric correlations you are referred to submodule correg, which contains several functions for that purpose.

There are a large number of nonparametric tests available. A selection of some of the more commonly used tests are included in this module.

numdiff - Numerical Differentiation (d04)

This module is concerned with calculating approximations to derivatives of a function .

ode - Ordinary Differential Equations (d02)

This module is concerned with the numerical solution of ordinary differential equations. There are two main types of problem: those in which all boundary conditions are specified at one point (initial value problems), and those in which the boundary conditions are distributed between two or more points (boundary value problems and eigenvalue problems). Functions are available for initial value problems, two-point boundary value problems and Sturm–Liouville eigenvalue problems.

omp - OpenMP Utilities (x06)

This module contains utilities for controlling the OpenMP environment for your program. They are based on OpenMP runtime library routines, although their functionality varies slightly.

opt - Minimizing or Maximizing a Function (e04)

This module provides functions for solving various mathematical optimization problems by solvers based on local stopping criteria. The main classes of problems covered in this module are:

Linear Programming (LP) – dense and sparse;

Quadratic Programming (QP) – convex and nonconvex, dense and sparse;

Quadratically Constrained Quadratic Programming (QCQP) – convex and nonconvex;

Nonlinear Programming (NLP) – dense and sparse, based on active-set SQP methods or interior point methods (IPM);

Second-order Cone Programming (SOCP);

Semidefinite Programming (SDP) – both linear matrix inequalities (LMI) and bilinear matrix inequalities (BMI);

Derivative-free Optimization (DFO);

Least Squares (LSQ) – linear and nonlinear, constrained and unconstrained;

General Nonlinear Data Fitting (NLDF) – nonlinear loss functions with regularization, constrained and unconstrained.

For a full overview of the functionality offered in this module, see the functionality index or the Module Contents (submodule opt).

See also other modules in the NAG Library relevant to optimization:

submodule glopt contains functions to solve global optimization problems;

submodule mip addresses problems arising in operational research and focuses on Mixed Integer Programming (MIP);

submodule lapacklin and submodule lapackeig include functions for linear algebra and in particular unconstrained linear least squares;

submodule fit focuses on curve and surface fitting, in which linear data fitting in or norm might be of interest;

submodule correg offers several regression (data fitting) functions, including linear, nonlinear and quantile regression, LARS, LASSO and others.

orthog - Orthogonalization (f05)

This module is concerned with the orthogonalization of vectors in a finite dimensional space.

pde - Partial Differential Equations (d03)

This module is concerned with the numerical solution of partial differential equations.

quad - Quadrature (d01)

This module provides functions for the numerical evaluation of definite integrals in one or more dimensions and for evaluating weights and abscissae of integration rules.

rand - Random Number Generators (g05)

This module is concerned with the generation of sequences of independent pseudorandom and quasi-random numbers from various distributions, and models.

rnla - Randomized Numerical Linear Algebra (f10)

This module covers linear algebra functions that make use of random projections to reduce problem dimension. This area is referred to as RNLA (Randomized Numerical Linear Algebra). The functions can be split into the following categories:

building blocks that are intended to be used as components in RNLA algorithms written by you;

RNLA algorithms for matrix factorization.

It is envisaged that users of the higher-level functions, such as matrix factorization, will have some background in linear algebra. A common use case would be that you have tried solving your problem using a deterministic linear algebra function, e.g., an LAPACK function from submodule lapackeig, and are in need of a function that is more computationally efficient.

Users of the building block functions would be expected to have some familiarity with the RNLA literature, i.e., a higher level of expertise.

roots - Roots of One or More Transcendental Equations (c05)

This module 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.

smooth - Smoothing in Statistics (g10)

This module is concerned with methods for smoothing data. Included are methods for density estimation, smoothing time series data, and statistical applications of splines. These methods may also be viewed as nonparametric modelling.

sort - Sorting and Searching (m01)

This module is concerned with sorting and searching numeric or character data. It handles only the simplest types of data structure and it is concerned only with internal sorting and searching – that is, sorting and searching a set of data which can all be stored within the program.

If you have large files of data or complicated data structures to be sorted or searched you should use a comprehensive sorting or searching program or package.

sparse - Large Scale Linear Systems (f11)

This module provides functions for the solution of large sparse systems of simultaneous linear equations. These include iterative methods for real nonsymmetric and symmetric, complex non-Hermitian and Hermitian linear systems and direct methods for general real linear systems. Further direct methods are currently available in submodule matop and submodule linsys.

sparseig - Large Scale Eigenproblems (f12)

This module provides functions for computing some eigenvalues and eigenvectors of large-scale (sparse) standard and generalized eigenvalue problems. It provides functions for:

solution of symmetric eigenvalue problems;

solution of nonsymmetric eigenvalue problems;

solution of generalized symmetric-definite eigenvalue problems;

solution of generalized nonsymmetric eigenvalue problems;

solution of polynomial eigenvalue problems;

partial singular value decomposition.

Functions are provided for both real and complex data.

ARPACK Functions

The functions in this module whose names do not contain substring ‘_feast_’ have all been derived from the ARPACK software suite (see Lehoucq et al. (1998)), a collection of Fortran 77 functions designed to solve large scale eigenvalue problems. The interfaces provided in this module have been chosen to combine ease of use with the flexibility of the original ARPACK software. The underlying iterative methods and algorithms remain essentially the same as those in ARPACK and are described fully in Lehoucq et al. (1998).

The algorithms used in the ARPACK functions are based upon an algorithmic variant of the Arnoldi process called the Implicitly Restarted Arnoldi Method. For symmetric matrices, this reduces to a variant of the Lanczos process called the Implicitly Restarted Lanczos Method. These variants may be viewed as a synthesis of the Arnoldi/Lanczos process with the Implicitly Shifted technique that is suitable for large scale problems. For many standard problems, a matrix factorization is not required. Only the action of the matrix on a vector is needed.

The ARPACK functions can be used to find the eigenvalues with the largest and/or smallest magnitudes, real part or imaginary part.

FEAST Functions

The functions in this module whose names contain substring ‘_feast_’ have been derived from the FEAST software suite (see Polizzi (2009)). FEAST is a general purpose eigensolver for standard, generalized and polynomial eigenvalue problems. It is suitable for both sparse and dense matrices, and functions are available for real, complex, symmetric, Hermitian and non-Hermitian eigenvalue problems. The FEAST algorithm requires you to specify a particular region of interest in the complex plane within which eigenvalues are sought. The algorithm then performs a numerical quadrature computation, involving solving linear systems along a complex contour around the region of interest.

specfun - Approximations of Special Functions (s)

This module is concerned with the provision of some commonly occurring physical and mathematical functions.

stat - Simple Calculations on Statistical Data (g01)

This module covers the following topics:

descriptive statistics and exploratory data analysis;

statistical distribution functions and their inverses;

testing for Normality and other distributions.

sum - Summation of Series (c06)

This module is concerned with the following tasks:

  1. calculating the discrete Fourier transform of a sequence of real or complex data values;

  2. calculating the discrete convolution or the discrete correlation of two sequences of real or complex data values using discrete Fourier transforms;

  3. calculating the inverse Laplace transform of a user-supplied function;

  4. calculating the fast Gauss transform approximation to the discrete Gauss transform;

  5. direct summation of orthogonal series;

  6. acceleration of convergence of a sequence of real values.

surviv - Survival Analysis (g12)

This module is concerned with statistical techniques used in the analysis of survival/reliability/failure time data.

Other modules contain functions which are also used to analyse this type of data. Submodule correg contains generalized linear models, submodule univar contains functions to fit distribution models, and submodule nonpar contains rank based methods.

tsa - Time Series Analysis (g13)

This module 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 module 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 (linear and nonlinear);

  7. GARCH models for volatility;

  8. inhomogeneous time series.

univar - Univariate Estimation (g07)

This module deals with the estimation of unknown parameters of a univariate distribution. It includes both point and interval estimation using maximum likelihood and robust methods.

wav - Wavelet Transforms (c09)

This module 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, , (called the mother wavelet) such that

where gives the scaling and determines the translation. Wavelet methods can be divided into continuous transforms and discrete transforms. In the continuous case, the pair and are real numbers with . For the discrete transform, and can be chosen as , for integers ,

The continuous real valued, one-dimensional wavelet transform (CWT) is included in this module. 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.

zeros - Zeros of Polynomials (c02)

This module is concerned with computing the zeros of a polynomial with real or complex coefficients.

Functionality Notes

The NAG Library Chapters file and time are not required in this product, so are not supplied.

Raises

NagLicenceError
(errno -399)

Your licence key may have expired or may not have been installed correctly.

Submodules

Subpackages