Skip to content

Commit ddd2718

Browse files
kgrytekgryte
committed
docs: update descriptions and refactor tests and benchmarks
1 parent 6a9ffa5 commit ddd2718

File tree

15 files changed

+181
-168
lines changed

15 files changed

+181
-168
lines changed

‎lib/node_modules/@stdlib/math/base/tools/evalrational/README.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ limitations under the License.
2020

2121
# evalrational
2222

23-
> Evaluate a [rational function][rational-function].
23+
> Evaluate a [rational function][rational-function] using double-precision floating-point arithmetic.
2424
2525
<section class="intro">
2626

@@ -70,7 +70,7 @@ var evalrational = require( '@stdlib/math/base/tools/evalrational' );
7070

7171
#### evalrational( P, Q, x )
7272

73-
Evaluates a [rational function][rational-function] at a value `x`. The coefficients `P` and `Q` are expected to be arrays of the **same** length.
73+
Evaluates a [rational function][rational-function] at a value `x` using double-precision floating-point arithmetic.
7474

7575
```javascript
7676
var P = [ -6.0, -5.0 ];
@@ -97,7 +97,7 @@ Coefficients should be ordered in **ascending** degree, thus matching summation
9797

9898
#### evalrational.factory( P, Q )
9999

100-
Uses code generation to in-line coefficients and return a `function` for evaluating a [rational function][rational-function].
100+
Uses code generation to in-line coefficients and return a function for evaluating a [rational function][rational-function] using double-precision floating-point arithmetic.
101101

102102
```javascript
103103
var P = [ 20.0, 8.0, 3.0 ];
@@ -120,6 +120,7 @@ v = rational( 2.0 ); // => (20*2^0 + 8*2^1 + 3*2^2) / (10*2^0 + 9*2^1 + 1*2^2) =
120120

121121
## Notes
122122

123+
- The coefficients `P` and `Q` are expected to be arrays of the **same** length.
123124
- For hot code paths in which coefficients are invariant, a compiled function will be more performant than `evalrational()`.
124125
- 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.
125126

‎lib/node_modules/@stdlib/math/base/tools/evalrational/benchmark/benchmark.factory.js

Lines changed: 20 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
// MODULES //
2222

