1: $u$ – double scalar: $u$ , the coefficient of $z^{3}$ .

Constraint: $u \neq 0.0$ .
2: $r$ – double scalar: $r$ , the coefficient of $z^{2}$ .
3: $s$ – double scalar: $s$ , the coefficient of $z$ .
4: $t$ – double scalar: $t$ , the constant coefficient.

Optional Input Parameters

None.

Output Parameters

1: $zeror (3)$ – double array
2: $zeroi (3)$ – double array: $zeror (i)$ and $zeroi (i)$ contain the real and imaginary parts, respectively, of the $i$ th root.
3: $errest (3)$ – double array: $errest (i)$ contains an approximate error estimate for the $i$ th root.
4: $ifail$ – int64int32nag_int scalar: $ifail = 0$ unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

Errors or warnings detected by the function:

$ifail = 1$

On entry,

u = 0.0

$ifail = 2$: The companion matrix $H$ cannot be formed without overflow.

$ifail = 3$: The iterative procedure used to determine the eigenvalues has failed to converge.

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.

$ifail = - 999$: Dynamic memory allocation failed.

Accuracy

ifail = 0

on exit, then the

i

th computed root should have approximately

|\log_{10} (errest (i))|

correct significant digits.

Further Comments

The method used by the function consists of the following steps, which are performed by functions from LAPACK in Chapter F08.

(a)	Form matrix $H$ .
(b)	Apply a diagonal similarity transformation to $H$ (to give $H^{'}$ ).
(c)	Calculate the eigenvalues and Schur factorization of $H^{'}$ .
(d)	Calculate the left and right eigenvectors of $H^{'}$ .
(e)	Estimate reciprocal condition numbers for all the eigenvalues of $H^{'}$ .
(f)	Calculate approximate error estimates for all the eigenvalues of $H^{'}$ (using the $1$ -norm).

Example

This example finds the roots of the cubic equation

z^{3} + 3 z^{2} + 9 z - 13 = 0 .

Open in the MATLAB editor: c02ak_example

function c02ak_example


fprintf('c02ak example results\n\n');

% roots of cubic z^3 + 3*z^2 + 9*z - 13 = 0
u =   1;
r =   3;
s =   9;
t = -13;
[zr, zi, errest, ifail] = c02ak(u, r, s, t);

fprintf('  Roots of cubic      error estimates\n');
for j = 1:3
   if (zi(j)<0)
     fprintf('%8.4f - %7.4fi     %8.2e\n',zr(j),abs(zi(j)),errest(j));
   else
     fprintf('%8.4f - %7.4fi     %8.2e\n',zr(j),abs(zi(j)),errest(j));
   end
end

c02ak example results

  Roots of cubic      error estimates
  1.0000 -  0.0000i     1.00e-15
 -2.0000 -  3.0000i     1.04e-15
 -2.0000 -  3.0000i     1.04e-15

PDF version (NAG web site, 64-bit version, 64-bit version)

Chapter Contents

Chapter Introduction

NAG Toolbox