NAG Library Manual, Mark 30.1

Interfaces: FL CL CPP AD PY MB

NAG FL Interface Introduction

E02 (Fit) Chapter Contents

E02 (Fit) Chapter Introduction

e02gb: FL CL CPP AD PY MB

NAG FL Interface
e02gbf (glinc_l1sol)

Keyword Search:

NAG Library Manual, Mark 30.1

Interfaces: FL CL CPP AD PY MB

NAG FL Interface Introduction

E02 (Fit) Chapter Contents

E02 (Fit) Chapter Introduction

e02gb: FL CL CPP AD PY MB

▸▿ Contents

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

8 Parallelism and Performance

9 Further Comments

▸▿ 10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

© The Numerical Algorithms Group Ltd. 2024

1 Purpose

e02gbf calculates an

l_{1}

solution to an overdetermined system of linear equations, possibly subject to linear inequality constraints.

2 Specification

Fortran Interface

Subroutine e02gbf (

m, n, mpl, e, lde, f, x, mxs, monit, iprint, k, el1n, indx, w, iw, ifail)

Integer, Intent (In)	::	m, n, mpl, lde, mxs, iprint, iw
Integer, Intent (Inout)	::	ifail
Integer, Intent (Out)	::	k, indx(mpl)
Real (Kind=nag_wp), Intent (In)	::	f(mpl)
Real (Kind=nag_wp), Intent (Inout)	::	e(lde,mpl), x(n)
Real (Kind=nag_wp), Intent (Out)	::	el1n, w(iw)
External	::	monit

C Header Interface

#include <nag.h>

void

e02gbf_ (const Integer *m, const Integer *n, const Integer *mpl, double e[], const Integer *lde, const double f[], double x[], const Integer *mxs,
void (NAG_CALL *monit)(const Integer *n, const double x[], const Integer *niter, const Integer *k, const double *el1n),
const Integer *iprint, Integer *k, double *el1n, Integer indx[], double w[], const Integer *iw, Integer *ifail)

The routine may be called by the names e02gbf or nagf_fit_glinc_l1sol.

3 Description

Given a matrix

A

with

m

rows and

n

columns

(m \geq n)

and a vector

b

with

m

elements, the routine calculates an

l_{1}

solution to the overdetermined system of equations

A x = b .

That is to say, it calculates a vector

x

, with

n

elements, which minimizes the

l_{1}

-norm (the sum of the absolute values) of the residuals

r (x) = \sum_{i = 1}^{m} | r_{i} |,

where the residuals

r_{i}

are given by

r_{i} = b_{i} - \sum_{j = 1}^{n} a_{i j} x_{j}, i = 1, 2, \dots, m .

Here

a_{i j}

is the element in row

i

and column

j

of

A

,

b_{i}

is the

i

th element of

b

and

x_{j}

the

j

th element of

x

.

If, in addition, a matrix

C

with

l

rows and

n

columns and a vector

d

with

l

elements, are given, the vector

x

computed by the routine is such as to minimize the

l_{1}

-norm

r (x)

subject to the set of inequality constraints

C x \geq d

.

The matrices

A

and

C

need not be of full rank.

Typically in applications to data fitting, data consisting of

m

points with coordinates

(t_{i}, y_{i})

is to be approximated by a linear combination of known functions

ϕ_{i} (t)

,

α_{1} ϕ_{1} (t) + α_{2} ϕ_{2} (t) + \dots + α_{n} ϕ_{n} (t),

in the

l_{1}

-norm, possibly subject to linear inequality constraints on the coefficients

α_{j}

of the form

C α \geq d

where

α

is the vector of the

α_{j}

and

C

and

d

are as in the previous paragraph. This is equivalent to finding an

l_{1}

solution to the overdetermined system of equations

\sum_{j = 1}^{n} ϕ_{j} (t_{i}) α_{j} = y_{i}, i = 1, 2, \dots, m,

subject to

C α \geq d

.

