NAG CL Interface
c02akc (cubic_​real)

Settings help

CL Name Style:


1 Purpose

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

2 Specification

#include <nag.h>
void  c02akc (double u, double r, double s, double t, double zeror[], double zeroi[], double errest[], NagError *fail)
The function may be called by the names: c02akc, nag_zeros_cubic_real or nag_cubic_roots.

3 Description

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, 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 double Input
On entry: u , the coefficient of z 3 .
Constraint: u0.0 .
2: r double Input
On entry: r , the coefficient of z 2 .
3: s double Input
On entry: s , the coefficient of z .
4: t double Input
On entry: t , the constant coefficient.
5: zeror[3] double Output
6: zeroi[3] double Output
On exit: zeror[i-1] and zeroi[i-1] contain the real and imaginary parts, respectively, of the i th root.
7: errest[3] double Output
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 7 in the Introduction to the NAG Library CL Interface).

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

Background information to multithreading can be found in the Multithreading documentation.
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.
  1. (a)Form H .
  2. (b)Apply a diagonal similarity transformation to H (to give H ).
  3. (c)Calculate the eigenvalues and Schur factorization of H .
  4. (d)Calculate the left and right eigenvectors of H .
  5. (e)Estimate reciprocal condition numbers for all the eigenvalues of H .
  6. (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)