README.md (9445B)
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 # Triangular Random Numbers 22 23 > [Triangular][triangular] distributed pseudorandom numbers. 24 25 <section class="usage"> 26 27 ## Usage 28 29 ```javascript 30 var triangular = require( '@stdlib/random/base/triangular' ); 31 ``` 32 33 #### triangular( a, b, c ) 34 35 Returns a pseudorandom number drawn from a [triangular][triangular] distribution with parameters `a` (minimum support), `b` (maximum support), and `c` (mode). 36 37 ```javascript 38 var r = triangular( 2.0, 5.0, 3.33 ); 39 // returns <number> 40 ``` 41 42 If either `a`, `b`, or `c` is `NaN`, the function returns `NaN`. 43 44 ```javascript 45 var r = triangular( NaN, 1.0, 0.5 ); 46 // returns NaN 47 48 r = triangular( 1.0, NaN, 2.42 ); 49 // returns NaN 50 51 r = triangular( 1.0, 10.0, NaN ); 52 // returns NaN 53 ``` 54 55 If the condition `a <= c <= b` is not satisfied, the function returns `NaN`. 56 57 ```javascript 58 var r = triangular( 13.0, 9.0, 0.5 ); 59 // returns NaN 60 ``` 61 62 #### triangular.factory( \[a, b, c, ]\[options] ) 63 64 Returns a pseudorandom number generator (PRNG) for generating pseudorandom numbers drawn from a [triangular][triangular] distribution. 65 66 ```javascript 67 var rand = triangular.factory(); 68 69 var r = rand( 0.0, 1.0, 0.5 ); 70 // returns <number> 71 ``` 72 73 If provided `a`, `b`, and `c`, the returned generator returns random variates from the specified distribution. 74 75 ```javascript 76 var rand = triangular.factory( -2.0, 2.0, 1.0 ); 77 78 var r = rand(); 79 // returns <number> 80 81 r = rand(); 82 // returns <number> 83 ``` 84 85 If not provided `a`, `b`, and `c`, the returned generator requires that all three parameters be provided at each invocation. 86 87 ```javascript 88 var rand = triangular.factory(); 89 90 var r = rand( 0.0, 1.0, 0.75 ); 91 // returns <number> 92 93 r = rand( -2.0, 2.0, 0.1 ); 94 // returns <number> 95 ``` 96 97 The function accepts the following `options`: 98 99 - **prng**: pseudorandom number generator for generating uniformly distributed pseudorandom numbers on the interval `[0,1)`. If provided, the function **ignores** both the `state` and `seed` options. In order to seed the returned pseudorandom number generator, one must seed the provided `prng` (assuming the provided `prng` is seedable). 100 - **seed**: pseudorandom number generator seed. 101 - **state**: a [`Uint32Array`][@stdlib/array/uint32] containing pseudorandom number generator state. If provided, the function ignores the `seed` option. 102 - **copy**: `boolean` indicating whether to copy a provided pseudorandom number generator state. Setting this option to `false` allows sharing state between two or more pseudorandom number generators. Setting this option to `true` ensures that a returned generator has exclusive control over its internal state. Default: `true`. 103 104 To use a custom PRNG as the underlying source of uniformly distributed pseudorandom numbers, set the `prng` option. 105 106 ```javascript 107 var minstd = require( '@stdlib/random/base/minstd' ); 108 109 var rand = triangular.factory({ 110 'prng': minstd.normalized 111 }); 112 113 var r = rand( 2.0, 4.0, 3.0 ); 114 // returns <number> 115 ``` 116 117 To seed a pseudorandom number generator, set the `seed` option. 118 119 ```javascript 120 var rand1 = triangular.factory({ 121 'seed': 12345 122 }); 123 124 var r1 = rand1( 2.0, 4.0, 3.0 ); 125 // returns <number> 126 127 var rand2 = triangular.factory( 2.0, 4.0, 3.0, { 128 'seed': 12345 129 }); 130 131 var r2 = rand2(); 132 // returns <number> 133 134 var bool = ( r1 === r2 ); 135 // returns true 136 ``` 137 138 To return a generator having a specific initial state, set the generator `state` option. 139 140 ```javascript 141 var rand; 142 var bool; 143 var r; 144 var i; 145 146 // Generate pseudorandom numbers, thus progressing the generator state: 147 for ( i = 0; i < 1000; i++ ) { 148 r = triangular( 0.0, 1.0, 0.5 ); 149 } 150 151 // Create a new PRNG initialized to the current state of `triangular`: 152 rand = triangular.factory({ 153 'state': triangular.state 154 }); 155 156 // Test that the generated pseudorandom numbers are the same: 157 bool = ( rand( 0.0, 1.0, 0.5 ) === triangular( 0.0, 1.0, 0.5 ) ); 158 // returns true 159 ``` 160 161 #### triangular.NAME 162 163 The generator name. 164 165 ```javascript 166 var str = triangular.NAME; 167 // returns 'triangular' 168 ``` 169 170 #### triangular.PRNG 171 172 The underlying pseudorandom number generator. 173 174 ```javascript 175 var prng = triangular.PRNG; 176 // returns <Function> 177 ``` 178 179 #### triangular.seed 180 181 The value used to seed `triangular()`. 182 183 ```javascript 184 var rand; 185 var r; 186 var i; 187 188 // Generate pseudorandom values... 189 for ( i = 0; i < 100; i++ ) { 190 r = triangular( 0.0, 10.0, 3.0 ); 191 } 192 193 // Generate the same pseudorandom values... 194 rand = triangular.factory( 0.0, 10.0, 3.0, { 195 'seed': triangular.seed 196 }); 197 for ( i = 0; i < 100; i++ ) { 198 r = rand(); 199 } 200 ``` 201 202 If provided a PRNG for uniformly distributed numbers, this value is `null`. 203 204 <!-- eslint-disable stdlib/no-builtin-math --> 205 206 ```javascript 207 var rand = triangular.factory({ 208 'prng': Math.random 209 }); 210 211 var seed = rand.seed; 212 // returns null 213 ``` 214 215 #### triangular.seedLength 216 217 Length of generator seed. 218 219 ```javascript 220 var len = triangular.seedLength; 221 // returns <number> 222 ``` 223 224 If provided a PRNG for uniformly distributed numbers, this value is `null`. 225 226 <!-- eslint-disable stdlib/no-builtin-math --> 227 228 ```javascript 229 var rand = triangular.factory({ 230 'prng': Math.random 231 }); 232 233 var len = rand.seedLength; 234 // returns null 235 ``` 236 237 #### triangular.state 238 239 Writable property for getting and setting the generator state. 240 241 ```javascript 242 var r = triangular( 0.0, 1.0, 0.5 ); 243 // returns <number> 244 245 r = triangular( 0.0, 1.0, 0.5 ); 246 // returns <number> 247 248 // ... 249 250 // Get a copy of the current state: 251 var state = triangular.state; 252 // returns <Uint32Array> 253 254 r = triangular( 0.0, 1.0, 0.5 ); 255 // returns <number> 256 257 r = triangular( 0.0, 1.0, 0.5 ); 258 // returns <number> 259 260 // Reset the state: 261 triangular.state = state; 262 263 // Replay the last two pseudorandom numbers: 264 r = triangular( 0.0, 1.0, 0.5 ); 265 // returns <number> 266 267 r = triangular( 0.0, 1.0, 0.5 ); 268 // returns <number> 269 270 // ... 271 ``` 272 273 If provided a PRNG for uniformly distributed numbers, this value is `null`. 274 275 <!-- eslint-disable stdlib/no-builtin-math --> 276 277 ```javascript 278 var rand = triangular.factory({ 279 'prng': Math.random 280 }); 281 282 var state = rand.state; 283 // returns null 284 ``` 285 286 #### triangular.stateLength 287 288 Length of generator state. 289 290 ```javascript 291 var len = triangular.stateLength; 292 // returns <number> 293 ``` 294 295 If provided a PRNG for uniformly distributed numbers, this value is `null`. 296 297 <!-- eslint-disable stdlib/no-builtin-math --> 298 299 ```javascript 300 var rand = triangular.factory({ 301 'prng': Math.random 302 }); 303 304 var len = rand.stateLength; 305 // returns null 306 ``` 307 308 #### triangular.byteLength 309 310 Size (in bytes) of generator state. 311 312 ```javascript 313 var sz = triangular.byteLength; 314 // returns <number> 315 ``` 316 317 If provided a PRNG for uniformly distributed numbers, this value is `null`. 318 319 <!-- eslint-disable stdlib/no-builtin-math --> 320 321 ```javascript 322 var rand = triangular.factory({ 323 'prng': Math.random 324 }); 325 326 var sz = rand.byteLength; 327 // returns null 328 ``` 329 330 #### triangular.toJSON() 331 332 Serializes the pseudorandom number generator as a JSON object. 333 334 ```javascript 335 var o = triangular.toJSON(); 336 // returns { 'type': 'PRNG', 'name': '...', 'state': {...}, 'params': [] } 337 ``` 338 339 If provided a PRNG for uniformly distributed numbers, this method returns `null`. 340 341 <!-- eslint-disable stdlib/no-builtin-math --> 342 343 ```javascript 344 var rand = triangular.factory({ 345 'prng': Math.random 346 }); 347 348 var o = rand.toJSON(); 349 // returns null 350 ``` 351 352 </section> 353 354 <!-- /.usage --> 355 356 <section class="notes"> 357 358 ## Notes 359 360 - If PRNG state is "shared" (meaning a state array was provided during PRNG creation and **not** copied) and one sets the generator state to a state array having a different length, the PRNG does **not** update the existing shared state and, instead, points to the newly provided state array. In order to synchronize PRNG output according to the new shared state array, the state array for **each** relevant PRNG must be **explicitly** set. 361 - If PRNG state is "shared" and one sets the generator state to a state array of the same length, the PRNG state is updated (along with the state of all other PRNGs sharing the PRNG's state array). 362 363 </section> 364 365 <!-- /.notes --> 366 367 <section class="examples"> 368 369 ## Examples 370 371 <!-- eslint no-undef: "error" --> 372 373 ```javascript 374 var triangular = require( '@stdlib/random/base/triangular' ); 375 376 var seed; 377 var rand; 378 var i; 379 380 // Generate pseudorandom numbers... 381 for ( i = 0; i < 100; i++ ) { 382 console.log( triangular( 0.0, 1.0, 0.5 ) ); 383 } 384 385 // Create a new pseudorandom number generator... 386 seed = 1234; 387 rand = triangular.factory( 2.0, 5.0, 3.0, { 388 'seed': seed 389 }); 390 for ( i = 0; i < 100; i++ ) { 391 console.log( rand() ); 392 } 393 394 // Create another pseudorandom number generator using a previous seed... 395 rand = triangular.factory( 0.0, 1.0, 0.5, { 396 'seed': triangular.seed 397 }); 398 for ( i = 0; i < 100; i++ ) { 399 console.log( rand() ); 400 } 401 ``` 402 403 </section> 404 405 <!-- /.examples --> 406 407 <section class="links"> 408 409 [triangular]: https://en.wikipedia.org/wiki/Triangular_distribution 410 411 [@stdlib/array/uint32]: https://www.npmjs.com/package/@stdlib/array-uint32 412 413 </section> 414 415 <!-- /.links -->