time-to-botec/js/node_modules/@stdlib/math/base/tools/sum-series/README.md

sum-series

Compute the sum of an infinite series.

Usage

var sumSeries = require( '@stdlib/math/base/tools/sum-series' );

sumSeries( generator[, options ] )

Computes the sum of the series given by the supplied generator argument. generator can be either an ES6 Generator object or a function which returns successive elements of the series at each invocation.

Using an ES6 Generator object:

var pow = require( '@stdlib/math/base/special/pow' );
var gen = geometricSeriesGenerator( 0.9 );
var out = sumSeries( gen );
// returns 10

function* geometricSeriesGenerator( x ) {
    var exponent = 0;
    while ( true ) {
        yield pow( x, exponent );
        exponent += 1;
    }
}

Alternatively, one can use a closure to achieve the same goal:

var pow = require( '@stdlib/math/base/special/pow' );
var gen = geometricSeriesClosure( 0.9 );
var out = sumSeries( gen );
// returns 10

function geometricSeriesClosure( x ) {
    var exponent = -1;
    return gen;

    function gen() {
        exponent += 1;
        return pow( x, exponent );
    }
}

The function accepts the following options:

• maxTerms: integer denoting the maximum number of terms to be summed. Default: 1000000.
• tolerance: number primitive specifying the tolerance used to assess convergence. Default: 2.22e-16.
• initialValue: number primitive specifying the initial value of the returned sum. Default: 0.

By default, the initial value of the sum is 0. To choose a different one, use the initialValue option.

var pow = require( '@stdlib/math/base/special/pow' );

var out = sumSeries( geometricSeriesClosure( 0.5 ), {
    'initialValue': 1
});
// returns 3

function geometricSeriesClosure( x ) {
    var exponent = -1;
    return gen;

    function gen() {
        exponent += 1;
        return pow( x, exponent );
    }
}

To change the maximum number of terms to be summed, set the maxTerms option.

var pow = require( '@stdlib/math/base/special/pow' );

var out = sumSeries( geometricSeriesClosure( 0.5 ), {
    'maxTerms': 10
});
// returns ~1.998 (infinite sum is 2)

function geometricSeriesClosure( x ) {
    var exponent = -1;
    return gen;

    function gen() {
        exponent += 1;
        return pow( x, exponent );
    }
}

The default tolerance of 2.22e-16 used to assess convergence can be changed via the tolerance option.

var pow = require( '@stdlib/math/base/special/pow' );

var out = sumSeries( geometricSeriesClosure( 0.5 ), {
    'tolerance': 1e-3
});
// returns ~1.998

function geometricSeriesClosure( x ) {
    var exponent = -1;
    return gen;

    function gen() {
        exponent += 1;
        return pow( x, exponent );
    }
}

Examples

var log1p = require( '@stdlib/math/base/special/log1p' );
var sumSeries = require( '@stdlib/math/base/tools/sum-series' );

function* log1pSeries( x ) {
    var mMult = -x;
    var mProd = -1;
    var k = 0;
    while ( true ) {
        mProd *= mMult;
        k += 1;
        yield ( mProd / k );
    }
}

console.log( 'log1p(0.5) evaluated via math-log1p module: %d', log1p( 0.5 ) );
console.log( 'log1p(0.5) evaluated via infinite series expansion: %d', sumSeries( log1pSeries( 0.5 ) ) );