NAG FL Interface
c02aff (poly_complex)

Note: this routine is deprecated. Replaced by c02aaf.

Old Code

Real (Kind=nag_wp) :: a(2,0:n)
Real (Kind=nag_wp) :: z(2,n)
Real (Kind=nag_wp) :: w(4*(n+1))
Logical :: scal
...
scal = .True.
Call c02aff(a, n, scal, z, w, ifail)

New Code

Real (Kind=nag_wp) :: a(2,0:n)
Real (Kind=nag_wp) :: z(2,n)
Complex (Kind=nag_wp) :: aa(0:n)
Complex (Kind=nag_wp) :: zz(n)
Integer :: itmax, polish
Real (Kind=nag_wp) :: berr(n), cond(n)
Integer :: conv(n)
...
itmax = 30
polish=1
! Convert array a from real to complex
aa(0:n) = Cmplx(a(1,0:n),a(2,0:n),kind=nag_wp)
Call c02aaf(aa, n, itmax, polish, zz, berr, cond, conv, ifail)
! Convert array z from Complex to Real
z(1,1:n) = Real(zz(1:n))
z(2,1:n) = Aimag(zz(1:n))

that arguments a and z are two-dimensional arrays of type real(kind=nag_wp) for c02aff, but are one-dimensional arrays of type complex(kind=nag_wp) for c02aaf. Note also that the roots may be returned in a different order in array z.

Keyword Search:

NAG Library Manual, Mark 28.6

Interfaces: FL CL CPP AD PY MB

NAG FL Interface Introduction

C02 (Zeros) Chapter Contents

C02 (Zeros) Chapter Introduction

c02af: FL CL CPP AD PY MB

▸▿ Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Parallelism and Performance

9 Further Comments

▸▿ 10 Example

10.1 Program Text

10.2 Program Data

10.3 Program Results

1 Purpose

c02aff finds all the roots of a complex polynomial equation, using a variant of Laguerre's method.

2 Specification

Fortran Interface

Subroutine c02aff (

a, n, scal, z, w, ifail)

Integer, Intent (In)	::	n
Integer, Intent (Inout)	::	ifail
Real (Kind=nag_wp), Intent (In)	::	a(2,n+1)
Real (Kind=nag_wp), Intent (Out)	::	z(2,n), w(4*(n+1))
Logical, Intent (In)	::	scal

C Header Interface

#include <nag.h>

void	c02aff_ (const double a[], const Integer n, const logical scal, double z[], double w[], Integer *ifail)

The routine may be called by the names c02aff or nagf_zeros_poly_complex.

3 Description

c02aff attempts to find all the roots of the

n

th degree complex polynomial equation

P (z) = a_{0} z^{n} + a_{1} z^{n - 1} + a_{2} z^{n - 2} + \dots + a_{n - 1} z + a_{n} = 0 .

The roots are located using a modified form of Laguerre's method, originally proposed by Smith (1967).

The method of Laguerre (see Wilkinson (1965)) can be described by the iterative scheme

