time-to-botec

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

README.md (3860B)

      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 # evalpoly
     22 
     23 > Evaluate a [polynomial][polynomial].
     24 
     25 <section class="intro">
     26 
     27 A [polynomial][polynomial] in a variable `x` can be expressed as
     28 
     29 <!-- <equation class="equation" label="eq:polynomial" align="center" raw="c_nx^n + c_{n-1}x^{n-1} + \ldots + c_1x^1 + c_0 = \sum_{i=0}^{n} c_ix^i" alt="Polynomial expression."> -->
     30 
     31 <div class="equation" align="center" data-raw-text="c_nx^n + c_{n-1}x^{n-1} + \ldots + c_1x^1 + c_0 = \sum_{i=0}^{n} c_ix^i" data-equation="eq:polynomial">
     32     <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@7e0a95722efd9c771b129597380c63dc6715508b/lib/node_modules/@stdlib/math/base/tools/evalpoly/docs/img/equation_polynomial.svg" alt="Polynomial expression.">
     33     <br>
     34 </div>
     35 
     36 <!-- </equation> -->
     37 
     38 where `c_n, c_{n-1}, ..., c_0` are constants.
     39 
     40 </section>
     41 
     42 <!-- /.intro -->
     43 
     44 <section class="usage">
     45 
     46 ## Usage
     47 
     48 ```javascript
     49 var evalpoly = require( '@stdlib/math/base/tools/evalpoly' );
     50 ```
     51 
     52 #### evalpoly( c, x )
     53 
     54 Evaluates a [polynomial][polynomial] having coefficients `c` and degree `n` at a value `x`, where `n = c.length-1`.
     55 
     56 ```javascript
     57 var v = evalpoly( [ 3.0, 2.0, 1.0 ], 10 ); // => 3*10^0 + 2*10^1 + 1*10^2
     58 // returns 123.0
     59 ```
     60 
     61 The coefficients should be ordered in **ascending** degree, thus matching summation notation.
     62 
     63 #### evalpoly.factory( c )
     64 
     65 Uses code generation to in-line coefficients and return a `function` for evaluating a [polynomial][polynomial].
     66 
     67 ```javascript
     68 var polyval = evalpoly.factory( [ 3.0, 2.0, 1.0 ] );
     69 
     70 var v = polyval( 10.0 ); // => 3*10^0 + 2*10^1 + 1*10^2
     71 // returns 123.0
     72 
     73 v = polyval( 5.0 ); // => 3*5^0 + 2*5^1 + 1*5^2
     74 // returns 38.0
     75 ```
     76 
     77 </section>
     78 
     79 <!-- /.usage -->
     80 
     81 <section class="notes">
     82 
     83 ## Notes
     84 
     85 -   For hot code paths in which coefficients are invariant, a compiled function will be more performant than `evalpoly()`.
     86 -   While code generation can boost performance, its use may be problematic in browser contexts enforcing a strict [content security policy][mdn-csp] (CSP). If running in or targeting an environment with a CSP, avoid using code generation.
     87 
     88 </section>
     89 
     90 <!-- /.notes -->
     91 
     92 <section class="examples">
     93 
     94 ## Examples
     95 
     96 <!-- eslint no-undef: "error" -->
     97 
     98 ```javascript
     99 var randu = require( '@stdlib/random/base/randu' );
    100 var round = require( '@stdlib/math/base/special/round' );
    101 var Float64Array = require( '@stdlib/array/float64' );
    102 var evalpoly = require( '@stdlib/math/base/tools/evalpoly' );
    103 
    104 var polyval;
    105 var coef;
    106 var sign;
    107 var v;
    108 var i;
    109 
    110 // Create an array of random coefficients...
    111 coef = new Float64Array( 10 );
    112 for ( i = 0; i < coef.length; i++ ) {
    113     if ( randu() < 0.5 ) {
    114         sign = -1.0;
    115     } else {
    116         sign = 1.0;
    117     }
    118     coef[ i ] = sign * round( randu()*100.0 );
    119 }
    120 
    121 // Evaluate the polynomial at random values...
    122 for ( i = 0; i < 100; i++ ) {
    123     v = randu() * 100.0;
    124     console.log( 'f(%d) = %d', v, evalpoly( coef, v ) );
    125 }
    126 
    127 // Generate an `evalpoly` function...
    128 polyval = evalpoly.factory( coef );
    129 for ( i = 0; i < 100; i++ ) {
    130     v = (randu()*100.0) - 50.0;
    131     console.log( 'f(%d) = %d', v, polyval( v ) );
    132 }
    133 ```
    134 
    135 </section>
    136 
    137 <!-- /.examples -->
    138 
    139 <section class="links">
    140 
    141 [polynomial]: https://en.wikipedia.org/wiki/Polynomial
    142 
    143 [mdn-csp]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP
    144 
    145 </section>
    146 
    147 <!-- /.links -->