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:     u doubleInput
On entry: u , the coefficient of z 3 .
Constraint: u0.0 .
2:     r doubleInput
On entry: r , the coefficient of z 2 .
3:     s doubleInput
On entry: s , the coefficient of z .
4:     t doubleInput
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:     fail NagError *Input/Output
The NAG error argument (see Section 2.7 in How to Use the NAG Library and its Documentation).

6  Error Indicators and Warnings

NE_C02_NOT_CONV
The iterative procedure used to determine the eigenvalues has failed to converge.
NE_C02_OVERFLOW
The companion matrix H  cannot be formed without overflow.
NE_INTERNAL_ERROR
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.
NE_REAL
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

nag_cubic_roots (c02akc) is not threaded in any implementation.

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. 2016