Thus if, for each value of

i

and

j

, the element

a_{i j}

of the matrix

A

above is set equal to the value of

ϕ_{j} (t_{i})

and

b_{i}

is equal to

y_{i}

and

C

and

d

are also supplied to the routine, the solution vector

x

will contain the required values of the

α_{j}

. Note that the independent variable

t

above can, instead, be a vector of several independent variables (this includes the case where each of

ϕ_{i}

is a function of a different variable, or set of variables).

The algorithm follows the Conn–Pietrzykowski approach (see Bartels et al. (1978) and Conn and Pietrzykowski (1977)), which is via an exact penalty function

g (x) = γ r (x) - \sum_{i = 1}^{l} \min (0, c_{i}^{T} x - d_{i}),

where

γ

is a penalty parameter,

c_{i}^{T}

is the

i

th row of the matrix

C

, and

d_{i}

is the

i

th element of the vector

d

. It proceeds in a step-by-step manner much like the simplex method for linear programming but does not move from vertex to vertex and does not require the problem to be cast in a form containing only non-negative unknowns. It uses stable procedures to update an orthogonal factorization of the current set of active equations and constraints.

4 References

Bartels R H, Conn A R and Charalambous C (1976) Minimisation techniques for piecewise Differentiable functions – the

l_{\infty}

solution to an overdetermined linear system Technical Report No. 247, CORR 76/30 Mathematical Sciences Department, The John Hopkins University

Bartels R H, Conn A R and Sinclair J W (1976) A Fortran program for solving overdetermined systems of linear equations in the

l_{1}

Sense Technical Report No. 236, CORR 76/7 Mathematical Sciences Department, The John Hopkins University

Bartels R H, Conn A R and Sinclair J W (1978) Minimisation techniques for piecewise differentiable functions – the

l_{1}

solution to an overdetermined linear system SIAM J. Numer. Anal. 15 224–241

Conn A R and Pietrzykowski T (1977) A penalty-function method converging directly to a constrained optimum SIAM J. Numer. Anal. 14 348–375

5 Arguments

1: $m$ – Integer Input

On entry: the number of equations in the overdetermined system,

m

(i.e., the number of rows of the matrix

A

).

Constraint:

m \geq n

.

2: $n$ – Integer Input

On entry: the number of unknowns,

n

(the number of columns of the matrix

A

).

Constraint:

n \geq 2

.

3: $mpl$ – Integer Input

On entry:

m + l

, where

l

is the number of constraints (which may be zero).

Constraint:

mpl \geq m

.

4: $e (lde, mpl)$ – Real (Kind=nag_wp) array Input/Output

On entry: the equation and constraint matrices stored in the following manner.

The first

m

columns contain the

m

rows of the matrix

A

; element

e (i, j)

specifying the element

a_{j i}

in the

j

th row and

i

th column of

A

(the coefficient of the

i

th unknown in the

j

th equation), for

i = 1, 2, \dots, n

and

j = 1, 2, \dots, m

. The next

l

columns contain the

l

rows of the constraint matrix

C

; element

e (i, j + m)

containing the element

c_{j i}

in the

j

th row and

i

th column of

C

(the coefficient of the

i

th unknown in the

j

th constraint), for

i = 1, 2, \dots, n

and

j = 1, 2, \dots, l

.

On exit: unchanged, except possibly to the extent of a small multiple of the machine precision. (See Section 9.)

5: $lde$ – Integer Input

On entry: the first dimension of the array e as declared in the (sub)program from which e02gbf is called.

Constraint:

lde \geq n

.

6: $f (mpl)$ – Real (Kind=nag_wp) array Input

On entry:

f (i)

, for

i = 1, 2, \dots, m

, must contain

b_{i}

(the

i

th element of the right-hand side vector of the overdetermined system of equations) and

f (m + i)

, for

i = 1, 2, \dots, l

, must contain

d_{i}

(the

i

th element of the right-hand side vector of the constraints), where

