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

Constraint: $u \neq (0.0, 0.0)$ .
2: $r$ – complex scalar: $r$ , the coefficient of $z^{2}$ .
3: $s$ – complex scalar: $s$ , the coefficient of $z$ .
4: $t$ – complex 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, 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} - (2 - 3 i) z^{2} + (5 + 14 i) z - (40 + 5 i) = 0 .

Open in the MATLAB editor: c02am_example

function c02am_example


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

u = complex(1);
r =   -2 +  3i;
s =    5 + 14i;
t =  -40 -  5i;
[zr, zi, errest, ifail] = c02am(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

c02am example results

  Roots of cubic      error estimates
 -2.0000 -  3.0000i     1.73e-15
  1.0000 -  2.0000i     3.64e-15
  3.0000 -  4.0000i     3.74e-15

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

Chapter Contents

Chapter Introduction

NAG Toolbox