time-to-botec

Benchmark sampling in different programming languages
Log | Files | Refs | README

README.md (4462B)

      1 <!--
      2 
      3 @license Apache-2.0
      4 
      5 Copyright (c) 2018 The Stdlib Authors.
      6 
      7 Licensed under the Apache License, Version 2.0 (the "License");
      8 you may not use this file except in compliance with the License.
      9 You may obtain a copy of the License at
     10 
     11    http://www.apache.org/licenses/LICENSE-2.0
     12 
     13 Unless required by applicable law or agreed to in writing, software
     14 distributed under the License is distributed on an "AS IS" BASIS,
     15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     16 See the License for the specific language governing permissions and
     17 limitations under the License.
     18 
     19 -->
     20 
     21 # sum-series
     22 
     23 > Compute the sum of an [infinite series][infinite-series].
     24 
     25 <section class="usage">
     26 
     27 ## Usage
     28 
     29 ```javascript
     30 var sumSeries = require( '@stdlib/math/base/tools/sum-series' );
     31 ```
     32 
     33 #### sumSeries( generator\[, options ] )
     34 
     35 Computes the sum of the series given by the supplied `generator` argument. `generator` can be either an ES6 [Generator object][es6-generator] or a function which returns successive elements of the series at each invocation.
     36 
     37 Using an ES6 [Generator object][es6-generator]:
     38 
     39 <!-- eslint-disable no-restricted-syntax -->
     40 
     41 ```javascript
     42 var pow = require( '@stdlib/math/base/special/pow' );
     43 var gen = geometricSeriesGenerator( 0.9 );
     44 var out = sumSeries( gen );
     45 // returns 10
     46 
     47 function* geometricSeriesGenerator( x ) {
     48     var exponent = 0;
     49     while ( true ) {
     50         yield pow( x, exponent );
     51         exponent += 1;
     52     }
     53 }
     54 ```
     55 
     56 Alternatively, one can use a closure to achieve the same goal:
     57 
     58 ```javascript
     59 var pow = require( '@stdlib/math/base/special/pow' );
     60 var gen = geometricSeriesClosure( 0.9 );
     61 var out = sumSeries( gen );
     62 // returns 10
     63 
     64 function geometricSeriesClosure( x ) {
     65     var exponent = -1;
     66     return gen;
     67 
     68     function gen() {
     69         exponent += 1;
     70         return pow( x, exponent );
     71     }
     72 }
     73 ```
     74 
     75 The `function` accepts the following `options`:
     76 
     77 -   **maxTerms**: integer denoting the maximum number of terms to be summed. Default: `1000000`.
     78 -   **tolerance**: number primitive specifying the tolerance used to assess convergence. Default: `2.22e-16`.
     79 -   **initialValue**: number primitive specifying the initial value of the returned sum. Default: `0`.
     80 
     81 By default, the initial value of the sum is `0`. To choose a different one, use the `initialValue` option.
     82 
     83 ```javascript
     84 var pow = require( '@stdlib/math/base/special/pow' );
     85 
     86 var out = sumSeries( geometricSeriesClosure( 0.5 ), {
     87     'initialValue': 1
     88 });
     89 // returns 3
     90 
     91 function geometricSeriesClosure( x ) {
     92     var exponent = -1;
     93     return gen;
     94 
     95     function gen() {
     96         exponent += 1;
     97         return pow( x, exponent );
     98     }
     99 }
    100 ```
    101 
    102 To change the maximum number of terms to be summed, set the `maxTerms` option.
    103 
    104 ```javascript
    105 var pow = require( '@stdlib/math/base/special/pow' );
    106 
    107 var out = sumSeries( geometricSeriesClosure( 0.5 ), {
    108     'maxTerms': 10
    109 });
    110 // returns ~1.998 (infinite sum is 2)
    111 
    112 function geometricSeriesClosure( x ) {
    113     var exponent = -1;
    114     return gen;
    115 
    116     function gen() {
    117         exponent += 1;
    118         return pow( x, exponent );
    119     }
    120 }
    121 ```
    122 
    123 The default tolerance of `2.22e-16` used to assess convergence can be changed via the `tolerance` option.
    124 
    125 ```javascript
    126 var pow = require( '@stdlib/math/base/special/pow' );
    127 
    128 var out = sumSeries( geometricSeriesClosure( 0.5 ), {
    129     'tolerance': 1e-3
    130 });
    131 // returns ~1.998
    132 
    133 function geometricSeriesClosure( x ) {
    134     var exponent = -1;
    135     return gen;
    136 
    137     function gen() {
    138         exponent += 1;
    139         return pow( x, exponent );
    140     }
    141 }
    142 ```
    143 
    144 </section>
    145 
    146 <!-- /.usage -->
    147 
    148 <section class="examples">
    149 
    150 ## Examples
    151 
    152 <!-- eslint-disable no-restricted-syntax -->
    153 
    154 <!-- eslint no-undef: "error" -->
    155 
    156 ```javascript
    157 var log1p = require( '@stdlib/math/base/special/log1p' );
    158 var sumSeries = require( '@stdlib/math/base/tools/sum-series' );
    159 
    160 function* log1pSeries( x ) {
    161     var mMult = -x;
    162     var mProd = -1;
    163     var k = 0;
    164     while ( true ) {
    165         mProd *= mMult;
    166         k += 1;
    167         yield ( mProd / k );
    168     }
    169 }
    170 
    171 console.log( 'log1p(0.5) evaluated via math-log1p module: %d', log1p( 0.5 ) );
    172 console.log( 'log1p(0.5) evaluated via infinite series expansion: %d', sumSeries( log1pSeries( 0.5 ) ) );
    173 ```
    174 
    175 </section>
    176 
    177 <!-- /.examples -->
    178 
    179 <section class="links">
    180 
    181 [infinite-series]: https://en.wikipedia.org/wiki/Series_%28mathematics%29
    182 
    183 [es6-generator]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function*
    184 
    185 </section>
    186 
    187 <!-- /.links -->