Package org.apache.commons.numbers.fraction

Class GeneralizedContinuedFraction

java.lang.Object

org.apache.commons.numbers.fraction.GeneralizedContinuedFraction

public final class GeneralizedContinuedFraction
extends Object

Provides a means to evaluate generalized continued fractions.

The continued fraction uses the following form for the numerator (a) and denominator (b) coefficients:

              a1
 b0 + ------------------
      b1 +      a2
           -------------
           b2 +    a3
                --------
                b3 + ...
 

A generator of the coefficients must be provided to evaluate the continued fraction.

The implementation of the fraction evaluation is based on the modified Lentz algorithm as described on page 508 in:

• I. J. Thompson, A. R. Barnett (1986). "Coulomb and Bessel Functions of Complex Arguments and Order." Journal of Computational Physics 64, 490-509. https://www.fresco.org.uk/papers/Thompson-JCP64p490.pdf

Since:

1.1

See Also:

Wikipedia: Generalized continued fraction, MathWorld: Generalized continued fraction

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	GeneralizedContinuedFraction.Coefficient	Defines the n-th "a" and "b" coefficients of the continued fraction.

Method Summary

Modifier and Type	Method	Description
static double	value(double b0, Supplier<GeneralizedContinuedFraction.Coefficient> gen)	Evaluates the continued fraction.
static double	value(double b0, Supplier<GeneralizedContinuedFraction.Coefficient> gen, double epsilon)	Evaluates the continued fraction.
static double	value(double b0, Supplier<GeneralizedContinuedFraction.Coefficient> gen, double epsilon, int maxIterations)	Evaluates the continued fraction.
static double	value(Supplier<GeneralizedContinuedFraction.Coefficient> gen)	Evaluates the continued fraction.
static double	value(Supplier<GeneralizedContinuedFraction.Coefficient> gen, double epsilon)	Evaluates the continued fraction.
static double	value(Supplier<GeneralizedContinuedFraction.Coefficient> gen, double epsilon, int maxIterations)	Evaluates the continued fraction.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

value

public static double value(Supplier<GeneralizedContinuedFraction.Coefficient> gen)

Evaluates the continued fraction.

Note: The first generated partial numerator a₀ is discarded.

Parameters:

gen - Generator of coefficients.

Returns:

the value of the continued fraction.

Throws:

ArithmeticException - if the algorithm fails to converge or if the maximal number of iterations is reached before the expected convergence is achieved.

See Also:

value(Supplier,double,int)

value

public static double value(Supplier<GeneralizedContinuedFraction.Coefficient> gen,
                           double epsilon)

Evaluates the continued fraction.

Note: The first generated partial numerator a₀ is discarded.

Parameters:

gen - Generator of coefficients.

epsilon - Maximum relative error allowed.

Returns:

the value of the continued fraction.

Throws:

ArithmeticException - if the algorithm fails to converge or if the maximal number of iterations is reached before the expected convergence is achieved.

See Also:

value(Supplier,double,int)

value

public static double value(Supplier<GeneralizedContinuedFraction.Coefficient> gen,
                           double epsilon,
                           int maxIterations)

Evaluates the continued fraction.

              a1
 b0 + ------------------
      b1 +      a2
           -------------
           b2 +    a3
                --------
                b3 + ...
 

Setting coefficient a_n to zero will signal the end of the recursive evaluation.

Note: The first generated partial numerator a₀ is discarded.

Usage Note

This method is not functionally identical to calling value(double, Supplier, double, int) with the generator configured to provide coefficients from n=1 and supplying b₀ separately. In some cases the computed result from the two variations may be different by more than the provided epsilon. The other method should be used if b₀ is zero or very small. See the corresponding javadoc for details.

Parameters:

gen - Generator of coefficients.

epsilon - Maximum relative error allowed.

maxIterations - Maximum number of iterations.

Returns:

the value of the continued fraction.

Throws:

ArithmeticException - if the algorithm fails to converge or if the maximal number of iterations is reached before the expected convergence is achieved.

See Also:

value(double, Supplier, double, int)

value

public static double value(double b0,
                           Supplier<GeneralizedContinuedFraction.Coefficient> gen)

Evaluates the continued fraction.

Note: The initial term b₀ is supplied as an argument. Both of the first generated terms a and b are used. This fraction evaluation can be used when:

• b₀ is not part of a regular series
• b₀ is zero and the result will evaluate only the continued fraction component
• b₀ is very small and the result is expected to approach zero

Parameters:

b0 - Coefficient b₀.

gen - Generator of coefficients.

Returns:

the value of the continued fraction.

Throws:

ArithmeticException - if the algorithm fails to converge or if the maximal number of iterations is reached before the expected convergence is achieved.

See Also:

value(double,Supplier,double,int)

value

public static double value(double b0,
                           Supplier<GeneralizedContinuedFraction.Coefficient> gen,
                           double epsilon)

Evaluates the continued fraction.

Note: The initial term b₀ is supplied as an argument. Both of the first generated terms a and b are used. This fraction evaluation can be used when:

• b₀ is not part of a regular series
• b₀ is zero and the result will evaluate only the continued fraction component
• b₀ is very small and the result is expected to approach zero

Parameters:

b0 - Coefficient b₀.

gen - Generator of coefficients.

epsilon - Maximum relative error allowed.

Returns:

the value of the continued fraction.

Throws:

ArithmeticException - if the algorithm fails to converge or if the maximal number of iterations is reached before the expected convergence is achieved.

See Also:

value(double,Supplier,double,int)

value

public static double value(double b0,
                           Supplier<GeneralizedContinuedFraction.Coefficient> gen,
                           double epsilon,
                           int maxIterations)

Evaluates the continued fraction.

              a1
 b0 + ------------------
      b1 +      a2
           -------------
           b2 +    a3
                --------
                b3 + ...
 

Setting coefficient a_n to zero will signal the end of the recursive evaluation.

Note: The initial term b₀ is supplied as an argument. Both of the first generated terms a and b are used. This fraction evaluation can be used when:

• b₀ is not part of a regular series
• b₀ is zero and the result will evaluate only the continued fraction component
• b₀ is very small and the result is expected to approach zero

Usage Note

This method is not functionally identical to calling value(Supplier, double, int) with the generator configured to provide term "b₀" in the first coefficient. In some cases the computed result from the two variations may be different by more than the provided epsilon. The convergence of the continued fraction algorithm relies on computing an update multiplier applied to the current value. Convergence is faster if the initial value is close to the final value. The value(Supplier, double, int) method will initialise the current value using b₀ and evaluate the continued fraction using updates computed from the generated coefficients. This method initialises the algorithm using b1 to evaluate part of the continued fraction and computes the result as:

        a1
 b0 + ------
       part
 

This is preferred if b₀ is smaller in magnitude than the continued fraction component. In particular the evaluation algorithm sets a bound on the minimum initial value as 1e-50. If b₀ is smaller than this value then using this method is the preferred evaluation.

Parameters:

b0 - Coefficient b₀.

gen - Generator of coefficients.

epsilon - Maximum relative error allowed.

maxIterations - Maximum number of iterations.

Returns:

the value of the continued fraction.

Throws:

ArithmeticException - if the algorithm fails to converge or if the maximal number of iterations is reached before the expected convergence is achieved.

See Also:

value(Supplier,double,int)