nag_cubic_roots (c02akc) (PDF version)
c02 Chapter Contents
c02 Chapter Introduction
NAG Library Manual

NAG Library Function Document

nag_cubic_roots (c02akc)

+ Contents

    1  Purpose
    7  Accuracy

1  Purpose

nag_cubic_roots (c02akc) determines the roots of a cubic equation with real coefficients.

2  Specification

#include <nag.h>
#include <nagc02.h>
void  nag_cubic_roots (double u, double r, double s, double t, double zeror[], double zeroi[], double errest[], NagError *fail)

3  Description

nag_cubic_roots (c02akc) attempts to find the roots of the cubic equation
uz3 + rz2 + sz + t = 0 ,
where u , r , s  and t  are real coefficients with u0 . The roots are located by finding the eigenvalues of the associated 3 by 3 (upper Hessenberg) companion matrix2 H  given by
H = 0 0 -t / u 1 0 -s / u 0 1 -r / u .
Further details can be found in Section 9.
To obtain the roots of a quadratic equation, nag_quartic_roots (c02alc) can be used.

4  References

Golub G H and Van Loan C F (1996) Matrix Computations (3rd Edition) Johns Hopkins University Press, Baltimore

5  Arguments

1:     udoubleInput
On entry: u , the coefficient of z 3 .
Constraint: u0.0 .
2:     rdoubleInput
On entry: r , the coefficient of z 2 .
3:     sdoubleInput
On entry: s , the coefficient of z .
4:     tdoubleInput
On entry: t , the constant coefficient.
5:     zeror[3]doubleOutput
6:     zeroi[3]doubleOutput
On exit: zeror[i-1]  and zeroi[i-1]  contain the real and imaginary parts, respectively, of the i th root.
7:     errest[3]doubleOutput
On exit: errest[i-1]  contains an approximate error estimate for the i th root.
8:     failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

The iterative procedure used to determine the eigenvalues has failed to converge.
The companion matrix H  cannot be formed without overflow.
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
On entry, u=0.0 .
Constraint: u0.0 .

7  Accuracy

If fail.code=NE_NOERROR  on exit, then the i th computed root should have approximately log10 errest[i-1]  correct significant digits.

8  Parallelism and Performance

Not applicable.

9  Further Comments

The method used by the function consists of the following steps, which are performed by functions from LAPACK.
(a) Form 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).

10  Example

To find the roots of the cubic equation
z 3 + 3 z 2 + 9 z - 13 = 0 .

10.1  Program Text

Program Text (c02akce.c)

10.2  Program Data

Program Data (c02akce.d)

10.3  Program Results

Program Results (c02akce.r)

nag_cubic_roots (c02akc) (PDF version)
c02 Chapter Contents
c02 Chapter Introduction
NAG Library Manual

© The Numerical Algorithms Group Ltd, Oxford, UK. 2014