time-to-botec

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

README.md (4180B)

      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 # incrprod
     22 
     23 > Compute a product incrementally.
     24 
     25 <section class="intro">
     26 
     27 The product is defined as
     28 
     29 <!-- <equation class="equation" label="eq:product" align="center" raw="p = \prod_{i=0}^{n-1} x_i" alt="Equation for the product."> -->
     30 
     31 <div class="equation" align="center" data-raw-text="p = \prod_{i=0}^{n-1} x_i" data-equation="eq:product">
     32     <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@ae1331d17d505898a27e695fc60144d786627384/lib/node_modules/@stdlib/stats/incr/prod/docs/img/equation_product.svg" alt="Equation for the product.">
     33     <br>
     34 </div>
     35 
     36 <!-- </equation> -->
     37 
     38 </section>
     39 
     40 <!-- /.intro -->
     41 
     42 <section class="usage">
     43 
     44 ## Usage
     45 
     46 ```javascript
     47 var incrprod = require( '@stdlib/stats/incr/prod' );
     48 ```
     49 
     50 #### incrprod()
     51 
     52 Returns an accumulator `function` which incrementally computes a product.
     53 
     54 ```javascript
     55 var accumulator = incrprod();
     56 ```
     57 
     58 #### accumulator( \[x] )
     59 
     60 If provided an input value `x`, the accumulator function returns an updated product. If not provided an input value `x`, the accumulator function returns the current product.
     61 
     62 ```javascript
     63 var accumulator = incrprod();
     64 
     65 var prod = accumulator( 2.0 );
     66 // returns 2.0
     67 
     68 prod = accumulator( 1.0 );
     69 // returns 2.0
     70 
     71 prod = accumulator( 3.0 );
     72 // returns 6.0
     73 
     74 prod = accumulator();
     75 // returns 6.0
     76 ```
     77 
     78 Under certain conditions, overflow may be transient.
     79 
     80 ```javascript
     81 // Large values:
     82 var x = 5.0e+300;
     83 var y = 1.0e+300;
     84 
     85 // Tiny value:
     86 var z = 2.0e-302;
     87 
     88 // Initialize an accumulator:
     89 var accumulator = incrprod();
     90 
     91 var prod = accumulator( x );
     92 // returns 5.0e+300
     93 
     94 // Transient overflow:
     95 prod = accumulator( y );
     96 // returns Infinity
     97 
     98 // Recover a finite result:
     99 prod = accumulator( z );
    100 // returns 1.0e+299
    101 ```
    102 
    103 Similarly, under certain conditions, underflow may be transient.
    104 
    105 ```javascript
    106 // Tiny values:
    107 var x = 4.0e-302;
    108 var y = 9.0e-303;
    109 
    110 // Large value:
    111 var z = 2.0e+300;
    112 
    113 // Initialize an accumulator:
    114 var accumulator = incrprod();
    115 
    116 var prod = accumulator( x );
    117 // returns 4.0e-302
    118 
    119 // Transient underflow:
    120 prod = accumulator( y );
    121 // returns 0.0
    122 
    123 // Recover a non-zero result:
    124 prod = accumulator( z );
    125 // returns 7.2e-304
    126 ```
    127 
    128 </section>
    129 
    130 <!-- /.usage -->
    131 
    132 <section class="notes">
    133 
    134 ## Notes
    135 
    136 -   Input values are **not** type checked. If provided `NaN` or a value which, when used in computations, results in `NaN`, the accumulated value is `NaN` for **all** future invocations. If non-numeric inputs are possible, you are advised to type check and handle accordingly **before** passing the value to the accumulator function.
    137 -   For long running accumulations or accumulations of either large or small numbers, care should be taken to prevent overflow and underflow. Note, however, that overflow/underflow may be transient, as the accumulator does not use a double-precision floating-point number to store an accumulated product. Instead, the accumulator splits an accumulated product into a normalized **fraction** and **exponent** and updates each component separately. Doing so guards against a loss in precision.
    138 
    139 </section>
    140 
    141 <!-- /.notes -->
    142 
    143 <section class="examples">
    144 
    145 ## Examples
    146 
    147 <!-- eslint no-undef: "error" -->
    148 
    149 ```javascript
    150 var randu = require( '@stdlib/random/base/randu' );
    151 var incrprod = require( '@stdlib/stats/incr/prod' );
    152 
    153 var accumulator;
    154 var v;
    155 var i;
    156 
    157 // Initialize an accumulator:
    158 accumulator = incrprod();
    159 
    160 // For each simulated value, update the product...
    161 for ( i = 0; i < 100; i++ ) {
    162     v = randu() * 100.0;
    163     accumulator( v );
    164 }
    165 console.log( accumulator() );
    166 ```
    167 
    168 </section>
    169 
    170 <!-- /.examples -->
    171 
    172 <section class="links">
    173 
    174 </section>
    175 
    176 <!-- /.links -->