VAGM 3CW "11 October 2007" "mathcw-1.00"

Table of contents


NAME

vagmf, vagm, vagml, vagmw, vagmq, vagmll, vagmdf, vagmd, vagmdl, vagmdll - arithmetic-geometric mean with result vectors

SYNOPSIS

cc [ flags ] -I/usr/local/include file(s) -L/usr/local/lib -lmcw [ ... ]

#include <mathcw.h>

extern float vagmf (float a, float b, float c, int nabc,
        float A[], float B[], float C[], int *pneed);

extern double vagm (double a, double b, double c, int nabc,
        double A[], double B[], double C[], int *pneed);

extern long double vagml (long double a, long double b, double c, int nabc,
        double A[], double B[], double C[], int *pneed);

extern __float80 vagmw (__float80 a, __float80 b, float80 c, int nabc,
        float80 A[], float80 B[], float80 C[], int *pneed);

extern __float128 vagmq (__float128 a, __float128 b, float128 c, int nabc,
        float128 A[], float128 B[], float128 C[], int *pneed);

extern long_long_double vagmll (long_long_double a, long_long_double b,
        long_long_double c, int nabc,
        double A[], double B[], double C[], int *pneed);

extern decimal_float vagmdf (decimal_float a, decimal_float b,
        decimal_float c, int nabc,
        float A[], float B[], float C[], int *pneed);

extern decimal_double vagmd (decimal_double a, decimal_double b,
        decimal_double c, int nabc,
        double A[], double B[], double C[], int *pneed);

extern decimal_long_double vagmdl (decimal_long_double a, decimal_long_double b,
        decimal_long_double c, int nabc,
        double A[], double B[], double C[], int *pneed);

extern decimal_long_long_double vagmdll (decimal_long_long_double a,
        decimal_long_long_double b, decimal_long_long_double c, int nabc,
        double A[], double B[], double C[], int *pneed);

NB: Functions with prototypes containing underscores in type names may be available only with certain extended compilers.


DESCRIPTION

Compute the arithmetic-geometric mean (AGM) of a, b, and c defined by the iteration
A[0] = a B[0] = b C[0] = c for k = 1, 2, 3, ..., do A[k] = (A[k-1] + B[k-1])/2 B[k] = sqrt(A[k-1] * B[k-1]) C[k] = (A[k-1] - B[k-1])/2
The first three arguments must be of the same sign, and should be nonzero. Use this function if your application of the AGM requires the result vectors. Otherwise, use the simpler function agm(a,b) as described in agm(3CW).

The three array arguments have dimension nabc. The worst case for the AGM requires as many iterations as there are bits in the significand, but with the starting values of a and b required in most applications, only a few steps are needed, and 20 elements in each of the arrays should be ample.

The simpler AGM function has these scaling and symmetry relations:

agm(s * a, s * b) = s * agm(a, b) agm(a, b) = agm(b, a) agm(0, b) = 0
The vector version behaves similarly with respect to its first two arguments.

Intermediate underflow or overflow in the geometric mean from the product A[k-1] * B[k-1] are avoided when necessary by exact scaling with s set to a power of the base, using the frexp(3CW) and ldexp(3CW) functions.

At convergence, after n iterations, we have A[n] = B[n], and either of them is the final function value. When the starting values are close, convergence is quadratic. When they are far apart, fewer than 20 iterations are needed in 70D extended IEEE 754 arithmetic, and even fewer at lower precisions and smaller relative sizes.

Unlike Newton--Raphson iteration, the AGM iteration is not self-correcting, and thus, errors accumulate. Consider using a function family member of higher than working precision, if available, and then cast the return value to working precision.

The arithmetic-geometric mean provides a fast computational path to several functions, including the arc tangent and the ordinary and complementary complete elliptic integral functions of the first and second kinds. Related algorithms have produced routes with quadratic, cubic, and quartic convergence for the computation of pi to more than 10**12 decimal digits. With hardware floating-point arithmetic, however, these algorithms are not sufficiently accurate for computing pi, unless arithmetic of higher than final precision is used for intermediate computations.


RETURN VALUES

If pneed is not NULL, set the location to which it points to the number of elements needed in the three argument arrays. Set up to nabc elements of the arrays to the sequence members. Then return the arithmetic-geometric mean of the arguments.

On return, if pneed is larger than nabc, the arrays were too small, and storage of additional values was suppressed to avoid writing out of bounds.


ERRORS

If any of a or b is a NaN, set errno to EDOM and return that NaN. If either is Infinity, and the other is zero, set errno to EDOM and return a quiet NaN. If either is Infinity, set errno to ERANGE and return Infinity.

The value of c is used only for storage, not for computation, so it never affects errno or the return value.


SEE ALSO

agm(3CW), atan(3CW), elle(3CW), ellec(3CW), ellk(3CW), ellkc(3CW), frexp(3CW), ldexp(3CW), sqrt(3CW).