time-to-botec

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

README.md (6366B)

      1 <!--
      2 
      3 @license Apache-2.0
      4 
      5 Copyright (c) 2020 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 # ramp
     22 
     23 > Evaluate the [ramp function][ramp-function] for each element in a strided array.
     24 
     25 <section class="intro">
     26 
     27 The [ramp function][ramp-function] is defined as
     28 
     29 <!-- <equation class="equation" label="eq:ramp_function" align="center" raw="R(x) = \begin{cases} x & \textrm{if}\ x \geq 0 \\ 0 & \textrm{if}\ x \lt 0\end{cases}" alt="Ramp function."> -->
     30 
     31 <div class="equation" align="center" data-raw-text="R(x) = \begin{cases} x &amp; \textrm{if}\ x \geq 0 \\ 0 &amp; \textrm{if}\ x \lt 0\end{cases}" data-equation="eq:ramp_function">
     32     <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@207485f5e3ed3e8f8e76edfe8d3d5afad7722746/lib/node_modules/@stdlib/math/strided/special/ramp/docs/img/equation_ramp_function.svg" alt="Ramp function.">
     33     <br>
     34 </div>
     35 
     36 <!-- </equation> -->
     37 
     38 or, alternatively, in terms of the `max` function
     39 
     40 <!-- <equation class="equation" label="eq:ramp_function_alternative_defn" align="center" raw="R(x) = \operatorname{max}( x, 0 )" alt="Ramp function alternative definition."> -->
     41 
     42 <div class="equation" align="center" data-raw-text="R(x) = \operatorname{max}( x, 0 )" data-equation="eq:ramp_function_alternative_defn">
     43     <img src="https://cdn.jsdelivr.net/gh/stdlib-js/stdlib@207485f5e3ed3e8f8e76edfe8d3d5afad7722746/lib/node_modules/@stdlib/math/strided/special/ramp/docs/img/equation_ramp_function_alternative_defn.svg" alt="Ramp function alternative definition.">
     44     <br>
     45 </div>
     46 
     47 <!-- </equation> -->
     48 
     49 </section>
     50 
     51 <!-- /.intro -->
     52 
     53 <section class="usage">
     54 
     55 ## Usage
     56 
     57 ```javascript
     58 var ramp = require( '@stdlib/math/strided/special/ramp' );
     59 ```
     60 
     61 #### ramp( N, x, strideX, y, strideY )
     62 
     63 Evaluates the [ramp function][ramp-function] for each element in a strided array `x` and assigns the results to elements in a strided array `y`.
     64 
     65 ```javascript
     66 var Float64Array = require( '@stdlib/array/float64' );
     67 
     68 var x = new Float64Array( [ 1.1, 2.5, -3.5, 4.0, -5.9 ] );
     69 
     70 // Perform operation in-place:
     71 ramp( x.length, x, 1, x, 1 );
     72 // x => <Float64Array>[ 1.1, 2.5, 0.0, 4.0, 0.0 ]
     73 ```
     74 
     75 The function accepts the following arguments:
     76 
     77 -   **N**: number of indexed elements.
     78 -   **x**: input array-like object.
     79 -   **strideX**: index increment for `x`.
     80 -   **y**: output array-like object.
     81 -   **strideY**: index increment for `y`.
     82 
     83 The `N` and `stride` parameters determine which elements in `x` and `y` are accessed at runtime. For example, to index every other value in `x` and the first `N` elements of `y` in reverse order,
     84 
     85 ```javascript
     86 var Float64Array = require( '@stdlib/array/float64' );
     87 
     88 var x = new Float64Array( [ 1.1, 2.5, -3.5, 4.0, -5.9, 6.4 ] );
     89 var y = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] );
     90 
     91 ramp( 3, x, 2, y, -1 );
     92 // y => <Float64Array>[ 0.0, 0.0, 1.1, 0.0, 0.0, 0.0 ]
     93 ```
     94 
     95 Note that indexing is relative to the first index. To introduce an offset, use [`typed array`][mdn-typed-array] views.
     96 
     97 ```javascript
     98 var Float64Array = require( '@stdlib/array/float64' );
     99 
    100 // Initial arrays...
    101 var x0 = new Float64Array( [ 1.1, 2.5, -3.5, 4.0, -5.9, 6.4 ] );
    102 var y0 = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] );
    103 
    104 // Create offset views...
    105 var x1 = new Float64Array( x0.buffer, x0.BYTES_PER_ELEMENT*1 ); // start at 2nd element
    106 var y1 = new Float64Array( y0.buffer, y0.BYTES_PER_ELEMENT*3 ); // start at 4th element
    107 
    108 ramp( 3, x1, -2, y1, 1 );
    109 // y0 => <Float64Array>[ 0.0, 0.0, 0.0, 6.4, 4.0, 2.5 ]
    110 ```
    111 
    112 #### ramp.ndarray( N, x, strideX, offsetX, y, strideY, offsetY )
    113 
    114 Evaluates the [ramp function][ramp-function] for each element in a strided array `x` and assigns the results to elements in a strided array `y` using alternative indexing semantics.
    115 
    116 ```javascript
    117 var Float64Array = require( '@stdlib/array/float64' );
    118 
    119 var x = new Float64Array( [ 1.1, 2.5, -3.5, 4.0, -5.9 ] );
    120 var y = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0 ] );
    121 
    122 ramp.ndarray( x.length, x, 1, 0, y, 1, 0 );
    123 // y => <Float64Array>[ 1.1, 2.5, 0.0, 4.0, 0.0 ]
    124 ```
    125 
    126 The function accepts the following additional arguments:
    127 
    128 -   **offsetX**: starting index for `x`.
    129 -   **offsetY**: starting index for `y`.
    130 
    131 While [`typed array`][mdn-typed-array] views mandate a view offset based on the underlying `buffer`, the `offsetX` and `offsetY` parameters support indexing semantics based on starting indices. For example, to index every other value in `x` starting from the second value and to index the last `N` elements in `y`,
    132 
    133 ```javascript
    134 var Float64Array = require( '@stdlib/array/float64' );
    135 
    136 var x = new Float64Array( [ 1.1, 2.5, -3.5, 4.0, -5.9, 6.4 ] );
    137 var y = new Float64Array( [ 0.0, 0.0, 0.0, 0.0, 0.0, 0.0 ] );
    138 
    139 ramp.ndarray( 3, x, 2, 1, y, -1, y.length-1 );
    140 // y => <Float64Array>[ 0.0, 0.0, 0.0, 6.4, 4.0, 2.5 ]
    141 ```
    142 
    143 </section>
    144 
    145 <!-- /.usage -->
    146 
    147 <section class="notes">
    148 
    149 </section>
    150 
    151 <!-- /.notes -->
    152 
    153 <section class="examples">
    154 
    155 ## Examples
    156 
    157 <!-- eslint no-undef: "error" -->
    158 
    159 ```javascript
    160 var uniform = require( '@stdlib/random/base/uniform' ).factory;
    161 var filledarray = require( '@stdlib/array/filled' );
    162 var dtypes = require( '@stdlib/array/dtypes' );
    163 var gfillBy = require( '@stdlib/blas/ext/base/gfill-by' );
    164 var ramp = require( '@stdlib/math/strided/special/ramp' );
    165 
    166 var dt;
    167 var x;
    168 var y;
    169 var i;
    170 
    171 dt = dtypes();
    172 for ( i = 0; i < dt.length; i++ ) {
    173     x = filledarray( 0.0, 10, dt[ i ] );
    174     gfillBy( x.length, x, 1, uniform( -10.0, 10.0 ) );
    175     console.log( x );
    176 
    177     y = filledarray( 0.0, x.length, 'generic' );
    178     console.log( y );
    179 
    180     ramp.ndarray( x.length, x, 1, 0, y, -1, y.length-1 );
    181     console.log( y );
    182     console.log( '' );
    183 }
    184 ```
    185 
    186 </section>
    187 
    188 <!-- /.examples -->
    189 
    190 <section class="links">
    191 
    192 [mdn-typed-array]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray
    193 
    194 [ramp-function]: https://en.wikipedia.org/wiki/Ramp_function
    195 
    196 </section>
    197 
    198 <!-- /.links -->