l

is the number of constraints.

7: $x (n)$ – Real (Kind=nag_wp) array Input/Output

On entry:

x (i)

must contain an estimate of the

i

th unknown, for

i = 1, 2, \dots, n

. If no better initial estimate for

x (i)

is available, set

x (i) = 0.0

.

On exit: the latest estimate of the

i

th unknown, for

i = 1, 2, \dots, n

. If

ifail = 0

on exit, these are the solution values.

8: $mxs$ – Integer Input

On entry: the maximum number of steps to be allowed for the solution of the unconstrained problem. Typically this may be a modest multiple of

n

. If, on entry, mxs is zero or negative, the value returned by x02bbf is used.

9: $monit$ – Subroutine, supplied by the user. External Procedure

monit can be used to print out the current values of any selection of its arguments. The frequency with which monit is called in e02gbf is controlled by iprint.

The specification of monit is:

Fortran Interface

Subroutine monit (

n, x, niter, k, el1n)

Integer, Intent (In)	::	n, niter, k
Real (Kind=nag_wp), Intent (In)	::	x(n), el1n

C Header Interface

void	monit (const Integer n, const double x[], const Integer niter, const Integer k, const double el1n)

1: $n$ – Integer Input: On entry: the number $n$ of unknowns (the number of columns of the matrix $A$ ).
2: $x (n)$ – Real (Kind=nag_wp) array Input: On entry: the latest estimate of the unknowns.
3: $niter$ – Integer Input: On entry: the number of iterations so far carried out.
4: $k$ – Integer Input: On entry: the total number of equations and constraints which are currently active (i.e., the number of equations with zero residuals plus the number of constraints which are satisfied as equations).
5: $el1n$ – Real (Kind=nag_wp) Input: On entry: the $l_{1}$ -norm of the current residuals of the overdetermined system of equations.

monit must either be a module subprogram USEd by, or declared as EXTERNAL in, the (sub)program from which e02gbf is called. Arguments denoted as Input must not be changed by this procedure.

10: $iprint$ – Integer Input

On entry: the frequency of iteration print out.

$iprint > 0$: monit is called every iprint iterations and at the solution.
$iprint = 0$: Information is printed out at the solution only. Otherwise monit is not called (but a dummy routine must still be provided).

11: $k$ – Integer Output

On exit: the total number of equations and constraints which are then active (i.e., the number of equations with zero residuals plus the number of constraints which are satisfied as equalities).

12: $el1n$ – Real (Kind=nag_wp) Output

On exit: the

l_{1}

-norm (sum of absolute values) of the equation residuals.

13: $indx (mpl)$ – Integer array Output

On exit: specifies which columns of e relate to the inactive equations and constraints.

indx (1)

up to

indx (k)

number the active columns and

indx (k + 1)

up to

indx (mpl)

number the inactive columns.

14: $w (iw)$ – Real (Kind=nag_wp) array Workspace

15: $iw$ – Integer Input

On entry: the dimension of the array w as declared in the (sub)program from which e02gbf is called.

Constraint:

iw \geq 3 \times mpl + 5 \times n + n^{2} + (n + 1) \times (n + 2) / 2

.

16: $ifail$ – Integer Input/Output

On entry: ifail must be set to

0

,

−1

or

1

to set behaviour on detection of an error; these values have no effect when no error is detected.

A value of

0

causes the printing of an error message and program execution will be halted; otherwise program execution continues. A value of

−1

means that an error message is printed while a value of

1

means that it is not.

If halting is not appropriate, the value

−1

or

1

is recommended. If message printing is undesirable, then the value

1

is recommended. Otherwise, the value

0

is recommended. When the value $- 1$ or $1$ is used it is essential to test the value of ifail on exit.

On exit:

ifail = 0

unless the routine detects an error or a warning has been flagged (see Section 6).

6 Error Indicators and Warnings

If on entry

ifail = 0

or

−1

, explanatory error messages are output on the current error message unit (as defined by x04aaf).