2323
var bench = require( '@stdlib/bench' );
24-
var randu = require( '@stdlib/random/base/randu' );
24+
var uniform = require( '@stdlib/random/array/uniform' );
2525
var isnan = require( '@stdlib/math/base/assert/is-nan' );
2626
var pkg = require( './../package.json' ).name;
2727
var factory = require( './../lib/factory.js' );
@@ -35,16 +35,19 @@ bench( pkg+'::create:factory', function benchmark( b ) {
3535
var f;
3636
var i;
3737

38-
P = [];
39-
Q = [];
40-
for ( i = 0; i < 10; i++ ) {
41-
P.push( randu() );
42-
Q.push( randu() );
43-
}
38+
P = [
39+
uniform( 10, 0.0, 100.0 ),
40+
uniform( 10, 0.0, 100.0 ),
41+
uniform( 10, 0.0, 100.0 )
42+
];
43+
Q = [
44+
uniform( 10, 0.0, 100.0 ),
45+
uniform( 10, 0.0, 100.0 ),
46+
uniform( 10, 0.0, 100.0 )
47+
];
4448
b.tic();
4549
for ( i = 0; i < b.iterations; i++ ) {
46-
P[ 0 ] = randu();
47-
f = factory( P, Q );
50+
f = factory( P[ i%P.length ], Q[ i%Q.length ] );
4851
if ( typeof f !== 'function' ) {
4952
b.fail( 'should return a function' );
5053
}
@@ -58,25 +61,22 @@ bench( pkg+'::create:factory', function benchmark( b ) {
5861
});
5962

6063
bench( pkg+'::evaluate:factory', function benchmark( b ) {
61-
var x;
62-
var v;
63-
var f;
64+
var values;
6465
var P;
6566
var Q;
67+
var v;
68+
var f;
6669
var i;
6770

68-
P = [];
69-
Q = [];
70-
for ( i = 0; i < 10; i++ ) {
71-
P.push( randu() );
72-
Q.push( randu() );
73-
}
71+
P = uniform( 10, 0.0, 100.0 );
72+
Q = uniform( 10, 0.0, 100.0 );
7473
f = factory( P, Q );
7574

75+
values = uniform( 10, 0.0, 100.0 );
76+
7677
b.tic();
7778
for ( i = 0; i < b.iterations; i++ ) {
78-
x = randu() * 100.0;
79-
v = f( x );
79+
v = f( values[ i%values.length ] );
8080
if ( isnan( v ) ) {
8181
b.fail( 'should not return NaN' );
8282
}

‎lib/node_modules/@stdlib/math/base/tools/evalrational/benchmark/benchmark.factory.length.js

Lines changed: 8 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222

2323
var bench = require( '@stdlib/bench' );
2424
var pow = require( '@stdlib/math/base/special/pow' );
25-
var randu = require( '@stdlib/random/base/randu' );
25+
var uniform = require( '@stdlib/random/array/uniform' );
2626
var isnan = require( '@stdlib/math/base/assert/is-nan' );
2727
var pkg = require( './../package.json' ).name;
2828
var factory = require( './../lib/factory.js' );
@@ -41,15 +41,12 @@ function createBenchmark( len ) {
4141
var rational;
4242
var P;
4343
var Q;
44-
var i;
4544

46-
P = [];
47-
Q = [];
48-
for ( i = 0; i < len; i++ ) {
49-
P.push( randu() );
50-
Q.push( randu() );
51-
}
45+
P = uniform( len, 0.0, 100.0 );
46+
Q = uniform( len, 0.0, 100.0 );
47+
5248
rational = factory( P, Q );
49+
5350
return benchmark;
5451

5552
/**
@@ -63,10 +60,11 @@ function createBenchmark( len ) {
6360
var v;
6461
var i;
6562

63+
x = uniform( 10, 0.0, 100.0 );
64+
6665
b.tic();
6766
for ( i = 0; i < b.iterations; i++ ) {
68-
x = ( randu()*100.0 ) - 50.0;
69-
v = rational( x );
67+
v = rational( x[ i%x.length ] );
7068
if ( isnan( v ) ) {
7169
b.fail( 'should not return NaN' );
7270
}

‎lib/node_modules/@stdlib/math/base/tools/evalrational/benchmark/benchmark.js

Lines changed: 14 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@
2121
// MODULES //
2222

2323
var bench = require( '@stdlib/bench' );
24-
var randu = require( '@stdlib/random/base/randu' );
24+
var uniform = require( '@stdlib/random/array/uniform' );
2525
var isnan = require( '@stdlib/math/base/assert/is-nan' );
2626
var pkg = require( './../package.json' ).name;
2727
var evalrational = require( './../lib' );
@@ -36,16 +36,21 @@ bench( pkg, function benchmark( b ) {
3636
var v;
3737
var i;
3838

39-
P = [];
40-
Q = [];
41-
for ( i = 0; i < 10; i++ ) {
42-
P.push( randu() );
43-
Q.push( randu() );
44-
}
39+
P = [
40+
uniform( 10, 0.0, 100.0 ),
41+
uniform( 10, 0.0, 100.0 ),
42+
uniform( 10, 0.0, 100.0 )
43+
];
44+
Q = [
45+
uniform( 10, 0.0, 100.0 ),
46+
uniform( 10, 0.0, 100.0 ),
47+
uniform( 10, 0.0, 100.0 )
48+
];
49+
x = uniform( 10, 0.0, 100.0 );
50+
4551
b.tic();
4652
for ( i = 0; i < b.iterations; i++ ) {
47-
x = ( randu()*100.0 ) - 50.0;
48-
v = evalrational( P, Q, x );
53+
v = evalrational( P[ i%P.length ], Q[ i%Q.length ], x[ i%x.length ] );
4954
if ( isnan( v ) ) {
5055
b.fail( 'should not return NaN' );
5156
}

‎lib/node_modules/@stdlib/math/base/tools/evalrational/benchmark/benchmark.length.js

Lines changed: 6 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@
2222

2323
var bench = require( '@stdlib/bench' );
2424
var pow = require( '@stdlib/math/base/special/pow' );
25-
var randu = require( '@stdlib/random/base/randu' );
25+
var uniform = require( '@stdlib/random/array/uniform' );
2626
var isnan = require( '@stdlib/math/base/assert/is-nan' );
2727
var pkg = require( './../package.json' ).name;
2828
var evalrational = require( './../lib' );
@@ -38,16 +38,8 @@ var evalrational = require( './../lib' );
3838
* @returns {Function} benchmark function
3939
*/
4040
function createBenchmark( len ) {
41-
var P;
42-
var Q;
43-
var i;
44-
45-
P = [];
46-
Q = [];
47-
for ( i = 0; i < len; i++ ) {
48-
P.push( randu() );
49-
Q.push( randu() );
50-
}
41+
var P = uniform( len, 0.0, 100.0 );
42+
var Q = uniform( len, 0.0, 100.0 );
5143
return benchmark;
5244

5345
/**
@@ -61,10 +53,11 @@ function createBenchmark( len ) {
6153
var v;
6254
var i;
6355

56+
x = uniform( 10, 0.0, 100.0 );
57+
6458
b.tic();
6559
for ( i = 0; i < b.iterations; i++ ) {
66-
x = ( randu()*100.0 ) - 50.0;
67-
v = evalrational( P, Q, x );
60+
v = evalrational( P, Q, x[ i%x.length ] );
6861
if ( isnan( v ) ) {
6962
b.fail( 'should not return NaN' );
7063
}

‎lib/node_modules/@stdlib/math/base/tools/evalrational/docs/repl.txt

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11

22
{{alias}}( P, Q, x )
3-
Evaluates a rational function.
3+
Evaluates a rational function using double-precision floating-point
4+
arithmetic.
45

56
A rational function `f(x)` is defined as
67

@@ -45,7 +46,8 @@
4546

4647

4748
{{alias}}.factory( P, Q )
48-
Returns a function for evaluating a rational function.
49+
Returns a function for evaluating a rational function using double-precision
50+
floating-point arithmetic.
4951

5052
Parameters
5153
----------
@@ -64,14 +66,14 @@
6466
--------
6567
> var P = [ 20.0, 8.0, 3.0 ];
6668
> var Q = [ 10.0, 9.0, 1.0 ];
67-
> var rational = {{alias}}.factory( P, Q );
69+
> var f = {{alias}}.factory( P, Q );
6870

6971
// (20*10^0 + 8*10^1 + 3*10^2) / (10*10^0 + 9*10^1 + 1*10^2):
70-
> var v = rational( 10.0 )
72+
> var v = f( 10.0 )
7173
2.0
7274

7375
// (20*2^0 + 8*2^1 + 3*2^2) / (10*2^0 + 9*2^1 + 1*2^2):
74-
> v = rational( 2.0 )
76+
> v = f( 2.0 )
7577
1.5
7678

7779
See Also

‎lib/node_modules/@stdlib/math/base/tools/evalrational/docs/types/index.d.ts

Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -18,20 +18,24 @@
1818

1919
// TypeScript Version: 4.1
2020

21+
/// <reference types="@stdlib/types"/>
22+
23+
import { Collection } from '@stdlib/types/array';
24+
2125
/**
22-
* Evaluates a rational function.
26+
* Evaluates a rational function using double-precision floating-point arithmetic.
2327
*
2428
* @param x - value at which to evaluate a rational function
2529
* @returns evaluated rational function
2630
*/
27-
type EvaluationFunction = ( x: number ) => number;
31+
type PolynomialFunction = ( x: number ) => number;
2832

2933
/**
3034
* Interface for evaluating rational functions.
3135
*/
3236
interface EvalRational {
3337
/**
34-
* Evaluates a rational function, i.e., the ratio of two polynomials described by the coefficients stored in \\(P\\) and \\(Q\\).
38+
* Evaluates a rational function (i.e., the ratio of two polynomials described by the coefficients stored in \\(P\\) and \\(Q\\)) using double-precision floating-point arithmetic.
3539
*
3640
* ## Notes
3741
*
@@ -40,7 +44,6 @@ interface EvalRational {
4044
*
4145
* [horners-method]: https://en.wikipedia.org/wiki/Horner%27s_method
4246
*
43-
*
4447
* @param P - numerator polynomial coefficients sorted in ascending degree
4548
* @param Q - denominator polynomial coefficients sorted in ascending degree
4649
* @param x - value at which to evaluate the rational function
@@ -63,18 +66,17 @@ interface EvalRational {
6366
* var v = evalrational( P, Q, 6.0 ); // => ( -6*6^0 - 5*6^1 + 4*6^2 + 2*6^3 ) / ( 3*6^0 + 0.5*6^1 + 0*6^2 + 0*6^3 ) = (-6-30+144+432)/(3+3)
6467
* // returns 90.0
6568
*/
66-
( P: Array<number>, Q: Array<number>, x: number ): number;
69+
( P: Collection<number>, Q: Collection<number>, x: number ): number;
6770

6871
/**
69-
* Generates a function for evaluating a rational function.
72+
* Generates a function for evaluating a rational function using double-precision floating-point arithmetic.
7073
*
7174
* ## Notes
7275
*
7376
* - The compiled function uses [Horner's rule][horners-method] for efficient computation.
7477
*
7578
* [horners-method]: https://en.wikipedia.org/wiki/Horner%27s_method
7679
*
77-
*
7880
* @param P - numerator polynomial coefficients sorted in ascending degree
7981
* @param Q - denominator polynomial coefficients sorted in ascending degree
8082
* @returns function for evaluating a rational function
@@ -91,11 +93,11 @@ interface EvalRational {
9193
* v = rational( 2.0 ); // => (20*2^0 + 8*2^1 + 3*2^2) / (10*2^0 + 9*2^1 + 1*2^2) = (20+16+12)/(10+18+4)
9294
* // returns 1.5
9395
*/
94-
factory( P: Array<number>, Q: Array<number> ): EvaluationFunction;
96+
factory( P: Collection<number>, Q: Collection<number> ): PolynomialFunction;
9597
}
9698

9799
/**
98-
* Evaluates a rational function, i.e., the ratio of two polynomials described by the coefficients stored in \\(P\\) and \\(Q\\).
100+
* Evaluates a rational function (i.e., the ratio of two polynomials described by the coefficients stored in \\(P\\) and \\(Q\\)) using double-precision floating-point arithmetic.
99101
*
100102
* ## Notes
101103
*
@@ -104,7 +106,6 @@ interface EvalRational {
104106
*
105107
* [horners-method]: https://en.wikipedia.org/wiki/Horner%27s_method
106108
*
107-
*
108109
* @param P - numerator polynomial coefficients sorted in ascending degree
109110
* @param Q - denominator polynomial coefficients sorted in ascending degree
110111
* @param x - value at which to evaluate the rational function

0 commit comments

Comments
 (0)