L (z_{k}) = z_{k + 1} - z_{k} = \frac{- n P (z_{k})}{P^{'} (z_{k}) \pm \sqrt{H (z_{k})}},

where

H (z_{k}) = (n - 1) [(n - 1) {(P^{'} (z_{k}))}^{2} - n P (z_{k}) P^{''} (z_{k})]

and

z_{0}

is specified.

The sign in the denominator is chosen so that the modulus of the Laguerre step at

z_{k}

, viz.

| L (z_{k}) |

, is as small as possible. The method can be shown to be cubically convergent for isolated roots (real or complex) and linearly convergent for multiple roots.

The routine generates a sequence of iterates

z_{1}, z_{2}, z_{3}, \dots

, such that

| P (z_{k + 1}) | < | P (z_{k}) |

and ensures that

z_{k + 1} + L (z_{k + 1})

‘roughly’ lies inside a circular region of radius

| F |

about

z_{k}

known to contain a zero of

P (z)

; that is,

| L (z_{k + 1}) | \leq | F |

, where

F

denotes the Fejér bound (see Marden (1966)) at the point

z_{k}

. Following Smith (1967),

F

is taken to be

\min (B, 1.445 n R)

, where

B

is an upper bound for the magnitude of the smallest zero given by

B = 1.0001 \times \min (\sqrt{n} L (z_{k}), | r_{1} |, {| a_{n} / a_{0} |}^{1 / n}),

r_{1}

is the zero

X

of smaller magnitude of the quadratic equation

\frac{P^{''} (z_{k})}{2 n (n - 1)} X^{2} + \frac{P^{'} (z_{k})}{n} X + \frac{1}{2} P (z_{k}) = 0

and the Cauchy lower bound

R

for the smallest zero is computed (using Newton's Method) as the positive root of the polynomial equation

| a_{0} | z^{n} + | a_{1} | z^{n - 1} + | a_{2} | z^{n - 2} + \dots + | a_{n - 1} | z - | a_{n} | = 0 .

Starting from the origin, successive iterates are generated according to the rule

z_{k + 1} = z_{k} + L (z_{k})

, for

k = 1, 2, 3, \dots

, and

L (z_{k})

is ‘adjusted’ so that

| P (z_{k + 1}) | < | P (z_{k}) |

and

| L (z_{k + 1}) | \leq | F |

. The iterative procedure terminates if

P (z_{k + 1})

is smaller in absolute value than the bound on the rounding error in

P (z_{k + 1})

and the current iterate

z_{p} = z_{k + 1}

is taken to be a zero of

P (z)

. The deflated polynomial

\tilde{P} (z) = P (z) / (z - z_{p})

of degree

n - 1

is then formed, and the above procedure is repeated on the deflated polynomial until

n < 3

, whereupon the remaining roots are obtained via the ‘standard’ closed formulae for a linear (

n = 1

) or quadratic (

n = 2

) equation.

Note that c02ahf, c02amf and c02anf can be used to obtain the roots of a quadratic, cubic (

n = 3

) and quartic (

n = 4

) polynomial, respectively.

4 References

Marden M (1966) Geometry of polynomials Mathematical Surveys 3 American Mathematical Society, Providence, RI

Smith B T (1967) ZERPOL: a zero finding algorithm for polynomials using Laguerre's method Technical Report Department of Computer Science, University of Toronto, Canada

Thompson K W (1991) Error analysis for polynomial solvers Fortran Journal (Volume 3) 3 10–13

Wilkinson J H (1965) The Algebraic Eigenvalue Problem Oxford University Press, Oxford

5 Arguments

1: $a (2, n + 1)$ – Real (Kind=nag_wp) array Input: On entry: if a is declared with bounds $(2, 0 : n)$ , $a (1, i)$ and $a (2, i)$ must contain the real and imaginary parts of $a_{i}$ (i.e., the coefficient of $z^{n - i}$ ), for $i = 0, 1, \dots, n$ .

Constraint: $a (1, 0) \neq 0.0$ or $a (2, 0) \neq 0.0$ .
2: $n$ – Integer Input: On entry: $n$ , the degree of the polynomial.

Constraint: $n \geq 1$ .
3: $scal$ – Logical Input: On entry: indicates whether or not the polynomial is to be scaled. See Section 9 for advice on when it may be preferable to set $scal = .FALSE.$ and for a description of the scaling strategy.

Suggested value: $scal = .TRUE.$ .
4: $z (2, n)$ – Real (Kind=nag_wp) array Output: On exit: the real and imaginary parts of the roots are stored in $z (1, i)$ and $z (2, i)$ respectively, for $i = 1, 2, \dots, n$ .
5: $w (4 \times (n + 1))$ – Real (Kind=nag_wp) array Workspace
6: $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

−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$: On entry, $a (1, 0) = 0.0$ and $a (2, 0) = 0.0$ .
Constraint: $a (1, 0) \neq 0.0$ or $a (2, 0) \neq 0.0$ .

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

$ifail = 2$: The iterative procedure has failed to converge. This error is very unlikely to occur. If it does, please contact NAG immediately, as some basic assumption for the arithmetic has been violated.

$ifail = 3$: c02aff cannot evaluate $P (z)$ near some of its zeros without overflow. If this message occurs please contact NAG.

c02aff cannot evaluate $P (z)$ near some of its zeros without underflow. If this message occurs please contact NAG.

$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

All roots are evaluated as accurately as possible, but because of the inherent nature of the problem complete accuracy cannot be guaranteed. See also Section 10.

8 Parallelism and Performance

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

c02aff is not threaded in any implementation.

9 Further Comments

scal = .TRUE.

, then a scaling factor for the coefficients is chosen as a power of the base

b

of the machine so that the largest coefficient in magnitude approaches

thresh = b^{e_{\max} - p}

. You should note that no scaling is performed if the largest coefficient in magnitude exceeds

thresh

, even if

scal = .TRUE.

. (

b

e_{\max}

and

p

are defined in Chapter X02.)

However, with

scal = .TRUE.

, overflow may be encountered when the input coefficients

a_{0}, a_{1}, a_{2}, \dots, a_{n}

vary widely in magnitude, particularly on those machines for which

b^{(4 p)}

overflows. In such cases, scal should be set to .FALSE. and the coefficients scaled so that the largest coefficient in magnitude does not exceed

b^{(e_{\max} - 2 p)}

Even so, the scaling strategy used by c02aff is sometimes insufficient to avoid overflow and/or underflow conditions. In such cases, you are recommended to scale the independent variable

(z)

so that the disparity between the largest and smallest coefficient in magnitude is reduced. That is, use the routine to locate the zeros of the polynomial

d P (c z)

for some suitable values of

c

and

d

. For example, if the original polynomial was

P (z) = 2^{−100} i + 2^{100} z^{20}

, then choosing

c = 2^{−10}

and

d = 2^{100}

, for instance, would yield the scaled polynomial

i + z^{20}

, which is well-behaved relative to overflow and underflow and has zeros which are

2^{10}

times those of

P (z)

If the routine fails with

ifail = 2

3

, then the real and imaginary parts of any roots obtained before the failure occurred are stored in z in the reverse order in which they were found. Let

n_{R}

denote the number of roots found before the failure occurred. Then

z (1, n)

and

z (2, n)

contain the real and imaginary parts of the first root found,

z (1, n - 1)

and

z (2, n - 1)

contain the real and imaginary parts of the second root found,

\dots, z (1, n - n_{R} + 1)

and

z (2, n - n_{R} + 1)

contain the real and imaginary parts of the

n_{R}

th root found. After the failure has occurred, the remaining

2 \times (n - n_{R})

elements of z contain a large negative number (equal to

−1 / (x02amf () \times \sqrt{2})

10 Example

For this routine two examples are presented. There is a single example program for c02aff, with a main program and the code to solve the two example problems given in the subroutines EX1 and EX2.

Example 1 (EX1)

This example finds the roots of the polynomial

a_{0} z^{5} + a_{1} z^{4} + a_{2} z^{3} + a_{3} z^{2} + a_{4} z + a_{5} = 0,