Errors or warnings detected by the routine:

$ifail = 1$: The constraints cannot all be satisfied simultaneously: they are not compatible with one another. Hence no solution is possible.

$ifail = 2$: The limit imposed by mxs has been reached without finding a solution. Consider restarting from the current point by simply calling e02gbf again without changing the arguments.

$ifail = 3$: The routine has failed because of numerical difficulties; the problem is too ill-conditioned. Consider rescaling the unknowns.

$ifail = 4$: Elements $1$ to m of one of the first mpl columns of the array e are all zero – this corresponds to a zero row in either of the matrices $A$ or $C$ .

On entry, iw is too small. $iw = ⟨ value ⟩$ . Minimum possible dimension: $⟨ value ⟩$ .

On entry, $lde = ⟨ value ⟩$ and $n = ⟨ value ⟩$ .
Constraint: $lde \geq n$ .

On entry, $m = ⟨ value ⟩$ and $n = ⟨ value ⟩$ .
Constraint: $m \geq n$ .

On entry, $mpl = ⟨ value ⟩$ and $m = ⟨ value ⟩$ .
Constraint: $mpl \geq m$ .

On entry, $n = ⟨ value ⟩$ .
Constraint: $n \geq 2$ .

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.
See Section 7 in the Introduction to the NAG Library FL Interface for further information.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.
See Section 8 in the Introduction to the NAG Library FL Interface for further information.

$ifail = - 999$: Dynamic memory allocation failed.
See Section 9 in the Introduction to the NAG Library FL Interface for further information.

7 Accuracy

The method is stable.

8 Parallelism and Performance

Background information to multithreading can be found in the Multithreading documentation.

e02gbf is threaded by NAG for parallel execution in multithreaded implementations of the NAG Library.

e02gbf makes calls to BLAS and/or LAPACK routines, which may be threaded within the vendor library used by this implementation. Consult the documentation for the vendor library for further information.

Please consult the X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this routine. Please also consult the Users' Note for your implementation for any additional implementation-specific information.

9 Further Comments

The effect of

m

and

n

on the time and on the number of iterations varies from problem to problem, but typically the number of iterations is a small multiple of

n

and the total time taken is approximately proportional to

m n^{2}

.

Linear dependencies among the rows or columns of

A

and

C

are not necessarily a problem to the algorithm. Solutions can be obtained from rank-deficient

A

and

C

. However, the algorithm requires that at every step the currently active columns of e form a linearly independent set. If this is not the case at any step, small, random perturbations of the order of rounding error are added to the appropriate columns of e. Normally this perturbation process will not affect the solution significantly. It does mean, however, that results may not be exactly reproducible.

10 Example

Suppose we wish to approximate in

[0, 1]

a set of data by a curve of the form

y = a x^{3} + b x^{2} + c x + d

which has non-negative slope at the data points. Given points

(t_{i}, y_{i})

we may form the equations

y_{i} = a t_{i}^{3} + b t_{i}^{2} + c t_{i} + d

for

i = 1, 2, \dots, 6

, for the

6

data points. The requirement of a non-negative slope at the data points demands

3 a t_{i}^{2} + 2 b t_{i} + c \geq 0

for each

t_{i}

and these form the constraints.

(Note that, for fitting with polynomials, it would usually be advisable to work with the polynomial expressed in Chebyshev series form (see the E02 Chapter Introduction). The power series form is used here for simplicity of exposition.)

10.1 Program Text

Program Text (e02gbfe.f90)

10.2 Program Data

Program Data (e02gbfe.d)

10.3 Program Results

Program Results (e02gbfe.r)

NAG Library Manual, Mark 30.1

Interfaces: FL CL CPP AD PY MB

NAG FL Interface Introduction

E02 (Fit) Chapter Contents

E02 (Fit) Chapter Introduction

e02gb: FL CL CPP AD PY MB

© The Numerical Algorithms Group Ltd. 2024